Nova-agent (Linux) and Rackspace agent (Windows)

This article describes nova-agent (Linux®) and Rackspace agent (Microsoft®
Windows®), which are required services used in Rackspace public cloud
virtualized servers. For brevity, both agents are referred to as nova-agent
in this article, but all statements apply equally to nova-agent and Rackspace

What is nova-agent?

Nova-agent is a required service for all virtualized servers in the Rackspace
public cloud. Thus OnMetal is excluded. The service interacts with XenServer®. According
to the Rackspace developer docs,
nova-agent is a service that:

"provides a means of interacting with the server through the API or the Cloud
Control Panel. Nova-agent enables components outside the server to control
the server by sending messages through the XenStore file system."

Nova-agent provides the following functionality:

  • Root or admin password resets that you request through the Cloud Control Panel
    or by using the API

  • Setting and changing network information, such as adding Cloud Networks or
    setting proper IPs and routes at build time

  • Red Hat® Enterprise Linux registration and Windows activation

When does nova-agent run?

Nova-agent is always listening when the server is active, but it only makes
changes in the following situations:

Initial server boot- Sets root password (Administrator for Windows)

- Sets network configuration

- Red Hat Enterprise Linux registration and Windows activation
Password reset request through the Cloud Control Panel or APISets root password (Administrator for Windows)
Attach/detach Cloud NetworkSets/removes interface IPs and routes

What does nova-agent require?

  • UNIX-like systems (Linux and FreeBSD®) must run the xe-linux-distribution
    service (XenServer Tools). You should configure the xe-linux-distribution
    service to start before nova-agent.

    Note: On newer distributions (distros), this might be called xe-daemon
    instead of xe-linux-distribution.

  • Windows systems must run the XenServer Tools.

If these required applications are missing, you can download the XenServer Tools
ISO from,
which works for Linux or Windows. Citrix® also has packages for the common
Linux distros.

What happens when nova-agent is broken or missing?

If you don't have nova-agent installed, the following symptoms might occur:

  • Builds take a long time, but eventually complete. The resulting server has the
    same IP address information and password as the server used to create its
    image. Thus, networking doesn't work, but you can log in by using the console.

  • You can't reset the root or admin password through the Cloud Control Panel.

  • You can't add or remove networks or set proper IP addresses and routes, which
    causes build failures.

  • Red Hat® Enterprise Linux registration or Windows activation does not occur.

  • (Windows only) Versions older versions than 1.3.1 do not work with RackConnect
    v3, because the agent can't properly create virtual Network Interface Cards
    (NICs) with the Cloud Network names.

All images created from a server with a broken nova-agent exhibit these issues.

Are there any known bugs?

Nova-agent for Linux and Windows does not deal with unexpected Ethernet
interfaces. For example, Tun and Tap devices, created by VPN applications, can cause
nova-agent to crash.

Windows known issues

You must enable IPv6 on the public interface, or the netsh commands that
nova-agent runs to set the network fail with the following error:

{"returncode":"1","message":"Command Failed. , Output:Element not found.\\r\\n"}


The following sections provide some possible solutions.

Operating system (OS) independent troubleshooting

General fixes in order of desirability:

  1. Fix the agent from a running server, and then take a new image to use as the
    golden image.

  2. If the source server was deleted but you know the root password of the source
    server, log in to the new server by using the console and manually set the IP
    address information. Then log in and fix nova-agent.

  3. If the source server was deleted and you don't have the root or admin password
    of the source server, perform the following steps:

    1. Build a new server from an image.
    2. Boot the new server into rescue mode.
    3. Fix the password.
    4. Boot out.
    5. Fix nova-agent.
    6. Take a new image.

Installing nova-agent on Linux

If starting the nova-agent service doesn't work, you can troubleshoot by looking
at the nova-agent logs. The newest version of nova-agent is now available in EPEL
and Rackspace's internal, Ubuntu® operating system, and Debian® repositories. Typically, package
installation commands (yum install nova-agent or apt-get install nova-agent)
should install or update the agent.

If that doesn't work, you can also try installing the packages from the OSPC repo.

If you're not on a Rackspace-supported distribution, you can try to install an
older version of nova-agent
from the rackerlabs Github repository. However, this is technically unsupported.

If you're using an imported image of a distro that supports cloud-init, you might
find it easier to use cloud-init instead of nova-agent. This requires setting
the following metadata on your imported image:

Metadata key and valueDescription
img_config_drive=mandatoryAlways attach the config drive on builds from this image.
The config-drive always contains meta-data.json,
network-data.json, and vendor-data.json.
Any distro with the cloud-init service active at boot
should be able to read these files and inject
a SecureShell (SSH) key, set network configuration, and so on.
vm_mode=hvmBoot in hardware virtual machine (HVM) mode as opposed to
the deprecated paravirtual (PV) mode.
PV mode is implicit, so you get bootloader errors
unless you set this mode.
xenapi_use_agent=FalseDon't check for the nova-agent response before marking
the server as ACTIVE in the Cloud Servers API.

Note: A RHEL® 7.2/CentOS® 7.2 update pushed in December 2015 broke legacy
behavior that older nova-agents relied on. You might still see this issue on
older custom images or on servers that haven't been updated lately. Tag
any related support tickets with "rm14157" so we can track this issue.

FreeBSD and Linux only: Nova-agent 2.x branch vs 1.x branch

The 2.x branch of nova-agent is a complete rewrite. We recommend the 2.x branch,
unless you are using an OS not supported by the 2.x branch (such as FreeBSD).
We don't recommend upgrading from 1.x to 2.x because there is nothing to be
gained, and the process is extremely complex.

Topic2.x branch1.3.9 branch
install method
yum or apt package managersDownload the release from github and run the script
Github link2.x link1.3.9 link
Only OS currently supported in
Rackspace Cloud (Fedora®,
CoreOS®, Red Hat/CentOS,
Debian, and Ubuntu operating system;
Supported OS plus some older
unsupported OS such as
OpenSuSE®, Gentoo®, FreeBSD,
and Arch®
Python3 supportYesNo

Installing nova-agent on Windows

  1. Download the latest versions of the following nova-agent files from

  2. Extract the contents of to
    C:\Program Files\Rackspace\Cloud Servers\Agent to install the agent.

  3. Run installagentservice.bat.

  4. Extract the contents of to
    C:\Program Files\Rackspace\Cloud Servers\AgentUpdater to install the
    agent updater.

  5. Run installupdateservice.bat.

Rerun bootstrap.cmd or bootstrap.bat (Windows)

If you would like the agent to rerun bootstrap.cmd on your next reboot, you
need to set the registry key cloud-automation-run in SOFTWARE/Rackspace
to any value. This causes that file to be rerun on next reboot. This is useful
for setting up golden images with autoscale.

Related Articles

Operating a cloud server with nova-agent
All About Nova-Agent (on Linux)