Manually Activating an Aquilon Appliance

The appliance comes pre-seeded with only a very small amount of information - basically just a few different hardware models. In order to make use of the appliance you will need to provide some metadata describing your environment.

1. The first step is to define an archetype. An archetype is a library of rules that define how to provision a machine. You can create multiple archetypes (for example, a filer may have a very different way of being provisioned compared to a Linux server!). For now, you should create an archetype called "example-arch". Make sure you select "compilable"! Only compilable archetypes will produce configuration profiles. You may want to have non-compilable archetypes in order to reference hosts that are managed outside of Aquilon.

2. Secondly, you need to define a personality. The personality defines a specific use-case of a host. For now, you should create a personality called "app-server". Note that personalities are created within an archetype - the archetype we just created should be the default choice on this form.

3. An operating systems must then be defined (again, within an archetype - this means that an operating system for something like a filer is managed completely distinct from operating systems used within Linux builds). Give a name of "rhel" and a version of "5u5_x64".

4. Define a network. You can of course define as many networks as you want, however networks cannot overlap. You must specify the name of the network (a name that will be used within /etc/networks), the IP address and mask of the network, and a location (in the network_location_opts) of the network. For now you can provide your organization code to define the location. Leave the 'add_network_modifiers' options blank.

5. Defining a DNS domain is simple - just specify the domain name, with no extra information.

6. A hub is an Aquilon name referring to the support "center" of a region. Typically, a single "hub" will look after satellite offices or sites. For example, you might have a hub of "ln" (London) which looks after all of the machines in EMEA. Note that regions are not the same as continents (for example, the commonly used region EMEA - "Europe, Middle East, Africa"). Define the hub as your center of operations. You should use the drop-down box on the organization to select your previously defined organization. Important Note: the "fullname" of the hub must be a single alphanumeric word at the moment due to a bug which will cause problems for you later. You can use a non-alphanunmeric fullname but it will break later compiles, so don't do that!

7. A continent, country and city must be defined. Obviously these don't change much so why do you need to define them? Because of an implementation detail that declares all locations as a hierarchy (with continents as children of regions). It's something that should be fixed real soon but for now you just have to live with it. Define a continent corresponding to your location and put it in the appropriate hub. The name of the continent, country and cities are short codes (e.g. "eu"). Filling in the fullname here will make future forms and displays more descriptive, so put down the fullname of the continent (e.g. "Europe").

8. A building is where it starts to get a little more interesting. Buildings are really datacenters. They have names similar to the previous location types (a short code and a fullname). You could subdivide buildings further into floors and rooms but we won't be doing that in this initial installation.

9. All hosts must be placed into racks. A rack has an identifier which is a unique name based on the building code. For example, if you have a building called "bu" and you're creating the very first rack, then you may want the rack to be called "bu1". If you just put an id number (e.g. "1") as the rack ID then Aquilon will assign a name using the building code as a prefix. The racks typically have a row and column (each of which use alphanumeric identifiers). The row/column location is stored out within the final configuration profile, for use by monitoring tools and the like, but is not used within Aquilon itself. Remember this rack name because you'll be using it in the next step.

10. Finally we can start defining machines! Although the machine form has a lot of options, you can happily ignore most of them! The key is in picking a machine model that has been fully defined (i.e. with information such as number of CPU's, etc). For example, the bl260c is a machine model that has been defined fully as an example. If you pick a "complete" model such as this, then the only other required field is the machine name and it's location. The machine name is a label used to identify that specific piece of equipment (irrelevant of what DNS hostname it may pick up over time). You might choose to use the serial number. Or an asset code. Or just a sequence of names based on the building prefix. The location of the machine should be the rack that you defined in step 9 - change the "add_machine_chassis_opts" to say "rack" and then provide the value. Sorry there's no drop-down for this form at the moment, you have to remember the values...

11. Add a network interface to your newly defined machine. The interface name is typically something like "eth0". For now, define the MAC address and don't use automac, since we're leaving virtual hardware for later! Leave all the other options empty/default, including the IP address.

12. At this point you can create a host that will run on this hardware. You must provide a fully qualified hostname (and the domainname must be one of the DNS domains you created in step 5). Select the machine, archetype and personality using the drop-down selectors. You should give the branch domain of "prod" and give the host a meaningful IP address (again, this must be an IP within one of the networks you defined in step 4. You can fill in the options here defining more about the host (you can also leave them blank and fill them in later, but at some point you're going to have to do it, so just do it now). Provide an osname of "rhel" and an osversion of "5u5_x64" (the same values that we defined earlier). Leave the other fields blank.

13. Finally, build the host. Specify the hostname you just created in step 12. The options should all be left alone here (since you just declared them in step 12). If all has gone well, you should receive the compiler output saying that the host was compiled successfully.

14. You can now sync the datawarehouse to try it out. If you now go to the appliance homepage, select the "Sync Datawarehouse" button (again, this will at some point turn into an automatic event-based trigger, but for now...). This should immediately populate the datawarehouse and the appliance status page will include extra information about the state of the datawarehouse. Selecting "View the datawarehouse" will take you to a standard CouchDB/Futon view where you can browse the compiled configuration profiles.