Each sample configuration file contains documentation on the options it contains (it not, it's a bug and you should file an issue).
The top-level configuration of Calamares is done in
settings.conf
, the file which defines which modules
the system uses and whether it is in OEM (dont-chroot) or normal
system-installer mode. The modules listed in settings.conf
are loaded one by one; their configurations are documented in
the respective files (see the source tree).
Distributions are strongly urged to package configuration files
separately from Calamares itself, and to install them in /etc/calamares
.
It is not recommended to edit or patch the configuration files
included with Calamares for production use -- they are examples.
At a high level, the settings.conf
file defines a sequence of things
to do (actions) during an installation. This defines the order in which
user-visible actions are taken (e.g. configuring the timezone) as well as
internal actions (e.g. installing the bootloader).
The sequence itself is split into a show and exec sections: the show parts are user-visible, and then exec does the work. During each exec section, the branding slideshow is displayed, and before each exec section, the user may be prompted to allow to continue the process. Normal installations have a show section for user interaction, and then a single exec section, and then a show section with only the "finished" module.
A viewmodule like "users" has a user-visible part for collecting information, and may also have a non-interactive part to do the actual work. Some viewmodules are therefore listed twice: once in a show section and once in an exec section.
A viewmodule in an exec section will not show a UI.
A section names module instances. Most modules are simply
listed as <modulename>
, which means the same as <modulename>@<modulename>
and uses the configuration file <modulename>.conf
. It is possible
to define specific module instances (for instance, to run the same
module multiple times with different configuration files).
See settings.conf
for details.
For internal actions, there are different kinds of Calamares modules which differ in how they are configured. These can be used to run commands or perform changes to the target system during installation:
- Always executing one or more commands (shellprocess instances).
Using this means defining an instance in
settings.conf
and adding a suitable configuration file with the list of commands to the configuration directory, e.g. to$USC/modules/shellprocess
. This does require intermediate directories, but allows fine-grained error handling. It makes sense to have multiple shellprocess instances, each with their own list of commands in their own configuration file (e.g.shellprocess-preboot.conf
and ashellprocess-erase.conf
for instancesshellprocess@preboot
andshellprocess@erase
, which are listed somewhere in the sequence). - Conditionally executing one or more commands (contextualprocess instances). This needs an instance and a configuration file describing which conditions (expressed as values in the Calamares global configuration) cause which commands to run.
- Conditionally executing one or more commands (python job)
with arbitrary logic. This means creating a new module directory
under
$USC/modules
and writing amain.py
. This allows much more expressive logic than contextualprocess instances, at the expense of more complicated packaging and programming. Most existing Calamares modules are of this type. - Conditionally executing one or more commands (C++ job) with arbitrary logic. This means creating a new module directory in the Calamares source tree and adding suitable C++ and CMake code to get it to compile. This is the most programmer-intensive form of modules, but does allow the most access to Calamares internals.
Calamares is usually shipped with PREFIX set to /usr
,
so that most of its configuration is in /usr/share/calamares
.
In the table below, $USC
means that directory.
File name | Deployment path (in search priority) | Purpose |
---|---|---|
branding.desc |
$USC/ brand_name |
Branding descriptor file, shipped with the rest of your branding component and selected in settings.conf |
modulename .conf , e.g. partition.conf , grubcfg.conf , unpackfs.conf , ... |
/etc/calamares/modules , $USC/modules |
Configuration files for every module that needs one |
displaymanager.conf |
Configuration for the display manager, select SDDM, lightdm, ... | |
locale.conf |
Locale and TimeZone configuration. GeoIP settings. | |
partition.conf |
Configuration for (automatic) partitioning and swap |
This section handles specialized settings or weird ways to start Calamares with specific configurations.
For most distributions, launching Calamares from the provided .desktop file is sufficient. When that is not the case, for example, you want to launch from a custom application or want to use a custom command line instead of the default Exec=pkexec /usr/bin/calamares
you can create a script to use instead.
An example of such a script:
#!/bin/sh
if [ ! -f /var/log/nvidia ] && [ ! -f /var/log/nvidia-340xx ]; then
sudo sed -i -e 's|- license|#- license|' /usr/share/calamares/settings.conf
fi
sudo /usr/bin/calamares -d > installation.log
This example shows the option to not show the License page if free graphics drivers are in use. It also shows creating an installation.log in the user's home directory.
Such a script can be used in the default calamares.desktop,
simply use a sed line to replace Exec=pkexec /usr/bin/calamares
with
Exec=/usr/bin/launch-calamares.sh
.
-
Integration when launched with sudo
When launching Calamares from a custom script using sudo, it does not inherit any of the system styles. A way to get this to integrate again is by setting some env variables in your
/etc/sudoers
file used in the Live system. Example of what to add to the end of that file:Defaults env_keep += "QTDIR PATH QT_PLUGIN_PATH QT_INCLUDE_PATH QML2_IMPORT_PATH KDE_SESSION_VERSION KDE_FULL_SESSION"
-
Integration when launched with pkexec
The
-E
flag may preserve sufficient environment to keep styling. -
Applying specific themes
You can use the stylesheets (via Calamares branding) and whatever environment is available in the user-that-runs-Calamares (e.g. root) for specific styling of Calamares, rather than integrating in the source user environment.