Merge branch 'issue-1227'
FIXES #1227 (Well, "fixes" .. documents the situation)
This commit is contained in:
Adriaan de Groot
commit
d3660436fe
@ -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.
|
||||
|
||||
@ -4,6 +4,13 @@
|
||||
# groupsUrl: http://example.org/netinstall.php
|
||||
# or it can be a locally installed file:
|
||||
# groupsUrl: file:///usr/share/calamares/netinstall.yaml
|
||||
#
|
||||
# Note that the contents of the groups file is the **inmportant**
|
||||
# part of the configuration of this module. It specifies what
|
||||
# the user may select and what commands are to be run.
|
||||
#
|
||||
# The format of the groups file is documented in `README.md`.
|
||||
#
|
||||
# groupsUrl: file:///usr/share/calamares/netinstall.yaml
|
||||
|
||||
# If the installation can proceed without netinstall (e.g. the Live CD
|
||||
|
||||
@ -1,3 +1,7 @@
|
||||
# Example configuration with groups and packages, taken from Chakra Linux.
|
||||
#
|
||||
# This example is rather limited. See `README.md` for full documentation
|
||||
# on the configuration format.
|
||||
- name: "Default"
|
||||
description: "Default group"
|
||||
hidden: true
|
||||
|
||||
@ -31,9 +31,9 @@ backend: dummy
|
||||
#
|
||||
# Set "update_db" to 'true' for refreshing the database on the
|
||||
# target system. On target installations, which got installed by
|
||||
# unsquashing, a full system update may be needed. Otherwise
|
||||
# unsquashing, a full system update may be needed. Otherwise
|
||||
# post-installing additional packages may result in conflicts.
|
||||
# Therefore set also "update_system" to 'true'.
|
||||
# Therefore set also "update_system" to 'true'.
|
||||
#
|
||||
skip_if_no_internet: false
|
||||
update_db: true
|
||||
@ -87,9 +87,25 @@ update_system: false
|
||||
# pre-script: touch /tmp/installing-vi
|
||||
# post-script: rm -f /tmp/installing-vi
|
||||
#
|
||||
# The pre- and post-scripts are optional, but you cannot leave both out: using
|
||||
# "package: vi" with neither script option will trick Calamares into
|
||||
# trying to install a package named "package: vi", which is unlikely to work.
|
||||
# The pre- and post-scripts are optional, but you cannot leave both out
|
||||
# if you do use the *package* key: using "package: vi" with neither script
|
||||
# option will trick Calamares into trying to install a package named
|
||||
# "package: vi", which is unlikely to work.
|
||||
#
|
||||
# The pre- and post-scripts are **not** executed by a shell unless you
|
||||
# explicitly invoke `/bin/sh` in them. The command-lines are passed
|
||||
# to exec(), which does not understand shell syntax. In other words:
|
||||
#
|
||||
# pre-script: ls | wc -l
|
||||
#
|
||||
# Will fail, because `|` is passed as a command-line argument to ls,
|
||||
# as are `wc`, and `-l`. No shell pipeline is set up, and ls is likely
|
||||
# to complain. Invoke the shell explicitly:
|
||||
#
|
||||
# pre-script: /bin/sh -c \"ls | wc -l\"
|
||||
#
|
||||
# The above note on shell-expansion applies to versions up-to-and-including
|
||||
# Calamares 3.2.12, but will change in future.
|
||||
#
|
||||
# Any package name may be localized; this is used to install localization
|
||||
# packages for software based on the selected system locale. By including
|
||||
@ -104,7 +120,7 @@ update_system: false
|
||||
#
|
||||
# Take care that just plain `LOCALE` will not be replaced, so `foo-LOCALE` will
|
||||
# be left unchanged, while `foo-$LOCALE` will be changed. However, `foo-LOCALE`
|
||||
# **will** be removed from the list of packages (i.e. not installed), if
|
||||
# **will** be removed from the list of packages (i.e. not installed), if
|
||||
# English is selected. If a non-English locale is selected, then `foo-LOCALE`
|
||||
# will be installed, unchanged (no language-name-substitution occurs).
|
||||
#
|
||||
|
||||
Loading…
Reference in New Issue
Block a user