[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.
This commit is contained in:
Adriaan de Groot
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.
|
||||
|
||||
@ -1,15 +1,58 @@
|
||||
### 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.
|
||||
# Without a *packages* module in the exec phase somewhere **after**
|
||||
# this netinstall, nothing will actually get installed. The packages
|
||||
# module must be correctly configured **and** the package manager must
|
||||
# be runnable from within the installed system at the point where it
|
||||
# is invoked, otherwise you'll get nothing.
|
||||
#
|
||||
# There are two basic deployment schemes:
|
||||
# - static package lists; the packages do not change for this release.
|
||||
# In this case, the package list file may be on the ISO-image itself
|
||||
# as a separate file, **or** included in this configuration file.
|
||||
# Either will do; separate file is easier to update independently
|
||||
# of the Calamares configuration, while merged configurations use
|
||||
# fewer files overall and are closer to self-documenting.
|
||||
# - online package lists; the package list is fetched from a remote
|
||||
# URL and handled otherwise like a static list. This can be useful
|
||||
# if the package list needs updating during the lifetime of an ISO-
|
||||
# image, e.g. packages are added or renamed.
|
||||
#
|
||||
# There is only one required key for this module, *groupsUrl*.
|
||||
#
|
||||
# This module supports multiple instances through the *label* key,
|
||||
# which allows you to distinguish them in the UI.
|
||||
---
|
||||
# This is the URL that is retrieved to get the netinstall groups-and-packages
|
||||
# data (which should be in the format described in netinstall.yaml), e.g.:
|
||||
# ```
|
||||
# groupsUrl: http://example.org/netinstall.php
|
||||
# ```
|
||||
# or it can be a locally installed file:
|
||||
# ```
|
||||
# groupsUrl: file:///usr/share/calamares/netinstall.yaml
|
||||
# ```
|
||||
# or it can be the special-case literal string "local":
|
||||
# ```
|
||||
# groupsUrl: local
|
||||
# ```
|
||||
#
|
||||
# Note that the contents of the groups file is the **important**
|
||||
# part of the configuration of this module. It specifies what
|
||||
# the user may select and what commands are to be run.
|
||||
# groups and packages the user may select (and so what commands are to
|
||||
# be run to install them).
|
||||
#
|
||||
# The format of the groups file is documented in `README.md`.
|
||||
# The format of the groups file is the same as the format of the
|
||||
# *groups* key described below, **except** that a stand-alone
|
||||
# groups file does not have the top-level *groups* key.
|
||||
#
|
||||
# TODO: remove that ^^ restriction
|
||||
#
|
||||
# As a special case, setting *groupsUrl* to the literal string
|
||||
# `local` means that the data is obtained from **this** config
|
||||
@ -24,10 +67,13 @@ groupsUrl: local
|
||||
#
|
||||
# This only has an effect if the netinstall data cannot be retrieved,
|
||||
# or is corrupt: having "required" set, means the install cannot proceed.
|
||||
# For local or file: type *groupsUrl* settings, this setting is not
|
||||
# really meaningful.
|
||||
required: false
|
||||
|
||||
# To support multiple instances of this module,
|
||||
# some strings are configurable and translatable here.
|
||||
# Sub-keys under *label* are used for the user interface.
|
||||
# - *sidebar* This is the name of the module in the progress-tree / sidebar
|
||||
# in Calamares.
|
||||
# - *title* This is displayed above the list of packages.
|
||||
@ -35,6 +81,10 @@ required: false
|
||||
# and existing translations. If no *title* values are provided, no string
|
||||
# is displayed.
|
||||
#
|
||||
# Translations are handled through [cc] notation, much like in
|
||||
# `.desktop` files. The string `key[cc]` is used for *key* when
|
||||
# when the language *cc* (country-code, like *nl* or *en_GB*) is used.
|
||||
#
|
||||
# The following strings are already known to Calamares and can be
|
||||
# listed here in *untranslated* form (e.g. as value of *sidebar*)
|
||||
# without bothering with the translations: they are picked up from
|
||||
@ -45,6 +95,19 @@ required: false
|
||||
# - "Browser software"
|
||||
# - "Browser package"
|
||||
# - "Web browser"
|
||||
# - "Kernel"
|
||||
# - "Services"
|
||||
# - "Login"
|
||||
# - "Desktop"
|
||||
# - "Applications"
|
||||
# - "Communication"
|
||||
# - "Development"
|
||||
# - "Office"
|
||||
# - "Multimedia"
|
||||
# - "Internet"
|
||||
# - "Theming"
|
||||
# - "Gaming"
|
||||
# - "Utilities"
|
||||
label:
|
||||
sidebar: "Package selection"
|
||||
# sidebar[nl]: "Pakketkeuze"
|
||||
@ -53,12 +116,87 @@ label:
|
||||
|
||||
# If, and only if, *groupsUrl* is set to the literal string `local`,
|
||||
# groups data is read from this file. The value of *groups* must be
|
||||
# a list, with the same format as the regular `netinstall.yaml` file.
|
||||
# See the `README.md` file in the *netinstall* module for documentation
|
||||
# on the format of groups data.
|
||||
# a list. Each item in the list is a group (of packages, or subgroups,
|
||||
# or both). A standalone groups file contains just the list,
|
||||
# without the top-level *groups* key.
|
||||
#
|
||||
# This is recommended only for small static package lists.
|
||||
# TODO: remove that restriction ^^
|
||||
#
|
||||
# Using `local` is recommended only for small static package lists.
|
||||
# Here it is used for documentation purposes.
|
||||
#
|
||||
#
|
||||
### Groups Format
|
||||
#
|
||||
# Each item in the list describes one group. The following keys are
|
||||
# required for each group:
|
||||
#
|
||||
# - *name* of the group; short and human-readable. Shown in the first
|
||||
# column of the UI.
|
||||
# - *description* of the group; longer and human-readable. Shown in the
|
||||
# second column of the UI. This is one of the things that visually
|
||||
# distinguishes groups (with descriptions) from packages (without).
|
||||
# - *packages*, a list of packages that belong to this group.
|
||||
# The items of the *packages* list are actual package names
|
||||
# as passed to the package manager (e.g. `qt5-creator-dev`).
|
||||
# This list may be empty (e.g. if your group contains only
|
||||
# subgroups). This key isn't **really** required, either --
|
||||
# one of *subgroups* or *packages* is.
|
||||
#
|
||||
# The following keys are **optional** for a group:
|
||||
#
|
||||
# - *hidden*: if true, do not show the group on the page. Defaults to false.
|
||||
# - *selected*: if true, display the group as selected. Defaults to the
|
||||
# parent group's value, if there is a parent group; top-level groups
|
||||
# are set to true by default.
|
||||
# - *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
|
||||
# groups, allowing 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. Setting *hidden* to true without *selected*, or with
|
||||
# *selected* set to false, is kind of pointless.
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# Non-critical groups are installed by calling the package manager
|
||||
# individually, once for each package (and ignoring errors), while
|
||||
# critical packages are installed in one single call to the package
|
||||
# manager (and errors cause the installation to terminate).
|
||||
#
|
||||
#
|
||||
#
|
||||
# The *groups* key below contains some common patterns for packages
|
||||
# and sub-groups, with documentation.
|
||||
|
||||
|
||||
groups:
|
||||
# This group is hidden, so the name and description are not really
|
||||
# important. Since it is selected, these packages will be installed.
|
||||
# It's non-critical, so they are installed one-by-one.
|
||||
#
|
||||
# This is a good approach for something you want up-to-date installed
|
||||
# in the target system every time.
|
||||
- name: "Default"
|
||||
description: "Default group"
|
||||
hidden: true
|
||||
@ -67,6 +205,15 @@ groups:
|
||||
packages:
|
||||
- base
|
||||
- chakra-live-skel
|
||||
# The Shells group contains only subgroups, no packages itself.
|
||||
# The *critical* value is set for the subgroups that do not
|
||||
# override it; *selected* is set to false but because one of
|
||||
# the subgroups sets *selected* to true, the overall state of
|
||||
# **this** group is partly-selected.
|
||||
#
|
||||
# Each of the sub-groups lists a bunch of packages that can
|
||||
# be individually selected, so a user can pick (for instance)
|
||||
# just one of the ZSH packages if they like.
|
||||
- name: "Shells"
|
||||
description: "Shells"
|
||||
hidden: false
|
||||
@ -85,6 +232,11 @@ groups:
|
||||
- zsh
|
||||
- zsh-completion
|
||||
- zsh-extensions
|
||||
# The kernel group has no checkbox, because it is immutable.
|
||||
# It can be (manually) expanded, and the packages inside it
|
||||
# will be shown, also without checkboxes. This is a way to
|
||||
# inform users that something will always be installed,
|
||||
# sort of like a hidden+selected group but visible.
|
||||
- name: "Kernel"
|
||||
description: "Kernel bits"
|
||||
hidden: false
|
||||
@ -95,6 +247,7 @@ groups:
|
||||
- kernel
|
||||
- kernel-debugsym
|
||||
- kernel-nvidia
|
||||
# *selected* defaults to true for top-level
|
||||
- name: Communications
|
||||
description: "Communications Software"
|
||||
packages:
|
||||
@ -102,3 +255,56 @@ groups:
|
||||
- konversation
|
||||
- nheko
|
||||
- quaternion
|
||||
# Setting *selected* is supported.
|
||||
- name: Editors
|
||||
description: "Editing"
|
||||
selected: false
|
||||
packages:
|
||||
- vi
|
||||
- emacs
|
||||
- nano
|
||||
# The "bare" package names can be intimidating, so you can use subgroups
|
||||
# to provide human-readable names while hiding the packages themselves.
|
||||
# This also allows you you group related packages -- suppose you feel
|
||||
# that KDevelop should be installed always with PHP and Python support,
|
||||
# but that support is split into multiple packages.
|
||||
#
|
||||
# So this subgroup (IDE) contains subgroups, one for each "package"
|
||||
# we want to install. Each of those subgroups (Emacs, KDevelop)
|
||||
# in turn contains **one** bogus subgroup, which then has the list
|
||||
# of relevant packages. This extra-level-of-subgrouping allows us
|
||||
# to list packages, while giving human-readable names.
|
||||
#
|
||||
# The name of the internal subgroup doesn't matter -- it is hidden
|
||||
# from the user -- so we can give them all bogus names and
|
||||
# descriptions, even the same name. Here, we use "bogus".
|
||||
#
|
||||
# Each internal subgroup is set to *hidden*, so it does not show up
|
||||
# as an entry in the list, and it is set to *selected*,
|
||||
# so that if you select its parent subgroup.
|
||||
- name: IDE
|
||||
description: "Development Environment"
|
||||
selected: false
|
||||
subgroups:
|
||||
- name: Emacs
|
||||
description: LISP environment and editor
|
||||
subgroups:
|
||||
- name: Bogus
|
||||
description: Bogus
|
||||
hidden: true
|
||||
selected: true
|
||||
packages:
|
||||
- emacs
|
||||
- name: KDevelop
|
||||
description: KDE's C++, PHP and Python environment
|
||||
subgroups:
|
||||
- name: Bogus
|
||||
description: Bogus
|
||||
hidden: true
|
||||
selected: true
|
||||
packages:
|
||||
- kdevelop
|
||||
- kdevelop-dev
|
||||
- kdev-php
|
||||
- kdev-python
|
||||
|
||||
|
||||
@ -1,7 +1,15 @@
|
||||
# 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.
|
||||
# This example is rather limited. See `netinstall.conf` for full documentation
|
||||
# on the configuration format. The module configuration file `netinstall.conf`
|
||||
# **may** contain the package-list, but that is only useful for static
|
||||
# package-lists. If you are updating the package lists or changing the package
|
||||
# offerings, an online `netinstall.yaml` is the way to go; or you can put the
|
||||
# `netinstall.yaml` on the installation media and modify that, while keeping
|
||||
# your Calamares configuration constant.
|
||||
#
|
||||
# Which approach works depends on what you want to offer and how your
|
||||
# ISO-image toolchain works.
|
||||
- name: "Default"
|
||||
description: "Default group"
|
||||
hidden: true
|
||||
|
||||
Loading…
Reference in New Issue
Block a user