# oss-network

Part of **OSS**

# Object Storage Service Network Security CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| `ossutil api get-user-antid-dos-info` | Query Anti-DDoS instances for your account | `ossutil api get-user-antid-dos-info [flags]` |
| `ossutil api init-user-antid-dos-info` | Create an Anti-DDoS instance | `ossutil api init-user-antid-dos-info` |
| `ossutil api init-bucket-antid-dos-info` | Initialize Anti-DDoS protection for a bucket | `ossutil api init-bucket-antid-dos-info [flags]` |
| `ossutil api list-bucket-antid-dos-info` | List Anti-DDoS protections applied to buckets | `ossutil api list-bucket-antid-dos-info [flags]` |
| `ossutil api update-bucket-antid-dos-info` | Update Anti-DDoS configuration for a bucket | `ossutil api update-bucket-antid-dos-info [flags]` |
| `ossutil api update-user-antid-dos-info` | Change the status of an Anti-DDoS instance | `ossutil api update-user-antid-dos-info [flags]` |
| `ossutil api put-bucket-https-config` | Configure TLS versions for secure bucket connections | `ossutil api put-bucket-https-config [flags]` |
| `ossutil probe` | Test network connectivity, upload/download speed, and symbolic links | `ossutil probe [flags] [file_name]` |

## Command Details

### get-user-antid-dos-info

**Purpose**: Queries all Anti-DDoS instances associated with your Alibaba Cloud account.

**Syntax**:
```bash
ossutil api get-user-antid-dos-info [--output-format <format>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--output-format` | — | string | No | Specifies output format. Valid values: `json`, `yaml` |

```bash
# Query Anti-DDoS instances in default format
ossutil api get-user-antid-dos-info

# Output results in JSON format
ossutil api get-user-antid-dos-info --output-format json

# Output results in YAML format
ossutil api get-user-antid-dos-info --output-format yaml
```

**Example Output**:
```text
{"Instances":[{"InstanceId":"ddos-12345","Status":"Active","Region":"cn-hangzhou"}]}
```

### init-user-antid-dos-info

**Purpose**: Creates a new Anti-DDoS instance for your account.

**Syntax**:
```bash
ossutil api init-user-antid-dos-info
```

**Parameters**:  
None

```bash
# Create a new Anti-DDoS instance
ossutil api init-user-antid-dos-info
```

### init-bucket-antid-dos-info

**Purpose**: Initializes Anti-DDoS protection for a specific bucket, optionally configuring custom domains.

**Syntax**:
```bash
ossutil api init-bucket-antid-dos-info --bucket <name> --defender-instance <id> --defender-type <type> --bucket-antiddos-configuration <config>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Name of the OSS bucket |
| `--defender-instance` | — | string | Yes | ID of the Anti-DDoS instance |
| `--defender-type` | — | string | Yes | Type of Anti-DDoS instance (e.g., `AntiDDosPremimum`) |
| `--bucket-antiddos-configuration` | — | string | Yes | Configuration in JSON/XML format or path prefixed with `file://` |

```bash
# Initialize using XML config file
ossutil api init-bucket-antid-dos-info --bucket examplebucket --defender-instance 123 --defender-type AntiDDosPremimum --bucket-antiddos-configuration file://bucket-antiddos-configuration.xml

# Initialize using JSON config file
ossutil api init-bucket-antid-dos-info --bucket examplebucket --defender-instance 123 --defender-type AntiDDosPremimum --bucket-antiddos-configuration file://bucket-antiddos-configuration.json

# Initialize using inline JSON
ossutil api init-bucket-antid-dos-info --bucket examplebucket --defender-instance 123 --defender-type AntiDDosPremimum --bucket-antiddos-configuration "{\"Cnames\":{\"Domains\":[\"abc1.example.cn\",\"abc2.example.cn\"]}}"
```

### list-bucket-antid-dos-info

**Purpose**: Lists Anti-DDoS protections applied to buckets, supporting pagination.

**Syntax**:
```bash
ossutil api list-bucket-antid-dos-info [--marker <value>] [--max-keys <number>] [--output-format <format>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--marker` | — | string | No | Start listing after this instance name (alphabetical) |
| `--max-keys` | — | string | No | Maximum number of instances to return |
| `--output-format` | — | string | No | Output format: `json` or `yaml` |

```bash
# List all bucket Anti-DDoS protections
ossutil api list-bucket-antid-dos-info

# Output in JSON
ossutil api list-bucket-antid-dos-info --output-format json

# List up to 10 entries starting after 'marker'
ossutil api list-bucket-antid-dos-info --marker marker --max-keys 10
```

### update-bucket-antid-dos-info

**Purpose**: Updates the status and configuration of Anti-DDoS protection for a bucket.

**Syntax**:
```bash
ossutil api update-bucket-antid-dos-info --bucket <name> --defender-instance <id> --defender-status <status> --bucket-antiddos-configuration <config>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Bucket name |
| `--defender-instance` | — | string | Yes | Anti-DDoS instance ID |
| `--defender-status` | — | string | Yes | New status (e.g., `Init`) |
| `--bucket-antiddos-configuration` | — | string | Yes | Configuration in JSON/XML or `file://` path |

```bash
# Update using XML config
ossutil api update-bucket-antid-dos-info --bucket examplebucket --defender-instance 123 --defender-status Init --bucket-antiddos-configuration file://bucket-antiddos-configuration.xml

# Update using inline JSON
ossutil api update-bucket-antiddos-info --bucket examplebucket --defender-instance 123 --defender-status Init --bucket-antiddos-configuration "{\"Cnames\":{\"Domains\":[\"abc1.example.cn\",\"abc2.example.cn\"]}}"
```

### update-user-antid-dos-info

**Purpose**: Changes the operational status of an Anti-DDoS instance (e.g., halt or start defense).

**Syntax**:
```bash
ossutil api update-user-antid-dos-info --defender-instance <id> --defender-status <status>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--defender-instance` | — | string | Yes | ID of the Anti-DDoS instance |
| `--defender-status` | — | string | Yes | New status (e.g., `HaltDefending`, `StartDefending`) |

```bash
# Halt DDoS defense for instance 123
ossutil api update-user-antid-dos-info --defender-instance 123 --defender-status HaltDefending
```

### put-bucket-https-config

**Purpose**: Configures TLS version settings for secure HTTPS connections to a bucket.

**Syntax**:
```bash
ossutil api put-bucket-https-config --bucket <name> --https-configuration <config>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Bucket name |
| `--https-configuration` | — | string | Yes | TLS config in JSON/XML or `file://` path |

```bash
# Configure using XML file
ossutil api put-bucket-https-config --bucket examplebucket --https-configuration file://https-configuration.xml

# Configure using inline JSON to enable TLS 1.2 and 1.3
ossutil api put-bucket-https-config --bucket examplebucket --https-configuration "{\"TLS\":{\"Enable\":\"true\",\"TLSVersion\":[\"TLSv1.2\",\"TLSv1.3\"]}}"
```

### probe

**Purpose**: Tests network connectivity, upload/download bandwidth, latency, and symbolic link integrity between your system and OSS.

**Syntax**:
```bash
ossutil probe [--upload | --download | --probe-item <item>] [options] [file_name]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--upload` | — | boolean | Yes (mutually exclusive with `--download`/`--probe-item`) | Test by uploading a file |
| `--download` | — | boolean | Yes (mutually exclusive with others) | Test by downloading from URL |
| `--probe-item` | — | string | Yes (mutually exclusive) | Test item: `cycle-symlink`, `upload-speed`, `download-speed`, `download-time` |
| `file_name` | — | string | Conditional | Local file path (for upload) or download destination |
| `--bucket` | — | string | Conditional | Bucket name (required unless `--probe-item=cycle-symlink`) |
| `--object` | — | string | Conditional | Object path (required for `download-speed`) |
| `--url` | — | string | Yes (with `--download`) | Public or signed object URL |
| `--addr` | — | string | No | Address to ping (default: `www.aliyun.com`) |
| `--upmode` | — | string | No | Upload mode: `normal` (default), `append`, `multipart` |
| `--parallel` | — | integer | No | Concurrent tasks (only for `download-time`) |
| `--part-size` | — | integer | No | Part size in bytes (only for `download-time`) |
| `--runtime` | — | integer | No | Max execution time in seconds (for speed tests) |

```bash
# Test upload connectivity to bucket
ossutil probe --upload --bucket examplebucket --addr aliyun.com

# Upload a specific file and keep it as an object
ossutil probe --upload example.txt --bucket examplebucket --object example.txt

# Download from public URL
ossutil probe --download --url https://examplebucket.oss-cn-beijing.aliyuncs.com/example.txt /local/test.txt

# Check for cyclic symbolic links in a directory
ossutil probe --probe-item cycle-symlink /root/localfolder

# Measure upload speed
ossutil probe --probe-item upload-speed --bucket examplebucket

# Measure download speed with 2-second timeout
ossutil probe --probe-item download-speed --bucket examplebucket --object largefile.zip --runtime 2

# Benchmark download time with parallel tasks
ossutil probe --probe-item download-time --bucket examplebucket --object largefile.zip --parallel 3
```

**Example Output**:
```text
begin parse parameters and prepare file...[✓]
begin network detection...[✓]
begin upload file(normal)...[✓]

*************************  upload result  *************************
upload file:success
upload file size:122880(byte)
upload time consuming:245(ms)
(only the time consumed by probe command)

************************* report log info*************************
report log file:/root/logOssProbe20201201173031.log
```

## Common Scenarios

### Scenario 1: Enable and Verify Anti-DDoS Protection for a Bucket

```bash
# Step 1: Create an Anti-DDoS instance
ossutil api init-user-antid-dos-info

# Step 2: Query your instances to get the InstanceId
ossutil api get-user-antid-dos-info --output-format json

# Step 3: Initialize protection for your bucket with custom domains
ossutil api init-bucket-antid-dos-info --bucket my-secure-bucket --defender-instance ddos-98765 --defender-type AntiDDosPremimum --bucket-antiddos-configuration "{\"Cnames\":{\"Domains\":[\"cdn.myapp.com\"]}}"

# Step 4: Verify the configuration
ossutil api list-bucket-antid-dos-info --output-format json
```

### Scenario 2: Secure Bucket with TLS 1.2+ and Test Connectivity

```bash
# Step 1: Enforce TLS 1.2 and 1.3 for the bucket
ossutil api put-bucket-https-config --bucket secure-bucket --https-configuration "{\"TLS\":{\"Enable\":\"true\",\"TLSVersion\":[\"TLSv1.2\",\"TLSv1.3\"]}}"

# Step 2: Test upload bandwidth to the bucket
ossutil probe --probe-item upload-speed --bucket secure-bucket

# Step 3: Test download performance from the bucket
ossutil probe --probe-item download-speed --bucket secure-bucket --object sample-data.bin
```

## Environment Setup

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

### Configuration
Configure credentials using one of the following methods:
- Run `ossutil config` to create a configuration file (`~/.ossutilconfig`)
- Set environment variables: `OSS_ACCESS_KEY_ID` and `OSS_ACCESS_KEY_SECRET`
- Use RAM user credentials with required permissions (e.g., `oss:GetUserAntiDDosInfo`, `oss:PutBucketHttpsConfig`)

Configure the default region and endpoint in the config file or via flags like `--region`.

## FAQ

Q: How do I configure credentials for these CLI commands?
A: Use `ossutil config` to set up AccessKey ID and Secret, or set `OSS_ACCESS_KEY_ID` and `OSS_ACCESS_KEY_SECRET` environment variables. Ensure your credentials have the necessary OSS permissions for each operation.

Q: What permissions are required to manage Anti-DDoS instances?
A: You need specific RAM permissions such as `oss:GetUserAntiDDosInfo`, `oss:InitUserAntiDDosInfo`, `oss:InitBucketAntiDDosInfo`, `oss:UpdateBucketAntiDDosInfo`, and `oss:UpdateUserAntiDDosInfo`. Assign these via RAM policies.

Q: Why does the `probe` command fail with a 403 error?
A: The 403 error indicates missing permissions. For upload tests, ensure `oss:PutObject` and `oss:DeleteObject`; for download tests, ensure `oss:GetObject`. Also verify the bucket and object exist and are accessible.

Q: Can I use the `probe` command without authentication?
A: Partially. The `--addr` ping test works without auth. However, upload/download tests require valid OSS credentials with appropriate permissions on the target bucket and objects.

Q: How do I verify that TLS configuration was applied successfully?
A: While the `put-bucket-https-config` command returns no output on success, you can validate by attempting HTTPS connections using only allowed TLS versions. Additionally, monitor access logs or use external TLS testing tools against your bucket endpoint.