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
|
# Netinstall module
|
||||||
|
|
||||||
The netinstall module allows distribution maintainers to ship minimal ISOs with
|
All of the actual documentation of the netinstall module has moved
|
||||||
only a basic set of preinstalled packages. At installation time, the user is
|
into the `netinstall.conf` file; since the configuration file **may**
|
||||||
presented with the choice to install groups of packages from a predefined list.
|
contain the groups-and-packages list itself, that format is
|
||||||
|
also described there.
|
||||||
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.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue