mirror of https://github.com/cutefishos/calamares
[netinstall] Hit the docs with a hammer
- Merge all the format documentation into netinstall.conf, where the example is given in full as an embedded *groups* entry. - Get README.md to point to the example. - Fix up headers in netinstall.yaml, pointing to the embedded example in netinstall.conf.main
Adriaan de Groot
6 years ago
parent
cd66405363
commit
7b4b268875
@ -1,127 +1,6 @@
|
||||
# Netinstall module
|
||||
|
||||
The netinstall module allows distribution maintainers to ship minimal ISOs with
|
||||
only a basic set of preinstalled packages. At installation time, the user is
|
||||
presented with the choice to install groups of packages from a predefined list.
|
||||
|
||||
Calamares will then use the *packages* module to install the packages.
|
||||
|
||||
|
||||
## Module Configuration
|
||||
|
||||
The `netinstall.conf` file is self-describing, and at the very
|
||||
least should contain a *groupsUrl* key:
|
||||
|
||||
```
|
||||
----
|
||||
groupsUrl: <URL to YAML file>
|
||||
```
|
||||
|
||||
The URL must point to a YAML file, the *groups* file. See below for
|
||||
the format of that groups file. The URL may be a local file (e.g.
|
||||
scheme `file:///`) or a regular HTTP(s) URL. The URL has one special
|
||||
case: the literal string `local` is used to indicate that the groups
|
||||
data is contained in the `netinstall.conf` file itself.
|
||||
|
||||
|
||||
## Groups Configuration
|
||||
|
||||
Here is a short example of how the YAML file should look.
|
||||
|
||||
```
|
||||
- name: "Group name"
|
||||
description: "Description of the group"
|
||||
packages:
|
||||
- lsb-release
|
||||
- avahi
|
||||
- grub
|
||||
- name: "Second group name"
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
The file is composed of a list of entries, each describing one group. The
|
||||
keys *name*, *description* and *packages* are required for each group.
|
||||
|
||||
More keys (per group) are supported:
|
||||
|
||||
- *hidden*: if true, do not show the group on the page. Defaults to false.
|
||||
- *selected*: if true, display the group as selected. Defaults to false.
|
||||
- *critical*: if true, make the installation process fail if installing
|
||||
any of the packages in the group fails. Otherwise, just log a warning.
|
||||
Defaults to false. If not set in a subgroup (see below), inherits from
|
||||
the parent group.
|
||||
- *immutable*: if true, the state of the group (and all its subgroups)
|
||||
cannot be changed; it really only makes sense in combination
|
||||
with *selected* set to true. This only affects the user-interface.
|
||||
- *expanded*: if true, the group is shown in an expanded form (that is,
|
||||
not-collapsed) in the treeview on start. This only affects the user-
|
||||
interface. Only top-level groups are show expanded-initially.
|
||||
- *immutable*: if true, the group cannot be changed (packages selected
|
||||
or deselected) and no checkboxes are shown for the group.
|
||||
- *subgroups*: if present this follows the same structure as the top level
|
||||
of the YAML file, allowing there to be sub-groups of packages to an
|
||||
arbitary depth
|
||||
- *pre-install*: an optional command to run within the new system before
|
||||
the group's packages are installed. It will run before each package in
|
||||
the group is installed.
|
||||
- *post-install*: an optional command to run within the new system after
|
||||
the group's packages are installed. It will run after each package in
|
||||
the group is installed.
|
||||
|
||||
If you set both *hidden* and *selected* for a group, you are basically creating
|
||||
a "default" group of packages which will always be installed in the user's
|
||||
system.
|
||||
|
||||
> The note below applies to Calamares up-to-and-including 3.2.13, but will
|
||||
> change in a later release.
|
||||
|
||||
The *pre-install* and *post-install* commands are **not** passed to
|
||||
a shell; see the **packages** module configuration (i.e. `packages.conf`)
|
||||
for details. To use a full shell pipeline, call the shell explicitly.
|
||||
|
||||
|
||||
|
||||
## Overall Configuration
|
||||
|
||||
Here is the set of instructions to have the module work in your Calamares.
|
||||
|
||||
First, if the module is used, we need to require a working Internet connection,
|
||||
otherwise the module will be unable to fetch the package groups and to perform
|
||||
the installation. Requirements for the Calamares instance are configured in the
|
||||
`welcome.conf` file (configuration for the **welcome** module). Make sure
|
||||
*internet* is listed under the *required* checks.
|
||||
|
||||
In the `settings.conf` file, decide where the **netinstall** page should be
|
||||
displayed. I put it just after the **welcome** page, but any position between
|
||||
that and just before **partition** should make no difference.
|
||||
|
||||
If not present, add the **packages** job in the *exec* list. This is the job
|
||||
that calls the package manager to install packages. Make sure it is configured
|
||||
to use the correct package manager for your distribution; this is configured in
|
||||
`packages.conf`.
|
||||
|
||||
The *exec* list in `settings.conf` should contain the following items in
|
||||
order (it's ok for other jobs to be listed inbetween them, though):
|
||||
|
||||
```
|
||||
- unpackfs
|
||||
- networkcfg
|
||||
- packages
|
||||
```
|
||||
|
||||
**unpackfs** creates the chroot where the installation is performed, and unpacks
|
||||
the root image with the filesystem structure; **networkcfg** set ups a working
|
||||
network in the chroot; and finally **packages** can install packages in the
|
||||
chroot.
|
||||
|
||||
## Common issues
|
||||
|
||||
If launching the package manager command returns you negative exit statuses and
|
||||
nothing is actually invoked, this is likely an error in the setup of the chroot;
|
||||
check that the parameter **rootMountPoint** is set to the correct value in the
|
||||
Calamares configuration.
|
||||
|
||||
If the command is run, but exits with error, check that the network is
|
||||
working in the chroot. Make sure `/etc/resolv.conf` exists and that
|
||||
it's not empty.
|
||||
All of the actual documentation of the netinstall module has moved
|
||||
into the `netinstall.conf` file; since the configuration file **may**
|
||||
contain the groups-and-packages list itself, that format is
|
||||
also described there.
|
||||
|
||||
Loading…
Reference in New Issue