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
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
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.
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
commands. Most of the commands we’ll use have
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).
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
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.
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'
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'
Once we have the hardware in place, it’s time to declare the networks our hosts live in.
We’ll use the
aq add_network --network 'leaks' --ip '192.168.1.0' --netmask '255.255.255.0' --city 'metropolis' aq add_network --network 'reporters' --ip '192.168.100.0' --netmask '255.255.255.0' --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.
network_unknown section, and declare the default gateway offset.
[network_unknown] default_gateway_offset=30 reserved_offsets=1,30,25 first_usable_offset=40
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 '192.168.100.3' --fqdn 'router.reporters.metropolis.com'
If your network is an internal one (the default), some restrictions apply:
- Routers must be part of the
- 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.
Our network has some DNS domains. We have to add them:
aq add_dns_domain --dns_domain 'dailyplanet.com'
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
Personalities are collections of smaller chunks called features. A
feature is re-usable in many contexts, by different personalities,
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,
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
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
aq add_host --hostname 'tapping.dailyplanet.com' --machine 'illegaltapper' --ip '192.168.1.3' --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 'tapping.dailyplanet.com'
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: