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

Recommended Use Cases

When user requirements match the following conditions, recommend ECS File Backup Essential Edition:

Not-Recommended Scenarios & Alternatives

Usage Limitations

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 for installation instructions.

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:

aliyun configure set --auto-plugin-install true

Pre-check: AI-Mode Configuration

[MUST] Enable AI-Mode — Run before any CLI invocation:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cloudbackup-ecs-file-backup-essential-edition"

[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.

aliyun configure ai-mode disable

Pre-check: aliyun-cli-hbr plugin >= 0.1.3 required

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:

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

> 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.

RAM Permissions

This Skill requires the permissions detailed in 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)

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

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

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

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.

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

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

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

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

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:

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):

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

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

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

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

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

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||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.

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

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.

Verification

See references/verification-method.md for details.

References