SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsecs-linux-troubleshooting

ecs-linux-troubleshooting

Deployment & operations

View repository

Updated 10-16 04:59

About this skill

ECS Linux Troubleshooting

This skillapplies only to Linux GuestOS on Alibaba Cloud ECS, and performs troubleshooting of abnormal issues for a user-specified Alibaba Cloud ECS Linux instance (target machine). The Agent runs on the target machine or another machine, and uses the aliyun CLI tool to perform remote diagnosis and data collection on the target ECS instance.

When to Use This Skill

  • When the troubleshooting target specified by the user is an Alibaba Cloud ECS Linux instance.
  • When the user describes abnormal issues involving boot/running status inconsistent with the OS, remote login failure, network unreachability, disk/resizing/mounting, performance anomalies, crashes or hangs, clock, configuration not taking effect, etc.
  • Not applicable: Non-Alibaba Cloud ECS, non-Linux GuestOS, other clouds or physical machines; pure management/billing/API-side issues with no GuestOS involvement

Principles and Requirements

  1. Troubleshooting target = the user-specified Alibaba Cloud ECS Linux instance: all checks and conclusions are for this one machine.references/ , commands, paths, etc. are written according to the in-instance environment.
  2. Use the aliyun CLI tool for remote diagnosis and data collection.: requiring that, except for the steps in references/utils/guestos-pe-prep.md , other steps may only usereferences/aliyun-cli-cheatsheet.mdthe subcommands listed in,subcommands not listed must not be called。
  3. Clarify the problem before investigating: strictly follow thetroubleshooting process, first converge the user description into aphenomenon domain, then follow thetroubleshooting documentto perform troubleshooting.
  4. Prefer to run the commands required for troubleshooting as described in thereferences/<slug>.md troubleshooting document,do not blindly guess commands on your own。
  5. Multi-instance scenarios: each ECS must be troubleshooted separately; do not mix results from machine A to draw conclusions about machine B.

Troubleshooting Process

must be executed in order

Phase 1: Abnormal Issue Clarification

Before opening any domain document, if the user's problem description is vague,first refine the problem through multiple rounds of dialogue, and through aliyun CLI and ask the user to fill in as much as possible the evidence of the abnormal issue occurrence and related environment information, which usually involves the following information:

Dimension Content to be completed How to obtain
Basic instance information, status, specification Instance status Call aliyun CLI as needed
Scope Whether it is reproducible; start and end time; whether there were changes, restarts, or scaling when the abnormal issue occurred Ask the user
Channel Whether VNC is available; whether SSH/Workbench/Cloud Assistant is available Ask the user
Network direction External→instance service port, instance→external network, only intra-VPC communication, etc. Ask the user
Symptom Original error text, screenshots Ask the user

Phase 2: Categorize into a Phenomenon Domain

  1. Open references/symptom-to-domain.md, and select the phenomenon domain category and phenomenon domain according to the abnormal issue description after user clarification.
  2. Output:one phenomenon domain, and record the troubleshooting document path corresponding to the symptom domain references/<slug>.md. At the same time,require the user to confirm whether the symptom domain is accurate, and only after it is accurate enter "Phase 3". If the user reports it is inaccurate, present to the user the top 3 secondary symptom domains after excluding the symptom domain in Step 2, and ask the user to confirm whether it belongs to these secondary symptom domains. If the user reports it does not belong to any of the secondary symptom domains, terminate all subsequent processes and recommend the user submit an Alibaba Cloud ticket.

Phase 3: Confirm whether it is a GuestOS issue

Open the selected references/<slug>.md , then complete the steps in the "Determine whether it is a GuestOS issue" section at the beginning of the document in order, with the requirement:

  1. mustconfirm that it is a GuestOS issue before entering all subsequent steps; otherwise, directly return the abnormal issue conclusion to the user.
  2. prioritize completing the determination yourself in order: for any data that can be obtained through the aliyun CLI, directly call it to obtain the data,must not directly ask the user without first attempting to obtain the data through the aliyun CLI. Only ask the user when the information can indeed only be obtained from the console or the user-side client environment.
  3. Before completing the determination, do not enter all subsequent steps.

Phase 4: Diagnostic tool troubleshooting

Before entering detailed troubleshooting within the domain, first perform quick troubleshooting based on the diagnostic tools recommended for the symptom domain.

  1. View references/phenomenon-domain.md in the "Recommended diagnostic set" column corresponding to the current symptom domain to determine the list of diagnostic sets to be invoked. If the recommended column is "—" (no recommended diagnostic set), skip this phase and directly enter "Phase 5".
  2. First, confirm with the user whether to execute the recommended diagnostic set。If the user agrees, then, according to the diagnostic set list obtained in Step 1,in orderrefer to references/create-diagnostic-report.md for the steps to create a resource diagnostic report and execute diagnostics.If the user does not agree, skip this phase. Note:
  3. If the diagnostic set requires additional input parameters, prioritize querying the relevant data through the aliyun CLI tool, and only require the user to provide it when the data cannot be obtained through the aliyun CLI.
  4. If the diagnostic set does not exist or creating the resource diagnostic report fails, first explain the situation to the user, then skip this phase and directly enter the next phase.
  5. View the resource diagnostic report details. If the diagnostic report already contains diagnostic items strongly related to the abnormal issue, directly enter "Phase 6". Otherwise, the diagnostic report output results should be carried into subsequent phases and analyzed together with the in-domain process.

Phase 5: Troubleshooting GuestOS internal issue-related components

Read references/<slug>.md in inside GuestOS section:

  1. Read the related components list in it; this is the list of GuestOS components that may be involved in the current symptom domain, such as NIC, routing, DNS, firewall, sshd, PAM, disk, kernel, etc.
  2. Perform troubleshooting according to the issue localization steps given in the document. When the troubleshooting steps point to a component troubleshooting document linkreferences/utils/<component-slug>.md, open the corresponding referenced document and perform component troubleshooting in order. Requirementcollect data through the aliyun CLI tool(when data inside GuestOS for the current symptom domain needs to be collected, you may call aliyun.ecs.RunCommand). Also, commands should be as detailed as possible and shouldcollect all required data for this symptom domain in one go, to reduce the number of RunCommand executions.
  3. Do not perform any repair operations, only provide conclusions and repair suggestions.

Phase 6: Summary and Recommendations

Finally, provide a summary and recommendations based on the following two cases:

  • Root cause identified: Provide a structured diagnostic report explaining the symptom domain, the evidence chain of the troubleshooting process, and the conclusion, and provide recommendations for fixing or avoiding the issue. Requirements:
    1. mustfollow the templatereferences/diagnosis-report-template.mdgenerate a diagnostic report.
    2. Clear and readable, avoid being vague.
    3. When multiple root causes exist, analyze their relationship: whether one root cause leads to another root cause, or multiple root causes jointly cause the problem.
  • Root cause still uncertain: List the candidate root causes that have been ruled out, and provide recommendations for the next troubleshooting steps.

Process Overview

flowchart TD
  A[阶段1 收集事实 + aliyun CLI采集元数据] --> B[阶段2 确定现象域（symptom-to-domain + phenomenon-domain）]
  B --> C[选定 references/slug.md]
  C --> D[阶段3 确认问题边界: GuestOS / 管控 / 客户端]
  D -->|非 GuestOS 主因| E[先处理/网络/平台侧]
  D -->|GuestOS| D2[阶段4 快速排查：资源诊断报告排查]
  D2 -->|有推荐诊断集合| D3[调用 aliyun.ecs.CreateDiagnosticReport]
  D2 -->|无推荐诊断集合| F[阶段5 域内排查: 组件排查 + 定位步骤]
  D3 --> F
  F --> G{需 utils / 更多数据?}
  G -->|是| H[打开对应引用文档按顺序进行组件排查]
  G -->|否| I[阶段6 总结与建议]
  H --> I
  E --> I

Referenced Document Index

Path Purpose
symptom-to-domain.md Natural language → symptom domain routing
phenomenon-domain.md Authoritative table: unique identifiers, concepts, typical symptoms, slugs, recommended diagnostic tools
aliyun-cli-cheatsheet.md aliyun CLI tool quick reference (whitelisted subcommands)
create-diagnostic-report.md Resource diagnostic report creation and interpretation
references/<slug>.md Complete troubleshooting process for each symptom domain
references/utils/<component-slug>.md GuestOS component-level troubleshooting