WALinuxAgent
2.11.1.12
Microsoft Azure Linux Agent
The editor of Downcodes will introduce you to Microsoft Azure Linux Agent (waagent), which is a tool that manages Linux provisioning and virtual machine interaction with Azure Fabric Controller. It provides the following capabilities for Linux IaaS deployments:
1. Image provisioning: waagent is responsible for managing the initial provisioning process of Linux virtual machines, including configuring the network, installing drivers, and setting up initial user accounts.
2. Network management: The waagent coordinates with the Azure Fabric Controller to configure the virtual machine's network settings, such as IP address, subnet mask, and gateway.
3. Kernel management: waagent can manage the kernel updates of the virtual machine to ensure that it is always running the latest and secure kernel version.
4. Diagnosis: waagent can collect and report virtual machine health information to help diagnose problems and resolve faults.
5. SCVMM deployment: waagent supports integration with System Center Virtual Machine Manager (SCVMM) to manage and provision virtual machines.
6. Virtual machine extensions: waagent supports running virtual machine extensions that provide additional functionality and customization, such as installing software or monitoring metrics.
7. Communication: waagent communicates with Azure Fabric Controller through two channels:
* Boot-time append DVD: For IaaS deployments, a boot-time append DVD containing an OVF-compatible configuration file provides provisioning information (in addition to the SSH key pair).
* REST API: A TCP endpoint exposing a REST API for obtaining deployment and topology configurations.
waagent can use an HTTP proxy through the httpproxy (for HTTP requests) or httpsproxy (for HTTPS requests) environment variables. Due to Python limitations, waagent does not support HTTP proxies that require authentication.
Similarly, if the no_proxy environment variable is set, waagent will bypass the proxy.
Note that the way these environment variables are defined for the waagent service varies between distributions. For distributions using systemd, a common approach is to use Environment or EnvironmentFile in the [Service] section of the service definition, for example using an override or inserting a 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/"
#
`
waagent passes its environment to the virtual machine extensions it executes, including httpproxy and httpsproxy, so defining a proxy for waagent will also define a proxy for the virtual machine extension.
If you use the HttpProxy.Host and HttpProxy.Port configuration variables, they override the environment settings. Note that these configuration variables are local to the waagent process and are not passed to the virtual machine extension.
waagent requires some system packages to function properly. These packages vary by distribution.
Installation through the distribution package repository is the only supported installation method.
You can install from source for more advanced options, such as installing to a custom location or creating a custom image. However, installing from source may override customizations made to waagent by your distribution and is intended for advanced users only. We have 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 the following command:
`
sudo python setup.py install --help
`
The waagent log file is saved in /var/log/waagent.log.
Finally, you can customize your own RPM or DEB package using the configuration examples provided in the DEB and RPM sections below. This method is also suitable for advanced users and we have very limited support for this method.
Upgrading via the distribution package repository or using automatic updates are the only supported methods. You can find more information here: Updating Linux Agent.
To upgrade waagent from source code, you can use setuptools. Upgrading from source is only for advanced users and we have very limited support for this method.
`
sudo python setup.py install --force
`
Restart the waagent service:
`
sudo service waagent restart
`
For Ubuntu, use:
`
sudo service walinuxagent restart
`
For CoreOS, use:
`
sudo systemctl restart waagent
`
-verbose: Increase the verbosity of the specified command.
-force: Skip interactive confirmation for some commands.
-help: List supported commands and flags.
-deprovision: Attempts to clean the system and make it suitable for reprovisioning by removing the following:
* All SSH host keys (if Provisioning.RegenerateSshHostKeyPair in the configuration file is 'y').
* Nameserver configuration in /etc/resolv.conf.
* The root password in /etc/shadow (if Provisioning.DeleteRootPassword in the configuration file is 'y').
* Cached DHCP client lease.
* Reset hostname to localhost.localdomain.
warn! deprovision cannot guarantee that the image has been cleaned of all sensitive information and is suitable for redistribution.
-deprovision+user: Performs all actions under deprovision (described above), plus deletes the last provisioned user account and its associated data.
-version: Display the waagent version.
-serialconsole: Configure GRUB to mark ttyS0 (the first serial port) as the boot console. This will ensure that kernel boot logs are sent to the serial port and can be used for debugging.
-daemon: Run waagent as a daemon process to manage interaction with the platform. This parameter is specified to waagent in the waagent initialization script.
-start: Run waagent as a background process.
-collect-logs [-full]: Runs the log collection utility, which will collect agent-related logs for debugging purposes and store them in the agent folder on disk. The exact location will be displayed when run. Use the -full flag for more comprehensive log collection.
A configuration file (/etc/waagent.conf) controls the operation of waagent. Empty lines and lines whose first character is # are ignored (end-of-line comments are not supported).
An example 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 divided into three types: boolean, string, and integer. Boolean configuration options can be specified as "y" or "n". The special keyword "None" can be used with certain string configuration items, as described below.
Type: Boolean
Default value: y
This option allows the user to enable or disable extended processing capabilities in the agent. Valid values are "y" or "n". If extended processing is disabled, target status will still be processed and virtual machine status will still be reported, but only every 5 minutes. Extended configuration in the target state will be ignored. Note that features such as password reset, SSH key updates, and backups rely on extensions. Only disable this option if you don't need the extension at all.
Note: Disabling the extension in this way is not the same as not using the proxy at all. To do this, the provisionVMAgent flag must be set at provisioning time through whatever API is used. We will provide more details on this on our wiki, but it is not available yet.
Type: Boolean
Default value: n
Wait for cloud-init to complete before performing virtual machine expansion (cloud-init status --wait).
cloud-init and virtual machine extensions are both common ways to customize a virtual machine during initial deployment. By default, the agent will start executing scaling while cloud-init may still be in the 'config' phase, and will not wait for the 'final' phase to complete. cloud-init and extensions may perform operations that conflict with each other (for example, they may both attempt to install a package). Setting this option to 'y' ensures that virtual machine expansion is only performed after cloud-init has completed all stages.
Note that using this option requires creating a custom image and setting the value of this option to 'y' to ensure that the wait operation is performed during the initial deployment of the virtual machine.
Type: integer
Default value: 3600
Timeout in seconds for the agent to wait for cloud-init. If the timeout expires, the agent continues to perform virtual machine expansion. See Extensions.WaitForCloudInit for more details.
Type: integer
Default value: 6
How often (in seconds) to poll for new target status and report the status of virtual machines and extensions. The target state describes the desired state of the extension on the virtual machine.
Note: Setting this parameter for more than a few minutes may cause the virtual machine status to be reported as Unresponsive/Unavailable on the Azure portal. Additionally, this setting affects how quickly the agent starts performing scaling.
Type: Boolean
Default value: y
Enables automatic updating of extension handlers. Extension handlers are responsible for managing extensions and reporting virtual machine status. The core functionality of the agent is contained in the extension handler, and users are encouraged to enable this option to maintain the latest version.
When this option is enabled, the agent will install new versions as they become available. When disabled, the agent will not install any new versions, but it will use the latest version already installed on the virtual machine.
illustrate:
For more information about agent versions, see our FAQ.
For more information about agent updates, see our FAQ.
For more information about AutoUpdate.UpdateToLatestVersion and AutoUpdate.Enabled, see our FAQ.
Type: Boolean
Default value: y
Enables automatic updating of extension handlers. This flag is supported for legacy reasons and we strongly recommend using AutoUpdate.UpdateToLatestVersion instead of this flag.
The difference between these two flags is that when set to 'n', AutoUpdate.Enabled will use the extension handler version pre-installed on the image, while AutoUpdate.UpdateToLatestVersion will use the latest version installed on the virtual machine ( via automatic updates).
In most distributions, the default value is 'y'.
Type: string
Default value: auto
Select the provisioning agent to use (or allow waagent to determine this by specifying "auto"). Possible options are "auto" (default), "waagent", "cloud-init" or "disabled".
Type: Boolean
Default value: y
This option allows the user to enable or disable provisioning functionality in the agent. Valid values are "y" or "n". If provisioning is disabled, the SSH host and user keys in the image will be preserved, and any configuration specified in the Azure Provisioning API will be ignored.
NOTE: This configuration option has been removed and no longer has any effect. waagent now automatically detects cloud-init as a provisioning agent (optionally overridden using Provisioning.Agent).
Type: Boolean
Default value: n
Monitor hostname changes and publish changes via DHCP requests.
Type: integer
Default value: 30
How often (in seconds) to monitor hostname changes. If MonitorHostName is not set, this setting is ignored.
Type: Boolean
Default value: n
This option enables/disables support for provisioning via cloud-init.
If true ("y"), the agent will wait for cloud-init to complete before installing extensions and processing the latest target state. Provisioning.Enabled Must be disabled ("n") for this option to take effect. Setting Provisioning.Enabled to true ("y") overrides this option and runs the built-in agent provisioning code.
NOTE: This configuration option has been removed and no longer has any effect. waagent now automatically detects cloud-init as a provisioning agent (optionally overridden using Provisioning.Agent).
Type: Boolean
Default value: n
If this option is set, the root password in the /etc/shadow file is removed during provisioning.
Type: Boolean
Default value: y
If this option is set, all SSH host key pairs (ecdsa, dsa, and rsa) in /etc/ssh/ will be deleted during provisioning. and generate a new key pair.
The encryption type of the new key pair can be configured through the Provisioning.SshHostKeyPairType entry. Note that some distributions will re-create SSH key pairs for any missing encryption types when the SSH daemon is restarted (for example, after a reboot).
Type: string
Default: rsa
This can be set to the type of encryption algorithm supported by the SSH daemon on the virtual machine. Commonly supported values include "rsa", "dsa", and "ecdsa".
Please note that "ecdsa" is not supported by "putty.exe" on Windows. Therefore, if you plan to use putty.exe on Windows to connect to a Linux deployment, use "rsa" or "dsa".
Type: Boolean
Default value: y
If this option is set, waagent will monitor Linux virtual machines for hostname changes (as returned by the "hostname" command) and automatically update the network configuration in the image to reflect the changes. In order to push the name change to the DNS server, the network in the virtual machine will be restarted. This will cause a brief loss of internet connection.
Type: Boolean
Default value: n
If this option is set, waagent will decode CustomData from Base64.
Type: Boolean
Default value: n
If this option is set, the waagent will execute CustomData after provisioning.
Type: string
Default value: 6
The algorithm used by crypt when generating password hashes.
Type: string
Default value: 10
The length of the random salt used when generating password hashes.
Type: Boolean
Default value: y
If this option is set, the resource disk provided by the platform will be formatted and mounted by waagent, provided that the file system type requested by the user in "ResourceDisk.Filesystem" is not "ntfs". A single partition of type Linux (83) will be provided on the disk. Note that if this partition can be successfully mounted, it will not be formatted.
Type: string
Default: ext4
This specifies the file system type of the resource disk. Supported values vary by Linux distribution. If the string is X, mkfs.X should be present in the Linux image. SLES 11 images should generally use 'ext3'. BSD images should use 'ufs2' here.
Type: string
Default value: /mnt/resource
This specifies the path to mount the resource disk.
Type: string
Default value: None
Specifies disk mount options to be passed to the mount -o command. This is a comma separated list of values, such as 'nodev,nosuid'. See mount(8) for details.
Type: Boolean
Default value: n
If this option is set, a swap file (/swapfile) is created on the resource disk and added to the system swap space.
Type: Boolean
Default value: n
If this option is set, the swap file (/swapfile) will be mounted as an encrypted filesystem (flag supported on FreeBSD only).
Type: integer
Default value: 0
The size of the swap file in megabytes.
Type: Boolean
Default value: n
If this option is set, log verbosity will be increased. waagent logs to /var/log/waagent.log and uses the system logrotate function to rotate the logs.
Type: Boolean
Default value: y
If this option is set, agent logs will be collected periodically and uploaded to a secure location to improve supportability.
NOTE: This feature relies on the agent's resource usage capabilities (cgroups); this flag will not take effect on any distribution that is not supported.
Type: integer
Default value: 3600
This configures how often logs are collected and uploaded. The default value is hourly.
Note: This only takes effect when the Logs.Collect option is enabled.
Type: Boolean
Default value: n
If SSL support is not compiled into Python, the proxy will fail all HTTPS requests. You can set this option to 'y' to cause the proxy to fall back to HTTP instead of failing the request.
Note: Allowing HTTP may inadvertently expose secure data.
Type: Boolean
Default value: n
If this option is set, the agent will attempt to install and load an RDMA kernel driver that matches the firmware version on the underlying hardware.
Type: Boolean
Default value: n
If this option is set, the agent will emit "OPENSSL_FIPS=1" to the environment when executing OpenSSL commands. This instructs OpenSSL to use any installed FIPS compliant libraries.
Note that the agent itself has no FIPS-related code. If a FIPS-compliant certificate is not installed, enabling this option causes all OpenSSL commands to fail.
Type: integer
Default value: 30
The agent monitors DHCP client restarts and restores network rules when a restart occurs. This setting determines how often, in seconds, monitoring restarts.
Type: integer
Default value: 300
This configures the SCSI timeout in seconds on the root device. If not set, the system default is used.
Type: integer
Default value: 30
How often (in seconds) to set the SCSI timeout on the root device. If RootDeviceScsiTimeout is not set, this setting is ignored.
Type: string
Default value: None
This can be used to specify an alternative path to the openssl binary used for cryptographic operations.
Type: integer
Default value: 30
How often (in seconds) udev rules (75-persistent-net-generator.rules and /etc/udev/rules.d/70-persistent-net.rules) are deleted for persistent network interface names.
Type: integer
Default: 180
This value sets the number of seconds that the agent uses for the SSH ClientAliveInterval configuration option.
Type: string
Default: /etc/ssh
This option can be used to override the default location of the SSH configuration directory.
Type: string
Default value: None
If this option is set, the agent will use this proxy server for HTTP/HTTPS requests. These values override the httpproxy or httpsproxy environment variables. Finally, HttpProxy.Host is required if used, and HttpProxy.Port is optional.
Type: Boolean
Default value: y
If this option is set, the agent will attempt to set cgroups limits for CPU and memory for the agent process itself as well as for extended processes. See the wiki for more details on this.
Type: string
Default value: customscript, runcommand
List of extensions to be excluded from cgroups restrictions. This should be comma separated.
WALinuxAgent collects and sends usage data to Microsoft to help us improve our products and services. The data collected is used to track service health and assist with Azure support requests. The data collected does not contain any personally identifiable information. Read our privacy statement to learn more.
WALinuxAgent currently does not support disabling telemetry. To disable telemetry collection, WALinuxAgent must be removed. If you need this functionality, please open an issue on GitHub and describe your needs.
We do not maintain packaging information in this repository, but some examples are shown below for reference. For officially maintained packaging, see the downstream release repository.
The official Ubuntu WALinuxAgent package can be found here.
Execute once:
Install required packages
`
sudo apt-get -y install ubuntu-dev-tools pbuilder python-all debhelper
`
Create pbuilder environment
`
sudo pbuilder create --debootstrapopts --variant=buildd
`
Get waagent.dsc from downstream package repository
To compile a package, do the following from the top-most directory:
Build source code package
`
dpkg-buildpackage -S
`
Build package
`
sudo pbuilder build waagent.dsc
`
Get the built package, usually located in /var/cache/pbuilder/result
The following instructions describe how to build rpm packages.
Install setuptools
`
curl https://bootstrap.pypa.io/ez_setup.py -o - | python
`
The following commands will build the binary and source RPMs:
`
python setup.py bdist_rpm
`
This project has adopted the Microsoft Code of Conduct for Open Source Code. For more information, see the Code of Conduct FAQ, or contact [email protected] with any additional questions or comments.
Example:
Apache-2.0 License
