Microsoft Azure Linux Agent

Linux distributions support

The list of distros we officially support is maintained at: Linux distributions supported by Azure. Our daily automation tests most of these distributions. The Agent can be used on other distributions as well, but development, testing and support for those are done by the open source community. This repo contains community-driven support for some distributions which are not officially supported by Azure.

Testing is done using the develop branch, which can be unstable. For a stable build please use the master branch instead.

Introduction

The Microsoft Azure Linux Agent (waagent) manages Linux provisioning and VM interaction with the Azure Fabric Controller. It provides the following functionality for Linux IaaS deployments:

• Image Provisioning

  • Creation of a user account
  • Configuring SSH authentication types
  • Deployment of SSH public keys and key pairs
  • Setting the host name
  • Publishing the host name to the platform DNS
  • Reporting SSH host key fingerprint to the platform
  • Resource Disk Management
  • Formatting and mounting the resource disk
  • Configuring swap space

• Networking

  • Manages routes to improve compatibility with platform DHCP servers
  • Ensures the stability of the network interface name

• Kernel

  • Configure virtual NUMA (disable for kernel <2.6.37)
  • Configure SCSI timeouts for the root device (which could be remote)

• Diagnostics

  • Console redirection to the serial port

• SCVMM Deployments

  • Detect and bootstrap the VMM agent for Linux when running in a System Center Virtual Machine Manager 2012R2 environment

• VM Extension

  • Inject component authored by Microsoft and Partners into Linux VM (IaaS) to enable software and configuration automation
  • VM Extension reference implementation on GitHub

Communication

The information flow from the platform to the agent occurs via two channels:

• A boot-time attached DVD for IaaS deployments. This DVD includes an OVF-compliant configuration file that includes all provisioning information other than the actual SSH keypairs.

• A TCP endpoint exposing a REST API used to obtain deployment and topology configuration.

HTTP Proxy

The Agent will use an HTTP proxy if provided via the http_proxy (for http requests) or https_proxy (for https requests) environment variables. Due to limitations of Python, the agent does not support HTTP proxies requiring authentication.

Similarly, the Agent will bypass the proxy if the environment variable no_proxy is set.

Note that the way to define those environment variables for the Agent service varies across different distros. For distros that use systemd, a common approach is to use Environment or EnvironmentFile in the [Service] section of the service definition, for example using an override or a drop-in file (see "systemctl edit" for overrides).

Example

    # cat /etc/systemd/system/walinuxagent.service.d/http-proxy.conf
    [Service]
    Environment="http_proxy=http://proxy.example.com:80/"
    Environment="https_proxy=http://proxy.example.com:80/"
    #

The Agent passes its environment to the VM Extensions it executes, including http_proxy and https_proxy, so defining a proxy for the Agent will also define it for the VM Extensions.

The HttpProxy.Host and HttpProxy.Port configuration variables, if used, override the environment settings. Note that this configuration variables are local to the Agent process and are not passed to VM Extensions.

Requirements

The following systems have been tested and are known to work with the Azure Linux Agent. Please note that this list may differ from the official list of supported systems on the Microsoft Azure Platform as described here.

Waagent depends on some system packages in order to function properly:

• Python 2.6+
• OpenSSL 1.0+
• OpenSSH 5.3+
• Filesystem utilities: sfdisk, fdisk, mkfs, parted
• Password tools: chpasswd, sudo
• Text processing tools: sed, grep
• Network tools: ip-route, iptables

Installation

Installing via your distribution's package repository is the only method that is supported.

You can install from source for more advanced options, such as installing to a custom location or creating custom images. Installing from source, though, may override customizations done to the Agent by your distribution, and is meant only for advanced users. We provide very limited support for this method.

To install from source, you can use setuptools:

    sudo python setup.py install --register-service

For Python 3, use:

    sudo python3 setup.py install --register-service

You can view more installation options by running:

    sudo python setup.py install --help

The agent's log file is kept at /var/log/waagent.log.

Lastly, you can also customize your own RPM or DEB packages using the configuration samples provided in the deb and rpm sections below. This method is also meant for advanced users and we provide very limited support for it.

Upgrade

Upgrading via your distribution's package repository or using automatic updates are the only supported methods. More information can be found here: Update Linux Agent

To upgrade the Agent from source, you can use setuptools. Upgrading from source is meant for advanced users and we provide very limited support for it.

    sudo python setup.py install --force

Restart waagent service,for most of linux distributions:

    sudo service waagent restart

For Ubuntu, use:

    sudo service walinuxagent restart

For CoreOS, use:

    sudo systemctl restart waagent

Command line options

Flags

-verbose: Increase verbosity of specified command

-force: Skip interactive confirmation for some commands

Commands

-help: Lists the supported commands and flags.

-deprovision: Attempt to clean the system and make it suitable for re-provisioning, by deleting the following:

• All SSH host keys (if Provisioning.RegenerateSshHostKeyPair is 'y' in the configuration file)

• Nameserver configuration in /etc/resolv.conf

• Root password from /etc/shadow (if Provisioning.DeleteRootPassword is 'y' in the configuration file)

• Cached DHCP client leases

• Resets host name to localhost.localdomain

  WARNING! Deprovision does not guarantee that the image is cleared of all sensitive information and suitable for redistribution.

-deprovision+user: Performs everything under deprovision (above) and also deletes the last provisioned user account and associated data.

-version: Displays the version of waagent

-serialconsole: Configures GRUB to mark ttyS0 (the first serial port) as the boot console. This ensures that kernel bootup logs are sent to the serial port and made available for debugging.

-daemon: Run waagent as a daemon to manage interaction with the platform. This argument is specified to waagent in the waagent init script.

-start: Run waagent as a background process

-collect-logs [-full]: Runs the log collector utility that collects relevant agent logs for debugging and stores them in the agent folder on disk. Exact location will be shown when run. Use flag -full for more exhaustive log collection.

Configuration

A configuration file (/etc/waagent.conf) controls the actions of waagent. Blank lines and lines whose first character is a # are ignored (end-of-line comments are not supported).

A sample configuration file is shown below:

Extensions.Enabled=y
Extensions.GoalStatePeriod=6
Provisioning.Agent=auto
Provisioning.DeleteRootPassword=n
Provisioning.RegenerateSshHostKeyPair=y
Provisioning.SshHostKeyPairType=rsa
Provisioning.MonitorHostName=y
Provisioning.DecodeCustomData=n
Provisioning.ExecuteCustomData=n
Provisioning.PasswordCryptId=6
Provisioning.PasswordCryptSaltLength=10
ResourceDisk.Format=y
ResourceDisk.Filesystem=ext4
ResourceDisk.MountPoint=/mnt/resource
ResourceDisk.MountOptions=None
ResourceDisk.EnableSwap=n
ResourceDisk.EnableSwapEncryption=n
ResourceDisk.SwapSizeMB=0
Logs.Verbose=n
Logs.Collect=y
Logs.CollectPeriod=3600
OS.AllowHTTP=n
OS.RootDeviceScsiTimeout=300
OS.EnableFIPS=n
OS.OpensslPath=None
OS.SshClientAliveInterval=180
OS.SshDir=/etc/ssh
HttpProxy.Host=None
HttpProxy.Port=None

The various configuration options are described in detail below. Configuration options are of three types : Boolean, String or Integer. The Boolean configuration options can be specified as "y" or "n". The special keyword "None" may be used for some string type configuration entries as detailed below.

Configuration File Options

Extensions.Enabled

Type: Boolean
Default: y

This allows the user to enable or disable the extension handling functionality in the agent. Valid values are "y" or "n". If extension handling is disabled, the goal state will still be processed and VM status is still reported, but only every 5 minutes. Extension config within the goal state will be ignored. Note that functionality such as password reset, ssh key updates and backups depend on extensions. Only disable this if you do not need extensions at all.

Note: disabling extensions in this manner is not the same as running completely without the agent. In order to do that, the provisionVMAgent flag must be set at provisioning time, via whichever API is being used. We will provide more details on this on our wiki when it is generally a