napcok/calamares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[netinstall] Polish the README

Browse Source 
- describe the format better
 - more consistent typography
 - refer to `packages.conf` for details on shell commands
This commit is contained in:
Adriaan de Groot 2019-08-26 16:26:06 +02:00
parent ee29c45433
commit 56792fdcb5
1 changed files with 82 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
src/modules/netinstall/README.md
View File

@ -1,86 +1,116 @@
# Netinstall module
The netinstall module allows distribution maintainers to ship minimal ISOs with only a basic set of preinstall packages.
At installation time, the user is presented with the choice to install groups of packages from a predefined list.
The netinstall module allows distribution maintainers to ship minimal ISOs with
only a basic set of preinstall packages. At installation time, the user is
presented with the choice to install groups of packages from a predefined list.
Calamares will then invoke the correct backend to install the packages.
## Configuration of the packages
Every distribution can choose which groups to display and which packages should be in the groups.
## Module Configuration
The *netinstall.conf* file should have this format:
The `netinstall.conf` file is self-describing, and at the very
lease should contain a *groupsUrl* key:
```
----
groupsUrl: <URL to YAML file>
```
The URL must point to a YAML file. Here is a short example of how the YAML file should look.
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.
- name: "Group name"
description: "Description of the group"
packages:
- lsb-release
- avahi
- grub
- name: "Second group name"
## 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 entry, each describing one group. The keys *name*, *description* and *packages* are required.
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 are supported:
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.
- 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.
- *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.
- *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.
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.
## Configuration of the module
> The note below applies to Calamares up-to-and-including 3.2.13, but will
> change in a later release.
Here is the set of instructions to have the module work in your Calamares. As of July 2016, this has been successfully
tested using the live installation of Chakra Fermi.
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.
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 below *required*.
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 src/modules/packages/packages.conf.
## Overall Configuration
The **exec** list in *settings.conf* should contain the following items in
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.
**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 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.
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.