Alibabacloud Ecs Linux Os Troubleshooting

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, all other steps may only use the subcommands listed in 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 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-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-linux-os-troubleshooting/<session-id>

Troubleshooting Workflow

Execute the phases in order.

Phase 1: Clarify the Abnormal Issue

First, call DescribeInstances to query the instance information:

• Success: record the instance metadata, such as region, image, and status, then continue with the normal workflow below.
• Failure (an error or an empty result is returned): ask the user "Has this instance been released?"
  • The user confirms it is released: enter degraded mode, see references/degraded-mode.md.
  • The user denies it but confirms the instance ID is correct: also enter degraded mode.

Before opening any domain document, if the user's issue description is vague, first refine the issue through multi-turn dialogue. Use the aliyun CLI and questions to the user to complete the evidence and related environment information for when the abnormal issue occurred. This usually includes the following information:

Note: the instance status and the GuestOS status may be inconsistent. Even if the instance status is Running, the GuestOS kernel may have failed to start. This phase only completes the environment information; do not make any root cause judgment or output any conclusion.

Phase 2: Classify into a Phenomenon Domain

1. Open references/symptom-to-domain.md, and select the phenomenon domain category and phenomenon domain based on the clarified abnormal issue description.
2. Output one phenomenon domain and record the corresponding troubleshooting document path references/<slug>.md. At the same time, ask the user to confirm whether the phenomenon domain is accurate. Enter Phase 3 only after it is confirmed as accurate. If the user says it is inaccurate, exclude the phenomenon domain selected in step 2 and show the TOP 3 secondary phenomenon domains to the user for confirmation. If the user says none of the secondary phenomenon domains applies, stop all subsequent workflows and recommend that the user submit an Alibaba Cloud support ticket.