# SPDX-FileCopyrightText: no # SPDX-License-Identifier: CC0-1.0 # ### 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. --- # The *groupsUrl* determines where the data for the netinstall groups-and- # packages comes from. The value of the key may be: # # - a single string (this is treated as a list with just that string in it) # - a list of strings # # Each string is treated as a URL (see below for special cases. The # list is examined **in order** and each URL is tried in turn. The # first URL to load successfully -- even if it yields 0 packages -- # ends the process. This allows using a network URL and a (fallback) # local URL for package lists, or for using multiple mirrors of # netinstall data. # # The URL must point to a YAML file that follows the format described # below at the key *groups* -- except for the special case URL "local". # Note that the contents of the groups file is the **important** # part of the configuration of this module. It specifies what # 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 the same as the format of the # *groups* key described below, **except** that a stand-alone # groups file does not have to have the top-level *groups* key. # (It **may** have one, though, for instance when you copy # this configuration file to `netinstall.yaml` and key *groups* # must have a list-of-groups as value; if the file does not have # a top-level key *groups*, then the file must contain only a list of groups. # # Each item in the list *groupsUrl* may be: # - A remote URL like `http://example.org/netinstall.php` # - A local file URL like `file:///usr/share/calamares/netinstall.yaml` # - The special-case literal string `local` # # Non-special case URLs are loaded as YAML; if the load succeeds, then # they are interpreted like the *groups* key below. The special case # `local` loads the data directly from **this** file. # groupsUrl: local # Alternate form: # groupsUrl: [ local ] # Net-based package list, with fallback to local file # groupsUrl: # - http://example.com/calamares/netinstall.yaml # - file:///etc/calamares/modules/netinstall.yaml # If the installation can proceed without netinstall (e.g. the Live CD # can create a working installed system, but netinstall is preferred # to bring it up-to-date or extend functionality) leave this set to # false (the default). If set to true, the netinstall data is required. # # 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. # If no *sidebar* values are provided, defaults to "Package selection" # and existing translations. If no *title* values are provided, no string # is displayed. # # Translations are handled through `[ll]` notation, much like in # `.desktop` files. The string associated with `key[ll]` is used for # *key* when when the language *ll* (language-code, like *nl* or *en_GB* # or *ja*) 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 # the regular translation framework: # - "Package selection" # - "Office software" # - "Office package" # - "Browser software" # - "Browser package" # - "Web browser" # - "Kernel" # - "Services" # - "Login" # - "Desktop" # - "Applications" # - "Communication" # - "Development" # - "Office" # - "Multimedia" # - "Internet" # - "Theming" # - "Gaming" # - "Utilities" # Other strings should follow the translations format. label: sidebar: "Package selection" # sidebar[nl]: "Pakketkeuze" # sidebar[en_GB]: "Package choice" # sidebar[ja]: "知りません" # "I don't know" # title: "Office Package" # title[nl]: "Kantoorsoftware" # 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. 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, or just the top-level *groups* # key and with the list as its value, like in this file). # # 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; no packages can be selected or deselected. No # checkboxes are show for the group. Setting *immutable* to true # really only makes sense in combination with *selected* set to true, # so that the packages will be installed. (Setting a group to immutable # can be seen as removing it from 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. # - *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 top-level group, you are # creating a "default" group of packages which will always be installed # in the user's system. Hidden selected subgroups are installed if their # parent is selected. Setting *hidden* to true without *selected*, or with # *selected* set to false, is kind of pointless and will generate a warning. # # 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 selected: true critical: false 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 selected: false critical: true subgroups: - name: "Bash" description: "Bourne Again Shell" selected: true packages: - bash - bash-completion - name: "Zsh" description: "Zee shell, boss" packages: - 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 selected: true critical: true immutable: true packages: - kernel - kernel-debugsym - kernel-nvidia # *selected* defaults to true for top-level - name: Communications description: "Communications Software" packages: - ruqola - konversation - nheko - quaternion # Setting *selected* is supported. Here we also show off "rich" # packages: ones with a package-name (for the package-manager) # and a description (for the human). - name: Editors description: "Editing" selected: false packages: - vi - emacs - nano - name: kate-git description: Kate (unstable) - name: kate description: KDE's text editor # 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". You # can re-use the subgroup name, it doesn't really matter. # # 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, the packages from # the subgroup are selected with it and get installed. - 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