Microsoft Azure Linux Agent (waagent)

The Microsoft Azure Linux Agent (waagent) manages Linux provisioning and VM interaction with the Azure Fabric Controller. It is responsible for:

• Image Provisioning: Creating user accounts, configuring SSH authentication/keys, setting hostnames, and managing resource disks (formatting, mounting, and swap space).
• Networking: Managing routes for DHCP compatibility and ensuring network interface name stability.
• Kernel Configuration: Configuring virtual NUMA and SCSI timeouts.
• Diagnostics: Redirecting the console to the serial port.
• VM Extensions: Injecting Microsoft and Partner components into the VM to enable software and configuration automation.

To build binary and source RPMs, follow these steps:

1. Install setuptools:

   curl https://bootstrap.pypa.io/ez_setup.py -o - | python

2. Run the build command:

   python setup.py bdist_rpm

The agent's behavior is controlled by a configuration file located at /etc/waagent.conf.

Rules for the configuration file:

• Comments: Lines starting with # are ignored. Blank lines are also ignored.
• End-of-line comments: Not supported. Ensure comments are on their own lines.
• Data Types: Options are either Boolean (y or n), String (can use the special keyword None), or Integer.
• Applying Changes: Changing a configuration option requires a service restart to take effect.

# Example /etc/waagent.conf snippet
Extensions.Enabled=y
Provisioning.Agent=auto
ResourceDisk.Format=y
HttpProxy.Host=None

The supported methods for upgrading are via your distribution's package repository or using automatic updates.

For advanced users upgrading from source using setuptools:

sudo python setup.py install --force

After upgrading, you must restart the waagent service. The command depends on your distribution:

• Most Linux distributions: sudo service waagent restart
• Ubuntu: sudo service walinuxagent restart
• CoreOS: sudo systemctl restart waagent

sudo python setup.py install --force
# Then restart the service
sudo service waagent restart

While installing via a distribution's package repository is the only officially supported method, advanced users can install from source using setuptools. Note that source installations may override distribution-specific customizations and have limited support.

To install using Python 2:

sudo python setup.py install --register-service

To install using Python 3:

sudo python3 setup.py install --register-service

To view all installation options:

sudo python setup.py install --help

Agent logs are located at /var/log/waagent.log.

To compile the agent into .deb packages, follow these steps:

1. Install build dependencies:

   sudo apt-get -y install ubuntu-dev-tools pbuilder python-all debhelper

2. Create the pbuilder environment:

   sudo pbuilder create --debootstrapopts --variant=buildd

3. Obtain waagent.dsc from a downstream package repository.
4. Build the source package (from the top-most directory):

   dpkg-buildpackage -S

5. Build the package:

   sudo pbuilder build waagent.dsc

6. Locate the result: Usually found in /var/cache/pbuilder/result.

# Build the source package
dpkg-buildpackage -S

# Build the package
sudo pbuilder build waagent.dsc

The EnvMonitor component runs a background thread to detect changes in the system environment that require agent intervention:

1. Hostname Changes: If Provisioning.MonitorHostName is enabled in the configuration and a hostname change is detected, the agent calls WaAgent.UpdateAndPublishHostName to synchronize the new name with the Azure fabric.
2. DHCP Client Restarts: The monitor tracks the PID of the DHCP client. If the PID changes (indicating a restart), the agent calls WaAgent.RestoreRoutes() to ensure routing tables are correctly re-established.
3. File Cleanup: It periodically moves files from defined RulesFiles locations to the library directory.

The SharedConfig class parses XML configuration provided by the Azure fabric, which includes deployment details, service instances, and networking information.

RDMA Configuration: If the SharedConfig contains rdmaMacAddress and rdmaIPv4Address for an instance, the agent triggers an RdmaHandler to:

1. Search for and update dat.conf files (e.g., /etc/dat.conf) with the correct RDMA IP address.
2. Write the RDMA configuration to the device /dev/hvnd_rdma.
3. Configure the network interface with the RDMA IP address using a 12-bit subnet mask (standard for InfiniBand in Azure).

Controls how the agent logs activity and collects diagnostic data.

• Logs.Verbose (Boolean, default: n): Increases log verbosity. Logs are written to /var/log/waagent.log.
• Logs.Collect (Boolean, default: y): Periodically collects and uploads logs to a secure location for support. Requires cgroups support.
• Logs.CollectPeriod (Integer, default: 3600): Frequency of log collection/upload in seconds (only works if Logs.Collect is y).

Note on Telemetry: WALinuxAgent collects usage data for service health and support. Telemetry cannot be disabled via configuration; the agent must be removed to stop collection.

Settings for OS-level features and connectivity.

• OS.AllowHTTP (Boolean, default: n): Allows falling back to HTTP if SSL support is missing in Python. Warning: May expose secure data.
• OS.EnableFIPS (Boolean, default: n): Sets OPENSSL_FIPS=1 in the environment. Requires FIPS-compliant libraries to be installed, otherwise OpenSSL commands will fail.
• OS.SshDir (String, default: /etc/ssh): Overrides the default SSH configuration directory.
• HttpProxy.Host (String, default: None): The proxy server host for HTTP/HTTPS requests. Required if using a proxy.
• HttpProxy.Port (String, default: None): The proxy server port. Overrides http_proxy or https_proxy environment variables.
• Protocol.EndpointDiscovery (String, default: dhcp): How to discover the WireServer endpoint. Options: dhcp (default) or static (uses 168.63.129.16).