cdist/docs/src/cdist-preos.rst

130 lines
3.9 KiB
ReStructuredText
Raw Normal View History

2019-09-20 05:15:37 +00:00
PreOS
=====
Description
-----------
With cdist you can install and configure new machines. You can use cdist to
2019-12-05 22:14:27 +00:00
create PreOS, minimal OS whose purpose is to boot a new machine.
After PreOS is booted, the machine is ready for installing the desired OS and
afterwards it is ready for configuration.
2019-09-20 05:15:37 +00:00
PreOS creation
--------------
With cdist you can create PreOS.
Currently supported PreOS-es include:
* debian
* ubuntu
2019-12-05 22:14:27 +00:00
* devuan
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
PreOS is created using the ``cdist preos`` command.
This command has subcommands that determine the desired PreOS.
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
For example, to create an ubuntu PreOS:
2019-09-20 05:15:37 +00:00
.. code-block:: sh
2019-09-20 17:56:17 +00:00
$ cdist preos ubuntu /preos/preos-ubuntu -B -C \
2019-09-20 05:15:37 +00:00
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu
2019-12-05 22:14:27 +00:00
For more info about the available options see the cdist manual page.
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
This will bootstrap (``-B``) ubuntu PreOS in the ``/preos/preos-ubuntu``
directory, it will be configured (``-C``) using default the built-in initial
manifest and with specified ssh authorized key (``-k``).
After bootstrapping and configuration, the PXE boot directory will be
created (``-p``) in ``/preos/pxe-ubuntu``.
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
After PreOS is created, new machines can be booted using the created PXE
(after proper dhcp and tftp settings).
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
Since PreOS is configured with ssh authorized key it can be accessed through
2019-09-20 05:15:37 +00:00
ssh, i.e. it can be further installed and configured with cdist.
2019-12-05 22:14:27 +00:00
Implementing a new PreOS sub-command
------------------------------------
2019-09-20 05:15:37 +00:00
preos command is implemented as a plugin system. This plugin system scans for
2019-12-05 22:14:27 +00:00
preos subcommands in the ``cdist/preos/`` distribution directory and also in
2019-09-20 05:15:37 +00:00
``~/.cdist/preos/`` directory if it exists.
preos subcommand is a module or a class that satisfies the following:
2019-12-05 22:14:27 +00:00
* it has the attribute ``_cdist_preos`` set to ``True``
* it defines a function/method ``commandline``.
2019-09-20 05:15:37 +00:00
2019-12-05 22:14:27 +00:00
For a module-based preos subcommand, the ``commandline`` function accepts a
module object as its first argument and the list of command line
2019-09-20 05:15:37 +00:00
arguments (``sys.argv[2:]``).
2019-12-05 22:14:27 +00:00
For a class-based preos subcommand ``commandline`` method should be
static-method and must accept a class as its first argument and the
list of command line arguments (``sys.argv[2:]``).
2019-09-20 05:15:37 +00:00
If preos scanning finds a module/class that has ``_cdist_preos`` set
2019-12-05 22:14:27 +00:00
to ``True`` and a function/method ``commandline`` then this module/class is
2019-09-20 05:15:37 +00:00
registered to preos subcommands. The name of the command is set to ``_preos_name``
2019-12-05 22:14:27 +00:00
attribute if defined in the module/class, defaulting to the module/class name in lowercase.
When a registered preos subcommand is specified, ``commandline``
will be called with the first argument set to module/class and the second
argument set to ``sys.argv[2:]``.
Example of writing new dummy preos sub-command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module-based preos:
2019-09-20 05:15:37 +00:00
^^^^^^^^^^^^^^^^^^^
#. Create directory ``~/.cdist/preos/`` if it does not exist
#. Create ``~/.cdist/preos/netbsd.py`` with the following contents:
.. code-block:: python
_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:
.. code-block:: sh
2019-12-06 18:40:05 +00:00
$ cdist preos -L
Available PreOS-es:
- debian
- devuan
- netbsd
- ubuntu
2019-09-20 05:15:37 +00:00
$ cdist preos netbsd
NetBSD PreOS: []
Class based preos:
^^^^^^^^^^^^^^^^^^
#. Create directory ``~/.cdist/preos/`` if it does not exist
#. Create ``~/.cdist/preos/freebsd.py`` with the following contents:
.. code-block:: python
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:
.. code-block:: sh
$ cdist preos -h
2019-12-06 18:40:05 +00:00
Available PreOS-es:
- debian
- devuan
- freebsd
- ubuntu
2019-09-20 05:15:37 +00:00
$ cdist preos freebsd
FreeBSD dummy preos: []
In the ``commandline`` function/method you have all the freedom to actually create
2019-12-05 22:14:27 +00:00
a PreOS.