mkosi.news

package: mkosi

title: mkosi.news(7)

summary: \-\f[R].

text:
# mkosi.news(7)

## mkosi Changelog

### v26

- Extra options to commands invoked by mkosi (e.g. when using mkosi boot or mkosi shell) should now be delimited from regular options using --. Options passed after the verb without using the -- delimiter are now interpreted as regular mkosi options.

- Boolean options specified on the command line now always expect a boolean argument. For example, --repository-key-check needs to become --repository-key-check=yes. The reason for this change is to remove ambiguity when parsing e.g. --repository-key-check build where build would be interpreted as the argument for --repository-key-check whereas now it’ll be properly interpreted as the verb.

- Teach --verity a new hash value, which skips the verity signature partition for extension / portable images. To align the possible values, yes is renamed to signed.

- Teach --verity a new defer value, which defers creation of the verity signature partition for disk, extension and portable images (but still allocates space for it). This is useful to implement offline signing of the verity roothash.

- A new way to specify modules included in the initrd has been added. The new default is that modules need to be specified to be included. Previous separate Include and Exclude options that take regexps are now deprecated and are replaced by a single option that takes a list of positive and negative globs. The new options are KernelModules= and KernelInitrdModules=.

- A new way to specify firmware files included in the initrd has been added. Previous separate Include and Exclude options that take regexps are now deprecated and are replaced by a single option that takes a list of positive and negative globs. The new option is FirmwareFiles=.

- The RuntimeScratch= option has been dropped. Use RuntimeSize= instead to grow the image before booting it.

- The CDROM= option has been dropped.

- Unknown settings now generate a warning message instead of failing the image build. This allows configs to work across a wider range of mkosi versions while still taking advantage of newer settings. MinimumVersion can still be used to enforce a minimum version of mkosi that knows all required settings.

### v25

- Instead of using bubblewrap, sandboxing is now done with a new tool mkosi-sandbox. This tool has a public API and can be used independently of mkosi.

- Image builds are now done in a user namespace with a single user when running unprivileged instead of using newuidmap/newgidmap. When running unprivileged, all files and directories in the image will be owned by the invoking user (and by root inside any produced archives). Any attempt to chown files to other users in scripts will fail unless the new environment variable $MKOSI_CHROOT_SUPPRESS_CHOWN is set to a true value.

- mkosi does not drop privileges anymore to the invoking user when running as root for various steps.

- A new cat-config verb will show all configuration files that were included for each configured image.

- Added support for Azure Linux

- Added support for Kali Linux

- If mkosi.version is executable, we now execute it and read the version from stdout.

- Added --wipe-build-dir to wipe the build directory before rebuilding the image.

- Introduced RepositoryKeyFetch= to control whether to fetch distribution GPG keys remotely. This setting is disabled by default for security reasons except when building rpm based or Arch Linux images on Ubuntu.

- We now handle SIGHUP gracefully

- Universal settings that take a collection of values cannot be appended to anymore in subimages. Usage of package manager trees in subimages will have to be moved to the top level image. Similarly, repositories will have to be enabled in the top level image.

- Repository metadata is not copied into images anymore.

- Repository metadata from base trees is not used anymore.

- Package manager trees are now named sandbox trees.

- Package manager trees (sandbox trees) do not use the skeleton trees as their default anymore if unset.

- Note to packagers: The manual pages have been moved to resources/man and now include man pages for mkosi-initrd and mkosi-sandbox as well.

- InitrdInclude= was removed. If you’re using InitrdInclude=, please build your initrd via a subimage in mkosi.images containing Include=mkosi-initrd and any customizations you wish to add and use the Initrds= setting to use it as the initrd for the main image instead of the default initrd.

- Added History= to have mkosi save the config used to build the image and reuse it when verbs such as qemu, boot, ... are invoked without -f.

- Introduced new [Build] section and moved various settings to it.

- Moved Include= to [Include] section

- Added sysupdate verb as a wrapper around systemd-sysupdate which invokes it with definitions from mkosi.sysupdate.

- Added RuntimeHome= to mount the current home directory to /root when running a command that boots the image

- More directories aside from /etc and /usr are now picked up from sandbox trees (formerly known as package manager trees).

- Profile configuration from mkosi.profiles is now parsed after mkosi.conf.d instead of before it. To set defaults for use in mkosi.conf.d based on the configured profile, use an early dropin in mkosi.conf.d that matches on the configured profile instead.

- Profile= is renamed to Profiles= and takes a comma separated list of profiles now. Scripts now receive $PROFILES with a space-separated list of profiles instead of $PROFILE. The %p specifier for profiles is removed.

- Multiple sync, prepare, build, postinst, finalize, postoutput and clean scripts are now picked up from mkosi.$SCRIPT.d.

- run0 is now automatically used to escalate privileges for commands that need it, like the burn verb.

- /usr/share/keyrings and /usr/share/distribution-gpg-keys are no longer automatically picked up from the tools tree when ToolsTreeCertificates= is set, since they aren’t certificates, use a sandbox tree instead. This allows one to override SignedBy= keys for APT repositories.

- The agetty.autologin and login.noauth credentials are no longer set unconditionally.

- Access to the output directory in build scripts was removed. To put artifacts from the build directory into the output directory, copy them from the build directory to the output directory in a post-installation script which does have access to the build directory and the output directory.

- BuildDirectory= is no longer available in PrepareScripts=. If you need to acquire some files for the build process place them somewhere sensible within $BUILDROOT so that they can be cached when building incrementally.

- When using a tools tree and a relaxed sandbox is used to run a command (qemu, nspawn, ...), we now keep all entries from $PATH outside of /usr intact. Note that this may cause issues if a $PATH entry contains binaries linked against libraries in /usr from the host.

- Introduced a new specifier %I which resolves to the name of the current subimage when used in a config under mkosi.images/. This differs to %o as it is always the name of the config file without extension (or the name of the directory).

- If /dev/fuse is found in the host context, it is made available in the sandbox context too.

- Added a sandbox verb to run a command within a relaxed mkosi sandbox (the same sandbox that mkosi vm, mkosi boot, ... run in).

- OpenSSL providers are now supported as key sources for the various key settings if a recent enough systemd version (257 or newer) is used.

- Added support for loading X.509 certificates from OpenSSL providers if a recent enough systemd version (257 or newer) is used.

- Added ToolsTreePackageDirectories=

- Added --kernel-image= to mkosi-initrd to specify the kernel image to use when building a UKI.

- Setting a collection based setting to the empty string via the CLI and then appending to the same setting will now override the settings coming from configuration files, whereas previously the CLI values would be appended to the values from configuration files.

- The mkosi-initrd default config now includes various extra kernel modules by default.

- The coredumpctl and journalctl verbs will now always operate on the image, even if ForwardJournal= is configured.

- Bumped default Fedora release to 41.

- Added addon output format to build UKI addons.

- Renamed [Host] section to [Runtime] section.

- Renamed various settings from [Host].

- Binaries coming from ExtraSearchPaths= are now executed with the tools tree mounted if one is configured (unlike before where the tools tree was not mounted). This means that any binaries coming from ExtraSearchPaths= have to be linked against libraries from the tools tree (or have to be statically linked). Alternatively, the tools tree distribution and release have to match the host.

- Binaries from ExtraSearchPaths= are not used anymore when building the default tools tree.

- Dropped support for pesign as a secure boot signing tool.

- Added support for systemd-sbsign as a secure boot signing tool.

- Added --register= to control whether to register containers and VMs with systemd-machined or not.

- mkosi.profiles is now parsed in subimages as well.

- mkosi-initrd now uses dnf5 on systems where it is the default.

- Added various packages to the default tools tree.

- Dropped support for Ubuntu Focal.

- Added Devicetree= setting for configuring bootloader device trees

- Added systemd-machined registration using varlink for mkosi qemu vms, which includes the vsock CID so that ssh vsock/<cid> or ssh machine/<name> will work on systems running systemd-machined 257 or newer.

- Bumped CentOS Stream default release to 10.

- mkosi now manages the pacman keyring itself so /etc/pacman.d/gnupg from the host is not used anymore and mkosi will run pacman-key --init and pacman-key --populate itself.

- Added ToolsTreeRelease= match

- mkosi now enforces that images built with Overlay=yes only add files on top of the base tree(s) and don’t overwrite any existing files or directories.

- Added a mkosi-addon tool and accompanying kernel-install plugin that allows building PE addons to extend a vendor provided unified kernel image.

- Added systemd-boot-signed, uki-signed and grub-signed variants for the Bootloader= option which instruct mkosi to only install pre-signed EFI binaries.

- mkosi.profiles is now parsed in configuration included with Include=.

- Any initrds configured with Initrds= are now used as fallback when booting with qemu direct kernel boot (--firmware=linux) if no split initrd was produced by the image build.

- mkosi now makes a greater effort to ensure the crypto-policies are configured to allow GPG keys from older distributions.

- We don’t pick up pre-signed bootloader binaries anymore when ShimBootloader=signed is configured. To force usage of pre-signed EFI binaries, use the new systemd-boot-signed, uki-signed and grub-signed variants for the Bootloader= option.

- Added a new constant microsoft-mok for the FirmwareVariables= option. If specified, a firmware variables file with the Microsoft keys enrolled will be extended to include a MokList entry that trusts the certificate configured with SecureBootCertificate= and passed to qemu.

- We now use mkosi.pkgcache as the package cache directory if the directory exists.

- BuildSourcesEphemeral= learned a new variant buildcache in which case the overlay will be cached in the build directory configured with BuildDirectory=.

### v24

- The default kernel command line of console=ttyS0 (or equivalent for other architectures) has been removed. The required console= argument to have the kernel output to the serial console has to be added manually from v24 onwards.

- Support for installing local packages located in directories in BuildSources= was dropped. Instead, the packages can be made available for installation via PackageManagerTrees=.

- Configuration parsing was reworked to remove the need for the @ specifier and to streamline building multiple images with mkosi.images/. If you were building multiple images with mkosi.images/, you’ll need to adapt your configuration to the rework. Read the Building multiple images section in the documentation for more information.

- mkosi has gained the option to generate completion scripts for bash, fish and zsh. Packagers should generate the scripts during packaging and ship them in the appropriate places.

- Added support for CentOS Stream 10.

- mkosi now installs a separate mkosi-initrd script that can be used to build initramfs images intended for use on the local system.

- We do not automatically append centos-stream or fedora anymore to CentOS (and derivatives) and Fedora mirrors specified with Mirror= as not all mirrors store the repository metadata under these subdirectories. Users are now required to add these subdirectories themselves in Mirror=. If the EPEL repositories are enabled for CentOS Stream (and derivatives) and Mirror= is used, we look for the EPEL repositories in ../fedora relative to the mirror specified in Mirror=.

- We now support compressed tar archives wherever we already accept tar archives as input.

- We now always rerun the build if Format=none and don’t remove previous outputs in that case (unless --force is specified). This allows using mkosi -t none to rerun the build scripts without removing the previous image. This can then be combined with RuntimeBuildSources=yes to make the build script outputs available in a booted container or virtual machine so they can be installed without having to rebuild the image.

- We now use virtconsole to provide the serial console when booting with qemu.

- root=PARTUUID and mount.usr=PARTUUID on the kernel command line are now automatically extended with the actual PARTUUID of the corresponding partition.

- All available OpenSUSE repositories are now supported and can be enabled with Repositories=.

- Building OpenSUSE aarch64 images is now supported

- mkosi dependencies was beefed up to handle more scenarios properly

- The default list of kernel modules that are always added to the initramfs was extended with various virtualization modules.

- Added a Repositories= match.

- Cached images are now invalidated if packages specified via PackageDirectories= change.

- Added VolatilePackageDirectories= which can be used to provide local packages that do not invalidate cached images.

- mkosi.pkgmngr is now used as the default path for PackageManagerTrees=.

- The package directory that build scripts can use to make built packages available for installation ($PACKAGEDIR) is now shared between all image builds. This means that packages built in earlier images and stored in $PACKAGEDIR become available for installation in all subsequent image builds.

- The default tools tree distribution is now chosen based on the host distribution instead of the target distribution.

- mkosi can now be invoked from the initramfs.

### v23.1
•

Respin due to git tag mismatch

### v23

- Added CleanScripts= to allow running custom cleanup code whenever mkosi cleans up the output directory. This allows cleaning up extra outputs produced by e.g. a build script that mkosi doesn’t know about.

- Added ConfigureScripts= to allow dynamically modifying the mkosi configuration. Each configure script receives the current config as JSON on stdin and should output the new config as JSON on stdout.

- When building a UKI, we don’t measure for the TPM SHA1 PCR bank anymore.

- All keys in the mkosi config JSON output are now in pascal case, except for credentials and environments, where the keys encode names of credentials and environment variables and are therefore case sensitive.

- Added various settings to allow running mkosi behind a proxy.

- Various fixes to kernel module filtering that should result in fewer modules being pulled into the default initrd when KernelModulesExclude= or KernelModulesInitrdExclude= are used.

- Added ToolsTreeDistribution= match.

- Removed vmspawn verb and replaced it with VirtualMachineMonitor=.

- New specifiers for various directories were added. %D resolves to the directory that mkosi was invoked in, %P to the current working directory, and %C to the parent directory of the config file.

- Added ForwardJournal= to have systemd inside a container/VM forward its journal to the specified file or directory.

- Systemd scopes are now allocated for qemu, swtpm, virtiofsd and systemd-journal-remote if available.

- The mkosi qemu virtual machine is now registered with systemd-machined if available.

- Added new oci output format

- Runtime trees without a target are now mounted to /root/src instead of a subdirectory of it (To have the same behaviour as BuildSources=).

- Added RuntimeBuildSources= to mount build and source directories when booting the image with mkosi nspawn or mkosi qemu.

- Introduced --append to allow command line settings to be parsed after parsing configuration files.

- distribution-release is not installed by default anymore on OpenSUSE.

- Setting QemuSmp= to 0 will now make qemu use all available CPUs

- Free page reporting and discard request processing are now enabled by default in VMs spawned by mkosi qemu.

- Added ToolsTreeCertificates= to allow configuring whether to use certificates and keys from the tools tree (if one is used) or the host.

- Added never for CacheOnly= to specify that repository metadata should always be refreshed.

- Renamed the none option for CacheOnly= to auto.

- Added ProxyExclude= to configure hostnames for which requests should not go through the configured proxy.

- The default tools tree is now reused on incremental builds.

- Added VolatilePackages= and InitrdVolatilePackages= to configure packages that should be installed after executing build scripts and which should not be cached when using Incremental=.

- PackageDirectories= now has an associated default path mkosi.packages.

- reprepro is now used to generate local apt repositories.

- Support for BSD tar/cpio was dropped.

- When both ExtraSearchPaths= and ToolsTree= are used, mkosi will now prefer running a binary found in ExtraSearchPaths= without the tools tree over running the binary from the tools tree. If a binary is not found in ExtraSearchPaths=, the tools tree is used instead.

- An artifact directory is now made available when running scripts which can be used to pass around data between different scripts. mkosi will also look for microcode and initrds in the artifact directory under the io.mkosi.microcode and io.mkosi.initrd subdirectories.

- Added Environment= match setting to check for environment variables defined with the Environment= setting.

- The basesystem package is now always installed in Fedora and CentOS images instead of the filesystem package.

- The qemu, shell and boot verbs do not automatically build the image anymore unless --force is specified.

- SplitArtifacts= is now supported for the portable, sysext and confext outputs.

- The WithDocs= option was implemented for pacman-based distributions.

- The default Fedora release was bumped to 40.

- QemuSwtpm= can now be used with QemuFirmware= set to linux or bios.

- Added UnitProperties= to allow configure properties on the scopes generated by systemd-nspawn and systemd-run.

- mkosi now only builds a single default tools tree per build using the settings from the last regular image that we’ll build.

- Configure scripts are now only executed for verbs which imply an image build and are executed with the tools tree instead of without it.

- $QEMU_ARCHITECTURE is now set for configure scripts to easily allow scripts to figure out which qemu binary will be used to run qemu.

- A file ID can now be specified for QemuDrives=. This allows adding multiple qemu drives that are backed by the same file.

- mkosi doesn’t fail anymore if images already exist when running mkosi build.

- Image names from mkosi.images/ are now preferred over the specified image ID when determining the output filename to use for an image.

- --include now has a shorthand option -I.

- The WITH_NETWORK environment variable is now passed to build and finalize scripts.

- We now clamp mtimes to the specified source date epoch timestamp instead of resetting all mtimes. This means that we won’t touch any mtimes that are already older than the given source date epoch timestamp.

- Removed support for CentOS 8 Stream as it is now EOL.

- The coredumpctl and journalctl verbs now operrate on the path specified in ForwardJournal= if one is set.

- Added UnifiedKernelImageFormat= format setting to allow configuring the naming of unified kernel images generated by mkosi.

- The versionlock plugin is now enabled by default for dnf with a noop configuration.

- Repositories= is now implemented for zypper.

- KernelModulesInclude= and KernelModulesInitrdInclude= now take the special values host and default to include the host’s loaded modules and the default kernel modules defined in mkosi-initrd respectively.

- KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= are now deprecated.

- Added mkosi dependencies to output the list of packages required by mkosi to build and boot images.

### v22

- We’ll now try to delete btrfs subvolumes with btrfs subvolume delete first before falling back to recursively deleting the directory.

- The invoking user is now always mapped to root when running sync scripts. This fixes an issue where we would fail when a package manager tree or skeleton tree contained a /usr directory as we would not have permissions to run mount in the sandbox.

- We now use qemu’s official firmware descriptions to find EDK2/OVMF UEFI firmware. Addititionally, QemuFirmware=uefi now boots without SecureBoot support, and QemuFirmware=uefi-secure-boot was introduced to boot with SecureBoot support. By default we will still boot with SecureBoot support if QemuFirmware=auto.

- Added support for QemuFirmwareVariables=custom and QemuFirmwareVariables=microsoft to use OVMF/EDK2 variables with either the user’s custom keys enrolled or with the Microsoft keys enrolled.

- Added UnifiedKernelImages= to control whether we generate unified kernel images or not.

- Bootloader=grub will now generate a grub EFI image and install it. If SecureBoot= is enabled and ShimBootloader= is not set to signed, the grub EFI image will be signed for SecureBoot.

- ShimBootloader=signed will now also instruct mkosi to look for and install already signed grub, systemd-boot, kernel and UKI binaries.

- We now build grub images with a fixed set of modules and don’t copy any grub modules to the ESP anymore.

- The configuration is now made available as a JSON file to all mkosi scripts via the $MKOSI_CONFIG environment variable.

- $PROFILE is now set for all mkosi scripts containing the value of Profile= if it is set.

### v21

- We now handle unmerged-usr systems correctly

- Builtin configs (mkosi-initrd, mkosi-tools) can now be included using Include= (e.g. Include=mkosi-initrd)

- The kernel-install plugin now uses the builtin mkosi-initrd config so there’s no need anymore to copy the full mkosi-initrd config into /usr/lib/mkosi-initrd.

- We don’t require a build anymore for the journalctl and coredumpctl verbs.

- mkosi ssh works again when used with ToolsTree=default

- We now use .zst instead of .zstd for compressed split artifacts produced by systemd-repart.

- systemd-repart uses a persistent temporary directory again for assembling images instead of a tmpfs.

- Added MicrocodeHost= setting to only include the CPU specific microcode for the current host system.

- The kernel-install plugin now only includes the CPU specific microcode

- Introduced PackageCacheDirectory= to set the directory for package manager caches. This setting defaults to a suitable location in the system or user directory depending on how mkosi is invoked. CacheDirectory= is only used for incremental cached images now.

- Repository metadata is now synced once at the start of each image build and never during an image build. Each image includes a snapshot of the repository metadata in the canonical locations in /var so that incremental images and extension images can reuse the same snapshot. When building an image intended to be used with BaseTrees=, disable CleanPackageMetadata= to make sure the repository metadata in /var is not cleaned up, otherwise any extension images using this image as their base tree will not be able to install additional packages.

- Implemented CacheOnly=metadata. Note that in the JSON output, the value of CacheOnly= will now be a string instead of a boolean.

- Added CompressLevel= to set the compression level to use.

- Dropped experimental Gentoo support.

- Added TriggerMatch= to specify multiple match sections of which only one should be satisfied.

- Added jq, attr, acl, git, sed, grep and findutils to the default tools tree.

- Added mkosi-install, mkosi-upgrade, mkosi-remove and mkosi-reinstall scripts which allow writing scripts that are independent of the package manager being used to build the image.

- We now expand specifiers in Match section values

- Made GPG key handling for Fedora rawhide more robust

- If systemd-repart 256 or newer is available, mkosi will instruct it to generate /etc/fstab and /etc/crypttab for the image if any partition definitions contain the corresponding settings (MountPoint= and EncryptedVolume=).

- bash is now started in the debug shell instead of sh.

- The default release for Ubuntu is now noble.

- Ubuntu is now used as the default tools tree distribution for Ubuntu instead of Debian.

- Added mkosi vmspawn which boots the image with systemd-vmspawn. Note that systemd-vmspawn is experimental and its interface may still change. As such mkosi vmspawn is also considered experimental. Note that systemd-vmspawn version 256 or newer is required.

- Added SyncScripts= which can be used to update various build sources before starting the image build.

- The DISTRIBUTION= and RELEASE= environment variables are now set when running scripts.

- Added ToolsTreeRepositories= and ToolsTreePackageManagerTrees=.

- Added RuntimeNetwork= to configure the networking used when booting the image.

- Added SecureBootKeySource= and VerityKeySource= to support signing images with OpenSSL engines. Note that these settings require various systemd tools to be version 256 or newer.

- We don’t clean up package manager metadata anymore unless explicitly requested with CleanPackageManagerMetadata=yes when building directory and tar images.

### v20.2

- Fixed a bug in signing unsigned shim EFI binaries.

- We now build an early microcode initrd in the mkosi kernel-install plugin.

- Added PackageDirectories= to allow providing extra packages to be made available during the build.

- Fixed issue where KernelModulesIncludeHost was including unnecessary modules

- Fixed --mirror specification for CentOS (and variants) and Fedora. Previously a subdirectory within the mirror had to be specified which prevented using CentOS and EPEL repositories from the same mirror. Now only the URL has be specified.

- We now mount package manager cache directories when running scripts on the host so that any packages installed in scripts are properly cached.

- We don’t download filelists on Fedora anymore

- Nested build sources don’t cause errors anymore when trying to install packages.

- We don’t try to build the same tools tree more than once anymore when building multiple images.

- We now create the /etc/mtab compatibility symlink in mkosi’s sandbox.

- We now always hash the root password ourselves instead of leaving it to systemd-firstboot.

- /srv and /mnt are not mounted read-only anymore during builds.

- Fixed a crash when running mkosi in a directory with fewer than two parent directories.

- Implemented RepositoryKeyCheck= for apt-based distributions.

### v20.1

- BuildSources= are now mounted when we install packages so local packages can be made available in the sandbox.

- Fixed check to see if we’re running as root which makes sure we don’t do shared mounts when running as root.

- The extension release file is now actually written when building system or configuration extensions.

- The nspawn settings are copied to the output directory again.

- Incremental caching is now skipped when Overlay= is enabled as this combination isn’t supported.

- The SELinux relabel check is more granular and now checks for all required files instead of just whether there’s a policy configured.

- qemu-system-xxx binaries are now preferred over the generic qemu and qemu-kvm binaries.

- Grub tools from the tools tree are now used to install grub instead of grub tools from the image itself. The grub tools were added to the default tools trees as well.

- The pacman keyring in tools trees is now only populated from the Arch Linux keyring (and not the Debian/Ubuntu ones anymore).

- gpg is allowed to access /run/pscsd/pscsd.comm on the host if it exists to allow interaction with smartcards.

### v20

- The current working directory is not mounted unconditionally to /work/src anymore. Instead, the default value for BuildSources= now mounts the current working directory to /work/src. This means that the current working directory is no longer implicitly included when BuildSources= is explicitly configured.

- Assigning the empty string to a setting that takes a list of values now overrides any configured default value as well.

- The github action does not build and install systemd from source anymore. Instead, ToolsTree=default can be used to make sure a recent version of systemd is used to do the image build.

- Added EnvironmentFiles= to read environment variables from environment files.

- We drastically reduced how much of the host system we expose to scripts. Aside from /usr, a few directories in /etc, /tmp, /var/tmp and various directories configured in mkosi settings, all host directories are hidden from scripts, package managers and other tools executed by mkosi.

- Added RuntimeScratch= to automatically mount a directory with extra scratch space into mkosi-spawned containers and virtual machines.

- Package manager trees can now be used to configure every tool invoked by mkosi while building an image that reads config files from /etc or /usr.

- Added SELinuxRelabel= to specify whether to relabel selinux files or not.

- Many fixes to tools trees were made and tools trees are now covered by

CI.

Some combinations aren’t possible yet but we’re actively working to make these possible.

- mkosi qemu now supports direct kernel boots of s390x and powerpc images.

- Added HostArchitecture= match to match against the host architecture.

- We don’t use the user’s SSH public/private keypair anymore for mkosi ssh but instead use a separate key pair which can be generated by mkosi genkey. Users using mkosi ssh will have to run mkosi genkey once to generate the necessary files to keep mkosi ssh working.

- We don’t automatically set --offline=no anymore when we detect the Subvolumes= setting is used in a systemd-repart partition definition file. Instead, use the new RepartOffline= option to explicitly disable running systemd-repart in offline mode.

- During the image build we now install UKIs/kernels/initrds to /boot instead of /efi. While this will generally not be noticeable, users with custom systemd-repart ESP partition definitions will need to add CopyFiles=/boot:/ along with the usual CopyFiles=/efi:/ to their ESP partition definitions. By installing UKIs/kernels/initrds to /boot, it becomes possible to use /boot to populate an XBOOTLDR partition which wasn’t possible before. Note that this is also safe to do before v20 so CopyFiles=/boot:/ can unconditionally be added to any ESP partition definition files.

- Added QemuFirmwareVariables= to allow specifying a custom OVMF variables file to use.

- Added MinimumVersion= to allow specifying the minimum required mkosi version to build an image.

- Added support for Arch Linux’s debug repositories.

- Merged the mkosi-initrd project into mkosi itself. mkosi-initrd is now used to build the default initrd.

- Implemented mkosi-initrd for all supported distributions.

- Added ShimBootloader= to support installing shim to the ESP.

- Added sysext, confext and portable output formats. These will produce signed disk images that can be used as sysexts, confexts and portable services respectively.

- Added QemuVsockConnectionId= to configure how to allocate the vsock connection ID when QemUVsock= is enabled.

- Added documentation on how to build sysexts with mkosi.

- Global systemd user presets are now also configured.

- Implemented WithDocs= for apt.

- On supported package managers, locale data for other locales is now stripped if the local is explicitly configured using Locale=.

- All rpm plugins are now disabled when building images.

- Added KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= to only include modules loaded on the host system in the image/initrd respectively.

- Implemented RemovePackages= for Arch Linux.

- Added useradd and groupadd scripts to configure these binaries to operate on the image during builds instead on the host.

- Added microcode support. If installed into the image, an early microcode initrd will automatically be built and prepended to the initrd.

- A passwordless root account may now be created by specifying hashed:.

- The Autologin= feature was extended with support for arm64, s390x and powerpc architectures.

- Added SecureBootAutoEnroll= to control automatic enrollment of secureboot keys separately from signing systemd-boot and generated UKIs.

- ImageVersion= is no longer automatically appended to the output files, instead this is automatically appended to Output= if not specified and results in the %o specifier being equivalent to %i or %i_%v depending on whether ImageVersion= is specified.

### v19

- Support for RHEL was added!

- Added journalctl and coredumpctl verbs for running the respective tools on built directory or disk images.

- Added a burn verb to write the output image to a block device.

- Added a new esp output format, which is largely similar to the existing uki output format but wraps it in a disk image with only an ESP.

- Presets were renamed to Images. mkosi.images/ is now used instead of mkosi.presets/, the Presets= setting was renamed to Images= and the Presets section was merged into the Config section. The old names can still be used for backwards compatibility.

- Added profiles to support building variants of the same image in one repository. Profiles can be defined in mkosi.profiles/ and one can be selected using the new Profile= setting.

- mkosi will now parse mkosi.local.conf before any other config files if that exists.

- Added a kernel-install plugin. This is only shipped in source tree and not included in the Python module.

- Added a --json option to get the output of mkosi summary as JSON.

- Added shorthand -a for --autologin.

- Added a --debug-workspace option to not remove the workspace directory after a build. This is useful to inspect the workspace after failing builds. As a consequence the prefix for the default workspace directory prefix has been changed from .mkosi-tmp to mkosi-workspace.

- Scripts with the .chroot extension are now executed in the image automatically.

- Added rpm helper script to have rpm automatically operate on the image when running scripts.

- Added mkosi-as-caller helper script that can be used in scripts to run commands as the user invoking mkosi.

- mkosi-chroot will now start a shell if no arguments are specified.

- Added WithRecommends= to configure whether to install recommended packages by default or not where this is supported. It is disabled by default.

- Added ToolsTreeMirror= setting for configuring the mirror to use for the default tools tree.

- WithDocs= is now enabled by default.

- Added BuildSourcesEphemeral= to make source directories ephemeral when running scripts. This means any changes made to source directories while running scripts will be undone after the scripts have finished executing.

- Added QemuDrives= to have mkosi create extra qemu drives and pass them to qemu when using the qemu verb.

- Added BuildSources= match to match against configured build source targets.

- PackageManagerTrees= was moved to the Distribution section.

- We now automatically configure the qemu firmware, kernel cmdline and initrd based on what type of kernel is passed by the user via -kernel or QemuKernel=.

- The mkosi repository itself now ships configuration to build basic bootable images that can be used to test mkosi.

- Added support for enabling updates-testing repositories for Fedora.

- GPG keys for CentOS, Fedora, Alma and Rocky are now looked up locally first before fetching them remotely.

- Signatures are not required for local packages on Arch anymore.

- Packages on opensuse are now always downloaded in advance before installation when using zypper.

- The tar output is now reproducible.

- We now make sure git can be executed from mkosi scripts without running into permission errors.

- We don’t create subdirectories beneath the configured cache directory anymore.

- Workspace directories are now created outside of any source directories. mkosi will either use XDG_CACHE_HOME, $HOME/.cache or /var/tmp depending on the situation.

- Added environment variable MKOSI_DNF to override which dnf to use for building images (dnf or dnf5).

- The rootfs can now be modified when running build scripts (with all changes thrown away after the last build script has been executed).

- mkosi now fails if configuration specified via the CLI does not apply to any image (because it is overridden).

- Added a new doc on building rpms from source with mkosi (docs/building-rpms-from-source.md).

- /etc/resolv.conf will now only be mounted for scripts when they are run with network access.

### v18

- $SCRIPT was renamed to $CHROOT_SCRIPT. $SCRIPT can still be used but is considered deprecated.

- Added RuntimeTrees= setting to mount directories when booting images via mkosi boot, mkosi shell or mkosi qemu. The directories are mounted with a uid map that maps the user invoking mkosi to the root user so that all files in the directory appear as if owned by the root user in the container or virtual machine and any new files created in the directories are owned by the user invoking mkosi. To make this work in VMs, we use VirtioFS via virtiofsd. Note that this requires systemd v254 or newer to be installed in the image.

- Added support for booting directory images with mkosi qemu via VirtioFS. When CONFIG_VIRTIOFS and CONFIG_VIRTIO_PCI are builtin modules, no initramfs is required to make this work.

- Added Include= or --include to include extra configuration files or directories.

- Added support for specifiers to access the current value of certain settings during configuration file parsing.

- mkosi will now exit with an error when no configuration was provided.

- Multiple scripts of the same type are now supported.

- Custom distributions are now supported via the new custom distribution. When using custom as the distribution, the rootfs must be provided via base trees, skeleton trees or prepare scripts.

- We now use local GPG keys for rpm based distributions if the distribution-gpg-keys package is installed on the host.

- Added RuntimeSize= to grow the image to a specific size before booting it when using mkosi boot or mkosi qemu.

- We now set MKOSI_UID and MKOSI_GID when running scripts which are set to the uid and gid of the user invoking mkosi respectively. These can be used to run commands as the user that invoked mkosi.

- Added an Architecture= match

- Initrds specified with Initrds= are now used for grub menuentries as well.

- ImageId= and ImageVersion= are now written to os-release as IMAGE_ID and IMAGE_VERSION if provided.

- We pass command line arguments passed to the build verb to the build script again.

- We added support for the “RHEL Universal Base Image” distribution.

### v17.1
•

Fixed bug where --autologin was broken when used in combination with a tools tree when using a packaged version of mkosi.

### v17

- Added ToolsTreePackages= to add extra packages to the default tools tree.

- Added SystemdVersion= match to match on the host’s systemd version

- Added Format= match to match on the configured output format

- Presets= can now be configured in global configuration files to select which presets to build

- UKIs can now be booted using direct linux boot.

- We don’t try to make images UEFI bootable anymore on architectures that do not support UEFI

- Fixed --help to show all options again

- We now warn when settings are configured in the wrong section

### v16

- mkosi.version is now picked up from preset and dropin directories as well following the usual config precedence logic

- Removed the “first assignment wins” logic from configuration parsing. Settings parsed later will now override earlier values

- Removed the ! operator for lists. Instead, assign the empty string to the list to remove all previous values.

- Added support for configuring custom default values for settings by prefixing their name in the configuration file with @.

- Added QemuCdrom= to attach the image to the virtual machine as a CD-ROM instead of a block device.

- Added SectorSize= to set the sector size of the disk images built by systemd-repart.

- Added back grub support (BIOS/UEFI). Note that we don’t install grub on UEFI yet but we do add the necessary configuration and partitions.

- Added Bootloader= option to configure which EFI bootloader to install. Added uki option to install just the UKI without systemd-boot and grub to generate grub configuration to chainload into the built UKIs.

- Added BiosBootloader= to configure whether grub for BIOS gets installed or not.

- Added QemuFirmware= to select which qemu firmware to use (OVMF, Seabios or direct kernel boot).

- Added QemuKernel= to specify the kernel that should be used with direct kernel boot.

- /var/lib/dbus/machine-id is now removed if it was added by a package manager postinstall script.

- The manifest is not generated by default anymore. Use ManifestFormat=json to make sure the manifest is generated.

- Added SourceDateEpoch= to enable more reproducible image builds.

- Added Seed= to set the seed passed to systemd-repart.

- Updated the default Fedora release to Fedora 39.

- If ToolsTree= is set to default, mkosi will now build a default tools tree containing all the necessary tools to build images. The distribution and release to use can be configured with ToolsTreeDistribution= and ToolsTreeRelease= or are determined automatically based on the image being built.

- Added uki output format. This is similar to cpio, except the cpio is packaged up as a UKI with a kernel image and stub picked up from the rootfs.

### v15.1

- The man page can be generated from the markdown file via tools/make-man-page.sh.

- Fixed issue where not all packages and data files where included in the generated python package.

- mkosi doesn’t try to unshare the network namespace anymore when it doesn’t have CAP_NET_ADMIN.

- Fixed issue when the workspace was located in /tmp.

- Don’t try to run timedatectl or ssh-add when they’re not installed.

### v15
•

Migrated to systemd-repart. Many options are dropped in favor of specifying them directly in repart partition definition files:

- Format=gpt_xxx options are replaced with a single “disk” options. Filesystem to use can now be specified with repart’s Format= option

- Format=plain_squashfs (Can be reproduced by a single repart squashfs root partition combined with SplitArtifacts=yes)

- Verity= (Replaced by repart’s Verity= options)

- Encrypt= (Replaced by repart’s Encrypt= option)

- RootSize=, HomeSize=, VarSize=, TmpSize=, ESPSize=, SwapSize=, SrvSize= (Replaced by repart’s size options)

- UsrOnly= (replaced with CopyFiles=/:/usr in a usr partition definition)

- OutputSplitRoot=, OutputSplitVerity=, (Replaced by repart’s SplitName= option)

- OutputSplitKernel= (UKI is now always written to its own output file)

- GPTFirstLBA (Removed, no equivalent in repart)

- ReadOnly= (Replaced by repart’s ReadOnly= option per partition)

- Minimize= (Replaced by repart’s Minimize= option per partition)

- CompressFs= (No equivalent in repart, can be replicated by replacing mkfs. in $PATH with a script that adds the necessary command line option)

- MkSquashfs= (Can be replaced with a script in $PATH that invokes the correct binary)

We also remove the WithoutUnifiedKernelImages= switch as building unified kernel images is trivial and fast these days.

- Support for –qemu-boot was dropped

- Support for –use-host-repositories was dropped, use –repository-directory instead

- RepositoryDirectory was removed, use PackageManagerTrees= or SkeletonTrees= instead.

- --repositories is now only usable on Debian/RPM based distros and can only be used to enable additional repositories. Specifically, it cannot be used on Arch Linux anymore to add new repositories.

- The _epel distributions were removed. Use --repositories=epel instead to enable the EPEL repository.

- Removed -stream from CentOS release specifiers. Instead of specifying 8-stream, you know just specify 8.

- Removed default kernel command line arguments rhgb, selinux=0 and audit=0.

- Dropped –all and –all-directory as this functionality is better implemented by using a build system.

- mkosi now builds images without needing root privileges.

- Removed --no-chown, --idmap and --nspawn-keep-unit options as they were made obsolete by moving to rootless builds.

- Removed --source-file-transfer, --source-file-transfer-final, --source-resolve-symlinks and --source-resolve-symlinks-final in favor of always mounting the source directory into the build image. --source-file-transfer-final might be reimplemented in the future using virtiofsd.

- Dropped --include-dir option. Usage can be replaced by using --incremental and reading includes from the cached build image tree.

- Removed --machine-id in favor of shipping images without a machine ID at all.

- Removed --skip-final-phase as we only have a single phase now.

- The post install script is only called for the final image now and not for the build image anymore. Use the prepare script instead.

- --ssh-key, --ssh-agent, --ssh-port and --ssh-timeout options were dropped as the SSH support was reimplemented using VSock. mkosi ssh can only be used with images booted with mkosi qemu. Use machinectl to access images booted with mkosi boot. Use –extra-tree or –credential with the .ssh.authorized_keys.root credentials as alternatives for provisioning the public key inside the image.

- Only configuration files matching *.conf are parsed in dropin directories now.

- Removed --qemu-headless, we now start qemu in the terminal by default and configure the serial console at runtime. Use the new --qemu-gui option to start qemu in its graphical interface.

- Removed --netdev. Can be replaced by manually installing systemd-networkd, putting a network file in the image and enabling systemd-networkd.

- If mkosi.extra/ or mkosi.skeleton/ exist, they are now always used instead of only when no explicit extra/skeleton trees are defined.

- mkosi doesn’t install any default packages anymore aside from packages required by the distro or the base filesystem layout package if there are no required packages. In practice, this means systemd and other basic tools have to be installed explicitly from now on.

- Removed --base-packages as it’s not needed anymore since we don’t install any packages by default anymore aside from the base filesystem layout package.

- Removed --qcow2 option in favor of supporting only raw disk images as the disk image output format.

- Removed --bmap option as it can be trivially added manually by utilizing a finalize script.

- The never value for --with-network was spun of into its own custom option --cache-only.

- --bootable now defaults to auto. When set to auto, mkosi will generate a bootable image only if all the necessary packages are installed. Documentation was added in docs/bootable.md on how a bootable image can be generated on mainstream distros.

- The RPM db is no longer rebuilt in bdb format on CentOS Stream 8. To be able to install packages on a CentOS Stream 8 image with a RPM db in sqlite format, rewrite the db in bdb format using rpm --rebuilddb --define _db_backend bdb.

- Repositories are now only written to /etc/apt/sources.list if apt is installed in the image.

- Removed the dependency on debootstrap to build Ubuntu or Debian images.

- Apt now uses the keyring from the host instead of the keyring from the image. This means debian-archive-keyring or ubuntu-archive-keyring are now required to be installed to build Debian or Ubuntu images respectively.

- --base-image is split into --base-tree and --overlay.

- Removed --cache-initrd, instead, use a prebuilt initrd with Initrds= to avoid rebuilding the initrd all the time.

- Disk images are now resized to 8G when booted to give some disk space to play around with in the booted image.

- Removed --install-directory= option. This was originally added for caching the installation results, but this doesn’t work properly as it might result in leftover files in the install directory from a previous installation, so we have to empty the directory before reusing it, invalidating the caching, so the option was removed.

- Build scripts are now executed on the host. See the SCRIPTS section in the manual for more information. Existing build scripts will need to be updated to make sure they keep working. Specifically, most paths in scripts will need to be prefixed with $BUILDROOT to have them operate on the image instead of on the host system. To ensure the host system cannot be modified when running a script, most host directories are mounted read-only when running a script to ensure a script cannot modify the host in any way. Alternatively to making the script run on the host, the script can also still be executed in the image itself by putting the following snippet at the top of the script:

```
if [ "$container" != "mkosi" ]; then

    exec mkosi-chroot "$SCRIPT" "$@"
fi

```

- Removed --tar-strip-selinux-context= option. We now label all files properly if selinux is enabled and if users don’t want the labels, they can simply exclude them when extracting the archive.

- Gentoo is now marked as experimental and unsupported and there’s no guarantee at all that it will work. Issues related to gentoo will generally not receive attention from core maintainers. All gentoo specific hacks outside of the gentoo implementation module have been removed.

- A verb documentation has been added. Calling mkosi with this verb will show the documentation. This is useful when running mkosi during development to always have the documentation in the correct version available. By default it will try several ways to output the documentation, but a specific option can be chosen with the --doc-format option. Distro packagers are encouraged to add a file mkosi.1 into the mkosi/resources directory of the Python package, if it is missing, as well es install it in the appropriate search path for man pages. The man page can be generated from the markdown file mkosi/resources/mkosi.md e.g via pandoc -t man -s -o mkosi.1 mkosi.md.

- BuildSources= now takes source:target pairs which specify the source directory and where to mount it relative to the top level source directory when running scripts. (e.g. BuildSources=../my-project:my-project)

### v14

- Support for Clear Linux was dropped. See https://github.com/systemd/mkosi/pull/1037 for more information.

- Support for Photon was dropped. See https://github.com/systemd/mkosi/pull/1048 for more information.

- The Arch kernel/bootloader pacman hooks were removed. For anyone that still wants to use them, they can be found here.

- mkosi now creates distro~release subdirectories inside the build, cache and output directories for each distro~release combination that is built. This allows building for multiple distros without throwing away the results of a previous distro build every time.

- The preferred names for mkosi configuration files and directories are now mkosi.conf and mkosi.conf.d/ respectively. The old names (mkosi.default and mkosi.default.d) have been removed from the docs but are still supported for backwards compatibility.

- plain_squashfs type images will now also be named with a .raw suffix.

- tar type images will now respect the --compress option.

- Pacman’s SigLevel option was changed to use the same default value as used on Arch which is SigLevel = Required DatabaseOptional. If this results in keyring errors, you need to update the keyring by running pacman-key --populate archlinux.

- Support for CentOS 7 was dropped. If you still need to support CentOS 7, we recommend using any mkosi version up to 13.

- Support for BIOS/grub was dropped. because EFI hardware is widely available and legacy BIOS systems do not support the feature set to fully verify a boot chain from firmware to userland and it has become bothersome to maintain for little use.

To generate BIOS images you can use any version of mkosi up to mkosi 13 or the new --bios-size option. This can be used to add a BIOS boot partition of the specified size on which grub (or any other bootloader) can be installed with the help of mkosi’s script support (depending on your needs most likely mkosi.postinst or mkosi.finalize). This method can also be used for other EFI bootloaders that mkosi intentionally does not support.

- mkosi now unconditionally copies the kernel, initrd and kernel cmdline from the image that were previously only copied out for Qemu boot.

- mkosi now runs apt and dpkg on the host. As such, we now require apt and dpkg to be installed on the host along with debootstrap in order to be able to build debian/ubuntu images.

- Split dm-verity artifacts default names have been changed to match what systemd and other tools expect: image.root.raw, image.root.verity, image.root.roothash, image.root.roothash.p7s (same for usr variants).

- mkosi will again default to the same OS release as the host system when the host system uses the same distribution as the image that’s being built.

- By default, mkosi will now change the owner of newly created directories to SUDO_UID or PKEXEC_UID if defined, unless --no-chown is used.

- If systemd-nspawn v252 or newer is used, bind-mounted directories with systemd-nspawn will use the new rootidmap option so files and directories created from within the container will be owned by the actual directory owner on the host.

### v13

- The --network-veth option has been renamed to --netdev. The old name made sense with virtual ethernet devices, but when booting images with qemu a TUN/TAP device is used instead.

- The network config file installed by mkosi when the --netdev (previously --network-veth) option is used (formerly /etc/systemd/network/80-mkosi-network-veth.network in the image) now only matches network interfaces using the virtio_net driver. Please make sure you weren’t relying on this file to configure any network interfaces other than the tun/tap virtio-net interface created by mkosi when booting the image in QEMU with the --netdev option. If you were relying on this config file when the host system uses the same distribution as the image that’s being built. Instead, when no release is specified, mkosi will now always default to the default version embedded in mkosi itself.

- mkosi will now use the pacman keyring from the host when building Arch images. This means that users will, on top of installing archlinux-keyring, also have to run pacman-key --init and pacman-key --populate archlinux on the host system to be able to build Arch images. Also, unless the package manager is configured to do it automatically, the host keyring will have to be updated after archlinux-keyring updates by running pacman-key --populate archlinux and pacman-key --updatedb.

- Direct qemu linux boot is now supported with BootProtocols=linux. When enabled, the kernel image, initrd, and cmdline will be extracted from the image and passed to qemu by mkosi qemu to directly boot into the kernel image without a bootloader. This can be used to boot for example s390x images in qemu.

- The initrd will now always be rebuilt after the extra trees and build artifacts have been installed into the image.

- The github action has been migrated to Ubuntu Jammy. To migrate any jobs using the action, add runs-on: ubuntu-22.04 to the job config.

- All images are now configured by default with the C.UTF-8 locale.

- New --repository-directory option can be used to configure a directory with extra repository files to be used by the package manager when building an image. Note that this option is currently only supported for pacman and dnf-based distros.

- Option --skeleton-tree is now supported on Debian-based distros.

- Removed --hostname as its trivial to configure using systemd-firstboot.

- Removed default locale configuration as its trivial to configure using systemd-firstboot and systemd writes a default locale well.

### v12
•

Fix handling of baselayout in Gentoo installations.

### v11

- Support for Rocky Linux, Alma Linux, and Gentoo has been added!

- A new ManifestFormat= option can be used to generate “manifest” files that describe what packages were installed. With json, a JSON file that shows the names and versions of all installed packages will be created. With changelog, a longer human-readable file that shows package descriptions and changelogs will be generated. This latter format should be considered experimental and likely to change in later versions.

- A new RemovePackages= option can be used to uninstall packages after the build and finalize scripts have been done. This is useful for the case where packages are required by the build scripts, or pulled in as dependencies for scriptlets of other packages, but are not necessary in the final image.

- A new BaseImage= option can be used to build “system extensions” a.k.a. “sysexts” — partial images which are mounted on top of an existing system to provide additional files under /usr/. See the systemd-sysext man page for more information.

- A new CleanPackageMetadata= option can be used to force or disable the removal of package manager files. When this option is not used, they are removed when the package manager is not installed in the final image.

- A new UseHostRepositories= option instructs mkosi to use repository configuration from the host system, instead of the internal list.

- A new SshAgent= option configures the path to the ssh agent.

- A new SshPort= option overrides the port used for ssh.

- The Verity= setting supports a new value signed. When set, verity data will be signed and the result inserted as an additional partition in the image. See https://systemd.io/DISCOVERABLE_PARTITIONS for details about signed disk images. This information is used by systemd-nspawn, systemd-dissect, systemd-sysext, systemd-portabled and systemd’s RootImage= setting (among others) to cryptographically validate the image file systems before use.

- The --build-environment= option was renamed to --environment= and extended to cover all invoked scripts, not just the mkosi.build. The old name is still understood.

- With --with-network=never, dnf is called with --cacheonly, so that the package lists are not refreshed. This gives a degree of reproducibility when doing repeated installs with the same package set (and also makes installs significantly faster).

- The --debug= option gained a new value disk to show information about disk sized and partition allocations.

- Some sections and settings have been renamed for clarity: [Packages] is now [Content], Password=, PasswordIsHashed=, and Autologin= are now in [Content]. The old names are still supported, but not documented.

- When --prepare-script=/--build-script=/--finalize-script= is used with an empty argument, the corresponding script will not be called.

- Python 3.7 is the minimal supported version.

- Note to packagers: the Python cryptography module is needed for signing of verity data.

### v10

- Minimum supported Python version is now 3.7.

- Automatic configuration of the network for Arch Linux was removed to bring different distros more in line with each other. To add it back, add a postinstall script to configure your network manager of choice.

- The --default option was changed to not affect the search location of mkosi.default.d/. mkosi now always searches for mkosi.default.d/ in the working directory.

- quiet was dropped from the default kernel command line.

- --source-file-transfer and --source-file-transfer-final now accept an empty value as the argument which can be used to override a previous setting.

- A new command mkosi serve can be used to serve build artifacts using a small embedded HTTP server. This is useful for machinectl pull-raw ... and machinectl pull-tar ....

- A new command mkosi genkey can be used to generate secure boot keys for use with mkosi’s --secure-boot options. The number of days the keys should remain valid can be specified via --secure-boot-valid-days= and their CN via --secure-boot-common-name=.

- When booting images with qemu, firmware that supports Secure Boot will be used if available.

- --source-resolve-symlinks and --source-resolve-symlinks-final options are added to control how symlinks in the build sources are handled when --source-file-transfer[-final]=copy-all is used.

- --build-environment= option was added to set variables for the build script.

- --usr-only option was added to build images that comprise only the /usr/ directory, instead of the whole root file system. This is useful for stateless systems where /etc/ and /var/ are populated by systemd-tmpfiles/systemd-sysusers and related calls at boot, or systems that are originally shipped without a root file system, but where systemd-repart adds one on the first boot.

- Support for “image versions” has been added. The version number can be set with --version-number=. It is included in the default output filename and passed as $IMAGE_VERSION to the build script. In addition, mkosi bump can be used to increase the version number by one, and --auto-bump can be used to increase it automatically after successful builds.

- Support for “image identifiers” has been added. The id can be set with --image=id and is passed to the build script as $IMAGE_ID.

- The list of packages to install can be configured with --base-packages=. With --base-packages=no, only packages specified with --packages= will be installed. With --base-packages=conditional, various packages will be installed “conditionally”, i.e. only if some other package is otherwise pulled in. For example, systemd-udev may be installed only if systemd is listed in --packages=.

- CPIO output format has been added. This is useful for kernel initramfs images.

- Output compression can be configured with --compress-fs= and --compress-output=, and support for zstd has been added.

- --ssh-key= option was added to control the ssh key used to connect to the image.

- --remove-files= option was added to remove file from the generated images.

- Inline comments are now allowed in config files (anything from # until the end of the line will be ignored).

- The development branch was renamed from master to main.

### Highlighted Changes

- The mkosi Github action now defaults to the current release of mkosi instead of the tip of the master branch.

- Add a ssh verb and accompanying --ssh option. The latter sets up SSH keys for direct SSH access into a booted image, whereas the former can be used to start an SSH connection to the image.

- Allow for distribution specific mkosi.* files in subdirectories of mkosi.default.d/. These files are only processed if a subdirectory named after the target distribution of the image is found in mkosi.default.d/.

- The summary of used options for the image is now only printed when building the image for the first time or when the summary verb is used.

- All of mkosi’s output, except for the build script, will now go to stderr. There was no clear policy on this before and this choice makes it easier to use images generated and booted via mkosi with language servers using stdin and stdout for communication.

- --source-file-transfer now defaults to copy-git-others to also include untracked files.

- black is now used as a code style and conformance with it is checked in CI.

- Add a new --ephemeral option to boot into a temporary snapshot of the image that will be thrown away on shutdown.

- Add a new option --network-veth to set up a virtual Ethernet link between the host and the image for usage with nspawn or QEMU

- Add a new --autologin option to automatically log into the root account upon boot of the image. This is useful when using mkosi for boot tests.

- Add a new --hostonly option to generate host specific initrds. This is useful when using mkosi for boot tests.

- Add a new --install-directory option and special directory mkosi.installdir/ that will be used as $DESTDIR for the build script, so that the contents of this directory can be shared between builds.

- Add a new --include-directory option and special directory mkosi.includedir/ that will be mounted at /usr/include during the build. This way headers files installed during the build can be made available to the host system, which is useful for usage with language servers.

- Add a new --source-file-transfer-final option to complement --source-file-transfer. It does the same --source-file-transfer does for the build image, but for the final one.

- Add a new --tar-strip-selinux-context option to remove SELinux xattrs. This is useful when an image with a target distribution not using SELinux is generated on a host that is using it.

- Document the --no-chown option. Using this option, artifacts generated by mkosi are not chowned to the user invoking mkosi when it is invoked via sudo. It has been with as for a while, but hasn’t been documented until now.

### Fixed Issues

- #506

- #559

- #561

- #562

- #575

- #580

- #593

### Authors

- Daan De Meyer

- Joerg Behrmann

- Luca Boccassi

- Peter Hutterer

- ValdikSS


moosefs

package: moosefs-master

title: moosefs(7)

text:
# moosefs(7)

## NAME
MooseFS - fault tolerant, highly reliable, near indefinitely scalable, fast distributed file system in User Space

## DESCRIPTION
MooseFS is a fault tolerant, distributed file system. It spreads data over several physical locations (servers), which are visible to user as one resource. For standard file operations MooseFS acts as any other Unix-like filesystem:

-

hierarchical structure (directory tree)

-

stores POSIX file attributes (permissions, last access and modification times)

-

supports special files (block and character devices, pipes and sockets)

-

supports symbolic links (file names pointing to target files, not necessarily on MooseFS) and hard links (different names of files that refer to the same data on MooseFS)

-

supports ACLs

-

supports file locks across all connected client processes

-

access to the file system can be limited based on IP address and/or password

Distinctive features of MooseFS are:

-

high reliability (several copies of the data can be stored on separate physical machines)

-

capacity is dynamically expandable by adding new computers/disks

-

deleted files are retained for a configurable period of time (a file system level ”trash bin”)

-

coherent snapshots of files, even while the file is being written/accessed

MooseFS consists of 4 key components:

Master Servers

in MooseFS CE one machine, in MooseFS Pro any number of machines running the mfsmaster binary, which is managing the whole filesystem, storing metadata for every file (information on size, attributes and file location(s), including all information about non-regular files, i.e. directories, sockets, pipes and devices)

Chunk Servers

any number of commodity servers running the mfschunkserver binary, which is storing files’ data and synchronizing it among themselves (if a certain file is supposed to exist in more than one copy).

Metalogger Servers

any number of servers running the mfsmetalogger binary, all of which store metadata changelogs and periodically download main metadata file

Client Processes

machines running the mfsmount processes, that access the files stored on MooseFS file system and expose them via a regular mount point inside a client's machine local directory tree

Additionally, a number of tools can be installed to aid in using the system:

GUI

a web based statistic and diagnostic tool (mfsgui, acts as a simple HTTP server)

CLI

command line statistic and diagnostic tool mfscli

Block device

Linux only special client process mfsbdev that maps single MooseFS files into block devices

TOOLS

various command line administrative tools

### ARCHITECTURE
From the user’s point of view, MooseFS behaves like a regular, POSIX compliant file system with almost indefinitely expandable capacity. To achieve this, the system was designed as a distributed network file system, where different processes run on different machines, perform specific tasks to assure proper performance of the whole file system. Master Sever stores metadata information about files and manages the whole file system. In case of MooseFS Pro installation, with several Master Servers, only one of them (in the role of Leader) manages the system at any given time, the others (Followers) just keep up, ready to pick up the Leader role at any time. The managing Master Server has following tasks: it stores all the metadata of the file system (information about files and directories), it answers the requests of client (mount) processes when they want to perform any operation on the file system, it monitors the state of Chunk Servers and stored data, sending replication or deletion requests to Chunk Servers when needed.

Metadata is stored in the memory of the Master Server and simultaneously saved on a local disk (as a periodically updated binary file and immediately updated incremental logs). The main binary file as well as the logs are synchronized to the Metaloggers (if present) and to spare Master Servers in MooseFS Pro version. Chunk Servers store actual file data. All data on the filesystem is divided into chunks (hence the name of the servers that keep them) of maximum size of 64 MiB. The chunks are kept in several copies on different servers according to appropriate policies to ensure safety of the data. Chunk Servers communicate with client processes (on client’s request, as directed by the master) to write or read file data. The chunks themselves are stored as regular files on local hard drive or drives.

All file operations on a client computer that has mounted a MooseFS instance are exactly the same as they would be with any other file system. The operating system’s kernel transfers all file operations to the FUSE module, which communicates with the mfsmount process. The mfsmount process communicates through the network subsequently with the managing server and data servers. This entire process is fully transparent to the user.

At any point in time new Chunk Servers can be added to the system to expand the total available space. Also, new hard drives can be added to existing Chunk Servers. The Master Server will add the ”new” space to the filesystem automatically. Thus, the system’s data capacity can be expanded almost indefinitely, as long as the Master Server is able to store all the relevant metadata information. The Master Server will ensure that all the available physical disk space is used in as balanced manner as possible.

In such a big system hardware failures will occur. MooseFS will automatically react in case of hard drive failure or whole Chunk Server failure. The safety of the data is ensured by storing it in several copies, according to defined storage policies. After a failure the Master Server will start replication of the still existing copies in accordance with endangered file’s storage policy, to restore its required safety redundancy level as soon as possible.

Failures of a client machine (that runs the mfsmount process) will have no influence on the coherence of the file system or on the other clients’ operations. In the worst case scenario the data that has not yet been sent from the failed client computer to the Master Server and/or Chunk Servers may be lost.

### SUPPORTED PLATFORMS
mfsmount is based on the FUSE mechanism (Filesystem in USErspace), so MooseFS client is available on every Operating System with a working FUSE implementation.

The Master Server, Metalogger and Chunk Servers can be run on any POSIX compliant OS on most major processor types and architectures. 32-bit processors will work too, but beware of RAM handicap and the consequences of it. Use of 64-bit versions of operating systems is highly recommended.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfschunkserver(8), mfsmetalogger(8), mfsmount(8), mfsbdev(8)

branch: sisyphus


mosquitto-tls

package: mosquitto

title: mosquitto-tls(7)

summary: Configure SSL/TLS support for Mosquitto

text:
# mosquitto-tls(7)

## NAME
mosquitto-tls - Configure SSL/TLS support for Mosquitto

## DESCRIPTION
mosquitto provides SSL support for encrypted network connections and authentication. This manual describes how to create the files needed.

Note

It is important to use different certificate subject parameters for your CA, server and clients. If the certificates appear identical, even though generated separately, the broker/client will not be able to distinguish between them and you will experience difficult to diagnose errors.

## GENERATING CERTIFICATES
The sections below give the openssl commands that can be used to generate certificates, but without any context. The asciicast at https://asciinema.org/a/201826 gives a full run through of how to use those commands.

## CERTIFICATE AUTHORITY
Generate a certificate authority certificate and key.

•openssl req -new -x509 -days <duration> -extensions v3_ca -keyout ca.key -out ca.crt

## SERVER
Generate a server key.

•openssl genrsa -aes256 -out server.key 2048

Generate a server key without encryption.

•openssl genrsa -out server.key 2048

Generate a certificate signing request to send to the CA.

•openssl req -out server.csr -key server.key -new

Note

When prompted for the CN (Common Name), please enter either your server (or broker) hostname or domain name.

Send the CSR to the CA, or sign it with your CA key:

•openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days <duration>

## CLIENT
Generate a client key.

•openssl genrsa -aes256 -out client.key 2048

Generate a certificate signing request to send to the CA.

•openssl req -out client.csr -key client.key -new

Send the CSR to the CA, or sign it with your CA key:

•openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days <duration>

## SEE ALSO
mosquitto(8), mosquitto.conf(5)

## AUTHOR
Roger Light <roger@atchoo.org>


mqtt

title: mqtt(7)

summary: MQ Telemetry Transport

text:
# mqtt(7)

## NAME
mqtt - MQ Telemetry Transport

## SYNOPSIS
MQTT

## DESCRIPTION
MQTT is a lightweight publish/subscribe messaging protocol. It is useful for use with low power sensors, but is applicable to many scenarios.

This manual describes some of the features of MQTT version 3.1.1/3.1, to assist end users in getting the most out of the protocol. For more complete information on MQTT, see http://mqtt.org/.

## PUBLISH/SUBSCRIBE
The MQTT protocol is based on the principle of publishing messages and subscribing to topics, or "pub/sub". Multiple clients connect to a broker and subscribe to topics that they are interested in. Clients also connect to the broker and publish messages to topics. Many clients may subscribe to the same topics and do with the information as they please. The broker and MQTT act as a simple, common interface for everything to connect to. This means that you if you have clients that dump subscribed messages to a database, to Twitter, Cosm or even a simple text file, then it becomes very simple to add new sensors or other data input to a database, Twitter or so on.

## TOPICS/SUBSCRIPTIONS
Messages in MQTT are published on topics. There is no need to configure a topic, publishing on it is enough. Topics are treated as a hierarchy, using a slash (/) as a separator. This allows sensible arrangement of common themes to be created, much in the same way as a filesystem. For example, multiple computers may all publish their hard drive temperature information on the following topic, with their own computer and hard drive name being replaced as appropriate:

•sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME

Clients can receive messages by creating subscriptions. A subscription may be to an explicit topic, in which case only messages to that topic will be received, or it may include wildcards. Two wildcards are available, + or #.

+ can be used as a wildcard for a single level of hierarchy. It could be used with the topic above to get information on all computers and hard drives as follows:

•sensors/+/temperature/+

As another example, for a topic of "a/b/c/d", the following example subscriptions will match:

•a/b/c/d

•+/b/c/d

•a/+/c/d

•a/+/+/d

•+/+/+/+

The following subscriptions will not match:

•a/b/c

•b/+/c/d

•+/+/+

\# can be used as a wildcard for all remaining levels of hierarchy. This means that it must be the final character in a subscription. With a topic of "a/b/c/d", the following example subscriptions will match:

•a/b/c/d

•#

•a/#

•a/b/#

•a/b/c/#

•+/b/c/#

Zero length topic levels are valid, which can lead to some slightly non-obvious behaviour. For example, a topic of "a//topic" would correctly match against a subscription of "a/+/topic". Likewise, zero length topic levels can exist at both the beginning and the end of a topic string, so "/a/topic" would match against a subscription of "+/a/topic", "#" or "/#", and a topic "a/topic/" would match against a subscription of "a/topic/+" or "a/topic/#".

## QUALITY OF SERVICE
MQTT defines three levels of Quality of Service (QoS). The QoS defines how hard the broker/client will try to ensure that a message is received. Messages may be sent at any QoS level, and clients may attempt to subscribe to topics at any QoS level. This means that the client chooses the maximum QoS it will receive. For example, if a message is published at QoS 2 and a client is subscribed with QoS 0, the message will be delivered to that client with QoS 0. If a second client is also subscribed to the same topic, but with QoS 2, then it will receive the same message but with QoS 2. For a second example, if a client is subscribed with QoS 2 and a message is published on QoS 0, the client will receive it on QoS 0.

Higher levels of QoS are more reliable, but involve higher latency and have higher bandwidth requirements.

•0: The broker/client will deliver the message once, with no confirmation.

•1: The broker/client will deliver the message at least once, with confirmation required.

•2: The broker/client will deliver the message exactly once by using a four step handshake.

## RETAINED MESSAGES
All messages may be set to be retained. This means that the broker will keep the message even after sending it to all current subscribers. If a new subscription is made that matches the topic of the retained message, then the message will be sent to the client. This is useful as a "last known good" mechanism. If a topic is only updated infrequently, then without a retained message, a newly subscribed client may have to wait a long time to receive an update. With a retained message, the client will receive an instant update.

## CLEAN SESSION / DURABLE CONNECTIONS
On connection, a client sets the "clean session" flag, which is sometimes also known as the "clean start" flag. If clean session is set to false, then the connection is treated as durable. This means that when the client disconnects, any subscriptions it has will remain and any subsequent QoS 1 or 2 messages will be stored until it connects again in the future. If clean session is true, then all subscriptions will be removed for the client when it disconnects.

## WILLS
When a client connects to a broker, it may inform the broker that it has a will. This is a message that it wishes the broker to send when the client disconnects unexpectedly. The will message has a topic, QoS and retain status just the same as any other message.

## SEE ALSO
mosquitto(8), mosquitto_pub(1), mosquitto_sub(1)

## AUTHOR
Roger Light <roger@atchoo.org>


mozplugger

package: mozilla-plugin-mozplugger

title: mozplugger(7)

text:
# mozplugger(7)

## NAME
mozplugger - a multimedia plugin for UNIX Web browsers that supports the mozilla npapi

## DESCRIPTION
MozPlugger is a browser plugin which can show many types of multimedia inside your Browser. To accomplish this, MozPlugger uses external programs such as mplayer, xanim, mtv, timidity and tracker.

## CONFIGURE FILE
You can configure mozplugger by changing the mozpluggerrc file(s). These can be located in any of the following directories depending on the browser:

For mozilla (and chromium) browsers

$MOZPLUGGER_HOME/

$XDG_CONFIG_HOME/mozplugger/

$HOME/.config/mozplugger/

$HOME/.mozplugger/

$HOME/.mozilla/

$MOZILLA_HOME/

/etc/

/usr/etc/

/usr/local/mozilla/

For netscape browsers

$MOZPLUGGER_HOME/

$XDG_CONFIG_HOME/mozplugger/

$HOME/.config/mozplugger/

$HOME/.mozplugger/

$HOME/.netscape/

/etc/

/usr/etc/

/usr/local/netscape/

For opera browsers

$MOZPLUGGER_HOME/

$XDG_CONFIG_HOME/mozplugger/

$HOME/.config/mozplugger/

$HOME/.mozplugger/

$HOME/.opera/

$OPERA_HOME/

/etc/

/usr/etc/

The command mozplugger-update must be run after installation and each time the configuration file changes or new helper applications are added to the system or old helper applications removed.

mozplugger-update will use the first mozpluggerrc it finds and ignore any others for each different browser installed on the system. The search order is from top of the list above, but skipping places not applicable to the particular browser that the config is being parsed for. mozplugger-update then caches processed results in files located at $XDG_CACHE_HOME/mozplugger/

The format of mozpluggerrc is very simple. The file is subdivided into sections. Each section starts with a plugin name and version in square brackets. This represents a class of mozplugger plugin. The name and version will be displayed as a separate plugin when viewing installed plugins in your browser. Some java script relies on the name and version of a plugin matching some value, hence the reason for seperate sections in mozpluggerrc. Two brackets are required because m4 processing needs to escape the brackets. e.g.

[[multimedia player @ 10.1]]

Within each section, the general layout is to have one or more lines describing mime types followed by one or more lines describing commands used to handle those mime types. Lines beginning with # are considered comments and are ignored. Here is a simple example:

video/mpeg: mpeg: Mpeg video

video/quicktime: qt,mov: Mpeg video

: xanim +W$window -Zr +q +Ze +f $file

Each line describing a mime type has three fields:

mime type : extensions : description

mime type

The mime type is the standardized name for the content type you want MozPlugger to handle. This must be the same type as the web server claims the file to be, or MozPlugger will not be used for that file, regardless of the extension. Note: Some web servers incorrectly report the wrong mime type, blame the web server adminstrator not mozplugger.

extensions

This is a comma separated list of extensions that should be associated with this particular mime type. The extensions are only used when a web server does not report what type of file it is, or when loading files directly from disk.

description

This is the description that shows up in about:plugins and in the application preferences section in Mozilla.

Lines that describe what command to use for a mime type must begin

with a whitespace and have two fields:

flags : command

flags

This is a space separated list of flags associated with the command and tells mozplugger how to handle this command. See below for further details.

command

This is a command which is sent to /bin/sh when handling this mime type. Mozplugger assumes the command line starts with the name of an application followed by various arguments passed to that application.

## USING M4
When running, mozplugger-update it will pass the mozpluggerrc file through m4, a general purpose macro processor (assuming m4 is installed). This provides the ablity to use macros within mozpluggerrc especially for those commonly used command lines. m4 brings text replacement, parameter substitution, file inclusion, string manipulation, conditional evaluation, arthemtic expressions, etc to mozpluggerrc. Please see m4 documentation for more details.

## FINDING THE RIGHT COMMAND
When MozPlugger is called from your browser, it looks through the cached processed configuration files and finds a matching mime type.

When a matching mimetype is found, it tries to figure out which command to use. Commands that have the flags loop, embed, noembed, link and fmatch will be rejected if they do not match what is expected from the associated HTML code (see later for details).

In addition for a command to be chosen the application has to be available. This will have been checked by mozplugger-update which will have assumed the first word of the command is the name of an application and search $PATH for that application. If that application is not found mozplugger-update will not have cached that in the processed config files. The output from mozplugger-update will indicate when applications have not been found.

Of the commands that remain, Mozplugger looks for the first command that has the stream flag set. If there is not such a command line, Mozplugger then downloads the file and picks the first (of the remaining) commands.

## WORKING WITH JAVA SCRIPT
Mozplugger supports a JavaScript interface that allows the state of the embedded object (i.e. mozplugger) to be queried from JavaScript. Currently mozplugger supports the following properties.

isPlaying

This property has the value true if the application that mozplugger launched to handle the embedded object is running and false if either no application was launched or that application has now terminated.

## WHEN IT DOESNT WORK
If for some reason the embedded object fails to be rendered in the browser, this could be a fault with the application as opposed to MozPlugger. To diagnosis the fault it is suggested that first you make sure that any output from the application will be visible to you by removing the noisy flag (if set in mozpluggerrc).

Next run the browser from the shell (xterm or equivalent) passing the appropriate browser command line flag to enable output from stdout and stderr to be displayed.

For example, for firefox the command line string is:

firefox -debug

This should allow any output from the application to be visible at the shell and hopefully lead to a diagnosis of the fault.

## FLAGS
autostart

This flag indicates that the command uses the $autostart environment variable. That is mozplugger will run the command on the assumption that the command/application will check the value of the $autostart environment variable. If this flag is not present and the HTML code for the embedded object indicates autostart is false, mozplugger will not run the command but instead draw a single start button.

repeat

This flag indicates that the command uses the $repeats environment variable. That is mozplugger will run the command on the assumption that the command/application will check the value of the $repeats environment variable and perform the repeats. If this flag is not set, mozplugger will perform the required number of repeats as indicated in the HTML code by calling the command $repeats times.

loop

This indicates that the command loops forever. If the HTML code for the embedded object indicates don't loop/repeat forever (e.g. the loop attribute is not present or not set to true), the command on this line will not be used.

stream

This indicates that this command can take an url. In this case, the environment variable $file contains the URL of the file to play and the browser does not download it. It is assumed that the command can handle the URL. Note: if a username and password is required for this URL, the command/application will have to obtain this as it is not passed to it from the browser.

ignore_errors

This flag tells MozPlugger to ignore the exit status of the command. For example is mozplugger is repeating the command 'n' times and the command exits with an error, normally mozplugger would terminate at this time. With this flag set, mozplugger continues the repeats.

noisy

This flag tells MozPlugger to redirect the stdout and stderr of the command to /dev/null.

swallow (name)

This flag tells mozplugger that the command will open a window with the specified name and that Mozplugger will then move this window inside your browser. If name is prefixed with '=' then mozplugger looks for an exact match with the window name, if the prefix is '~' then mozplugger looks for a case insensitive match, if prefixed with '*' then mozplugger looks for a window name that starts with 'name' and is case insensitive. If none of these prefixes then, mozplugger checks if name occurs anywhere in the window name, but is case sensitive. Note any spaces between the brackets are counted as part of the window name. The window name to use in mozpluggerrc can be obtained by using the utility xprop(). Run the command in question, type "xprop WM_CLASS" at a shell prompt and then click on the application window. In addition any occurance of %f in the name is replaced with the filename being loaded (without path), %p is replaced with the full filename including path. Some applications do not like to be swallowed and some window managers do not like windows being managed by mozplugger, so avoid using this option where possible.

fmatch (string)

This flag defines a command that will be used only if the filename or url (i.e. $file) contains 'string'. If 'string' is prefixed with '*' then mozplugger defines a match when the file starts with 'string' (the check is case insensitive). If 'string' is prefixed with '%' then mozplugger defines a match when the file ends with 'string' (the check is case insenstive and ignores any parameters at the end of a url {i.e. '?xxx=yyy'}). If none of these prefixes then mozplugger defines a match when the 'string' is found somewhere in the file (but this time match is case sensitive). Note any spaces between the brackets are counted as part of the 'string'.

nokill

This flag tells MozPlugger to not try to kill the command when leaving the page, and to not start the command in a loop. This is normally used for applications that are not swallowed and can play multiple files, such as xmms.

exits

This flag tells MozPlugger that the command will exits straight away and hence does not need to be killed when leaving the page, and to not start the command in a loop. This is normally used for applications that just display an image in the $window and then exit.

fill

This flag tells MozPlugger to maximize a swallowed window.

maxaspect

This flag tells Mozplugger to maximize a swallowed window while keeping the width/height ratio constant.

controls

This flag tells MozPlugger to draw controls and is typically used with audio files to display a controller with the buttons play, pause and stop. Be aware if the embedded object has no sub-window defined within the browser's window (e.g. if the HTML uses the tag hidden = true) then the controls will not appear.

embed

This flags tells Mozplugger to only use this command if the associated HTML refers to an embedded object that is a small part of a HTML page.

noembed

This flags tells Mozplugger to only use this command if the associated HTML refers to a separate window that only contains the object.

links

This flag tells Mozplugger to display as a button within the browser and when pressed to run the command without embedding in the browser. This can be used when swallow does not work.

needs_xembed

Some applications when embedded requires the Xembed protocol, other applications don't want the Xembed protocol. Add or remove this flag if you find that you cannot move keyboard focus to the embedded window. Currently it appears QT4 based applications require this flag.

## ENVIRONMENT VARIABLES
There are some envirnoment variables that control the behaviour of Mozplugger.

MOZPLUGGER_HOME

If MOZPLUGGER_HOME is defined, the folder $MOZPLUGGER_HOME is checked for the configuration file mozpluggerrc and is also used for the base of storing the results of processing mozpluggerrc

MOZPLUGGER_TMP

If MOZPLUGGER_TMP is defined, then any temporary files are placed in $MOZPLUGGER_TMP.

TMPDIR

If MOZPLUGGER_TMP is not defined, but TMPDIR is defined, then any temporary files are placed in $TMPDIR/mozplugger-xxx/ where xxx = PID.

PATH

mozplugger-update uses PATH to look for executables

MozPlugger gives some variables to /bin/sh when running the command,

these variables are:

$autostart

This variable contains 1 or 0. When set to 1 it indicates that the command should start playing/showing the associated media. By default it is 0 if controls flag is present and 1 otherwise, but it is overridden if the associated HTML contains the attribute autostart or autoplay. Command/applications that use this environment variable should also have the autostart flag set.

$repeats

This variable contains how many times the file should be played. By default it is once, but it is overridden if the associated HTML contains the attribute loop, numloop or playcount. Command/applications which use this environment variable should also have the repeat flag set.

$window

This is the X window Mozilla has given the plugin. This can be used with applications such as MPlayer to display graphics inside the mozilla window. Be aware if the embedded object has no sub-window defined within the browser's window (e.g. if the HTML uses the tag hidden = true) then the variable will have the value zero (null).

$hexwindow

Same as $window except the value is expressed as an hexidecimal string in the form 0xNNNNNN where NNNNNN is the hexadecimal digits.

$width

This is the horizontal resolution in pixels and is taken from the width attribute in the HTML code.

$height

This is the vertical resolution in pixels and is taken from the height attribute in the HTML code.

$file

This is the file to play. If the command has the stream flag set, this variable contains the URL of the file to play. This is taken from the associated HTML code. The value is that of the attribute src, data, href, qtsrc, filename, url or location depending on which is present and whether the <EMBED> or <OBJECT> tag is used. If the stream is not set, this variable contains a local temporary file that the browser has created.

$fragment

This is the part of the original URL that appears after the # if it exists. Sometimes this contains additional information that could be useful for the application e.g. starting page number in a pdf document

$mimetype

This variable contains the mime type of $file.

$VAR_<parameter_name>

All the parameters of the <EMBED> or <OBJECT> tags are made available in mozpluggerrc through environment variables. For example the parameter loop="1" in an <EMBED> tag defines the variable VAR_loop=1.

## BUGS
You have to run mozplugger-update after changing the configuration, or nothing will happen.

Netscape 3.x will not play anything for <EMBED> tags for which height or width are zero. This too is a Netscape bug.

Occassionally you may notice some zombie mozplugger-helper processes (defunct), this is not a bug, this is by design. The zombie processes occur when either the application exits or when using nokill flag (without exiting the page with the embedded object). The zombie(s) are reaped when closing the web page containing the associated embedded objects.

If using behind a non-transparent HTTP proxy, it may be found that the commands using the stream flag do not work. This is because the proxy settings are not passed to the application in the command line. To work around this situation, don't use the stream flag OR edit the mozpluggerrc file and passed in necessary proxy setiings via the command line.

It has been found that certain combinations of browser, embedded applications and window managers do not play nicely with the swallow flag. If this happens to you first try adding or removing the "needs_xembed" flag from the associated command in mozpluggerrc, if this fails remove the swallow flag and perhaps use the links flag instead.

## AUTHORS
Fredrik Hubinette, author of plugger which mozplugger is a fork of.

Louis Bavoil

Peter Leese