Unterbefehle¶

Die folgenden Unterbefehle werden erkannt:

summary

Gibt eine menschenlesbare Zusammenfassung aller für den Bau des Abbilds verwandten Optionena aus. Dies wird die Befehlszeile und mkosi.conf wie bei einem build auswerten, aber nur ausgeben, wofür es konfiguriert ist und nicht wirklich etwas bauen.

build

Dies baut das Abbild basierend auf den auf der Befehlszeile übergebenen oder aus den Konfigurationsdateien gelesenen Einstellungen. Diese Befehl ist die Vorgabe, falls kein Unterbefehl explizit angegeben ist. Falls irgenwelche Befehlszeilenargumente angegeben sind, werden sie direkt an das Bauskript übergeben, falls eines definiert ist.

shell

Dies baut das Abbild, falls es noch nicht gebaut ist, und ruft dann systemd-nspawn(1) auf, um darin eine interaktive Shell-Eingabeauforderung zu erlanben. Nach dem Unterbefehl shell kann eine optionale Befehlszeile angegeben werden, die anstelle der Shell in dem Container aufgerufen werden soll. Verwenden Sie -f, um das Abbild bedingungslos vor dem Erlangen der Shell neuzubauen, siehe unten. Dieser Befehl muss als root ausgeführt werden.

boot

Ähnlich wie shell, startet das Abbild aber mittels systemd-nspawn(1). Nach dem Unterbefehl boot kann eine optionale Befehlszeile angegeben werden, die zusätzliche Nspawn-Optionen sowie Argumente enthalten kann, die an die Kernelbefehlszeile des Init-Systems im Abbild übergeben werden.

qemu

Ähnlich wie boot, verwendet aber den konfigurierten Monitor für virtuelle Maschinen (standardmäßig qemu) um das Abbild zu starten, d.h. anstelle einer Container-Virtualisierung wird eine Virtualisierung einer virtuellen Maschine verwandt. Wie zusätzliche Befehlszeilenargumente interpretiert werden hängt von dem konfigurierten Monitor für virtuelle Maschinen ab. Siehe VirtualMachineMonitor= für weitere Informationen.

ssh

Wenn das Abbild mit der Option Ssh=yes gebaut wird, verbindet dieser Befehl die gestartete virtuelle Maschine (qemu) mittels SSH. Stellen Sie sicher, dass mkosi ssh mit der gleichen Konfiguration wie mkosi build ausgeführt wird, so dass es die notwendigen Informationen hat, um sich mit der laufenden virtuellen Maschine mittels SSH zu verbinden. Insbesondere wird der private SSH-Schlüssel aus der Einstellung SshKey= verwandt, um sich mit der virtuellen Maschine zu verbinden. Verwenden Sie mkosi genkey, um automatisch einen Schlüssel und ein Zertifikat zu erstellen, das von Mkosi aufgenommen wird. Alle nach dem Unterbefehl ssh übergebene Argumente werden als Argumente an den Aufruf von ssh(1) übergeben. Um sich mit einem Container zu verbinden, verwenden Sie machinectl login oder machinectl shell.

journalctl

Verwendet journalctl(1), um das Journal innerhalb des Abbildes zu untersuchen. Alle nach dem Unterbefehl journalctl angegebenen Argumente werden an den Aufruf von journalctl(1) angehängt.

coredumpctl

Verwendet coredumpctl(1), um nach Speicherauszügen innerhalb des Abbilds zu suchen. Alle nach dem Unterbefehl coredumpctl angegebenen Argumente werden an den Aufruf von coredumpctl(1) angehängt.

clean

Entfernt aus vorherigen Bauläufen erstellte Bauartefakte. Falls mit -f kombiniert, werden auch inkrementelle Bauzwischenspeicher-Abbilder entfernt. Falls -f zweimal angegeben ist, werden sämtliche Paketzwischenspeicher entfernt.

serve

Dies baut das Abbild, falls es noch nicht gebaut wurde und liefert dann das Ausgabeverzeichnis (d.h. normalerweise mkosi.output/, s.u.) über einen kleinen eingebauten HTTP-Server, der auf Port 8081 auf Anfragen wartet, aus. Kombinieren Sie dies mit -f, um das Abbild bedingungslos neuzubauen, bevor es ausgeliefert wird. Dieser Befehl ist für das Testen netzwerkbasierten Erwerbens von Betriebssystemabbildern nützlich, beispielsweise mittels machinectl pull-raw … und machinectl pull-tar ….

burn <Gerät>

Dies baut das Abbild, falls es noch nicht gebaut wurde und schreibt es dann auf das angegebene Blockgerät. Die Partitionsinhalte werden unverändert geschrieben, aber die GPT-Partitionstabelle wird korrigiert, so dass sie auf die Sektor- und Blockgrößen des angegebenen Mediums passt.

bump

Erhöht die Version des Abbildes aus mkosi.version und schreibt die resultierende Versionszeichenkette nach mkosi.version. Dies ist zur Implementierung eines einfachen Versionierungsschematas nützlich: jedes Mal, wenn dieser Unterbefehl aufgerufen wird, wird die Version als Vorbereitung für den nächsten Bau erhöht. Beachten Sie, dass --auto-bump/-B zum automatischen Erhöhen der Version nach jedem erfolgreichen Bau verwandt werden kann.

genkey

Erstellt ein Paar von SecureBoot-Schlüsseln zur Verwendung mit den Optionen SecureBootKey=/--secure-boot-key= und SecureBootCertificate=/--secure-boot-certificate=.

documentation

Zeigt die Dokumentation von mkosi an. Standardmäßig wird dieser Unterbefehl verschiedene Arten zur Ausgabe der Dokumentation ausprobieren, eine bestimmte Option kann mit der Option --doc-format ausgewählt werden. Paketierer von Distributionen wird empfohlen, eine Datei mkosi.1 in das Verzeichnis mkosi/resources des Python-Pakets abzulegen, falls sie dort fehlt, sowie sie im geeigneten Suchpfad für Handbuchseiten zu installieren. Die Handbuchseite kann aus der Markdown-Datei mkosi/resources/mkosi.md zum Beispiel mittels pandoc -t man -s -o mkosi.1 mkosi.md erstellt werden.

dependencies

Gibt die Liste der von Mkosi zum Bauen und Starten von Abbildern benötigten Pakete aus.

help

Dieser Unterbefehl ist identisch zum nachfolgend dokumentierten Schalter --help: Er zeigt eine kurze Erklärung zur Verwendung.

Reine Befehlszeilenoptionen¶

Diese Einstellungen können nicht mittels der Konfigurationsdateien konfiguriert werden.

--force, -f

Ersetzt beim Bau eines Abbildes die Ausgabedatei, falls sie bereits existiert. Standardmäßig verweigert mkosi eine Aktion, wenn ein Abbild und ein Ausgabeartefakt bereits existiert. Geben Sie diese Option einmal an, um alle Bauartefakte aus einem vorherigen Lauf vor dem Neubau des Abbildes zu entfernen. Falls inkrementelle Bauten aktiviert sind, wird zweimalige Angabe sicherstellen, dass inkrementelle Zwischenspeicherdateien auch entfernt werden, bevor der Neubau eingeleitet wird. Falls ein Paketzwischenspeicher verwandt wird (siehe auch den nachfolgenden Abschnitt Dateien) wird die dreimalige Angabe sicherstellen, dass auch der Paketzwischenspeicher entfernt wird, bevor der Neubau eingeleitet wird. Für die Aktion clean hat diese Option eine leicht andere Auswirkung: Standardmäßig wird der Unterbefehl nur Bauartefakte aus dem vorherigen Lauf entfernen, durch einmalige Angabe werden auch die inkrementellen Zwischenspeicherdateien gelöscht, bei doppelter Angabe wird auch der Paketezwischenspeicher entfernt.

--directory=, -C

Akzeptiert einen Pfad zu einem Verzeichnis. Bevor es etwas macht, wechselt mkosi in dieses Verzeichnis. Beachten Sie, dass in diesem Verzeichnis nach den verschiedenen Konfigurationsdateien gesucht wird, daher ist die Verwendung dieser Option ein wirksammes Mittel, ein Projekt zu bauen, das sich in einem bestimmten Verzeichnis befindet.

--debug=

Aktiviert zusätzliche Fehlersuchausgabe.

--debug-shell

Falls die Ausführung eines Befehls in dem Abbild fehlschlägt, wird Mkosi eine interaktive Shell in dem Abbild starten, um weitere Fehlersuche zu ermöglichen.

--debug-workspace=

Falls ein Fehler auftritt, wird das Arbeitsbereichsverzeichnis nicht gelöscht.

--version

Zeigt die Paketversion.

--help, -h

Zeigt einen kurzen Hinweis zum Aufruf.

--genkey-common-name=

Allgemeiner Name, der bei der Erzeugung von Schlüsseln mittels des Befehls genkey von Mkosi verwandt wird. Standardmäßig mkosi of %u, wobei %u auf den Benutzernamen des Benutzer, der Mkosi aufruft, erweitert wird.

--genkey-valid-days=

Anzahl an Tagen, die Schlüssel gültig bleiben sollen, wenn Schlüssel mit dem Befehl genkey von Mkosi erstellt werden. Standardmäßig zwei Jahre (730 Tage).

--auto-bump=, -B

Falls angegeben wird nach jedem erfolgreichen Bau in Vorbereitung des nächsten Baus die Version auf eine ähnliche Art wie beim Unterbefehl bump erhöht. Dies ist für einfaches, lineares Versionsmanagement nützlich: jeder Bau in einer Reihe wird eine um eins gegenüber dem vorherigen Bau erhöhte Versionsnummer haben.

--doc-format

Das Format, in dem die Dokumentation angezeigt werden soll. Unterstützt die Werte markdown, man, pandoc, system und auto. Im Falle von markdown wird die Dokumentation im usrpünglichen Markdown-Format angezeigt. man zeigt die Dokumentation im Handbuchseitenformat, falls dies verfügbar ist. pandoc erstellt das Handbuchseitenformat dynamisch, falls pandoc(1) verfügbar ist. system zeigt die systemweite Handbuchseite für mkosi, die nicht zwingend der Version entspricht, die Sie verwenden, abhängig davon, wie mkosi installiert wurde. auto (die Vorgabe) wird alle Methoden in der Reihenfolge man, pandoc, markdown, system ausprobieren.

--json

Zeigt die zusammenfassende Ausgabe als JSON-SEQ.

Unterstützte Ausgabeformate¶

Die folgenden Ausgabeformate werden unterstützt:

•

Rohes GPT-Plattenabbild, mittels systemd-repart(8) (Platte) erstellt.

•

Einfaches Verzeichnis, enthält den Betriebssystembaum (Verzeichnis)

•

TAR-Archiv (tar)

•

CPIO-Archiv (cpio)

Das Ausgabeformat kann auch auf none gesetzt werden, wenn Sie möchten, dass mkosi überhaupt kein Abbild erstellt. Dies kann nützlich sein, falls Sie das Abbild nur dazu verwenden möchten, eine andere Ausgabe in den Bauskripten zu erstellen (z.B. ein RPM zu bauen).

Wenn ein GPT-Plattenabbild erstellt wird, können Repart-Partitionsdefinitionsdateien in mkosi.repart/ abgelegt werden, um das erstellte Plattenabbild zu konfigurieren.

Es wird nachdrücklich empfohlen, mkosi auf einem Dateisystem auszuführen, das Reflinks unterstützt, wie xfs(5) und btrfs(5) und alle zusammengehörigen Verzeichnisse auf dem gleichen Dateisystem zu behalten. Dies ermöglicht es mkosi, Abbilder sehr schnell durch Verwendung von Reflinks zur Durchführung von Kopieren-Beim-Schreiben-Aktionen zu erstellen.

Konfigurationseinstellungen¶

Die folgenden Einstellungen können über Konfigurationsdateien (der Syntax mit EineEinstellung=Wert) und auf der Befehlszeile (der Syntax mit --Eine-Einstellung=Wert) gesetzt werden. Für einige Befehlszeilenparameter ist auch eine Abkürzung mit einem Buchstaben erlaubt. In den Konfigurationsdateien muss die Einstellung in dem korrekten Abschnitt erfolgen, daher sind die Einstellungen nachfolgend gemäß des Abschnittes gruppiert.

Die Konfiguration wird in der folgenden Reihenfolge ausgewertet:

•

Die Befehlszeilenargumente werden ausgewertet

•

mkosi.local.conf wird ausgewertet, falls es existiert. Diese Datei sollte in gitignore (oder äquivalent) sein und ist für lokale Konfiguration gedacht.

•

Alle Vorgabepfade (abhängig von der Option) werden konfiguriert, falls der entsprechende Pfad existiert.

•

mkosi.conf wird ausgewertet, falls es in dem mit --directory= konfigurierten Verzeichnis liegt oder im aktuellen Verzeichnis, falls --directory= nicht verwandt wird.

•

If a profile is defined, its configuration is parsed from the mkosi.profiles/ directory.

•

mkosi.conf.d/ wird im gleichen Verzeichnis ausgewertet, falls sie existiert. Jedes Verzeichnis und jede Datei mit der Endung .conf in mkosi.conf.d/ wird ausgewertet. Jedes Verzeichnis in mkosi.conf.d wird ausgewertet, also ob es ein normales Verzeichnis auf der obersten Ebene wäre.

•

Subimages are parsed from the mkosi.images directory if it exists.

Note that settings configured via the command line always override settings configured via configuration files. If the same setting is configured more than once via configuration files, later assignments override earlier assignments except for settings that take a collection of values. Also, settings read from mkosi.local.conf will override settings from configuration files that are parsed later but not settings specified on the CLI.

Einstellungen, die eine Sammlung von Werten akzeptieren, werden zusammengeführt, indem neue Werte an die bereits konfigurierten Werte angehängt werden. Durch Zuweisung einer leeren Zeichenkette zu einer solchen Einstellung werden alle vorher zugewiesenen Werte entfernt und auch alle konfigurierten Standardwerte außer Kraft gesetzt. Die auf der CLI angegebenen Werte werden nach allen Werten aus den Konfigurationsdateien angehängt.

Um Konfigurationsdateien bedingt einzubinden, kann der Abschnitt [Match] verwandt werden. Ein Abschnitt [Match] besteht aus einzelnen Bedingungen. Bedingungen können ein Weiterleitungssymbol (|) nach dem Gleichheitszeichen verwenden (…=|…). Dadurch wird die Bedingung eine auslösende Bedingung. Die Konfigurationsdatei wird eingebunden, falls das logische UND aller nicht auslösenden Bedingungen und das logische ODER aller auslösenden Bedingungen erfüllt wird. Um das Ergebnis einer Bedingung zu negieren, stellen Sie dem Argument ein Ausrufezeichen voran. Falls einem Argument ein Weiterleitungssymbol und ein Ausrufezeichen vorangestellt wird, muss das Weiterleitungssymbol zuerst angegeben werden und anschließend das Ausrufezeichen.

Beachten Sie, dass die Bedingungen in [Match] mit den aktuellen Werten einer bestimmten Einstellung verglichen werden und keine Änderungen an Einstellungen berücksichtigen, die in Konfigurationsdateien bereits erfolgten, aber noch nicht ausgewertet wurden (auf der CLI angegebene Einstellungen werden berücksichtigt). Beachten Sie auch, dass das Prüfen der Übereinstimmung mit einer Einstellung und das anschließende Ändern in einer anderen Konfigurationsdatei zu unerwarteten Ergebnissen führen kann.

The [Match] section of a mkosi.conf file in a directory applies to the entire directory. If the conditions are not satisfied, the entire directory is skipped. The [Match] sections of files in mkosi.conf.d/ and mkosi.local.conf only apply to the file itself.

Falls es mehrere Abschnitte [Match] in der gleichen Konfigurationsdatei gibt, muss jede erfüllt werden, damit die Konfigurationsdatei eingebunden wird. Insbesondere gelten auslösende Bedingungen nur für den aktuellen Abschnitt [Match] und werden zwischen mehreren Abschnitten [Match] zurückgesetzt. In dem folgenden Beispiel erfolgt nur eine Übereinstimmung, falls das Ausgabeformat entweder disk oder directory ist und die Architektur entweder x86-64 oder arm64 ist:

[Match]
Format=|disk
Format=|directory
[Match]
Architecture=|x86-64
Architecture=|arm64
    

The [TriggerMatch] section can be used to indicate triggering match sections. These are identical to triggering conditions except they apply to the entire match section instead of just a single condition. As an example, the following will match if the distribution is debian and the release is bookworm or if the distribution is ubuntu and the release is focal.

[TriggerMatch]
Distribution=debian
Release=bookworm
[TriggerMatch]
Distribution=ubuntu
Release=focal
    

The semantics of conditions in [TriggerMatch] sections is the same as in [Match], i.e. all normal conditions are joined by a logical AND and all triggering conditions are joined by a logical OR. When mixing [Match] and [TriggerMatch] sections, a match is achieved when all [Match] sections match and at least one [TriggerMatch] section matches. No match sections are valued as true. Logically this means:

(⋀ᵢ Matchᵢ) ∧ (⋁ᵢ TriggerMatchᵢ)
    

Command line options that take no argument are shown without = in their long version. In the config files, they should be specified with a boolean argument: either 1, yes, or true to enable, or 0, no, false to disable.

Abschnitt [Distribution]¶

Distribution=, --distribution=, -d

The distribution to install in the image. Takes one of the following arguments: fedora, debian, ubuntu, arch, opensuse, mageia, centos, rhel, rhel-ubi, openmandriva, rocky, alma, custom. If not specified, defaults to the distribution of the host or custom if the distribution of the host is not a supported distribution.

Release=, --release=, -r

The release of the distribution to install in the image. The precise syntax of the argument this takes depends on the distribution used, and is either a numeric string (in case of Fedora Linux, CentOS, ..., e.g. 29), or a distribution version name (in case of Debian, Ubuntu, ..., e.g. artful). Defaults to a recent version of the chosen distribution, or the version of the distribution running on the host if it matches the configured distribution.

Architecture=, --architecture=

Die Architektur für die das Abbild gebaut wird. Die tatsächlich unterstützten Architekturen hängen von der verwandten Distribution ab und ob ein startbares Abbild erbeten wird. Beim Bau für eine fremde Architektur müssen Sie auch den Benutzermodus-Emulator für diese Architektur installieren und registrieren.

Mirror=, --mirror=, -m

Der Spiegel für das Herunterladen der Distributionspakete. Erwartet eine Spiegel-URL als Argument. Falls nicht angegeben wird der Standard-Spiegel für die Distribution verwandt.

LocalMirror=, --local-mirror=

The mirror will be used as a local, plain and direct mirror instead of using it as a prefix for the full set of repositories normally supported by distributions. Useful for fully offline builds with a single repository. Supported on deb/rpm/arch based distributions. Overrides --mirror= but only for the local mkosi build, it will not be configured inside the final image, --mirror= (or the default repository) will be configured inside the final image instead.

RepositoryKeyCheck=, --repository-key-check=

Controls signature/key checks when using repositories, enabled by default. Useful to disable checks when combined with --local-mirror= and using only a repository from a local filesystem. Not used for DNF-based distros yet.

Repositories=, --repositories=

Aktiviert standardmäßig deaktivierte Paket-Depots. Dies kann zur Aktivierung der EPEL-Depots für CentOS oder anderer Komponenten der Debian/Ubuntu-Depots verwandt werden.

CacheOnly=, --cache-only=

Akzeptiert entweder auto, metadata, always oder never. Standardmäßig auto. Falls always, wird der Paketverwalter angewiesen, das Netzwerk nicht zu kontaktieren. Dies stellt eine minimale Reproduzierbarkeitsstufe bereit, solang der Paketzwischenspeicher bereits vollständig gefüllt ist. Falls auf metadata gesetzt kann der Paketverwalter weiterhin Pakete herunterladen, aber nicht die Metadaten des Depots synchronisieren. Falls auf auto gesetzt werden während des Baus die Metadaten des Depots synchronisiert, außer es liegt ein zwischengespeichertes Abbild vor (siehe Incremental= und Pakete können heruntergeladen werden. Falls auf never gesetzt, werden während des Baus die Metadaten des Depots immer synchronisiert und Pakete können heruntergeladen werden.

PackageManagerTrees=, --package-manager-tree=

Akzeptiert eine Kommata-getrennte Liste von Doppelpunkt-getrennten Pfadpaaren. Der erste Pfad jedes Paares bezieht sich auf ein Verzeichnis, das vor Aufruf des Paketverwalters in den Betriebssystembaum kopiert werden soll. Diese Option ist ähnlich der Option SkeletonTrees=, installiert aber die Dateien in ein Unterverzeichnis des Arbeitsbereichsverzeichnisses statt in den Betriebssystembaum. Dieses Unterverzeichnis des Arbeitsbereichs wird zur Konfiguration des Paketverwalters verwandt. Falls das Verzeichnis mkosi.pkgmngr// in dem lokalen Verzeichnis gefunden wird, wird es für diesen Zweck mit dem Wurzelverzeichnis als Ziel verwandt (siehe auch den nachfolgenden Abschnitt Dateien). Falls überhaupt nicht konfiguriert, wird dieser Wert als Vorgabe den gleichen Wert wie SkeletonTrees= enthalten.

Abschnitt [Output]¶

Format=, --format=, -t

Das zu erstellende Abbild-Format. Entweder directory (zur direkten Erstellung eines Betriebssystemabbildes im lokalen Verzeichnis), tar (ähnlich, es wird aber ein Tarball des Betriebssystemabbildes erstellt), cpio (ähnlich, es wird aber ein Cpio-Archiv erstellt), disk (ein Blockgerät-Betriebssystemabbild mit einer GPT-Partitionstabelle), uki (ein vereinigtes Kernel-Abbild mit einem Betriebssystemabbild im PE-Abschnitt .initrd), esp (uki aber in einem Platten-Abbild mit nur einer ESP-Partition eingehüllt), oci (ein mit der OCI-Abbildspezifikation kompatibles Verzeichnis, sysext, confext, portable oder none (das Betriebssystem-Abbild ist nur als Bau-Artefakt zur Erstellung eines weiteren Artefaktes gedacht).

ManifestFormat=, --manifest-format=

The manifest format type or types to generate. A comma-delimited list consisting of json (the standard JSON output format that describes the packages installed), changelog (a human-readable text format designed for diffing). By default no manifest is generated.

Output=, --output=, -o

Für die erstellte Ausgabedatei oder das Ausgabeverzeichnis zu verwendender Name. Standardmäßig image oder, falls ImageId= verwandt wird, wird dieser als standardmäßiger Ausgabename verwandt, optional wird die mit ImageVersion= angegebene Version angehängt oder der Name des Abbildes wird gegenüber ImageId bevorzugt, falls ein bestimmtes Abbild aus mkosi.images gebaut wird. Beachten Sie, dass diese Option nicht die Konfiguration des Ausgabeverzeichnisses ermöglicht, verwenden Sie dafür OutputDirectory=.

CompressOutput=, --compress-output=

Konfiguriert die Komprimierung für das resultierende Abbild oder Archiv. Das Argument kann entweder ein logischer Wert oder ein Komprimierungsalgorithmus (xz(1), zstd(1)) sein. Standardmäßig wird die Komprimierung zstd(1) sein, außer bei CentOS und abgeleiteten Distributionen bis Version 8, wo die Vorgabe xz(1) ist und OCI-Abbildern, bei denen die Vorgabe gzip(1) ist. Beachten Sie, dass das Abbild nicht direkt gestartet werden kann, wenn Komprimierung auf Plattenabbildtypen angewendet wird, sondern erst eine Dekomprimierung erfolgen muss. Das bedeutet auch, dass die Unterbefehle shell, boot, qemu bei der Verwendung dieser Option nicht verfügbar sind. Impliziert für tar, cpio, uki, esp und oci.

CompressLevel=, --compress-level=

Konfiguriert die zu verwendende Komprimierungsstufe. Akzeptiert eine Ganzzahl. Die möglichen Werte hängen von der verwandten Komprimierung ab.

OutputDirectory=, --output-dir=, -O

Path to a directory where to place all generated artifacts. If this is not specified and the directory mkosi.output/ exists in the local directory, it is automatically used for this purpose.

WorkspaceDirectory=, --workspace-dir=

Pfad zu einem Verzeichnis, in dem temporär während eines Abbild-Baus benötigte Daten gespeichert werden. Dieses Verzeichnis sollte über genug Platz verfügen, das vollständige Betriebssystemabbild zu speichern, obwohl in den meisten Modi der tatsächlich verwandte Plattenplatz kleiner ist. Falls nicht angegeben, wird ein Unterverzeichnis von $XDG_CACHE_HOME (falls gesetzt), $HOME/.cache (falls gesetzt) oder /var/tmp verwandt.

CacheDirectory=, --cache-dir=

Takes a path to a directory to use as the incremental cache directory for the incremental images produced when the Incremental= option is enabled. If this option is not used, but a mkosi.cache/ directory is found in the local directory it is automatically used for this purpose.

PackageCacheDirectory=, --package-cache-dir

Akzeptiert einen Pfad zu einem Verzeichnis, das als Paketzwischenspeicherverzeichnis für den eingesetzten Distributionspaketverwalter verwandt wird. Falls nicht gesetzt, wird ein geeignetes Verzeichnis in dem Home-Verzeichnis des Benutzers oder des Systems verwandt.

BuildDirectory=, --build-dir=

Takes a path to a directory to use as the build directory for build systems that support out-of-tree builds (such as Meson). The directory used this way is shared between repeated builds, and allows the build system to reuse artifacts (such as object files, executable, ...) generated on previous invocations. The build scripts can find the path to this directory in the $BUILDDIR environment variable. This directory is mounted into the image’s root directory when mkosi-chroot is invoked during execution of the build scripts. If this option is not specified, but a directory mkosi.builddir/ exists in the local directory it is automatically used for this purpose (also see the Files section below).

ImageVersion=, --image-version=

Konfiguriert die Abbild-Version. Dies akzeptiert jede Zeichenkette, es wird aber empfohlen, eine Reihe von durch Punkten getrennte Komponenten festzulegen. Die Version kann auch in einer Datei mkosi.version konfiguriert werden. In diesem Fall kann sie bequem mit dem Unterbefehl bump oder der Option --auto-bump verwaltet werden. Wenn dies angegeben ist, wird die festgelegte Abbildversion in den standardmäßigen Ausgabedateinamen aufgenommen, d.h. anstelle von image.raw wird die Vorgabe image_0.1.raw für Version 0.1 des Abbildes oder ähnlich lauten. Die Version wird auch mittels $IMAGE_VERSION an alle aufgerufenen Bauskripte übergeben (das könnte nützlich sein, um es in /etc/os-release oder ähnliche einzubauen, insbesondere in das darin befindliche Feld IMAGE_VERSION=).

ImageId=, --image-id=

Configure the image identifier. This accepts a freeform string that shall be used to identify the image with. If set the default output file will be named after it (possibly suffixed with the version). The identifier is also passed via the $IMAGE_ID to any build scripts invoked. The image ID is automatically added to /usr/lib/os-release.

SplitArtifacts=, --split-artifacts

If specified and building a disk image, pass --split=yes to systemd-repart to have it write out split partition files for each configured partition. Read the man (https://www.freedesktop.org/software/systemd/man/systemd-repart.html#--split=BOOL) page for more information. This is useful in A/B update scenarios where an existing disk image shall be augmented with a new version of a root or /usr partition along with its Verity partition and unified kernel.

RepartDirectories=, --repart-dir=

Paths to directories containing systemd-repart partition definition files that are used when mkosi invokes systemd-repart when building a disk image. If mkosi.repart/ exists in the local directory, it will be used for this purpose as well. Note that mkosi invokes repart with --root= set to the root of the image root, so any CopyFiles= source paths in partition definition files will be relative to the image root directory.

SectorSize=, --sector-size=

Setzt die Standardsektorgröße, die systemd-repart(8) zum Bau eines Plattenabilds benutzt, außer Kraft.

RepartOffline=, --repart-offline=

Legt fest, ob Plattenabbilder mittels Loopback-Geräten gebaut werden. Standardmäßig aktiviert. Wenn aktiviert, wird systemd-repart(8) keine Loopback-Geräte zum Bau von Plattenabbildern verwenden. Wenn deaktiviert, wird systemd-repart(8) immer Loopback-Geräte zum Bau von Plattenabbildern verwenden.

Overlay=, --overlay

Bei der Verwendung zusammen mit BaseTrees= wird die Ausgabe nur aus Änderungen an den angegebenen Basisbäumen bestehen. Jeder Basisbaum wird als untere Lage in einer Overlayfs-Struktur angehängt und die Ausgabe wird die obere Lage, die am Anfang leer ist. Daher werden Dateien, die sich gegenüber dem Basisbaum nicht ändern, nicht in der abschließenden Ausgabe enthalten sein.

UseSubvolumes=, --use-subvolumes=

Takes a boolean or auto. Enables or disables use of btrfs subvolumes for directory tree outputs. If enabled, mkosi will create the root directory as a btrfs subvolume and use btrfs subvolume snapshots where possible to copy base or cached trees which is much faster than doing a recursive copy. If explicitly enabled and btrfs is not installed or subvolumes cannot be created, an error is raised. If auto, missing btrfs or failures to create subvolumes are ignored.

Seed=, --seed=

Takes a UUID as argument or the special value random. Overrides the seed that systemd-repart(8) (https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html) uses when building a disk image. This is useful to achieve reproducible builds, where deterministic UUIDs and other partition metadata should be derived on each build.

SourceDateEpoch=, --source-date-epoch=

Akzeptiert einen Zeitstempel in Sekunden seit dem UNIX-Epoch als Argument. Dateiveränderungszeiten aller Dateien werden auf diesen Wert festgestellt. Die Variable wird auch an systemd-repart(8) und alle von Mkosi ausgeführten Skripte weitergegeben. Falls nicht explizit gesetzt, wird SOURCE_DATE_EPOCH aus --environment und aus der Umgebung des Wirtsystems in dieser Reihenfolge ausprobiert. Siehe SOURCE_DATE_EPOCH (https://reproducible-builds.org/specs/source-date-epoch/) für weitere Informationen.

CleanScripts=, --clean-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Bereinigungsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

Abschnitt [Content]¶

Packages=, --package=, -p

Install the specified distribution packages (i.e. RPM, DEB, ...) in the image. Takes a comma separated list of package specifications. This option may be used multiple times in which case the specified package lists are combined. Use BuildPackages= to specify packages that shall only be installed in an overlay that is mounted when the prepare scripts are executed with the build argument and when the build scripts are executed.

BuildPackages=, --build-package=

Similar to Packages=, but configures packages to install only in an overlay that is made available on top of the image to the prepare scripts when executed with the build argument and the build scripts. This option should be used to list packages containing header files, compilers, build systems, linkers and other build tools the mkosi.build scripts require to operate. Note that packages listed here will be absent in the final image.

VolatilePackages=, --volatile-package=

Similar to Packages=, but packages configured with this setting are not cached when Incremental= is enabled and are installed after executing any build scripts.

PackageDirectories=, --package-directory=

Legt Verzeichnisse fest, die zusätzliche Pakete enthalten, die während des Baus verfügbar gemacht werden sollen. mkosi wird ein lokales Depot mit allen Paketen aus diesen Verzeichnissen erstellen und es beim Installieren von Paketen oder Ausführen von Skripten verfügbar machen. Falls das Verzeichnis mkosi.packages/ in dem lokalen Verzeichnis gefunden wird, wird es auf für diesen Zweck verwandt.

VolatilePackageDirectories=, --volatile-package-directory=

Like PackageDirectories=, but any changes to the packages in these directories will not invalidate the cached images if Incremental= is enabled.

WithRecommends=, --with-recommends=

Konfiguriert, ob empfohlene Pakete oder schwache Abhängigkeiten installiert werden, abhängig davon, wie sie vom verwandten Paketverwalter benannt werden. Standardmäßig werden empfohlene Pakete nicht installiert. Dies wird nur von Paketverwaltern unterstützt, die dieses Konzept unterstützen. Derzeit sind dies apt(8), dnf(8) und zypper(8).

WithDocs=, --with-docs

Include documentation in the image. Enabled by default. When disabled, if the underlying distribution package manager supports it documentation is not included in the image. The $WITH_DOCS environment variable passed to the mkosi.build scripts is set to 0 or 1 depending on whether this option is enabled or disabled.

BaseTrees=, --base-tree=

Akzeptiert eine Komma-getrennte Liste von Pfaden zu Verwendung als Basisbäume. Bei der Verwendung werden dieses Basisbäume in die Betriebssystembäume kopiert und formen die Basisdistribution anstelle der normalen Installation. Es werden nur zusätzliche Pakete ergänzend zu den bereits in den Basisbäumen installierten Paketen installiert. Beachten Sie, dass das Basisabbild weiterhin die Paketverwaltermetadaten durch Setzen von CleanPackageMetadata=no (siehe CleanPackageMetadata=) enthalten muss, damit das korrekt funktioniert.

SkeletonTrees=, --skeleton-tree=

Akzeptiert eine Kommata-getrennte Liste von Doppelpunkt-getrennten Pfadpaaren. Der erste Pfad jedes Paares bezieht sich auf ein Verzeichnis, das vor Aufruf des Paketverwalters in den Betriebssystembaum kopiert werden soll. Der zweite Pfad in jedem Paar bezieht sich auf das Zielverzeichnis innerhalb des Abbildes. Falls der zweite Pfad nicht bereit gestellt wird, wird das Verzeichnis auf das Wurzelverzeichnis des Abbildes kopiert. Der zweite Pfad wird immer als ein absoluter Pfad interpretiert. Verwenden Sie dies, um Dateien und Verzeichnisse in den Betriebssystembaum einzufügen, bevor der Paketverwalter irgendwelche Pakete installiert. Falls das Verzeichnis mkosi.skeleton/ in dem lokalen Verzeichnis gefunden wird, wird es auch für diesen Zweck mit dem Wurzelverzeichnis als Ziel verwandt (siehe auch den nachfolgenden Abschnitt Dateien).

ExtraTrees=, --extra-tree=

Akzeptiert eine Kommata-getrennte Liste von Doppelpunkt-getrennten Pfadpaaren. Der erste Pfad jedes Paares bezieht sich auf ein Verzeichnis, das vom Wirtsystem in das Abbild kopiert werden soll. Der zweite Pfad in jedem Paar bezieht sich auf das Zielverzeichnis innerhalb des Abbildes. Falls der zweite Pfad nicht bereit gestellt wird, wird das Verzeichnis auf das Wurzelverzeichnis des Abbildes kopiert. Der zweite Pfad wird immer als ein absoluter Pfad interpretiert. Verwenden Sie dies, um beliebige, mit der Distribution ausgelieferte Standardkonfigurationsdateien außer Kraft zu setzen. Falls das Verzeichnis mkosi.extra/ in dem lokalen Verzeichnis gefunden wird, wird es auch für diesen Zweck mit dem Wurzelverzeichnis als Ziel verwandt (siehe auch den nachfolgenden Abschnitt Dateien).

RemovePackages=, --remove-package=

Takes a comma-separated list of package specifications for removal, in the same format as Packages=. The removal will be performed as one of the last steps. This step is skipped if CleanPackageMetadata=no is used.

RemoveFiles=, --remove-files=

Akzeptiert eine Kommata-getrennte Liste von Globs. Dateien im Abbild, die auf die Globs passen, werden am Ende vollständig entfernt.

CleanPackageMetadata=, --clean-package-metadata=

Enable/disable removal of package manager databases and repository metadata at the end of installation. Can be specified as true, false, or auto (the default). With auto, package manager databases and repository metadata will be removed if the respective package manager executable is not present at the end of the installation.

SyncScripts=, --sync-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Synchronisationsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

PrepareScripts=, --prepare-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Vorbereitungsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

BuildScripts=, --build-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Bauskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

PostInstallationScripts=, --postinst-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Post-Installationsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

FinalizeScripts=, --finalize-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Finalisierungsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

PostOutputScripts=, --postoutput-script

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Post-Ausgabeskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

BuildSources=, --build-sources=

Takes a comma separated list of colon separated path pairs. The first path of each pair refers to a directory to mount from the host. The second path of each pair refers to the directory where the source directory should be mounted when running scripts. Every target path is prefixed with /work/src and all build sources are sorted lexicographically by their target before mounting, so that top level paths are mounted first. If not configured explicitly, the current working directory is mounted to /work/src.

BuildSourcesEphemeral=, --build-sources-ephemeral=

Akzeptiert einen logischen Wert. Standardmäßig deaktiviert. Konfiguriert, ob Änderungen an Quellverzeichnissen (dem Arbeitsverzeichnis und dem mit BuildSources= konfigurierten) dauerhaft sind. Falls aktiviert, werden nach der Ausführung aller Skripte eines bestimmten Typs (außer Synchronisationsskripte) alle Quellverzeichnisse auf ihren Originalzustand zurückgesetzt.

Environment=, --environment=

Adds variables to the environment that package managers and the prepare/build/postinstall/finalize scripts are executed with. Takes a space-separated list of variable assignments or just variable names. In the latter case, the values of those variables will be passed through from the environment in which mkosi was invoked. This option may be specified more than once, in which case all listed variables will be set. If the same variable is set twice, the later setting overrides the earlier one.

EnvironmentFiles=, --env-file=

Takes a comma-separated list of paths to files that contain environment variable definitions to be added to the scripting environment. Uses mkosi.env if it is found in the local directory. The variables are first read from mkosi.env if it exists, then from the given list of files and then from the Environment= settings.

WithTests=, --without-tests, -T

If set to false (or when the command-line option is used), the $WITH_TESTS environment variable is set to 0 when the mkosi.build scripts are invoked. This is supposed to be used by the build scripts to bypass any unit or integration tests that are normally run during the source build process. Note that this option has no effect unless the mkosi.build build scripts honor it.

WithNetwork=, --with-network=

When true, enables network connectivity while the build scripts mkosi.build are invoked. By default, the build scripts run with networking turned off. The $WITH_NETWORK environment variable is passed to the mkosi.build build scripts indicating whether the build is done with or without network.

Bootable=, --bootable=

Takes a boolean or auto. Enables or disables generation of a bootable image. If enabled, mkosi will install an EFI bootloader, and add an ESP partition when the disk image output is used. If the selected EFI bootloader (See Bootloader=) is not installed or no kernel images can be found, the build will fail. auto behaves as if the option was enabled, but the build won’t fail if either no kernel images or the selected EFI bootloader can’t be found. If disabled, no bootloader will be installed even if found inside the image, no unified kernel images will be generated and no ESP partition will be added to the image if the disk output format is used.

Bootloader=, --bootloader=

Akzeptiert entweder none, systemd-boot, uki oder grub. Standardmäßig systemd-boot. Falls auf none gesetzt, wird kein EFI-Systemstartprogramm in das Abbild installiert. Falls auf systemd-boot gesetzt, wird systemd-boot(7) installiert und für jeden installierten Kernel ein UKI erstellt und in EFI/Linux im ESP gespeichert. Falls auf uki gesetzt, wird ein einzelnes UKI für den neuesten installierten Kernel (demjenigen mit der höchsten Version), der in EFI/BOOT/BOOTX64.EFI im ESP installiert ist, generiert. Falls auf grub gesetzt, wird für jeden installierten Kernel ein UKI erstellt und in EFI/Linux im ESP gespeichert. Für jeden erstellten UKI wird ein Menüeintrag zu der Grub-Konfiguration in grub/grub.cfg im ESP hinzugefügt, der in den UKI weiterlädt. Zur Anpassung wird ein grub.cfg auch nach EFI/<Distribution>/grub.cfg aus Kompatibilitätsgründen mit signierten Versionen von Grub grub/grub.cfg im ESP geschrieben, da diese die Konfiguration von diesem Ort laden.

BiosBootloader=, --bios-bootloader=

Akzeptiert entweder none oder grub. Standardmäßig none. Falls auf none gesetzt, wird kein BIOS-Systemstartprogramm installiert. Falls auf grub gesetzt, wird Grub als BIOS-Systemstartprogramm installiert, falls ein selbststartendes Abbild mit der Option Bootable= erbeten wird. Falls keine Repart-Partitionsdefinitionsdateien konfiguriert sind, wird Mkosi eine Grub-BIOS-Systemstartpartition und eine EFI-Systempartition zu den Standard-Partitionsdefinitionsdateien hinzufügen.

ShimBootloader=, --shim-bootloader=

Akzeptiert entweder none, unsigned oder signed. Standardmäßig none. Falls auf none gesetzt, werden Shim und MokManager nicht in das ESP installiert. Falls auf unsigned gesetzt, wird Mkosi nach unsignierten Shim- und MokManager-EFI-Programmen suchen und sie installieren. Falls SecureBoot= aktiviert ist, wird Mkosi vor der Installation die unsignierte EFI-Programme signieren. Falls auf signed gesetzt, wird Mkosi nach signierten EFI-Programmen suchen und sie installieren. Selbst wenn SecureBoot= aktiviert ist, wird Mkosi die Programm nicht erneut signieren.

UnifiedKernelImages=, --unified-kernel-images=

Specifies whether to use unified kernel images or not when Bootloader= is set to systemd-boot or grub. Takes a boolean value or auto. Defaults to auto. If enabled, unified kernel images are always used and the build will fail if any components required to build unified kernel images are missing. If set to auto, unified kernel images will be used if all necessary components are available. Otherwise Type 1 entries as defined by the Boot Loader Specification will be used instead. If disabled, Type 1 entries will always be used.

UnifiedKernelImageFormat=, --unified-kernel-image-format=

Takes a filename without any path components to specify the format that unified kernel images should be installed as. This may include both the regular specifiers (see Specifiers) and special delayed specifiers, that are expanded during the installation of the files, which are described below. The default format for this parameter is &e-&k with -&h being appended if roothash= or usrhash= is found on the kernel command line and +&c if /etc/kernel/tries is found in the image.

Initrds=, --initrd

Vom Benutzer bereitgestellte Initrd(s). Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Initrd-Dateien. Diese Option kann mehrfach angewendet werden. Dann werden die aufgeführten Initrd-Listen kombiniert. Falls keine Initirds angegeben sind und ein startbares Medium erbeten wurde, wird Mkosi nach Initrds in einem Unterverzeichnis io.mkosi.initrd des Artefakt-Verzeichnisses nach Initrds suchen (siehe $ARTIFACTDIR in dem Abschnitt UMGEBUNGSVARIABLEN). Falls dort keine gefunden werden, wird Mkosi automatisch eine Standard-Initrd bauen.

InitrdPackages=, --initrd-package=

Extra-Pakete, die in die Standard-Initrd installiert werden sollen. Akzeptiert eine Kommata-getrennte Liste von Paketspezifikationen. Diese Option kann mehrfach angewendet werden. Dann werden die aufgeführten Paketlisten kombiniert.

InitrdVolatilePackages=, --initrd-volatile-package=

Similar to VolatilePackages=, except it applies to the default initrd.

MicrocodeHost=, --microcode-host=

Wenn auf wahr gesetzt, wird nur der Mikrocode für die CPU des Wirtsystems in dem Abbild aufgenommen.

KernelCommandLine=, --kernel-command-line=

Use the specified kernel command line when building images.

KernelModulesInclude=, --kernel-modules-include=

Akzeptiert eine Liste von Mustern regulärer Ausdrücke, die im Abbild aufzunehmende Kernelmodule festlegen. Die Muster sollten relativ zum Verzeichnis /usr/lib/modules/<kver>/kernel sein. Mkosi prüft überall im Modulpfad auf Übereinstimmung (z.B. passt i915 auf drivers/gpu/drm/i915.ko). Alle Module, die auf das angegebene Muster passen werden im Abbild aufgenommen. Alle Module und Firmwareabhängigkeiten des übereinstimmenden Moduls werden auch im Abbild aufgenommen.

KernelModulesExclude=, --kernel-modules-exclude=

Takes a list of regex patterns that specify modules to exclude from the image. Behaves the same as KernelModulesInclude= except that all modules that match any of the specified patterns are excluded from the image.

KernelModulesInitrd=, --kernel-modules-initrd=

Aktiviert/Deaktiviert beim Bau eines startbaren Abbilds die Erstellung von Kernelmodulen in der Initrd. Standardmäßig aktiviert. Falls aktiviert, wird beim Bau eines startbaren Abbilds für jeden Kernel, für den ein vereinigtes Kernelabbild zusammengebaut wird, eine zusätzliche Initrd erstellt, die nur die Kernelmodule für diese Kernelversion enthält und diese an die vorabgebaute Initrd angehängt. Dies ermöglicht es, Kernel-unabhängige Initrds zu erstellen, die mit den notwendigen kernelmodulen ergänzt werden, wenn das UKI zusammengebaut wird.

KernelModulesInitrdInclude=, --kernel-modules-initrd-include=

Like KernelModulesInclude=, but applies to the kernel modules included in the kernel modules initrd.

KernelModulesInitrdExclude=, --kernel-modules-initrd-exclude=

Like KernelModulesExclude=, but applies to the kernel modules included in the kernel modules initrd.

Locale=, --locale=, LocaleMessages=, --locale-messages=, Keymap=, --keymap=, Timezone=, --timezone=, Hostname=, --hostname=, RootShell=, --root-shell=

The settings Locale=, --locale=, LocaleMessages=, --locale-messages=, Keymap=, --keymap=, Timezone=, --timezone=, Hostname=, --hostname=, RootShell=, --root-shell= correspond to the identically named systemd-firstboot options. See the systemd firstboot manpage (https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html) for more information. Additionally, where applicable, the corresponding systemd credentials for these settings are written to /usr/lib/credstore, so that they apply even if only /usr is shipped in the image.

RootPassword=, --root-password=,

Set the system root password. If this option is not used, but a mkosi.rootpw file is found in the local directory, the password is automatically read from it. If the password starts with hashed:, it is treated as an already hashed root password. The root password is also stored in /usr/lib/credstore under the appropriate systemd credential so that it applies even if only /usr is shipped in the image. To create an unlocked account without any password use hashed: without a hash.

Autologin=, --autologin

Aktiviert die automatische Anmeldung für den Benutzer root auf /dev/pts/0 (nspawn), /dev/tty1 und /dev/hvc0.

MakeInitrd=, --make-initrd

Add /etc/initrd-release and /init to the image so that it can be used as an initramfs.

Ssh=, --ssh

If specified, an sshd socket unit and matching service are installed in the final image that expose SSH over VSock. When building with this option and running the image using mkosi qemu, the mkosi ssh command can be used to connect to the container/VM via SSH. Note that you still have to make sure openssh is installed in the image to make this option behave correctly. Run mkosi genkey to automatically generate an X509 certificate and private key to be used by mkosi to enable SSH access to any virtual machines via mkosi ssh. To access images booted using mkosi boot, use machinectl.

SELinuxRelabel=, --selinux-relabel=

Legt fest, ob Dateien neu markiert werden sollen, um auf die SELinux-Richtlinie des Abbilds zu passen. Akzeptiert einen logischen Wert oder auto. Standardmäßig auto. Falls deaktiviert, werden Dateien nicht neu markiert. Falls aktiviert, muss eine SELinux-Richtlinie im Abbild installiert werden und setfiles(8) verfügbar sein, um Dateien zu markieren. Falls während setfiles(8) irgendein Fehler auftritt, wird der Bau fehlschlagen. Falls auf auto gesetzt, werden Dateien neu markiert, falls eine SELinux-Richtlinie im Abbild installiert und setfiles(8) verfügbar ist. Alle während setfiles(8) aufgetretenen Fehler werden ignoriert.

Abschnitt [Validation]¶

SecureBoot=, --secure-boot

Signiert systemd-boot(7) (falls es noch nicht signiert ist) und sämtliche vereinigten Kernelabbilder für UEFI SecureBoot.

SecureBootAutoEnroll=, --secure-boot-auto-enroll=

Set up automatic enrollment of the secure boot keys in virtual machines as documented in the systemd-boot man page (https://www.freedesktop.org/software/systemd/man/systemd-boot.html) if SecureBoot= is used. Note that systemd-boot will only do automatic secure boot key enrollment in virtual machines starting from systemd v253. To do auto enrollment on systemd v252 or on bare metal machines, write a systemd-boot configuration file to /efi/loader/loader.conf using an extra tree with secure-boot-enroll force or secure-boot-enroll manual in it. Auto enrollment is not supported on systemd versions older than v252. Defaults to yes.

SecureBootKey=, --secure-boot-key=

Path to the PEM file containing the secret key for signing the UEFI kernel image if SecureBoot= is used and PCR signatures when SignExpectedPcr= is also used. When SecureBootKeySource= is specified, the input type depends on the source.

SecureBootKeySource=, --secure-boot-key-source=

Quelle von SecureBootKey=, um OpenSSL-Einheiten zu unterstützen. Beispiel: --secure-boot-key-source=engine:pkcs11

SecureBootCertificate=, --secure-boot-certificate=

Path to the X.509 file containing the certificate for the signed UEFI kernel image, if SecureBoot= is used.

SecureBootSignTool=, --secure-boot-sign-tool

Tool to use to sign secure boot PE binaries. Takes one of sbsign, pesign or auto. Defaults to auto. If set to auto, either sbsign or pesign are used if available, with sbsign being preferred if both are installed.

VerityKey=, --verity-key=

Path to the PEM file containing the secret key for signing the verity signature, if a verity signature partition is added with systemd-repart. When VerityKeySource= is specified, the input type depends on the source.

VerityKeySource=, --verity-key-source=

Source of VerityKey=, to support OpenSSL engines. E.g.: --verity-key-source=engine:pkcs11

VerityCertificate=, --verity-certificate=

Pfad zu einer X.509-Datei, die das Zertifikat zum Signieren der Verity-Signatur enthält, falls eine Verity-Signaturpartition mittels systemd-repart(8) hinzugefügt wird.

SignExpectedPcr=, --sign-expected-pcr

Measure the components of the unified kernel image (UKI) using systemd-measure and embed the PCR signature into the unified kernel image. This option takes a boolean value or the special value auto, which is the default, which is equal to a true value if the systemd-measure binary is in PATH. Depends on SecureBoot= being enabled and key from SecureBootKey=.

Passphrase=, --passphrase

Specify the path to a file containing the passphrase to use for LUKS encryption. It should contain the passphrase literally, and not end in a newline character (i.e. in the same format as cryptsetup and /etc/crypttab expect the passphrase files). The file must have an access mode of 0600 or less.

Checksum=, --checksum

Generate a SHA256SUMS file of all generated artifacts after the build is complete.

Sign=, --sign

Sign the generated SHA256SUMS using gpg after completion.

Key=, --key=

Select the gpg key to use for signing SHA256SUMS. This key must be already present in the gpg keyring.

Abschnitt [Host]¶

ProxyUrl=, --proxy-url=

Configure a proxy to be used for all outgoing network connections. Various tools that mkosi invokes and for which the proxy can be configured are configured to use this proxy. mkosi also sets various well-known environment variables to specify the proxy to use for any programs it invokes that may need internet access.

ProxyExclude=, --proxy-exclude=

Configure hostnames for which requests should not go through the proxy. Takes a comma separated list of hostnames.

ProxyPeerCertificate=, --proxy-peer-certificate=

Configure a file containing certificates used to verify the proxy. Defaults to the system-wide certificate store.

ProxyClientCertificate=, --proxy-client-certificate=

Configure a file containing the certificate used to authenticate the client with the proxy.

ProxyClientKey=, --proxy-client-key=

Configure a file containing the private key used to authenticate the client with the proxy. Defaults to the proxy client certificate if one is provided.

Incremental=, --incremental=, -i

Enable incremental build mode. In this mode, a copy of the OS image is created immediately after all OS packages are installed and the prepare scripts have executed but before the mkosi.build scripts are invoked (or anything that happens after it). On subsequent invocations of mkosi with the -i switch this cached image may be used to skip the OS package installation, thus drastically speeding up repetitive build times. Note that while there is some rudimentary cache invalidation, it is definitely not perfect. In order to force rebuilding of the cached image, combine -i with -ff to ensure the cached image is first removed and then re-created.

NSpawnSettings=, --settings=

Specifies a .nspawn settings file for systemd-nspawn to use in the boot and shell verbs, and to place next to the generated image file. This is useful to configure the systemd-nspawn environment when the image is run. If this setting is not used but an mkosi.nspawn file found in the local directory it is automatically used for this purpose.

ExtraSearchPaths=, --extra-search-path=

List of colon-separated paths to look for tools in, before using the regular $PATH search path.

VirtualMachineMonitor=, --vmm=

Configures the virtual machine monitor to use. Takes one of qemu or vmspawn. Defaults to qemu.

QemuGui=, --qemu-gui=

Falls aktiviert, wird Qemu mit seiner graphischen Oberfläche anstelle einer seriellen Konsole ausgeführt.

QemuSmp=, --qemu-smp=

When used with the qemu verb, this options sets qemu’s -smp argument which controls the number of guest’s CPUs. Defaults to 2.

QemuMem=, --qemu-mem=

When used with the qemu verb, this options sets qemu’s -m argument which controls the amount of guest’s RAM. Defaults to 2G.

QemuKvm=, --qemu-kvm=

When used with the qemu verb, this option specifies whether QEMU should use KVM acceleration. Takes a boolean value or auto. Defaults to auto.

QemuVsock=, --qemu-vsock=

When used with the qemu verb, this option specifies whether QEMU should be configured with a vsock. Takes a boolean value or auto. Defaults to auto.

QemuVsockConnectionId=, --qemu-vsock-cid=

Bei der Verwendung mit dem Unterbefehl qemu legt diese Option die zu verwendende Verbindungskennung fest. Akzeptiert eine Zahl im Intervall [3, 0xFFFFFFFF) oder hash oder auto. Standardmäßig hash. Wenn auf hash gesetzt wird die Verbindungskennung von dem vollständigen Pfad zum Abbild abgeleitet. Wenn auf auto gesetzt, wird mkosi versuchen, automatisch eine freie Verbindungskennung zu finden. Andernfalls wird die bereitgestellte Nummer unverändert verwandt.

QemuSwtpm=, --qemu-swtpm=

When used with the qemu verb, this option specifies whether to start an instance of swtpm to be used as a TPM with qemu. This requires swtpm to be installed on the host. Takes a boolean value or auto. Defaults to auto.

QemuCdrom=, --qemu-cdrom=

When used with the qemu verb, this option specifies whether to attach the image to the virtual machine as a CD-ROM device. Takes a boolean. Defaults to no.

QemuFirmware=, --qemu-firmware=

When used with the qemu verb, this option specifies which firmware to use. Takes one of uefi, uefi-secure-boot, bios, linux, or auto. Defaults to auto. When set to uefi, the OVMF firmware without secure boot support is used. When set to uefi-secure-boot, the OVMF firmware with secure boot support is used. When set to bios, the default SeaBIOS firmware is used. When set to linux, direct kernel boot is used. See the QemuKernel= option for more details on which kernel image is used with direct kernel boot. When set to auto, uefi-secure-boot is used if possible and linux otherwise.

QemuFirmwareVariables=, --qemu-firmware-variables=

When used with the qemu verb, this option specifies the path to the the firmware variables file to use. Currently, this option is only taken into account when the uefi or uefi-secure-boot firmware is used. If not specified, mkosi will search for the default variables file and use that instead.

QemuKernel=, --qemu-kernel=

Setzt das für direkten Kernelsystemstart in Qemu zu verwendende Kernelabbild. Falls nicht angegeben wird Mkosi den über die Befehlszeile bereitgestellten Kernel (Option -kernel) oder den neusten Kernel, der im Abbild installiert wurde, verwenden (oder fehlschlagen, falls kein Kernel im Abbild installiert wurde).

QemuDrives=, --qemu-drive=

Fügt ein Qemu-Laufwerk hinzu. Akzeptiert eine Doppelpunkt-getrennte Zeichenkette im Format <Kennung>:<Größe>[:<Verzeichnis>[:<Optionen>[:<Dateikennung>]]]. Kennung legt die dem Laufwerk zugeordnete Kennung fest. Diese kann als die Eigenschaft drive= in verschiedenen Qemu-Geräten verwandt werden. Größe legt die Größe des Laufwerks fest. Dies akzeptiert eine Größe in Byte. Zusätzliche können die Endungen K, M und G zur Festlegung einer Größe in Kilobyte, Megabyte bzw. Gigabyte verwandt werden. Verzeichnis legt optional das Verzeichnis fest, in dem das dem Laufwerk zugrunde liegende Verzeichnis erstellt werden soll. Optionen legen optional zusätzliche, durch Kommata getrennte Eigenschaften fest, die unverändert an die Option -drive von Qemu übergeben werden. Dateikennung legt die Kennung der Datei fest, die dem Laufwerk zugrunde liegt. Laufwerke mit der gleichen Dateikennung haben eine gemeinsame zugrundeliegende Datei. Das Verzeichnis und die Größe der Datei wird aus dem ersten Laufwerk mit der angegebenen Dateikennung bestimmt.

QemuArgs=

Leerzeichen-begrenzte Liste von zusätzlich beim Aufruf von Qemu zu übergebenen Argumenten.

Ephemeral=, --ephemeral

When used with the shell, boot, or qemu verbs, this option runs the specified verb on a temporary snapshot of the output image that is removed immediately when the container terminates. Taking the temporary snapshot is more efficient on file systems that support reflinks natively (btrfs or xfs) than on more traditional file systems that do not (ext4).

Credentials=, --credential=

Set credentials to be passed to systemd-nspawn or qemu respectively when mkosi shell/boot or mkosi qemu are used. This option takes a space separated list of values which can be either key=value pairs or paths. If a path is provided, if it is a file, the credential name will be the name of the file. If the file is executable, the credential value will be the output of executing the file. Otherwise, the credential value will be the contents of the file. If the path is a directory, the same logic applies to each file in the directory.

KernelCommandLineExtra=, --kernel-command-line-extra=

Setzt zusätzliche Kernelbefehlszeilenargumente, die zur Laufzeit beim Starten des Abbilds an die Kernelbefehlszeile angehängt werden. Beim Systemstart in einen Container werden diese als zusätzliches Argument an systemd(1) übergeben. Beim Systemstart in eine VM werden diese mittels der SMBIOS-OEM-Zeichenkette io.systemd.stub.kernel-cmdline-extra an die Kernelbefehlszeile angehängt. Dies wird von systemd-boot(7)/systemd-stub(7) erst ab Version v254 aufgenommen.

Acl=, --acl=

Falls angegeben, werden ACLS auf allen erstellten Wurzeldateisystemverzeichnissen erstellt, die dem Benutzer, der Mkosi ausführt, erlauben, diese ohne zusätzlich benötigte Privilegien zu entfernen.

ToolsTree=, --tools-tree=

Falls angegeben, werden von Mkosi ausgeführte Programme zum Bau und Starten eines Abbilds innerhalb des angegeben Baums statt im Wirtsystem nachgesucht. Verwenden Sie diese Option, um den Abbildbau reproduzierbarer zu machen, indem Sie immer die gleiche Version von Programmen zum Bau des letztendlichen Abbildes verwenden, anstelle der gerade im Wirtsystem installierten Version. Falls diese Option nicht verwandt wird, aber das Verzeichnis mkosi.tools/ im lokalen Verzeichnis gefunden wird, wird es automatisch für diesen Zweck mit dem Wurzelverzeichnis als Ziel verwandt.

ToolsTreeDistribution=, --tools-tree-distribution=

Setzt die für den Standard-Werkzeugbaum zu verwendende Distribution. Standardmäßig wird die gleiche Distribution wie für das zu bauende Abbild verwandt, außer für CentOS- und Ubuntu-Abbilder, bei denen Fedora bzw. Debian verwandt werden.

ToolsTreeRelease=, --tools-tree-release=

Setzt die für den Standard-Werkzeugbaum zu verwendende Distributionsveröffentlichung. Standardmäßig wird die in Mkosi fest eingebaute Standard-Veröffentlichung für die Distribution verwandt.

ToolsTreeMirror=, --tools-tree-mirror=

Setzt den für den Standardbaum zu verwendenen Spiegel. Standardmäßig wird der Standardspiegel für die Werkzeugbaumdistribution verwandt.

ToolsTreeRepositories=, --tools-tree-repository

Identisch zu Repositories=, aber für den Standardwerkzeugbaum.

ToolsTreePackageManagerTrees=, --tools-tree-package-manager-tree=

Identisch zu PackageManagerTrees=, aber für den Standardwerkzeugbaum.

ToolsTreePackages=, --tools-tree-packages=

Zusätzliche Pakete, die in den Standardwerkzeugbaum installiert werden sollen. Akzeptiert eine Kommata-getrennte Liste von Paketspezifikationen. Diese Option kann mehrfach verwandt werden, dann werden die angegebenen Paketlisten kombiniert.

ToolsTreeCertificates=, --tools-tree-certificates=

Specify whether to use certificates and keys from the tools tree. If enabled, /usr/share/keyrings, /usr/share/distribution-gpg-keys, /etc/pki, /etc/ssl, /etc/ca-certificates, /etc/pacman.d/gnupg and /var/lib/ca-certificates from the tools tree are used. Otherwise, these directories are picked up from the host.

RuntimeTrees=, --runtime-tree=

Akzeptiert eine Doppelpunkt-getrennte Liste von Pfaden. Der erste Pfad bezieht sich auf ein in jede von Mkosi zu startende Maschine (Container oder VM) einzuhängendes Verzeichnis. Der zweite Pfad bezieht sich auf das Zielverzeichnis innerhalb der Maschine. Falls der zweite Pfad nicht bereitgestellt wird, wird das Verzeichnis unter von /root/src in der Maschine eingehängt. Falls der zweite Pfad relativ ist, wird er relativ zu /root/src in der Maschine interpretiert.

RuntimeSize=, --runtime-size=

Falls angegeben werden Plattenabbilder bis zu der angegebenen Größe aufgewachsen, wenn sie mit mkosi boot oder mkosi qemu gestartet werden. Akzeptiert eine Größe in Byte. Zusätzlich können die Endungen K, M und G verwandt werden, um eine Größe in Kilobyte, Megabyte bzw. Gigabyte festzulegen.

RuntimeScratch=, --runtime-scratch=

Akzeptiert einen logischen Wert oder auto. Legt fest, ob ein zusätzlicher Arbeitsbereich unter /var/tmp eingehängt werden soll. Falls aktiviert, wird ein praktisch unbegrenzter Arbeitsbereich unter /var/tmp zur Verfügung gestellt, wenn das Abbild mit mkosi qemu, mkosi boot oder mkosi shell gestartet wird.

RuntimeNetwork=, --runtime-network=

Akzeptiert entweder user, interface oder none. Standardmäßig user. Legt das beim Systemstart einzurichtende Netzwerk fest. user richtet Benutzermodus-Vernetzung ein. interface richtet eine virtuelle Netzwerkverbindung zwischen dem Wirtrechner und dem Abbild ein. Dies übersetzt sich in eine Veth-Schnittstelle für mkosi shell und mkosi boot und eine Tap-Schnittstelle für mkosi qemu und mkosi vmspawn.

RuntimeBuildSources=, --runtime-build-sources=

Mount the build sources configured with BuildSources= and the build directory (if one is configured) to the same locations in /work that they were mounted to when running the build script when using mkosi boot or mkosi qemu.

UnitProperties=, --unit-property=

Configure systemd unit properties to add to the systemd scopes allocated when using mkosi boot or mkosi qemu. These are passed directly to the --property options of systemd-nspawn and systemd-run respectively.

SshKey=, --ssh-key=

Path to the X509 private key in PEM format to use to connect to a virtual machine started with mkosi qemu and built with the Ssh= option enabled via the mkosi ssh command. If not configured and mkosi.key exists in the working directory, it will automatically be used for this purpose. Run mkosi genkey to automatically generate a key in mkosi.key.

SshCertificate=, --ssh-certificate=

Path to the X509 certificate in PEM format to provision as the SSH public key in virtual machines started with mkosi qemu. If not configured and mkosi.crt exists in the working directory, it will automatically be used for this purpose. Run mkosi genkey to automatically generate a certificate in mkosi.crt.

Machine=, --machine=

Specify the machine name to use when booting the image. Can also be used to refer to a specific image when SSH-ing into an image (e.g. mkosi --image=myimage ssh).

ForwardJournal=, --forward-journal=

Specify the path to which journal logs from containers and virtual machines should be forwarded. If the path has the .journal extension, it is interpreted as a file to which the journal should be written. Otherwise, the path is interpreted as a directory to which the journal should be written.

Abschnitt [Match]¶

Profile=

Übereinstimmung mit dem konfigurierten Profil.

Distribution=

Übereinstimmung mit der konfigurierten Distribution.

Release=

Übereinstimmung mit der konfigurierten Distributionsveröffentlichung. Falls diese Bedingung verwandt wird und noch keine Distribution explizit konfiguriert wurde, wird die Distribution und Veröffentlichung der Wirtmaschine verwandt.

Architecture=

Übereinstimmung mit der konfigurierten Architektur. Falls diese Bedingung verwandt wird und noch keine Architektur explizit konfiguriert wurde, wird die Architektur des Wirtsystems verwandt.

Repositories=

Matches against repositories enabled with the Repositories= setting. Takes a single repository name.

PathExists=

Diese Bedingung ist erfüllt, wenn der angegebene Pfad existiert. Relative Pfade werden als relativ zum Elternverzeichnis der Konfigurationsdatei interpretiert, aus der diese Bedingung ausgelesen wurde.

ImageId=

Übereinstimmung mit der konfigurierten Abbildkennung, Globs werden unterstützt. Falls diese Bedingung verwandt wird und noch keine Abbildkennung explizit konfiguriert wurde, schlägt diese Bedingung fehl.

ImageVersion=

Matches against the configured image version. Image versions can be prepended by the operators ==, !=, >=, <=, <, > for rich version comparisons according to the UAPI group version format specification. If no operator is prepended, the equality operator is assumed by default. If this condition is used and no image version has been explicitly configured yet, this condition fails.

Bootable=

Matches against the configured value for the Bootable= feature. Takes a boolean value or auto.

Format=

Matches against the configured value for the Format= option. Takes an output format (see the Format= option).

SystemdVersion=

Matches against the systemd version on the host (as reported by systemctl --version). Values can be prepended by the operators ==, !=, >=, <=, <, > for rich version comparisons according to the UAPI group version format specification. If no operator is prepended, the equality operator is assumed by default.

BuildSources=

Takes a build source target path (see BuildSources=). This match is satisfied if any of the configured build sources uses this target path. For example, if we have a mkosi.conf file containing:

HostArchitecture=

Matches against the host’s native architecture. See the Architecture= setting for a list of possible values.

ToolsTreeDistribution=

Übereinstimmung mit der konfigurierten Werkzeugbaum-Distribution.

Environment=

Matches against a specific key/value pair configured with Environment=. If no value is provided, check if the given key is in the environment regardless of which value it has.

This table shows which matchers support globs, rich comparisons and the default value that is matched against if no value has been configured at the time the config file is read:

Abschnitt [Config]¶

Profile=, --profile=

Select the given profile. A profile is a configuration file or directory in the mkosi.profiles/ directory. When selected, this configuration file or directory is included after parsing the mkosi.conf file, but before any mkosi.conf.d/*.conf drop in configuration.

Include=, --include=, -I

Include extra configuration from the given file or directory. The extra configuration is included immediately after parsing the setting, except when used on the command line, in which case the extra configuration is included after parsing all command line arguments.

InitrdInclude=, --initrd-include=

Same as Include=, but the extra configuration files or directories are included when building the default initrd.

Dependencies=, --dependency=

Die Abbilder, von denen dieses Abbild abhängt, festgelegt als Kommata-getrennte Liste. Alle in dieser Option konfigurierten Abbilder werden vor diesem Abbild gebaut.

MinimumVersion=, --minimum-version=

Die minimale Version von Mkosi, die zum Bau dieser Konfiguration benötigt wird. Falls mehrfach angegeben, wird die höchste festgelegte Version verwandt.

ConfigureScripts=, --configure-script=

Akzeptiert eine Kommata-getrennte Liste von Pfaden zu Programmen, die als Konfigurationsskripte für dieses Abbild verwandt werden. Siehe den Abschnitt Skripte für weitere Informationen.

PassEnvironment=, --pass-environment=

Akzeptiert eine Liste von durch Leerzeichen getrennten Umgebungsvariablennamen. Bei Bau mehrere Abbilder werden die aufgeführten Umgebungsvariablen an jedes einzelne Unterabbild übergeben, als ob sie »universelle« Einstellungen wären. Siehe den Abschnitt Bau mehrerer Abbilder für weitere Informationen.

Kennzeichner¶

The current value of various settings can be accessed when parsing configuration files by using specifiers. To write a literal % character in a configuration file without treating it as a specifier, use %%. The following specifiers are understood:

There are also specifiers that are independent of settings:

Finally, there are specifiers that are derived from a setting:

Note that the current working directory changes as mkosi parses its configuration. Specifically, each time mkosi parses a directory containing a mkosi.conf file, mkosi changes its working directory to that directory.

Note that the directory that mkosi was invoked in is influenced by the --directory= command line argument.

The following table shows example values for the directory specifiers listed above:

Unterstützte Distributionen¶

Für die folgenden Distributionen können Abbilder zur Installation erstellt werden:

•

Fedora Linux

•

Debian

•

Ubuntu

•

Arch Linux

•

openSUSE

•

Mageia

•

CentOS

•

RHEL

•

RHEL UBI

•

OpenMandriva

•

Rocky Linux

•

Alma Linux

•

None (Dazu muss der Benutzer ein bereits gebautes Rootfs bereitstellen)

In theory, any distribution may be used on the host for building images containing any other distribution, as long as the necessary tools are available. Specifically, any distribution that packages apt may be used to build Debian or Ubuntu images. Any distribution that packages dnf may be used to build images for any of the rpm-based distributions. Any distro that packages pacman may be used to build Arch Linux images. Any distribution that packages zypper may be used to build openSUSE images. Other distributions and build automation tools for embedded Linux systems such as Buildroot, OpenEmbedded and Yocto Project may be used by selecting the custom distribution, and populating the rootfs via a combination of base trees, skeleton trees, and prepare scripts.

Derzeit paketiert Fedora Linux alle relevanten Werkzeuge seit Fedora 28.

Note that when not using a custom mirror, RHEL images can only be built from a host system with a RHEL subscription (established using e.g. subscription-manager).

Different ways to boot with qemu¶

The easiest way to boot a virtual machine is to build an image with the required components and let mkosi call qemu with all the right options:

$ mkosi -d fedora \


    --autologin \


    -p systemd-udev,systemd-boot,kernel-core \


    build
$ mkosi -d fedora qemu
…
fedora login: root (automatic login)
[root@fedora ~]#
    

The default is to boot with a text console only. In this mode, messages from the boot loader, the kernel, and systemd, and later the getty login prompt and shell all use the same terminal. It is possible to switch between the qemu console and monitor by pressing Ctrl-a c. The qemu monitor may for example be used to inject special keys or shut down the machine quickly. Alternatively the machine can be shut down using Ctrl-a x.

To boot with a graphical window, add --qemu-qui:

$ mkosi -d fedora --qemu-gui qemu
    

A kernel may be booted directly with mkosi qemu -kernel ... -initrd ... -append '...'. This is a bit faster because no boot loader is used, and it is also easier to experiment with different kernels and kernel commandlines. Note that despite the name, qemu’s -append option replaces the default kernel commandline embedded in the kernel and any previous -append specifications.

The UKI is also copied into the output directory and may be booted directly:

$ mkosi qemu -kernel mkosi.output/fedora~38/image.efi
    

When booting using an external kernel, we don’t need the kernel in the image, but we would still want the kernel modules to be installed.

It is also possible to do a direct kernel boot into a boot loader, taking advantage of the fact that systemd-boot(7) is a valid UEFI binary:

$ mkosi qemu -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
    

In this scenario, the kernel is loaded from the ESP in the image by systemd-boot.