18. PreOS

18.1. Description

With cdist you can install and configure new machines. You can use cdist to create PreOS, minimal OS which purpose is to boot new machine. After PreOS is booted machine is ready for installing desired OS and then it is ready for configuration.

18.2. PreOS creation

With cdist you can create PreOS. Currently supported PreOS-es include:

  • debian
  • ubuntu.

PreOS is created using cdist preos command. preos command has subcommands that create the desired PreOS.

For example, to create ubuntu PreOS:

$ cdist preos ubuntu /preos/preos-ubuntu -b -C \
    -k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu \
    -t "/usr/bin/curl 192.168.111.5:3000/install/"

For more info about available options see cdist manual page.

This will bootstrap (-b) ubuntu PreOS in /preos/preos-ubuntu directory, it will be configured (-C) using default built-in initial manifest and with specified ssh authorized key (-k) and with specified trigger command (-t). After bootstrapping and configuration PXE boot directory will be created (-p) in /preos/pxe-ubuntu.

After PreOS is created new machines can be booted using created PXE (after proper dhcp, tftp setting).

Since PreOS is configured with ssh authorized key it can be accessed throguh ssh, i.e. it can be further installed and configured with cdist.

18.3. Triggering installation/configuration

When installing and configuring new machines using cdist's PreOS concept cdist also supports triggering for host installation/configuration. At management node you start trigger server as:

$ cdist trigger -b -v -i ~/.cdist/manifest/init-for-triggered

This will start cdist trigger server in verbose mode. It accepts simple requests for configuration and for installation:

  • /install/.* for installation
  • /config/.* for configuration.

When new machine is booted with PreOS then trigger command is executed. Machine will connect to cdist trigger server. If the request is, for example, for installation then cdist trigger server will start install command for the client host using parameters specified at trigger server startup. For the above example that means that client will be installed using specified initial manifest ~/.cdist/manifest/init-for-triggered.

18.4. Implementing new PreOS sub-command

preos command is implemented as a plugin system. This plugin system scans for preos subcommands in cdist/preos/ distribution directory and also in ~/.cdist/preos/ directory if it exists.

preos subcommand is a module or a class that satisfies the following:

  • it has attribute _cdist_preos set to True
  • it has function/method commandline.

For a module based preos subcommand commandline function accepts a module object as its first argument and the list of command line arguments (sys.argv[2:]).

For a class preos subcommand commandline method should be staticmethod and it accepts a class object as its first argument and the list of command line arguments(sys.argv[2:]).

If preos scanning finds a module/class that has _cdist_preos set to True and it has function/method commandline then this module/class is registered to preos subcommands. The name of the command is set to _preos_name attribute if it exists, otherwise it is set to the module/class name, lowercase. When registered preos subcommand is specified as preos command then commandline will be called with first argument set to module/class object and second argument set to sys.argv[2:].

18.4.1. Example writing new dummy preos sub-command

18.4.1.1. Module based preos:

  1. Create directory ~/.cdist/preos/ if it does not exist
  2. Create ~/.cdist/preos/netbsd.py with the following contents:
_preos_name = 'netbsd'
_cdist_preos = True

def commandline(cls, args):
    print("NetBSD PreOS: {}".format(args))

When you try to run this new preos you will get:

$ cdist preos -h
usage: cdist preos [-h] preos

Create PreOS

positional arguments:
  preos       PreOS to create, one of: {'netbsd', 'debian', 'ubuntu'}

optional arguments:
  -h, --help  show this help message and exit
$ cdist preos netbsd
NetBSD PreOS: []

18.4.1.2. Class based preos:

  1. Create directory ~/.cdist/preos/ if it does not exist
  2. Create ~/.cdist/preos/freebsd.py with the following contents:
class FreeBSD(object):
    _cdist_preos = True

    @classmethod
    def commandline(cls, args):
        print("FreeBSD dummy preos: {}".format(args))

When you try to run this new preos you will get:

$ cdist preos -h
usage: cdist preos [-h] preos

Create PreOS

positional arguments:
  preos       PreOS to create, one of: {'freebsd', 'debian', 'ubuntu'}

optional arguments:
  -h, --help  show this help message and exit
$ cdist preos freebsd
FreeBSD dummy preos: []

In the commandline function/method you have all the freedom to actually create PreOS.

18.5. Simple tipical use case for using PreOS and trigger

Tipical use case for using PreOS and trigger command include the following steps.

  1. Create PreOS PXE with ssh key and trigger command for installation.

    $ cdist preos ubuntu /preos/ubuntu -b -C \
    -k ~/.ssh/id_rsa.pub -p /preos/pxe \
    -t "/usr/bin/curl 192.168.111.5:3000/install/"

  2. Configure dhcp server and tftp server.

  3. On cdist host (192.168.111.5 from above) start trigger command (it will use default init manifest for installation).

    $ cdist trigger -b -v

  4. After all is set up start new machines (PXE boot).

  5. New machine boots and executes trigger command, i.e. triggers installation.

  6. Cdist trigger server starts installing host that has triggered it.

  7. After cdist install is finished new host is installed.