Debian Codegraph @

docs/src/cdist-preos.rst

raw
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.