Install the Cloud Assistant agent - Elastic Compute Service

To manage your instances without logging in, run commands, or send files using the console or an API, you must install and run the Cloud Assistant agent on the target instances.

Applicability

The Cloud Assistant agent is supported on the following operating systems:

Linux: Alibaba Cloud Linux, AlmaLinux 8+, Anolis OS 7+, CentOS 5+, Debian 8+, Ubuntu 12+, RHEL 5+, SUSE 11+, Fedora 33+, CoreOS, and OpenSUSE.
FreeBSD: 11+.
Windows: Windows Server 2012+.

Alibaba Cloud pre-installs the Cloud Assistant agent on ECS instances created from public images after December 1, 2017.

Procedure

Console

Go to the ECS console - Cloud Assistant page.
In the upper-left corner of the page, select the resource group and region of the target resources.
Click the ECS Instance tab to view the Cloud Assistant status for ECS instances in the current region.
- Normal: The agent is installed.
- Not Installed: Click Install and wait for the installation to complete. Restart the instance, and then check whether the status changes to Normal.
- Abnormal: For more information, see Handle exceptions for Cloud Assistant.

Linux instance

Step 1: Check agent installation

Connect to the Linux instance using Workbench.
Identify the init system type.
The init system loads and manages service processes at startup. Cloud Assistant agent commands vary by init system.
- systemd: Alibaba Cloud Linux, CentOS 7+, RHEL 7+, Fedora 15+, Ubuntu 15.04+, Debian 8+, and other similar distributions.
- Upstart: Ubuntu 6.10 to 14.10, RHEL 6, CentOS 6, and other similar distributions.
- SysVinit: RHEL 5, CentOS 5, Debian 6, and other similar distributions.
Verify that the Cloud Assistant agent is installed.
systemd
```
systemctl status aliyun.service
```
If the output contains the Unit aliyun.service could not be found message, the agent is not installed.
Upstart
```
/sbin/initctl status aliyun-service
```
If the output contains the initctl: Unknown job: aliyun-service message, the agent is not installed.
SysVinit
```
/etc/init.d/aliyun-service status
```
If the output is empty, the agent is not installed.

Step 2: Download and install agent

This script is for Alibaba Cloud ECS instances. By default, it installs the latest agent version. To install a specific version, modify VERSION=latest.

#!/bin/bash
VERSION=latest
PACKAGE=
PKG_URI=

REGION=$(curl -s http://100.100.100.200/latest/meta-data/region-id)
DOMAIN=aliyun-client-assist-${REGION}.oss-${REGION}-internal.aliyuncs.com

arch=$(uname -m)
echo "[main] arch = ${arch}"

# Detect whether the system is openSUSE or SLES.
is_suse_like() {
    if [[ -f /etc/os-release ]]; then
        local os_id
        os_id=$(grep -E "^ID=" /etc/os-release | tr -d '"' | cut -d= -f2)
        local os_version
        os_version=$(grep -E "^VERSION_ID=" /etc/os-release | tr -d '"' | cut -d= -f2 | cut -d. -f1)
        if ([[ "$os_id" == "opensuse"* ]] || [[ "$os_id" == "sles" ]]) && [[ "$os_version" == "16" ]]; then
            return 0
        fi
    fi
    return 1
}

case $arch in
    "i386"|"i686"|"x86_64"|"amd64")
        if command -v rpm && ! command -v dpkg; then
            if [[ "$arch" == "x86_64" ]] && is_suse_like; then
                PACKAGE="aliyun_assist_${VERSION}_x86_64.rpm"
            else
                PACKAGE="aliyun_assist_${VERSION}.rpm"
            fi
        else
            if [[ "$arch" == "x86_64" ]] && is_suse_like; then
                PACKAGE="aliyun_assist_${VERSION}_x86_64.deb"
            else
                PACKAGE="aliyun_assist_${VERSION}.deb"
            fi
        fi
        PKG_URI="https://$DOMAIN/linux/$PACKAGE"
        ;;
    *)
        if command -v rpm && ! command -v dpkg; then
            PACKAGE="aliyun-assist-${VERSION}-1.aarch64.rpm"
        else
            PACKAGE="aliyun-assist_${VERSION}-1_arm64.deb"
        fi
        PKG_URI="https://$DOMAIN/arm/$PACKAGE"
        ;;
esac

echo "[main] package = ${PACKAGE}"
echo "[main] pkg_uri = ${PKG_URI}"

if command -v wget; then
    sudo wget -O "${PACKAGE}" "${PKG_URI}"
elif command -v curl; then
    sudo curl -o "${PACKAGE}" "${PKG_URI}"
else
    echo "[WARN] command wget/curl not found, exit"
    exit 1
fi

if command -v rpm && ! command -v dpkg; then
    sudo rpm -ivh --force "${PACKAGE}"
elif command -v dpkg; then
    sudo dpkg -i "${PACKAGE}"
else
    echo "[WARN] command rpm/dpkg not found, exit"
    exit 2
fi

if [[ -e /etc/redhat-release ]]; then
    if sudo systemctl status qemu-guest-agent; then
        sudo systemctl stop qemu-guest-agent
        sudo systemctl disable qemu-guest-agent
        sudo systemctl restart aliyun.service
    fi
fi

Windows instance

Step 1: Check agent installation

Connect to a Windows instance using a Remote Desktop client or the Windows App.
Check the status of the Cloud Assistant service.
1. Open the Start menu and search for Computer Management.
2. Navigate to Services and Applications > Services.
3. Look for Aliyun Assist Service. If it is not listed, the agent is not installed.

Step 2: Download and install agent

Method 1: Download via browser

Download the Cloud Assistant agent.

Replace {regionId} with your instance's region ID, and then open the URL in a browser.

https://aliyun-client-assist-{regionId}.oss-{regionId}-internal.aliyuncs.com/windows/aliyun_agent_latest_setup.exe

# Example download URL for the China (Hangzhou) region (cn-hangzhou)
https://aliyun-client-assist-cn-hangzhou.oss-cn-hangzhou-internal.aliyuncs.com/windows/aliyun_agent_latest_setup.exe

Install the Cloud Assistant agent.
Double-click the Cloud Assistant agent file and follow the installation wizard. The default installation path is C:\ProgramData\aliyun\assist\.

Method 2: Use PowerShell

Replace {regionId} with your instance's region ID, and then run the following commands in PowerShell.

curl -UseBasicParsing -Uri https://aliyun-client-assist-{regionId}.oss-{regionId}-internal.aliyuncs.com/windows/aliyun_agent_latest_setup.exe -OutFile 'C:\aliyun_agent_latest_setup.exe'
& "C:\aliyun_agent_latest_setup.exe" /S

API

The API installation process is the same for all supported operating systems.

Call the DescribeCloudAssistantStatus operation to check whether the Cloud Assistant agent is installed on the target ECS instance.
If the CloudAssistantStatus parameter returns false, the agent is not installed.
If the agent is not installed, call the InstallCloudAssistant operation to install the Cloud Assistant agent.
After the installation is complete, call the RebootInstance operation to restart the ECS instance to apply the changes.

CLI

You can use Alibaba Cloud CLI to install the Cloud Assistant agent on most supported operating systems. Replace <YOUR-REGION-ID> with the region ID of your ECS instance and <YOUR-INSTANCE-ID> with the ID of your ECS instance.

Red Hat Enterprise Linux (RHEL) does not support installation using Alibaba Cloud CLI.

Call the DescribeCloudAssistantStatus operation to check whether the Cloud Assistant agent is installed on the target ECS instance.
```
aliyun ecs DescribeCloudAssistantStatus --RegionId <YOUR-REGION-ID> --InstanceId.1 <YOUR-INSTANCE-ID> --output cols=CloudAssistantStatus rows=InstanceCloudAssistantStatusSet.InstanceCloudAssistantStatus[]
```
If the command returns CloudAssistantStatus=true, the Cloud Assistant agent is installed on the ECS instance.

Call the InstallCloudAssistant operation to install the Cloud Assistant agent.

aliyun ecs InstallCloudAssistant --RegionId <YOUR-REGION-ID> --InstanceId.1 <YOUR-INSTANCE-ID>

Call the RebootInstance operation to restart the ECS instance.
```
aliyun ecs RebootInstance --InstanceId <YOUR-INSTANCE-ID>
```

FAQ

Unsupported operating systems

Migrate the OS: Upgrade or migrate your current system to a supported version.
Replace the OS (change the system disk): Use the Replace OS feature to install a supported operating system on the instance.

Latest version installation limits

Some kernels limit the highest agent version that you can install.

Run the uname -r command to check the kernel version.

Instance kernel version	Highest supported version
Linux kernel version < 2.6.32	x86/x64 architecture: 2.2.3.398 ARM architecture: 2.4.3.398
FreeBSD kernel version < 12.x	2.3.3.529

FreeBSD installation

For Alibaba Cloud ECS instances

#!/bin/sh

VERSION=latest
use_curl=0
which curl >/dev/null 2>&1 && use_curl=1
if [ $use_curl -eq 1 ];then
    REGION=$(curl http://100.100.100.200/latest/meta-data/region-id)
else
    REGION=$(wget -O - http://100.100.100.200/latest/meta-data/region-id)
fi
DOMAIN=aliyun-client-assist-${REGION}.oss-${REGION}-internal.aliyuncs.com
PACKAGE=aliyun_assist_${VERSION}.txz
PKG_URI="https://$DOMAIN/freebsd/$PACKAGE"

if [ $use_curl -eq 1 ];then
    curl -o $PACKAGE $PKG_URI
else
    wget -O $PACKAGE $PKG_URI
fi
pkg install -U -y $PACKAGE
service aliyun start

For managed instances (non-Alibaba Cloud servers)

#!/bin/sh

VERSION=latest
DOMAIN=aliyun-client-assist.oss-accelerate.aliyuncs.com
PACKAGE=aliyun_assist_${VERSION}.txz
PKG_URI="https://$DOMAIN/freebsd/$PACKAGE"

use_curl=0
which curl >/dev/null 2>&1 && use_curl=1
if [ $use_curl -eq 1 ];then
    curl -o $PACKAGE $PKG_URI
else
    wget -O $PACKAGE $PKG_URI
fi
pkg install -U -y $PACKAGE
service aliyun start

Managed instance installation

Linux

This script installs the latest agent version by default. To install a specific version, modify VERSION=latest.

#!/bin/bash
VERSION=latest
PACKAGE=
PKG_URI=

DOMAIN=aliyun-client-assist.oss-accelerate.aliyuncs.com

arch=$(uname -m)
echo "[main] arch = ${arch}"

# Detect whether the system is openSUSE or SLES.
is_suse_like() {
    if [[ -f /etc/os-release ]]; then
        local os_id
        os_id=$(grep -E "^ID=" /etc/os-release | tr -d '"' | cut -d= -f2)
        local os_version
        os_version=$(grep -E "^VERSION_ID=" /etc/os-release | tr -d '"' | cut -d= -f2 | cut -d. -f1)
        if ([[ "$os_id" == "opensuse"* ]] || [[ "$os_id" == "sles" ]]) && [[ "$os_version" == "16" ]]; then
            return 0
        fi
    fi
    return 1
}

case $arch in
    "i386"|"i686"|"x86_64"|"amd64")
        if command -v rpm && ! command -v dpkg; then
            if [[ "$arch" == "x86_64" ]] && is_suse_like; then
                PACKAGE="aliyun_assist_${VERSION}_x86_64.rpm"
            else
                PACKAGE="aliyun_assist_${VERSION}.rpm"
            fi
        else
            if [[ "$arch" == "x86_64" ]] && is_suse_like; then
                PACKAGE="aliyun_assist_${VERSION}_x86_64.deb"
            else
                PACKAGE="aliyun_assist_${VERSION}.deb"
            fi
        fi
        PKG_URI="https://$DOMAIN/linux/$PACKAGE"
        ;;
    *)
        if command -v rpm && ! command -v dpkg; then
            PACKAGE="aliyun-assist-${VERSION}-1.aarch64.rpm"
        else
            PACKAGE="aliyun-assist_${VERSION}-1_arm64.deb"
        fi
        PKG_URI="https://$DOMAIN/arm/$PACKAGE"
        ;;
esac

echo "[main] package = ${PACKAGE}"
echo "[main] pkg_uri = ${PKG_URI}"

if command -v wget; then
    sudo wget -O "${PACKAGE}" "${PKG_URI}"
elif command -v curl; then
    sudo curl -o "${PACKAGE}" "${PKG_URI}"
else
    echo "[WARN] command wget/curl not found, exit"
    exit 1
fi

if command -v rpm && ! command -v dpkg; then
    sudo rpm -ivh --force "${PACKAGE}"
elif command -v dpkg; then
    sudo dpkg -i "${PACKAGE}"
else
    echo "[WARN] command rpm/dpkg not found, exit"
    exit 2
fi

if [[ -e /etc/redhat-release ]]; then
    if sudo systemctl status qemu-guest-agent; then
        sudo systemctl stop qemu-guest-agent
        sudo systemctl disable qemu-guest-agent
        sudo systemctl restart aliyun.service
    fi
fi

Windows

Method 1: Download via browser

Open the following URL in a browser to download the Cloud Assistant agent.

https://aliyun-client-assist.oss-accelerate.aliyuncs.com/windows/aliyun_agent_latest_setup.exe

Install the Cloud Assistant agent.
Double-click the Cloud Assistant agent file and follow the installation wizard. The default installation path is C:\ProgramData\aliyun\assist\.

Method 2: Use PowerShell

curl -UseBasicParsing -Uri https://aliyun-client-assist.oss-accelerate.aliyuncs.com/windows/aliyun_agent_latest_setup.exe -OutFile 'C:\\aliyun_agent_latest_setup.exe' & "C:\\aliyun_agent_latest_setup.exe" /S

Install from binary or source code

Binary package

For Alibaba Cloud ECS instances

This script installs the latest agent version by default. To install a specific version, modify VERSION=latest.

#!/bin/bash

VERSION=latest
PACKAGE=
PKG_URI=

REGION=$(curl -s http://100.100.100.200/latest/meta-data/region-id)
DOMAIN=aliyun-client-assist-${REGION}.oss-${REGION}-internal.aliyuncs.com

arch=$(uname -m)
echo "[main] arch = ${arch}"

# Detect whether the system is openSUSE or SLES.
is_suse_like() {
    if [[ -f /etc/os-release ]]; then
        local os_id
        os_id=$(grep -E "^ID=" /etc/os-release | tr -d '"' | cut -d= -f2)
        local os_version
        os_version=$(grep -E "^VERSION_ID=" /etc/os-release | tr -d '"' | cut -d= -f2 | cut -d. -f1)
        if ([[ "$os_id" == "opensuse"* ]] || [[ "$os_id" == "sles" ]]) && [[ "$os_version" == "16" ]]; then
            return 0
        fi
    fi
    return 1
}

case $arch in
    "i386"|"i686"|"x86_64"|"amd64")
        if [[ "$arch" == "x86_64" ]] && is_suse_like; then
            PACKAGE="aliyun_assist_${VERSION}_update_x86_64.zip"
        else
            PACKAGE="aliyun_assist_${VERSION}_update.zip"
        fi
        PKG_URI="https://$DOMAIN/linux/$PACKAGE"
        ;;
    *)
        PACKAGE="aliyun_assist_${VERSION}_update_arm.zip"
        PKG_URI="https://$DOMAIN/arm/$PACKAGE"
        ;;
esac

echo "[main] package = ${PACKAGE}"
echo "[main] pkg_uri = ${PKG_URI}"

if command -v wget; then
    sudo wget -O "${PACKAGE}" "${PKG_URI}"
elif command -v curl; then
    sudo curl -o "${PACKAGE}" "${PKG_URI}"
else
    echo "[WARN] command wget/curl not found, exit"
    exit 1
fi

TARGET_DIR=/usr/local/share/aliyun-assist
sudo unzip -o "${PACKAGE}" -d $TARGET_DIR/
TRUE_VERSION=$(cat $TARGET_DIR/version)
sudo chmod a+x $TARGET_DIR/$TRUE_VERSION/update_install
sudo bash $TARGET_DIR/$TRUE_VERSION/update_install

For managed instances (non-Alibaba Cloud servers)

#!/bin/bash

VERSION=latest
PACKAGE=
PKG_URI=

DOMAIN=aliyun-client-assist.oss-accelerate.aliyuncs.com

arch=$(uname -m)
echo "[main] arch = ${arch}"

# Detect whether the system is openSUSE or SLES.
is_suse_like() {
    if [[ -f /etc/os-release ]]; then
        local os_id
        os_id=$(grep -E "^ID=" /etc/os-release | tr -d '"' | cut -d= -f2)
        local os_version
        os_version=$(grep -E "^VERSION_ID=" /etc/os-release | tr -d '"' | cut -d= -f2 | cut -d. -f1)
        if ([[ "$os_id" == "opensuse"* ]] || [[ "$os_id" == "sles" ]]) && [[ "$os_version" == "16" ]]; then
            return 0
        fi
    fi
    return 1
}

case $arch in
    "i386"|"i686"|"x86_64"|"amd64")
        if [[ "$arch" == "x86_64" ]] && is_suse_like; then
            PACKAGE="aliyun_assist_${VERSION}_update_x86_64.zip"
        else
            PACKAGE="aliyun_assist_${VERSION}_update.zip"
        fi
        PKG_URI="https://$DOMAIN/linux/$PACKAGE"
        ;;
    *)
        PACKAGE="aliyun_assist_${VERSION}_update_arm.zip"
        PKG_URI="https://$DOMAIN/arm/$PACKAGE"
        ;;
esac

echo "[main] package = ${PACKAGE}"
echo "[main] pkg_uri = ${PKG_URI}"

if command -v wget; then
    sudo wget -O "${PACKAGE}" "${PKG_URI}"
elif command -v curl; then
    sudo curl -o "${PACKAGE}" "${PKG_URI}"
else
    echo "[WARN] command wget/curl not found, exit"
    exit 1
fi

TARGET_DIR=/usr/local/share/aliyun-assist
sudo unzip -o "${PACKAGE}" -d $TARGET_DIR/
TRUE_VERSION=$(cat $TARGET_DIR/version)
sudo chmod a+x $TARGET_DIR/$TRUE_VERSION/update_install
sudo bash $TARGET_DIR/$TRUE_VERSION/update_install

Source code

The following example uses yum. For other Linux distributions, use the corresponding package manager.

Install prerequisites, such as Git and Go.

# Install Git
sudo yum install git -y

# Install Go
sudo yum install go -y

Download the Cloud Assistant agent source code.

sudo git clone https://github.com/aliyun/aliyun_assist_client

Navigate to the source code directory and compile the source code.
```
# Go to the source code directory.
cd ./aliyun_assist_client

# Compile the source code.
sudo go build
```
If the response contains no error messages, the installation is successful.

Applicability

Procedure

Console

Linux instance

Step 1: Check agent installation

systemd

Upstart

SysVinit

Step 2: Download and install agent

Windows instance

Step 1: Check agent installation

Step 2: Download and install agent

Method 1: Download via browser

Method 2: Use PowerShell

API

CLI

FAQ

Unsupported operating systems

Latest version installation limits

FreeBSD installation

Managed instance installation

Linux

Windows

Method 1: Download via browser

Method 2: Use PowerShell

Install from binary or source code

Binary package

Source code