Starting a site with Aquilon

Luis Fernando Muñoz Mejías


After installing Aquilon, we want to add hosts to our instance, and produce some useful configuration.

This document explains the steps required to set up the clusters for the Daily Planet, Superman’s employer.

Note: this documentation assumes that you have an aq command available in your path. If this is not the case, define an aq alias to /opt/aquilon/bin/

Aquilon terminology

These are the basic terms in Aquilon operations:

  • archetype: The highest possible grouping of hosts into distinctly seperate types, analogous to a QWG site. Archetypes are a bundle that expresses how to build something. It defines what set of templates to use (for example, what operating systems are available, etc). Hosts therefore require an archetype to define how they are compiled.
  • broker: The backend which the aq client communicates with and the owner of all object and production templates. We’ll refer to it also as aqd.
  • cluster: A group of hosts related in some way, different to an archetype in that hosts may or may not be in a cluster. When grouping hosts into a cluster, an object profile is also built for the cluster, as well as the hosts. Clusters go through a completely different schema and build process to how hosts are built and therefore have a different archetypes.
  • domain: A set of shared Quattor templates. Entities to be configured live in exactly one domain. A domain is currently implemented as a branch in the template-king git repository.
  • feature: A re-useable configuration template that configures a specific thing but does not in itself describe a complete system. (So similar to a chef recipe.) A feature may be included in a personality or anywhere else that PAN template code can be included.
  • personality: Analogous to QWG machine types, describes the services required but not the instance (selected using plenary template information).
  • plenary: Template generated by the broker, on the fly, from an external source such as a database.
  • sandbox: A development area for making changes to (Pan) templates. Each sandbox must be started from a domain and hosts or clusters may be managed into the sandbox to allow for pre-deployment testing. Once the template code is fully tested, it must be published back to the broker and then deployed to the shared domain.
  • service: A network-based service with well-known clients and servers such as DNS, DHCP, NTP, etc. Each service can have multiple instances. Service instances must be mapped which allows the administrator to model client hosts connecting to different instances based on location and optionally personality.

Before proceeding

Some understanding of Quattor’s architecture and the Pan language are expected before reading this document.

We’ll interact with the broker using the aq command, which has lots of sub-commands. Each sub-command has a detailed help.

In this stage we will be adding a site, so we will use add_* commands. Most of the commands we’ll use have show_, update_ and del_ counterparts. You are recommended to read the help of each command before actually running it.

Before starting using the aq command, you need get a Kerberos ticket. If the user you are logged on has been declared as a Kerberos principal, you can do it with kinit command (without parameters).

Archetypes, domains…

You need to start by declaring archetypes and the basic domains for your Aquilon instance. Let’s imagine we have two archetypes, one for Linux hosts under Quattor control and another one for IPMI interfaces

aq add_archetype --archetype 'linux' --compilable
aq add_archetype --archetype 'ipmi' --nocompilable

Next come the domains, which are just Git branches with some metadata. We’ll define a production and a testing domains.

aq show domain --all
# If domain 'prod' already exists, skip its creation
aq add_domain --domain 'prod'
aq add_domain --domain 'test'

Storing your inventory

The Aquilon database contains the entire inventory of your infrastructure. You may use it as your asset management database, or feed it from your existing one. You will have to store all your hardware, its characteristics and locations, which is easy to script but nevertheless may be an annoying process.

Geographical locations

Before starting, you have to add the geographical locations of your infrastructure. The meanings of the commands to run should be obvious. We list here an example:

aq add_organization --organization 'daily_planet'
aq add_hub --hub 'pacific' --organization 'daily_planet'
aq add_continent --continent 'america' --hub 'pacific'
aq add_country --country 'us' --continent 'america'
aq add_city --city 'metropolis' --fullname 'Metropolis' --country 'us' --timezone 'dct'
aq add_building --building 'hq' --city 'metropolis' --address '355, 1000 Broadway'
aq add_room --room 'supersecret' --building 'hq'

List your own addresses, rooms… but remember that each step depends on the previous ones. If you want to add European countries, you have to insert Europe as a continent first! Also note that object names should not start with a digit and cannot contain spaces.

Your hardware inventory

Next comes your hardware. At the very least, your racks, chassis and servers will be stored here. It is a good place to store other hardware such as switches.

For racks, you’ll have to specify on which row and column inside that row they are.

aq add_rack --rackid 'forlexluthor' --row 'R' --column 'C' --building 'hq'

Next come servers, switches, routers… we’ll go for servers, _machine_s in Aquilon terms. Aquilon has to know the exact vendor and model for each server, so here we go:

aq add_vendor --vendor 'luthorindustries' --comments "Bad guys make good sells"
aq add_model --model 'spyserver' --vendor 'luthorindustries' --type 'rackmount'
aq add_machine --machine 'illegaltapper' --model 'spyserver' --rack 'forlexluthor'

Network interfaces

Each machine has a number of network interfaces, with their MAC addresses. Don’t forget to add them!

aq add_interface --interface eth0 --machine 'illegaltapper' --mac 'AA:BB:CC:DD:EE:FF'

Declaring networks

Once we have the hardware in place, it’s time to declare the networks our hosts live in.

We’ll use the add_network command:

aq add_network --network 'leaks' --ip '' --netmask '' --city 'metropolis'
aq add_network --network 'reporters' --ip '' --netmask '' --city 'metropolis'

And now the broker knows about two networks, each with its own separate gateways. Networks can live in different network environments (for instance, internal, public…) on which separate policies may apply. Check the help for the aq add_network_environment command.

Wait, how do I define the routers for my networks?

When we declare our networks, Aquilon will assume a fixed IP (typically the first IP in the range) is the gateway in it. If this isn’t correct, you have to modify the configuration for the broker. Create a network_unknown section, and declare the default gateway offset.


And finally we restart the broker:

service aqd restart

If some of your networks don’t adhere to this convention, you’ll need to declare their routers in Aquilon. For instance, let’s suppose that the gateway in reporters network has offset 3:

aq add_router --ip '' --fqdn ''

If your network is an internal one (the default), some restrictions apply:

  • Routers must be part of the reserved_offsets list.
  • Router offsets must be below the first_usable_offset, which the broker uses when assigning IP addresses automatically.

If you need an external network, you have to create it with --network_environment external in its command line.

DNS domains

Our network has some DNS domains. We have to add them:

aq add_dns_domain --dns_domain ''

Personalities and features

Now that we have registered our host in the database, we want to use it for something. We want to give it a purpose, a personality.

Personalities are collections of smaller chunks called features. A feature is re-usable in many contexts, by different personalities, hardware models.

A host needs to be receive a personality when it is first registered in Aquilon, so we add its personality first and bind some features to it:

aq add_personality --personality 'illegal-spying-and-tapping' --archetype 'linux'
aq add_feature --feature 'hushhush' --type host
aq add_feature --feature 'rootpasswd' --type host

And we bind the personality to the hushhush feature. On the other hand, we want the root password to be set up for the entire archetype, so:

aq bind_feature --feature 'hushhush' --personality 'illegal-syping-and-tapping' --archetype 'linux'
aq bind_feature --feature 'rootpasswd' --archetype 'linux'

Declaring your first host

Now we can declare a host on our illegaltapper machine.

To do so, we have already:

  • Stored all the relevant hardware in the database
  • Declared all the network interfaces, with their MAC addresses
  • Declared all the networks it will be connected to
  • Declared all the DNS domains our host will live in
  • Declared a personality for our host

Now, we use all that information to add a tapping host:

aq add_host --hostname '' --machine 'illegaltapper' --ip '' --personality 'illegal-syping-and-tapping'

Congratulations! You have your first host! Run aq show_host --all to see it.

But we aren’t done yet. This host is empty!! And Aquilon won’t even compile it. Now it’s time to produce Pan code to configure the host.

Creating your first sandbox

We’ll do all our work in sandboxes, and we’ll dispose of them when their purpose is ready. So, let’s create our first sandbox:

aq add_sandbox --sandbox site-init

We’ll also associate one host to it:

aq manage --sandbox $USER/site-init --hostname ''

And you can now cd to the templatesdir (in our case, /var/lib/templates/$USER/site-init) and start producing code there.

Importing your first templates

It’s now time for some Pan code! Let’s start by setting up the archetype. We’ll create a directory for the linux archetype, and put two Pan templates there: base and final.

Compiling the first host

Deploying the first configuration