| 1 |
PreOS |
| 2 |
===== |
| 3 |
|
| 4 |
Description |
| 5 |
----------- |
| 6 |
With cdist you can install and configure new machines. You can use cdist to |
| 7 |
create PreOS, minimal OS whose purpose is to boot a new machine. |
| 8 |
After PreOS is booted, the machine is ready for installing the desired OS and |
| 9 |
afterwards it is ready for configuration. |
| 10 |
|
| 11 |
PreOS creation |
| 12 |
-------------- |
| 13 |
With cdist you can create PreOS. |
| 14 |
Currently supported PreOS-es include: |
| 15 |
|
| 16 |
* debian |
| 17 |
* ubuntu |
| 18 |
* devuan |
| 19 |
|
| 20 |
PreOS is created using the ``cdist preos`` command. |
| 21 |
This command has subcommands that determine the desired PreOS. |
| 22 |
|
| 23 |
For example, to create an ubuntu PreOS: |
| 24 |
|
| 25 |
.. code-block:: sh |
| 26 |
|
| 27 |
$ cdist preos ubuntu /preos/preos-ubuntu -B -C \ |
| 28 |
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu |
| 29 |
|
| 30 |
For more info about the available options see the cdist manual page. |
| 31 |
|
| 32 |
This will bootstrap (``-B``) ubuntu PreOS in the ``/preos/preos-ubuntu`` |
| 33 |
directory, it will be configured (``-C``) using default the built-in initial |
| 34 |
manifest and with specified ssh authorized key (``-k``). |
| 35 |
After bootstrapping and configuration, the PXE boot directory will be |
| 36 |
created (``-p``) in ``/preos/pxe-ubuntu``. |
| 37 |
|
| 38 |
After PreOS is created, new machines can be booted using the created PXE |
| 39 |
(after proper dhcp and tftp settings). |
| 40 |
|
| 41 |
Since PreOS is configured with ssh authorized key it can be accessed through |
| 42 |
ssh, i.e. it can be further installed and configured with cdist. |
| 43 |
|
| 44 |
Implementing a new PreOS sub-command |
| 45 |
------------------------------------ |
| 46 |
preos command is implemented as a plugin system. This plugin system scans for |
| 47 |
preos subcommands in the ``cdist/preos/`` distribution directory and also in |
| 48 |
``~/.cdist/preos/`` directory if it exists. |
| 49 |
|
| 50 |
preos subcommand is a module or a class that satisfies the following: |
| 51 |
|
| 52 |
* it has the attribute ``_cdist_preos`` set to ``True`` |
| 53 |
* it defines a function/method ``commandline``. |
| 54 |
|
| 55 |
For a module-based preos subcommand, the ``commandline`` function accepts a |
| 56 |
module object as its first argument and the list of command line |
| 57 |
arguments (``sys.argv[2:]``). |
| 58 |
|
| 59 |
For a class-based preos subcommand ``commandline`` method should be |
| 60 |
static-method and must accept a class as its first argument and the |
| 61 |
list of command line arguments (``sys.argv[2:]``). |
| 62 |
|
| 63 |
If preos scanning finds a module/class that has ``_cdist_preos`` set |
| 64 |
to ``True`` and a function/method ``commandline`` then this module/class is |
| 65 |
registered to preos subcommands. The name of the command is set to ``_preos_name`` |
| 66 |
attribute if defined in the module/class, defaulting to the module/class name in lowercase. |
| 67 |
When a registered preos subcommand is specified, ``commandline`` |
| 68 |
will be called with the first argument set to module/class and the second |
| 69 |
argument set to ``sys.argv[2:]``. |
| 70 |
|
| 71 |
Example of writing new dummy preos sub-command |
| 72 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 73 |
Module-based preos: |
| 74 |
^^^^^^^^^^^^^^^^^^^ |
| 75 |
|
| 76 |
#. Create directory ``~/.cdist/preos/`` if it does not exist |
| 77 |
#. Create ``~/.cdist/preos/netbsd.py`` with the following contents: |
| 78 |
|
| 79 |
.. code-block:: python |
| 80 |
|
| 81 |
_preos_name = 'netbsd' |
| 82 |
_cdist_preos = True |
| 83 |
|
| 84 |
def commandline(cls, args): |
| 85 |
print("NetBSD PreOS: {}".format(args)) |
| 86 |
|
| 87 |
When you try to run this new preos you will get: |
| 88 |
|
| 89 |
.. code-block:: sh |
| 90 |
|
| 91 |
$ cdist preos -L |
| 92 |
Available PreOS-es: |
| 93 |
- debian |
| 94 |
- devuan |
| 95 |
- netbsd |
| 96 |
- ubuntu |
| 97 |
$ cdist preos netbsd |
| 98 |
NetBSD PreOS: [] |
| 99 |
|
| 100 |
Class based preos: |
| 101 |
^^^^^^^^^^^^^^^^^^ |
| 102 |
|
| 103 |
#. Create directory ``~/.cdist/preos/`` if it does not exist |
| 104 |
#. Create ``~/.cdist/preos/freebsd.py`` with the following contents: |
| 105 |
|
| 106 |
.. code-block:: python |
| 107 |
|
| 108 |
class FreeBSD(object): |
| 109 |
_cdist_preos = True |
| 110 |
|
| 111 |
@classmethod |
| 112 |
def commandline(cls, args): |
| 113 |
print("FreeBSD dummy preos: {}".format(args)) |
| 114 |
|
| 115 |
When you try to run this new preos you will get: |
| 116 |
|
| 117 |
.. code-block:: sh |
| 118 |
|
| 119 |
$ cdist preos -h |
| 120 |
Available PreOS-es: |
| 121 |
- debian |
| 122 |
- devuan |
| 123 |
- freebsd |
| 124 |
- ubuntu |
| 125 |
$ cdist preos freebsd |
| 126 |
FreeBSD dummy preos: [] |
| 127 |
|
| 128 |
In the ``commandline`` function/method you have all the freedom to actually create |
| 129 |
a PreOS. |