Skill: sdk-team/alibabacloud-cloudbackup-ecs-file-backup-essential-edition (version 0.0.2)

--- name: alibabacloud-cloudbackup-ecs-file-backup-essential-edition description: | Alibaba Cloud ECS File Backup Essential Edition (ECS文件备份基础版). One-click activation, daily automatic backup, 30-day file recovery, 100 GiB free quota. Trigger words: ECS file backup, HBR essential edition, Cloud Backup essential, file deletion recovery, free backup quota, ECS data protection, lightweight backup, affordable ECS backup Redirect words: ECS database backup, ECS full-machine backup, full-machine clone, cross-region backup, cross-account backup, KMS encrypted backup --- # ECS File Backup Essential Edition - Operations & Viewing ## Scenario Description ECS File Backup Essential Edition (ECS文件备份基础版) is a basic backup product launched by Alibaba Cloud's Cloud Backup service (HBR) for ECS file scenarios, featuring one-click activation and zero-configuration setup. ### Core Features | Feature | Description | |---------|-------------| | Automatic Backup (自动备份) | Daily automatic backup with 30-day retention | | File Recovery (文件恢复) | Files accidentally deleted within 30 days can be recovered; supports file-level restoration | | Free Quota (免费额度) | 100 GiB permanent free block storage backup quota per account (shared across all regions) | | Low Maintenance (低运维) | One-click activation, zero configuration required, backup client auto-installed | ### Recommended Use Cases When user requirements match the following conditions, recommend ECS File Backup Essential Edition: | Scenario | Description | |----------|-------------| | **ECS File Data Protection** | Need to protect/backup ECS file data and recover from accidental deletion | | **Accept Daily Backup Policy** | Accept once-daily backup with 30-day retention | | **Cost-Effective** | Affordable/free ECS data backup; 100 GiB permanent free quota per account (shared across all regions) | | **Personal Websites/Blogs** | Quick recovery from accidental deletion of images or config files | | **Dev/Test Environments** | Protection for code and configuration files | | **Small Business Applications** | Basic data protection needs with low maintenance cost | ### Not-Recommended Scenarios & Alternatives | Scenario | Reason | Alternative | |----------|--------|-------------| | **RDS or Self-Managed Database Backup** (数据库备份) | Database files are locked by the main process; backups may be inconsistent | For RDS, contact the RDS team; for MySQL/Oracle/SQL Server, use **Cloud Backup Database Backup** | | **Cannot Install Backup Client** (不接受安装备份客户端) | Backup client consumes ECS CPU and memory resources | Use **ECS Snapshots** (note: no file-level recovery) | | **ECS Spec < 1C512MB** | Specs too low, affecting backup performance | Use **ECS Snapshots**, or upgrade ECS specs first | | **Full-Machine Clone/DR Failover** (整机克隆/异地拉起) | Essential Edition does not support full-machine recovery | Use **ECS Snapshots** | | **Cross-Region/Cross-Account Backup** (跨地域/跨账号备份) | Essential Edition does not support cross-region or cross-account | Use **Cloud Backup ECS File Backup Standard Edition** (enterprise-grade) | | **KMS-Encrypted Backup Data** (KMS加密备份) | Essential Edition does not support KMS encryption | Use **Cloud Backup ECS File Backup Standard Edition** | | **Custom Backup Policy** (自定义备份策略) | Essential Edition is fixed at once-daily backup with 30-day retention | Use **Cloud Backup ECS File Backup Standard Edition** (customizable policy) | | **Data Volume > 2 TB** | Backup may not complete within 24 hours | Contact Cloud Backup technical support, or use Standard Edition | ### Usage Limitations | Limitation | Description | |------------|-------------| | Operating System | 32-bit operating systems not supported | | Network Type | Classic network (经典网络) ECS not supported | | Storage Type | Only block storage (块存储) supported; NAS/OSS and other network-mounted storage not supported | | Dependent Service | Requires Cloud Assistant (云助手) service (ECS purchased before Dec 2017 requires manual installation of Cloud Assistant Agent) | | ECS Spec | Recommended >= 1 vCPU, 512 MB memory for adequate backup performance | | Data Volume | Low priority: < 600 GB; High priority: < 2 TB | --- ## Scenario Eligibility Check (Mandatory First Step) > **CRITICAL - Hard Gate**: This is the **first step** before all operations, taking priority over installation checks, credential verification, and any workflow. > The agent **MUST** complete this check before executing any other step. **Decision Flow:** ``` User requests ECS backup/restore | +-> Check each item in "Not-Recommended Scenarios & Alternatives" | +-> Matches any not-recommended scenario -> Execute [HALT Flow] | +-> No match -> Pass, continue to "Installation Requirements" | +-> Not-recommended scenario keywords: - Database: MySQL/Oracle/SQL Server/PostgreSQL/MongoDB/Redis/database data directory - Full-machine: full-machine recovery/DR failover/clone instance - Cross-region/cross-account: remote backup/cross-account replication - Custom policy: hourly backup/custom retention period - Large data volume: data exceeds 2 TB ``` **[HALT Flow] - Must execute when a not-recommended scenario is matched:** 1. **Stop immediately** - Do NOT execute installation checks, credential verification, parameter confirmation, or any CLI command 2. **Output warning to user** - Explain why the current scenario is not suitable for ECS File Backup Essential Edition (cite the reason from "Not-Recommended Scenarios & Alternatives") 3. **Recommend alternatives** - Provide specific alternative products/features 4. **End current task** - After outputting the warning and alternatives, the agent **MUST stop** and **NOT continue with any subsequent steps of this Skill** > **Sole recovery condition**: Only when the user **proactively and explicitly** states "I understand the risks and still want to use ECS File Backup Essential Edition" (or semantically equivalent), may the agent continue. > The following are **NOT** valid confirmations (agent must remain stopped): no reply; vague confirmations ("OK", "Continue", "Help me backup") without mentioning "ECS File Backup Essential Edition"; topic changes; asking about alternatives. --- ## Installation Requirements (Mandatory Pre-check) > **CRITICAL**: The agent **MUST** complete the following pre-checks before executing any core workflow. ### Pre-check: Aliyun CLI >= 3.3.3 required > Run `aliyun version` to verify >= 3.3.3. If not installed or version too low, > run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to update, > or see [references/cli-installation-guide.md](references/cli-installation-guide.md) for installation instructions. ```bash aliyun version ``` Then [MUST] run `aliyun plugin update` to ensure that any existing plugins on your local machine are always up-to-date. **[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include: `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition` Enable automatic plugin installation: ```bash aliyun configure set --auto-plugin-install true ``` ### Pre-check: AI-Mode Configuration **[MUST] Enable AI-Mode** — Run before any CLI invocation: ```bash aliyun configure ai-mode enable aliyun configure ai-mode set-user-agent --user-agent [REDACTED_SECRET] ``` **[MUST] Disable AI-Mode at EVERY exit point** — Before delivering the final response for ANY reason (success, failure, error, cancellation), always disable AI-mode first. AI-mode MUST NOT remain enabled after the skill stops running. ```bash aliyun configure ai-mode disable ``` ### Pre-check: aliyun-cli-hbr plugin >= 0.1.3 required ```bash aliyun plugin list 2>/dev/null | grep aliyun-cli-hbr ``` If the plugin is not installed or the version is below 0.1.3, install/update: ```bash aliyun plugin install --names aliyun-cli-hbr ``` > After plugin installation, HBR commands and parameter names use kebab-case naming convention (e.g., `describe-backup-plans` instead of `DescribeBackupPlans`). --- ## Credential Verification > **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** print, echo, or output AK/SK values in any form (including partial fragments or masked forms) > - **NEVER** expose any credential content in command-line arguments, logs, conversation output, or code comments > - **NEVER** enter AK/SK directly in the command line > - **ONLY USE** `aliyun configure list` to check credential status; **NEVER echo the output of this command to the user** (output may contain credential-related information); the agent should only use the output internally to determine whether credentials are valid > > ```bash > aliyun configure list > ``` > > Confirm the output shows a valid profile (AK, STS, or OAuth identity). > > **If no valid credentials exist, configure first:** > 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) > 2. Run `aliyun configure` in the terminal to configure credentials > 3. Re-run `aliyun configure list` to confirm successful configuration --- ## Parameter Confirmation & Validation > **IMPORTANT: Parameter Confirmation** - Before executing any command, all customizable parameters must be confirmed with the user. > Do not assume default values; explicit user confirmation is required. > **If the user refuses to confirm or does not respond to the confirmation request, the agent MUST abort the current operation and NOT continue with subsequent steps.** > **CRITICAL - Security Gate**: Before embedding any parameter into a CLI command, the agent **MUST** validate all user-provided parameters against the validation regex in the table below. > On validation failure, the agent **MUST refuse to execute the command**, inform the user which parameter is invalid and what format is expected, and wait for the user to provide a valid value before re-validating. | Parameter | Required/Optional | Description | Validation Regex | Example | |-----------|-------------------|-------------|------------------|---------| | `REGION_ID` | Required | Region of the ECS instance (ECS实例所在地域) | `^[a-zA-Z0-9-]+$` | `cn-hangzhou` | | `INSTANCE_ID` | Required | ECS Instance ID (ECS实例ID) | `^[a-zA-Z0-9-]+$` | `i-bp1abc123def456` | | `PLAN_ID` | Required for some ops | Backup Plan ID (备份计划ID); needed for pause/resume/cancel | `^[a-zA-Z0-9-]+$` | `plan-abc123` | | `VAULT_ID` | Required for restore | Backup Vault ID (备份仓库ID); obtained via `search-historical-snapshots` | `^[a-zA-Z0-9-]+$` | `v-0001xjb123` | | `SNAPSHOT_ID` | Required for restore | Snapshot ID (备份版本ID); obtained via `search-historical-snapshots` | `^[a-zA-Z0-9-]+$` | `s-0001abc123` | | `SNAPSHOT_HASH` | Required for restore | Snapshot Hash (备份版本哈希值); obtained via `search-historical-snapshots` | `^[a-zA-Z0-9-]+$` | `sh-abc123` | | `performanceLevel` | Optional | Backup priority (备份优先级): `L0` (default, data < 600 GB) or `L1` (data 600 GB~2 TB) | `^(L0\|L1)$` | `L0` | | `ConflictPolicy` | Required for restore | File conflict policy (文件冲突策略): `SKIP_THE_FILE` (skip) or `OVERWRITE_EXISTING` (overwrite) | `^(SKIP_THE_FILE\|OVERWRITE_EXISTING)$` | `SKIP_THE_FILE` | | `CLIENT_TOKEN` | Required for restore | Idempotency token (幂等令牌); agent-generated UUID, reuse on timeout retry | `^[a-zA-Z0-9-]{1,64}$` | [REDACTED_SECRET] | | `keep-latest-snapshots` | Optional | Keep last backup version (保留最后一个备份版本): `1` (keep) or `0` (don't keep) | `^(0\|1)$` | `1` | | `SOURCE_PATH` | Optional for restore | Source file path to restore (要恢复的源文件路径) | `^[a-zA-Z0-9/_.-]+$` | `/home/data/file.txt` | | `TARGET_PATH` | Required for restore | Restore target directory (恢复目标目录); must already exist | `^[a-zA-Z0-9/_.-]+$` | `/tmp/restore` | ## RAM Permissions This Skill requires the permissions detailed in [references/ram-policies.md](references/ram-policies.md). Recommended system policy: `AliyunHBRFullAccess` --- ## Core Workflows > **CRITICAL**: Before executing any of the following workflows, the agent **MUST** complete all steps in "Scenario Eligibility Check" and "Installation Requirements (Mandatory Pre-check)". > If Aliyun CLI or the aliyun-cli-hbr plugin is not installed or does not meet version requirements, it **MUST be installed/updated first** before proceeding. > **Note**: All CLI operations below are idempotent and safe to retry. ### 1. Activate Backup Activate ECS File Backup Essential Edition for a specified ECS instance. **Step 1: Enable Cloud Backup Service (first-time use)** ```bash aliyun hbr open-hbr-service \ --endpoint hbr.aliyuncs.com \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` **Step 2: Activate ECS Instance Backup** ```bash aliyun hbr create-backup-plan \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --instance-id <INSTANCE_ID> \ --keep-latest-snapshots 1 \ --options '{"performanceLevel":"<LEVEL>"}' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > Idempotent operation; repeated calls for the same instance will not create duplicate backup plans. Safe to retry on timeout. **Step 3: Verify Activation Status** > Activation and client installation are asynchronous operations; they typically take a few minutes to become ready. Use the status determination logic from "5. View ECS Backup Status" to verify. Expected state progression: `Preparing` -> `Ready` -> `Backing Up` --- ### 2. Pause Backup (Suspend) Pause the backup plan (备份计划) while retaining existing backup data; can be resumed later. **Step 1: Get Backup Plan ID** ```bash aliyun hbr describe-backup-plans \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > Extract `PlanId` from the response. **Step 2: Pause Backup** ```bash aliyun hbr disable-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` --- ### 3. Resume Backup Resume a previously paused backup plan. ```bash aliyun hbr enable-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` --- ### 4. Cancel Backup (Delete) > **WARNING**: This operation will permanently delete all backup data and is irreversible! User intent must be confirmed before execution. > **If the user has not explicitly confirmed deletion, the agent MUST abort the operation and NOT continue.** **Step 1: Get Backup Plan ID** ```bash aliyun hbr describe-backup-plans \ --region <REGION_ID> \ --source-type ECS_FILE \ --edition BASIC \ --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` **Step 2: Delete Backup Plan** ```bash aliyun hbr delete-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > After cancellation, the instance stops incurring charges; deleted backup data cannot be recovered. Safe to call repeatedly on an already-deleted plan. --- ### 5. View ECS Backup Status **Step 1: Query Backup Plan** ```bash aliyun hbr describe-backup-plans \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` **Step 2: Query Latest Backup Job** ```bash aliyun hbr describe-backup-jobs-2 \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > `describe-backup-jobs-2` returns backup jobs sorted by creation time in descending order; the first record is the latest execution result. **Status Determination Logic** ``` describe-backup-plans finds no plan -> Not Activated (未激活) describe-backup-plans finds a plan +-> Disabled = true -> Paused (已暂停) +-> Query describe-backup-jobs-2 for latest backup job +-> No backup jobs -> Preparing (准备中) +-> Has backup jobs (first record = latest result) +-> COMPLETE/PARTIAL_COMPLETE -> Backup Normal (备份正常) +-> RUNNING/QUEUED/CREATED -> Backing Up (备份中) +-> CANCELED -> Canceled (已取消) +-> FAILED/EXPIRED -> Backup Abnormal (备份异常); troubleshoot via describe-backup-clients ``` **Auxiliary Query Commands** View backup client status: ```bash aliyun hbr describe-backup-clients \ --region <REGION_ID> \ --client-type ECS_CLIENT \ --instance-ids '["<INSTANCE_ID>"]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` View backup history (Snapshot list): ```bash aliyun hbr search-historical-snapshots \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --query '[{"field":"instanceId","value":"<INSTANCE_ID>","operation":"MATCH_TERM"}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` --- ### 6. View Free Quota & Capacity ```bash aliyun hbr get-basic-statistics \ --source-type ECS_FILE \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` **Key field**: `GlobalStatistics.ProtectedDataSize` is the total block storage capacity of backed-up ECS instances (in bytes). **Free quota rules**: 100 GiB per account (permanent, shared across all regions). Usage beyond the quota is billed on a pay-as-you-go basis; billing is based on the total block storage capacity mounted on backed-up ECS instances. --- ### 7. File Restore ```bash aliyun hbr create-restore-job \ --region <REGION_ID> \ --restore-type ECS_FILE \ --edition BASIC \ --source-type ECS_FILE \ --vault-id <VAULT_ID> \ --snapshot-id <SNAPSHOT_ID> \ --snapshot-hash <SNAPSHOT_HASH> \ --include '["<SOURCE_PATH>"]' \ --target-instance-id <INSTANCE_ID> \ --target-path <TARGET_PATH> \ --options '{"ConflictPolicy":"<CONFLICT_POLICY>"}' \ --client-token <UUID> \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > `VaultId`, `SnapshotId`, and `SnapshotHash` can be obtained via `search-historical-snapshots`. > Omitting `--include` restores all files in the snapshot. > `TargetPath` must be an existing directory on the target ECS instance; otherwise the restore job will report a `TARGET_NOT_EXIST` error. > Using the `OVERWRITE_EXISTING` policy will overwrite files with the same name at the target path; explicit user confirmation is required before execution. If the user has not confirmed, the agent MUST abort the restore operation. > Use `--client-token` to ensure idempotency; the agent should generate a UUID as the ClientToken and reuse the same token on timeout retries to prevent duplicate restore jobs. **View Restore Progress** ```bash aliyun hbr describe-restore-jobs-2 \ --region <REGION_ID> \ --edition BASIC \ --restore-type ECS_FILE \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` --- ### 8. Modify Scheduled Backup Time **Step 1: Get Backup Plan ID** ```bash aliyun hbr describe-backup-plans \ --region <REGION_ID> \ --edition BASIC \ --source-type ECS_FILE \ --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` **Step 2: Update Backup Schedule** ```bash aliyun hbr update-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --schedule 'I|<TIMESTAMP>|P1D' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > Schedule format: `I|<start_timestamp>|P1D`, where start_timestamp is a Unix timestamp in seconds, and `P1D` means once per day (fixed for Essential Edition). --- ### 9. Toggle Keep-Last-Snapshot When enabled, even if all backup versions exceed the retention period, the system will retain the last version without deleting it. ```bash aliyun hbr update-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --keep-latest-snapshots <0_OR_1> \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > `1` = keep the last backup version (recommended); `0` = do not keep; all backup points older than 30 days will be automatically deleted. --- ### 10. Adjust Backup Execution Priority ```bash aliyun hbr update-backup-plan \ --region <REGION_ID> \ --plan-id <PLAN_ID> \ --edition BASIC \ --options '{"performanceLevel":"<LEVEL>"}' \ --read-timeout 60 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition ``` > See `performanceLevel` in the Parameter Confirmation table for valid values; detailed use cases are described in [references/related-apis.md](references/related-apis.md). --- ## Verification See [references/verification-method.md](references/verification-method.md) for details. --- ## References | Document | Link | |----------|------| | CLI Installation Guide | [references/cli-installation-guide.md](references/cli-installation-guide.md) | | API & CLI Command Reference | [references/related-apis.md](references/related-apis.md) | | RAM Permission Policies | [references/ram-policies.md](references/ram-policies.md) | | Verification Methods | [references/verification-method.md](references/verification-method.md) | | Official User Guide | [ECS File Backup Essential Edition](https://help.aliyun.com/zh/cloud-backup/user-guide/ecs-file-backup-essential-edition) | | Cloud Backup API Docs | [HBR API Reference](https://help.aliyun.com/zh/cloud-backup/developer-reference/api-hbr-2017-09-08-overview) |

path: references/cli-installation-guide.md
content: # Aliyun CLI Installation Guide

Complete guide for installing Aliyun CLI.

> **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

## Installation

### macOS

**Using Homebrew (Recommended)**
```bash
brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version
```

**Using Binary**
```bash
# Download
wget --timeout=30 --connect-timeout=10 https://aliyuncli.alicdn.com/aliyun-cli-macosx-3.3.3-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-3.3.3-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version
```

### Linux

**Debian/Ubuntu**
```bash
# Download
wget --timeout=30 --connect-timeout=10 https://aliyuncli.alicdn.com/aliyun-cli-linux-3.3.3-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-3.3.3-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version
```

**ARM64 Architecture**
```bash
# Download ARM64 version
wget --timeout=30 --connect-timeout=10 https://aliyuncli.alicdn.com/aliyun-cli-linux-3.3.3-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-3.3.3-arm64.tgz
sudo mv aliyun /usr/local/bin/
```

### Windows

**Using Binary**
1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-3.3.3-amd64.zip
2. Extract the ZIP file
3. Add the directory to your PATH environment variable
4. Open new Command Prompt or PowerShell
5. Verify: `aliyun version`

## Configuration

Aliyun CLI relies on the default credential chain for authentication. Run `aliyun configure` interactively to set up credentials:

```bash
aliyun configure
```

The default credential chain resolves credentials in the following order:
1. Environment variables (automatically detected by the CLI)
2. Configuration file (`~/.aliyun/config.json`)
3. Instance metadata (ECS instance role, available when running on ECS)

> **Security**: Do not pass access keys explicitly via command-line arguments or hardcode them in scripts. Always rely on the default credential chain.

**Where to Get Credentials**

1. Log in to Aliyun Console: https://ram.console.aliyun.com/
2. Navigate to: AccessKey Management
3. Create a new AccessKey pair
4. Save the secret immediately — it's only shown once

## Verification

```bash
# Basic test - list regions
aliyun ecs describe-regions

# Show current configuration
aliyun configure get
```

## References

- Official Documentation: https://help.aliyun.com/zh/cli/
- RAM Console: https://ram.console.aliyun.com/
- Access Key Management: https://ram.console.aliyun.com/manage/ak


path: references/ram-policies.md
content: # RAM Permission Policies - ECS File Backup Essential Edition

## Required Permissions

### Least-Privilege Policy

The following is the minimum set of RAM permissions required to use ECS File Backup Essential Edition CLI commands:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "hbr:OpenHbrService",
        "hbr:CreateBackupPlan",
        "hbr:DescribeBackupPlans",
        "hbr:DisableBackupPlan",
        "hbr:EnableBackupPlan",
        "hbr:DeleteBackupPlan",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeBackupClients",
        "hbr:SearchHistoricalSnapshots",
        "hbr:GetBasicStatistics",
        "hbr:CreateRestoreJob",
        "hbr:DescribeRestoreJobs2"
      ],
      "Resource": "*"
    }
  ]
}
```

### Permission Descriptions

| API Action | Description | Operation Type |
|------------|-------------|----------------|
| `hbr:OpenHbrService` | Enable Cloud Backup service (开通云备份服务, one-time operation) | Service Activation |
| `hbr:CreateBackupPlan` | Create a backup plan; activate ECS instance backup (创建备份计划) | Write |
| `hbr:DescribeBackupPlans` | Query backup plan list and status (查询备份计划列表和状态) | Read-only |
| `hbr:DisableBackupPlan` | Pause a backup plan (暂停备份计划) | Write |
| `hbr:EnableBackupPlan` | Resume a paused backup plan (恢复已暂停的备份计划) | Write |
| `hbr:DeleteBackupPlan` | Delete a backup plan / cancel backup (删除备份计划) | Write |
| `hbr:DescribeBackupJobs2` | Query backup job execution status (查询备份任务执行状态) | Read-only |
| `hbr:DescribeBackupClients` | Query backup client status (查询备份客户端状态) | Read-only |
| `hbr:SearchHistoricalSnapshots` | Search historical backup snapshots (搜索历史备份版本) | Read-only |
| `hbr:GetBasicStatistics` | Get capacity statistics (获取容量统计信息) | Read-only |
| `hbr:CreateRestoreJob` | Create a file restore job (创建文件恢复任务) | Write |
| `hbr:DescribeRestoreJobs2` | Query restore job status (查询恢复任务状态) | Read-only |

### Read-Only Policy

If you only need to view backup status and capacity information:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "hbr:DescribeBackupPlans",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeBackupClients",
        "hbr:SearchHistoricalSnapshots",
        "hbr:GetBasicStatistics",
        "hbr:DescribeRestoreJobs2"
      ],
      "Resource": "*"
    }
  ]
}
```

### Service-Linked Role

When ECS File Backup Essential Edition is activated for the first time, the system automatically creates a service-linked role:

- **Role Name**: `AliyunServiceRoleForHbrEcsBackup`
- **Purpose**: Cloud Backup service uses this role to install backup clients and perform backup operations
- **Creation Method**: Automatically created; no manual configuration required

> **Note**: If the account lacks permission to create service-linked roles, backup activation may fail. Ensure the account has the `ram:CreateServiceLinkedRole` permission.

### Recommended System Policies

Alibaba Cloud provides the following system policies for direct use:

| Policy Name | Description |
|-------------|-------------|
| `AliyunHBRFullAccess` | Full access to Cloud Backup |
| `AliyunHBRReadOnlyAccess` | Read-only access to Cloud Backup |

## References

- [Cloud Backup RAM Permission Reference](https://help.aliyun.com/zh/cloud-backup/developer-reference/authorization-rules)
- [RAM Access Control Console](https://ram.console.aliyun.com/)


path: references/related-apis.md
content: # Related APIs - ECS File Backup Essential Edition

## API & CLI Command Reference

| Product | CLI Command | API Action | Description | CLI Supported |
|---------|-------------|------------|-------------|---------------|
| HBR | `aliyun hbr open-hbr-service` | OpenHbrService | Enable Cloud Backup service (开通云备份服务) | Yes |
| HBR | `aliyun hbr create-backup-plan` | CreateBackupPlan | Create/activate a backup plan (创建/激活备份计划) | Yes |
| HBR | `aliyun hbr describe-backup-plans` | DescribeBackupPlans | Query backup plan list (查询备份计划列表) | Yes |
| HBR | `aliyun hbr disable-backup-plan` | DisableBackupPlan | Pause a backup plan (暂停备份计划) | Yes |
| HBR | `aliyun hbr enable-backup-plan` | EnableBackupPlan | Resume a backup plan (恢复备份计划) | Yes |
| HBR | `aliyun hbr delete-backup-plan` | DeleteBackupPlan | Delete/cancel a backup plan (删除/取消备份计划) | Yes |
| HBR | `aliyun hbr update-backup-plan` | UpdateBackupPlan | Update a backup plan (schedule/priority, etc.) (更新备份计划) | Yes |
| HBR | `aliyun hbr describe-backup-jobs-2` | DescribeBackupJobs2 | Query backup job list (查询备份任务列表) | Yes |
| HBR | `aliyun hbr describe-backup-clients` | DescribeBackupClients | Query backup client status (查询备份客户端状态) | Yes |
| HBR | `aliyun hbr search-historical-snapshots` | SearchHistoricalSnapshots | Search historical backup snapshots (搜索历史备份版本) | Yes |
| HBR | `aliyun hbr get-basic-statistics` | GetBasicStatistics | Get basic statistics including capacity (获取基础统计信息) | Yes |
| HBR | `aliyun hbr create-restore-job` | CreateRestoreJob | Create a restore job (创建恢复任务) | Yes |
| HBR | `aliyun hbr describe-restore-jobs-2` | DescribeRestoreJobs2 | Query restore job status (查询恢复任务状态) | Yes |

## API Version Information

| Product | API Version | Endpoint |
|---------|-------------|----------|
| HBR (Cloud Backup, 云备份) | 2017-09-08 | hbr.{region}.aliyuncs.com |

## Key Parameter Descriptions

### edition

- `BASIC` - Essential Edition (基础版, for ECS File Backup Essential Edition)

### source-type

- `ECS_FILE` - ECS file backup (ECS文件备份)

### performanceLevel (Backup Priority, 备份优先级)

| Value | Meaning | Max Throughput | Recommended Data Volume |
|-------|---------|----------------|-------------------------|
| `L0` | Low priority (低优先级) | 10 MB/s, 1 vCPU | < 600 GB |
| `L1` | High priority (高优先级) | 30 MB/s, 2 vCPU | < 2 TB |

### Backup Plan Status (备份计划状态)

| Status | Description |
|--------|-------------|
| `ENABLED` | Enabled (已启用) |
| `DISABLED` | Paused (已暂停) |

### Client Status (客户端状态)

| Status | Description |
|--------|-------------|
| Preparing (准备中) | Client is being installed |
| Ready (就绪) | Client is ready |
| Backing Up (备份中) | Backup is in progress |

## Console-Only Operations (Not Available via CLI)

The following features are currently **not available via CLI** and require console access:

| Feature | Description | Console Path |
|---------|-------------|--------------|
| Backup Overview Dashboard | Visual display of backed-up ECS instances, block storage capacity, etc. | Cloud Backup Console > ECS File Backup Essential Edition |
| Browse File Directory | Browse the directory structure of backed-up files online | Backup Plan Details > Browse Files |
| Selective Single-File Restore | Select specific files to restore through the UI | Backup Plan Details > Restore Files |
| Modify Backup Time Window | Change the daily backup start time | Backup Plan Details > Edit |

## References

- [Cloud Backup API Documentation](https://help.aliyun.com/zh/cloud-backup/developer-reference/api-hbr-2017-09-08-overview)
- [ECS File Backup Essential Edition User Guide](https://help.aliyun.com/zh/cloud-backup/user-guide/ecs-file-backup-essential-edition)


path: references/verification-method.md
content: # Verification Methods - ECS File Backup Essential Edition

This document describes how to verify that each operation has been executed successfully.

## 1. Activate Backup Verification

### Verification Steps

**Step 1: Confirm the backup plan has been created**
```bash
aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The `BackupPlans` array contains a backup plan for the corresponding instance
- `BusinessStatus` is `ACTIVE`

**Step 2: Confirm backup job status**
```bash
aliyun hbr describe-backup-jobs-2 \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The first record returned is the latest backup job (sorted by creation time in descending order)
- `Status` is `COMPLETE` or `PARTIAL_COMPLETE`, indicating a successful backup

### Success Criteria
- Backup plan `BusinessStatus` is `ACTIVE`
- Latest backup job `Status` is `COMPLETE` or `PARTIAL_COMPLETE`

---

## 2. Pause Backup Verification

### Verification Steps

```bash
aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"planId","Values":["<PLAN_ID>"]}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The `Disabled` field is `true`

### Success Criteria
- Backup plan `Disabled` is `true`
- No new backup jobs are generated

---

## 3. Resume Backup Verification

### Verification Steps

```bash
aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"planId","Values":["<PLAN_ID>"]}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The `Disabled` field is `false`

### Success Criteria
- Backup plan `Disabled` is `false`
- The next backup window will execute a backup job

---

## 4. Cancel Backup Verification

### Verification Steps

```bash
# Check whether the backup plan has been deleted
aliyun hbr describe-backup-plans \
  --region <REGION_ID> \
  --edition BASIC \
  --source-type ECS_FILE \
  --filters '[{"Key":"instanceId","Values":["<INSTANCE_ID>"]}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The `BackupPlans` array is empty
- Or it does not contain a backup plan for the specified instance

### Success Criteria
- No backup plan found for the corresponding instance
- The instance is no longer billed

---

## 5. Free Quota Viewing Verification

### Verification Steps

```bash
aliyun hbr get-basic-statistics \
  --edition BASIC \
  --source-type ECS_FILE \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- Returns a `GlobalStatistics` object
- Contains the `ProtectedDataSize` field (unit: bytes)

### Key Metric Interpretation

| Metric | Description |
|--------|-------------|
| `ProtectedDataSize` | Total block storage capacity of backed-up ECS instances (bytes) |
| Free Quota (免费额度) | 100 GiB/account (permanent, shared across all regions) = 107,374,182,400 bytes |

**Calculation Example**:
```
ProtectedDataSize = 53,687,091,200 bytes = 50 GiB
Remaining Free Quota = 100 GiB - 50 GiB = 50 GiB
```

### Success Criteria
- The `ProtectedDataSize` value is retrieved successfully
- The value matches the console display

---

## 6. File Restore Verification

### Verification Steps

**Step 1: Query status after creating a restore job**
```bash
aliyun hbr describe-restore-jobs-2 \
  --region <REGION_ID> \
  --edition BASIC \
  --restore-type ECS_FILE \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```

**Expected Result**:
- The newly created restore job can be found
- The `Status` field shows the job status

### Restore Job Status Descriptions

| Status | Description |
|--------|-------------|
| `CREATED` | Job has been created (任务已创建) |
| `RUNNING` | Restore in progress (正在恢复) |
| `COMPLETE` | Restore completed (恢复完成) |
| `FAILED` | Restore failed (恢复失败) |
| `CANCELED` | Canceled (已取消) |

### Success Criteria
- Restore job status is `COMPLETE`
- Restored files are visible on the target ECS instance

---

## General Troubleshooting

### Common Errors and Solutions

| Error Message | Possible Cause | Solution |
|---------------|----------------|----------|
| `InvalidInstanceId` | ECS instance ID does not exist | Verify the instance ID is correct |
| `Forbidden.RAM` | Insufficient permissions | Check RAM policy configuration |
| `ServiceNotActivated` | Service not enabled | Run `open-hbr-service` first |
| `ClientNotInstalled` | Cloud Assistant (云助手) not installed | Install Cloud Assistant Agent on the ECS instance |

### Debug Command

```bash
# Enable verbose logging
aliyun hbr describe-backup-plans \
  --region cn-hangzhou \
  --edition BASIC \
  --source-type ECS_FILE \
  --log-level=debug \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)