# oss-protection

Part of **OSS**

# Object Storage Service Data Protection CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| `ossutil worm init` | Initialize a WORM retention policy on a bucket | `ossutil worm init oss://<bucket> <days>` |
| `ossutil worm complete` | Lock a WORM retention policy | `ossutil worm complete oss://<bucket> <WormId>` |
| `ossutil worm extend` | Extend the retention period of a locked policy | `ossutil worm extend oss://<bucket> <days> <WormId>` |
| `ossutil worm get` | Retrieve current retention policy details | `ossutil worm get oss://<bucket>` |
| `ossutil worm abort` | Delete an unlocked retention policy | `ossutil worm abort oss://<bucket>` |
| `ossutil api invoke-operation` (QoS get) | Get priority QoS configuration for a resource pool | `ossutil api invoke-operation --op-name get-resource-pool-priority-qos-configuration [flags]` |
| `ossutil api invoke-operation` (QoS put) | Configure priority or requester QoS for a resource pool | `ossutil api invoke-operation --op-name put-resource-pool-*-qos-configuration [flags]` |
| `ossutil api invoke-operation` (QoS list) | List requester QoS info for a resource pool | `ossutil api invoke-operation --op-name list-resource-pool-requester-qos-infos [flags]` |
| `ossutil api invoke-operation` (QoS delete) | Delete requester priority QoS configuration | `ossutil api invoke-operation --op-name delete-resource-pool-requester-priority-qos-configuration [flags]` |
| `ossutil config` | Manage ossutil configuration files and credentials | `ossutil config [subcommand] [flags]` |

## Command Details

### ossutil worm init

**Purpose**: Initialize a Write Once Read Many (WORM) retention policy on a bucket with a specified retention period. The policy is in "InProgress" state until locked.

**Syntax**:
```bash
ossutil worm init oss://<BucketName> <RetentionPeriodInDays>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `oss://<BucketName>` | — | string | Yes | The name of the OSS bucket |
| `<RetentionPeriodInDays>` | — | integer | Yes | Retention period in days (1–25550) |

```bash
# Initialize a 180-day retention policy on examplebucket
ossutil worm init oss://examplebucket 180

# Initialize with explicit credentials and endpoint (China region)
ossutil worm init oss://test -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret
```

### ossutil worm complete

**Purpose**: Lock an initialized WORM retention policy, making it immutable and active.

**Syntax**:
```bash
ossutil worm complete oss://<BucketName> <WormId>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `oss://<BucketName>` | — | string | Yes | The name of the OSS bucket |
| `<WormId>` | — | string | Yes | The ID of the retention policy returned during initialization |

```bash
# Lock the retention policy with given WormId
ossutil worm complete oss://examplebucket 581D8A7FFA064C80827CAB4076A93A78
```

### ossutil worm extend

**Purpose**: Extend the retention period of a locked WORM policy. Only allowed if the new period is longer than the current one.

**Syntax**:
```bash
ossutil worm extend oss://<BucketName> <NewRetentionPeriodInDays> <WormId>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `oss://<BucketName>` | — | string | Yes | The name of the OSS bucket |
| `<NewRetentionPeriodInDays>` | — | integer | Yes | New retention period (must be > current) |
| `<WormId>` | — | string | Yes | The ID of the locked retention policy |

```bash
# Extend retention period to 360 days
ossutil worm extend oss://examplebucket 360 581D8A7FFA064C80827CAB4076A93A78
```

### ossutil worm get

**Purpose**: Retrieve the current WORM retention policy configuration for a bucket.

**Syntax**:
```bash
ossutil worm get oss://<BucketName>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `oss://<BucketName>` | — | string | Yes | The name of the OSS bucket |

```bash
# Get retention policy details
ossutil worm get oss://examplebucket
```

**Output Example**:
```text
<WormConfiguration>
  <WormId>581D8A7FFA064C80827CAB4076A93A78</WormId>
  <State>Locked</State>
  <RetentionPeriodInDays>360</RetentionPeriodInDays>
  <CreationDate>2021-01-19T03:36:53.000Z</CreationDate>
</WormConfiguration>
```

### ossutil worm abort

**Purpose**: Delete an unlocked (InProgress) retention policy. Cannot be used on locked policies.

**Syntax**:
```bash
ossutil worm abort oss://<BucketName>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `oss://<BucketName>` | — | string | Yes | The name of the OSS bucket |

```bash
# Abort (delete) an unlocked retention policy
ossutil worm abort oss://examplebucket
```

### ossutil api invoke-operation (QoS Operations)

**Purpose**: Perform API-level operations to manage Quality of Service (QoS) settings for resource pools, including priority and requester-based bandwidth controls.

**Syntax**:
```bash
ossutil api invoke-operation --op-name <operation> --method <HTTP_METHOD> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--op-name` | — | string | Yes | Operation name (e.g., `get-resource-pool-priority-qos-configuration`) |
| `--method` | — | string | Yes | HTTP method (`GET`, `PUT`, `DELETE`) |
| `--parameters resourcePool` | — | string | Yes | Name of the resource pool (e.g., `hz-rp-03`) |
| `--parameters priorityQos` | — | boolean | Conditional | Flag to indicate priority QoS operation (no value needed) |
| `--parameters requesterPriorityQos` | — | boolean | Conditional | Flag for requester priority QoS |
| `--parameters requesterQosInfo` | — | string | Yes (for list) | Indicates listing requester QoS info |
| `--parameters continuation-token` | — | string | No | Token for paginated results |
| `--parameters max-keys` | — | integer | No | Max entries per response (1–1000, default 100) |
| `--body` | — | string | Yes (for PUT) | Path to XML config file (`file://path`) |
| `--endpoint` | — | string | No | OSS endpoint URL |

```bash
# Get priority QoS config for resource pool
ossutil api invoke-operation --op-name get-resource-pool-priority-qos-configuration --method GET --parameters resourcePool=hz-rp-03 --parameters priorityQos

# Configure requester priority QoS using XML file
ossutil api invoke-operation --op-name put-resource-pool-requester-priority-qos-configuration --method PUT --parameters resourcePool=hz-rp-03 --parameters requesterPriorityQos --body=file://requester-priority-qos.xml

# List requester QoS info with pagination
ossutil api invoke-operation --op-name list-resource-pool-requester-qos-infos --method GET --parameters resourcePool=examplePool --parameters requesterQosInfo --parameters max-keys=10

# Delete requester priority QoS config
ossutil api invoke-operation --op-name delete-resource-pool-requester-priority-qos-configuration --method DELETE --parameters resourcePool=hz-rp-03 --parameters requesterPriorityQos
```

### ossutil config

**Purpose**: Create and manage ossutil configuration files for credentials, regions, and profiles.

**Syntax**:
```bash
ossutil config [set|get|list-profiles|credential] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--config-file` | — | string | No | Path to custom config file |
| `--profile` | — | string | No | Named profile within config |
| `region` / `accessKeyID` / `accessKeySecret` / `endpoint` | — | string | Conditional | Configuration values |

```bash
# Interactive configuration setup
ossutil config

# Set region for a profile in a custom config file
ossutil config set region cn-hangzhou --config-file myconfig --profile dev

# Get region from a profile
ossutil config get region --config-file myconfig --profile dev

# List all available profiles
ossutil config list-profiles

# Manage credentials interactively
ossutil config credential
```

## Common Scenarios

### Scenario 1: Set Up a Compliant Immutable Bucket

```bash
# Step 1: Initialize a 365-day WORM policy
ossutil worm init oss://compliance-bucket 365

# Step 2: Lock the policy to enforce immutability
ossutil worm complete oss://compliance-bucket <WormId_from_step1>

# Step 3: Verify the policy is active and locked
ossutil worm get oss://compliance-bucket
```

### Scenario 2: Configure and Monitor Resource Pool QoS

```bash
# Step 1: Define priority QoS in an XML file (priority-qos.xml)

# Step 2: Apply the configuration to a resource pool
ossutil api invoke-operation --op-name put-resource-pool-priority-qos-configuration --method PUT --parameters resourcePool=prod-pool --parameters priorityQos --body=file://priority-qos.xml

# Step 3: Verify the configuration was applied
ossutil api invoke-operation --op-name get-resource-pool-priority-qos-configuration --method GET --parameters resourcePool=prod-pool --parameters priorityQos

# Step 4: List all requester QoS settings for auditing
ossutil api invoke-operation --op-name list-resource-pool-requester-qos-infos --method GET --parameters resourcePool=prod-pool --parameters requesterQosInfo
```

## Environment Setup

### Installation
Install `ossutil` by downloading the appropriate binary for your OS from the official Alibaba Cloud OSS documentation. Ensure the binary is in your system PATH.

### Configuration
Configure credentials and region using one of the following methods:

1. **Interactive setup**:
   ```bash
   ossutil config
   ```

2. **Environment variables**:
   ```bash
   export ALIYUN_ACCESS_KEY_ID=yourAccessKeyID
   export ALIYUN_ACCESS_KEY_SECRET=yourAccessKeySecret
   ```

3. **Command-line flags** (for one-time use):
   ```bash
   ossutil worm get oss://bucket -e oss-cn-hangzhou.aliyuncs.com -i <ID> -k <Secret>
   ```

Ensure your RAM user has the required permissions:
- `oss:InitiateBucketWorm`, `oss:CompleteBucketWorm` for retention policies
- `oss:GetResourcePoolPriorityQosConfiguration`, `oss:PutResourcePoolRequesterPriorityQosConfiguration`, etc., for QoS operations

## FAQ

Q: How do I configure credentials for ossutil?
A: Use `ossutil config` for interactive setup, set environment variables (`ALIYUN_ACCESS_KEY_ID` and `ALIYUN_ACCESS_KEY_SECRET`), or pass `-i` and `-k` flags directly in commands.

Q: What is the difference between `priorityQos` and `requesterPriorityQos`?
A: `priorityQos` configures general priority scheduling for the resource pool, while `requesterPriorityQos` defines QoS rules specific to RAM users (requesters) accessing the pool.

Q: Can I modify or delete a locked retention policy?
A: No. Once a WORM policy is locked (`complete`d), it cannot be modified or deleted until the retention period expires. You can only extend the period (to a longer duration).

Q: Why do I get a 403 error when running QoS commands?
A: Your RAM user lacks the required permissions (e.g., `oss:GetResourcePoolPriorityQosConfiguration`). Attach a policy granting the necessary QoS-related actions.

Q: How do I handle large lists of requester QoS info?
A: Use `--parameters max-keys` to limit results per call and `--parameters continuation-token` from the previous response to paginate through all entries.