/alibabacloud-ecs-linux-os-troubleshooting

name: alibabacloud-ecs-linux-os-troubleshooting
description: >
    Troubleshoot an Alibaba Cloud ECS Linux OS. Use when a user needs to diagnose a specified ECS Linux instance, such as instance stuck in Starting, boot stuck, SSH/VNC/Workbench login failure, network issues, disk/FS issues, performance anomalies, suspected mining or hidden processes, crash/hang, clock drift, or configuration not taking effect.
metadata:
  author: alibabacloud
  version: "1.0"

ECS Linux Troubleshooting

This skill applies **only to Linux GuestOS on Alibaba Cloud ECS** and diagnoses abnormal issues on the Alibaba Cloud ECS Linux instance specified by the user (the target instance). The agent may run on the target instance or another machine, and uses the aliyun CLI to remotely diagnose and collect data from the target ECS instance.

When to Use This Skill

• The troubleshooting target specified by the user is an Alibaba Cloud ECS Linux instance.
• The user's description involves abnormal issues such as mismatches between startup/running status and OS state, remote login failures, network connectivity failures, disk expansion/mount issues, performance anomalies, crashes or hangs, clock drift, or configurations not taking effect.
• **Not applicable**: non-Alibaba Cloud ECS, non-Linux GuestOS, other clouds or physical machines; purely control-plane, billing, or API-side issues with no GuestOS involvement.

Principles and Requirements

1. **Troubleshooting target = the Alibaba Cloud ECS Linux instance specified by the user**: all checks and conclusions must target that one machine. Commands and paths in `references/` are written for the in-instance environment. 2. **Use the aliyun CLI for remote diagnosis and data collection**: except for the steps in [`references/utils/guestos-pe-prep.md`](references/utils/guestos-pe-prep.md), all other steps may only use the subcommands listed in [`references/aliyun-cli-cheatsheet.md`](references/aliyun-cli-cheatsheet.md). **Do not call subcommands that are not listed there**. 3. **Clarify the problem before investigating**: strictly follow the **troubleshooting workflow**. First narrow the user's description to a **phenomenon domain**, then follow the corresponding **troubleshooting document**. **Do not skip phases or reorder them**, and **do not draw a conclusion or stop the workflow early when the evidence does not uniquely point to a single root cause**. 4. Prefer the commands described in the `references/<slug>.md` troubleshooting document. **Do not blindly guess commands on your own**. 5. **External reference material**: when a troubleshooting document contains a URL, such as an Alibaba Cloud help page, **you must fetch the content of that link and use it as the basis for the investigation**. Do not judge based only on the link title or on prior knowledge. 6. **Multiple-instance scenarios**: troubleshoot each ECS instance separately. Do not use results from instance A to draw conclusions about instance B. 7. **Least-privilege permissions**: before running this skill, ensure the caller has only the required RAM actions for the selected workflow. Use [`references/ram-policies.md`](references/ram-policies.md) as the permission source of truth.

Progress Checklist

Before starting the troubleshooting workflow, create the following 6 phase tasks with the progress checklist tool. After completing each phase, **immediately** mark the corresponding task as complete before moving to the next phase:

1. [ ] Phase 1: Clarify the abnormal issue 2. [ ] Phase 2: Classify into a phenomenon domain 3. [ ] Phase 3: Confirm whether it is a GuestOS issue 4. [ ] Phase 4: Diagnostic tool investigation 5. [ ] Phase 5: GuestOS-internal component investigation 6. [ ] Phase 6: Summary and recommendations

Input Validation and Execution Safety

Validate all user-provided and model-derived values before placing them in an aliyun CLI command because invalid identifiers or shell metacharacters can target the wrong resource or change command meaning.

• Business region (`--biz-region-id`): allow only Alibaba Cloud region identifiers such as `cn-hangzhou`; use `^[a-z]+-[a-z]+-[a-z0-9]+$` as the baseline pattern.
• ECS instance IDs, disk IDs, image IDs, security group IDs, ENI IDs, diagnostic report IDs, and invoke IDs: require the expected product prefix and reject whitespace, quotes, shell metacharacters, command substitution, or newlines.
• JSON parameters such as `InstanceIds` and `AdditionalOptions`: build them with a JSON serializer or a quoted literal verified as valid JSON; do not concatenate untrusted fragments.
• Time windows: accept only ISO 8601 timestamps and ensure `StartTime <= EndTime`.
• Passwords and key-pair names in offline rollback: treat them as sensitive inputs, never echo them in the final report, and pass them only after explicit user confirmation.
• If any value cannot be validated, stop that command path and ask the user for a corrected value.

Use bounded waits for all polling operations because cloud operations may stay pending or fail silently. Default policy: poll every 10 to 20 seconds, stop after 10 minutes or 30 attempts, and then report the last observed status and the next safe action. A referenced document may define a shorter timeout for a specific operation.

Observability

Every aliyun CLI command must include the following user-agent parameter:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-linux-os-troubleshooting/{session-id}

Requirements:

1. Generate or obtain one non-empty `session-id` for each troubleshooting session. 2. Reuse the same `session-id` for all aliyun CLI commands within the same troubleshooting session. 3. Do not reuse a `session-id` across different troubleshooting sessions. 4. Include the parameter in every example and every actual aliyun CLI command execution.

Example:

aliyun ecs describe-instances \
  --biz-region-id <region-id> \
  --instance-ids '["<instance-id>"]' \
  --user-agen