= Automation Thing Without A Name =
Atwan automates the steps required to install an operating system on a server
or virtual machine, which may then be used as a gold image or template, and
setting up configuration management on the new (possibly cloned) host securely.
This is an extremely early release. A lot of functionality has not been worked
out and much is likely to change.
Currently Debian 7 (Wheezy) and CentOS 6.4 are supported.
DHCP is not supported because I'm lazy.
The trust model and the cryptography which supports it is very much
work-in-progress. Don't trust it.
== Overview ==
Atwan does not configure nodes on its own. It installs an operating system,
gives a new server its identity (ie. hostname) and sets up the software
necessary to be configured by a trusted 3rd party, eg. a puppet master or chef
server. The basic Atwan initialiser installs openssh with a known private key
(the public counterpart is saved locally so that it can be included in
known_hosts files) and includes specified user public keys in the new server's
/root/.ssh/authorized_keys file.
Plugins, explained below, are used to replace this method with one suitable for
Puppet, Chef or the CMDB of your choice.
# Prepare the installer. Change debian-7 to centos-6.4 (here and below) to
# install CentOS instead.
atwan gold-installer -r debian-7
# Use the installer to create the gold iamge.
MB=$((8 * 1024))
dd if=/dev/zero of=gold.img bs=1048576 seek=$(($MB - 1)) count=1
kvm -m 2048 -drive if=virtio,file=gold.img -cdrom goldimage-installer-debian-7.iso
# Prepare an ISO (*) signed using GPG which configures the gold image.
atwan initialiser -r debian-7 -n foo -i 10.0.0.5 -d 8.8.8.8
# Clone the gold image and initialise it.
dd if=gold.img of=foo.img bs=$((1048576 * 32))
kvm -m 2048 -drive if=virtio,file=foo.img -cdrom initialiser--foo.iso
# Or insert the CD using the qemu console after the VM is started:
> change ide1-cd0 initialiser--foo.iso
# Alternative nodes:
# Build a puppetmaster with the bootstrap (+) in $HOME/atwan/bootstrap
at_plugins=puppet atwan initialiser -r debian-7 -n bar -i 10.0.0.6 -d 8.8.8.8 \
-b -E $HOME/atwan/bootstrap
# Prepare an ISO which uses puppet.
# * The node will talk to the puppet master at puppetmaster.example.com
# * Atwan prepares keys using the puppet CA at puppetca.example.com
at_plugins=puppet atwan initialiser -r debian-7 -n bar -i 10.0.0.7 -d 8.8.8.8 \
-M puppetmaster.example.com -K puppetca.example.com
[*] Because VMWare.
[+] A tarball (or a directory from which a tarball is created) which is
extracted over /etc on the new server.
== Plugins ==
The script bin/atwan is, slightly by accident, a general tool which reads a
meta file describing a list of steps and the options with which to configure
them, then parses the command-line arguments and runs the defined steps in
sequence. Each step consists of a short section of bash code which is sourced
within the atwan shell environment.
A plugin system is unfortunately used to override the steps as appropriate for
different hardware and operating system platforms and configuration management
systems and it warrants some explanation, although it is the end result of
shaving a mighty yak.
* The first thing the bin/atwan script does is use the command which has been
called ($0), or the first argument if that is 'atwan', to determine which
sequence of steps to run.
* The newly-discovered name, with 'atwan-' stripped off the beginning if
it is there, is the name of the directory to look for at the top of each
plugin, in which is a file called 'meta' which is sourced by bash and
describes that process, or any changes the plugin is making to that process.
* The list of plugins to load is specified by the at_plugins environment
variable, which is a list of paths separated by a colon (:). Relative paths
are to the at_lib directory defined at the top of the script, which should
be changed during installation.
* The 'atwan' plugin is prepended to the list of plugins to load and defines
the base set of tasks required to automate whatever process is being
automated by that sequence of steps.
To find out what 'atwan foo' does, look at meta in $at_lib/atwan/foo
* If a particular operating system release requires further refinement to the
list of steps or changes, they are defined in a subdirectory of the plugin's
main process directory named after the value to the '-r' flag. This
directory must also contain a 'meta' file but is not parsed until after the
plugins are loaded, and critically its contents are not available when
displaying the usage statement.
== Gold Images ==
Atwan creates a gold image which is then cloned for each node. The gold image
includes a trusted gpg public key and looks for a signed package (usually a CD)
which includes a configuration script to run. The gold-installer command
downloads a vendor's installer, includes the gpg key and script, and modifies
it to install them and the operating system without user input.
The superuser password, gpg key and installer URL (and OS release) can all be
specified on the command-line.
The gold-installer command requires only that 'an initialiser' be installed on
the gold image. The atwan plugin's initialiser script is a sequence of shell
functions which are defined in initialiser.in files in each gold-installer
plugin used. Ultimately this sources (not executes) a signed script in the
initialiser package called autorun, built up by the components of the plugins'
initialiser steps.
== Initialiser ==
The initialiser command is very closely linked with the gold-installer command.
The script included on the gold image is built according to the plugins which
have been loaded, and so it is unlikely that an initialiser will be created
using a different set of plugins than the gold image for which it is destined.
The initialiser does whatever it needs to so that another device which it
trusts and which trusts it (ie. the puppet master, chef server, etc.) can take
it over. Usually this should just be to bring up the network, install the
appropriate client with its trust credentials (eg. signed keypair) and run it
but some other options can also be set:
* Authentication
* Logging
* Software/packaging
* Clock
* Entropy
* Filesystem
== Bootstrap ==
Clunky.