MKMEDIA(1)

📦 version 6.0, in opensuse-leap 16.0

💿 MKMEDIA(1) — mkmedia / mksusecd, bestie edition 💿

okay so this is the mkmedia(1) page, manual name folded in right here at the top because we’re not doing boring headers today. It’s literally the group-chat explainer for mkmedia and mksusecd, and every flag is staying. No cap.

🌸 NAME 🌸

mkmedia, mksusecd — create and modify bootable media. That’s the whole NAME section, periodt.

✨ SYNOPSIS ✨

mkmedia [OPTIONS]... SOURCES...

💖 DESCRIPTION 💖

mkmedia (formerly named mksusecd) can modify or create bootable installation or Live media. They can be either ISO images or disk images (to be used on USB sticks, for example). iconic behavior, honestly.

mkmedia supports media in both openSUSE/SLES and Fedora/RHEL layout. See Fedora/RHEL notes for details.

The main purpose is to adjust existing media. For example:

  • change boot options
  • add boot menu entries
  • update the installer
  • update software used by the installer (including kernel and modules)
  • integrate driver updates
  • integrate add-on repositories
  • create small network / online boot media

SOURCES can be directories, existing ISO image files, or RPMs. They are all combined to produce a single ISO. See Sources below for more details.

🛠️ General Options 🛠️

  • --verbose — show more detailed messages. Can be repeated to log even more. yapping levels: adjustable.
  • --version — show mkmedia version.
  • --mkisofs — use mkiosfs to build ISO images (default if available). yes, that spelling is literally in the page — keeping it exact, bestie.
  • --xorriso — use xorriso to build ISO images.
  • --dry-run — do everything except writing the final image. rehearsal girlie behavior.
  • --tmp-dir=TMPDIR — use TMPDIR as temporary directory (default: /tmp).
Some operations can require a substantial amount of temporary disk space. For example, modifying the installation system involves unpacking the Live root file system of the installer — which is typically around 6GB. Use this option if you would otherwise run out of disk space. this is your “my disk is crying” warning, fr fr.
  • --save-tmp — keep temporary files.
  • --help — show this help text.

🔍 Show available repositories 🔍

  • --list-repos — list all available repositories in SOURCES.

🎀 Create new image 🎀

  • -c, --create=FILE — create ISO or disk image FILE from SOURCES.
  • --micro — create image with just enough files to run the installer. Note: this gives a network installation image which uses the installer from the medium (the typical online media). For this to work, either the installation is registration-based or the location of the installation repository must be explicitly set using the --defaultrepo option.
  • --nano — create image with just enough files for a network based installation. Note: this gives a small network installation image which has to load even the installer via network. For this to work, the location of the installation repository must be explicitly set using the --defaultrepo option.. (yes, two dots — the page said it, not me 😭)
  • --pico — even less than --nano, keep just the boot loader (for testing).
  • --check — tag ISO to be verified before starting the installation.
  • --no-check — don’t tag ISO (default).
  • --digest=DIGEST — embed DIGEST to verify ISO integrity, available digests: md5, sha1, sha224, sha256, sha384, sha512 (default: sha256).
  • --no-digest — don’t embed any digest to verify ISO integrity.
  • --sign-image — embed signature for entire image. See Image signing notes below.
  • --no-sign-image — don’t embed signature for entire image. (default) See Image signing notes below.
  • --signature-file=FILE — store embedded signature in FILE (default: /.signature for SUSE-style media, no signature file for RH-style media). See Image signing notes below.
  • --sign — re-sign /CHECKSUMS if it has changed. The public part of the sign key is added to the initrd. (default) See Signing notes below.
  • --no-sign — don’t re-sign /CHECKSUMS.
  • --sign-key=KEY_FILE — use this key file instead of generating a transient key. See Signing notes below.
  • --sign-key-id=KEY_ID — use this key id instead of generating a transient key. Note: gpg might show an interactive dialog asking for a password to unlock the key unless you use the --sign-pass-file option. See Signing notes below.
  • --sign-pass-file — use the password stored in this file to open the key. See Signing notes below.
  • --apply-dud=DUD — apply driver update DUD (can be repeated). See Driver update notes below.
  • --initrd=DIR|RPM|DUD — add content of DIR, RPM, or DUD to initrd (can be repeated). See Driver update notes below.
  • --rebuild-initrd — rebuild the entire initrd instead of appending changes. This makes the initrd smaller but requires to run mkmedia with root permissions. See Kernel update notes below.
  • --no-rebuild-initrd — append changes to the initrd instead of rebuilding. This makes the initrd larger but does not require to run mkmedia with root permissions. See Kernel update notes below.
  • --initrd-config=KEY=VALUE — add config option to initrd intended for linuxrc, YaST, dracut, Agama, or Anaconda (option can be repeated). The config option is stored in /etc/linuxrc.d/61_mkmedia (for linuxrc-based media) or /etc/cmdline.d/61-mkmedia.conf (dracut-based media). See Boot option and initrd config option notes below.
  • --instsys=DIR|RPM — add content of DIR or RPM to installation system or root file system for Live media (can be repeated).
  • --live-root=DIR|RPM — alias for --instsys.
  • --rescue=DIR|RPM — add content of DIR or RPM to rescue system (can be repeated).
  • --instsys-size=SIZE_SPEC — resize Live root file system. SIZE_SPEC can be a number, optionally followed by a unit ('k', 'm', 'g', 't') indicating kiB, MiB, GiB, or TiB, respectively. If SIZE_SPEC starts with a '+' or '-', the size is increased or decreased, respectively.
  • --live-root-size=SIZE_SPEC — alias for --instsys-size.
  • --dud-dist=DIST — apply DUDs intended for DIST. Usually --apply-dud applies only DUDs that match the product of the installation medium. If you want to apply a DUD even if the product does not match, set DIST to the dist tag used in the DUD. Examples are 'leap16.1' (Leap 16.1), 'tw' (Tumbleweed), 'sles16.1' (SLES 16.1). The option value is actually a shell glob — so, to catch all, you can set DIST to '*'.
  • --no-docs — don’t include package documentation files (default).
  • --keep-docs — include package documentation files.
  • --kernel=RPM_LIST — replace kernel, kernel modules, and kernel firmware used for booting. RPM_LIST is a list of kernel or firmware packages. Note: this option takes a variable number of arguments. So it may be necessary to terminate the arg list with an explicit '--'. Note also: since mkmedia 3.0 this option automatically implies --rebuild-initrd. Use --no-rebuild-inintrd to revert this. See Kernel update notes below.
  • --modules=MODULE_LIST — a list of modules to be added to the initrd. Use this in combination with --kernel. You can prefix module names with '-' to have them removed instead. MODULE_LIST may be space or comma separated. Note: this option takes a variable number of arguments. So it may be necessary to terminate the arg list with an explicit '--'.
  • --no-compression=LIST — a comma-separated list of: firmware, modules, squashfs. See Kernel compression notes below.
  • --addon=RPM_LIST — a list of RPMs that should be made available as an add-on to the main product. Note: this option takes a variable number of arguments. So it may be necessary to terminate the arg list with an explicit '--'. See Add-on notes below.
  • --addon-name=NAME — use NAME as the add-on name. If unset, the auto-generated name 'Add-On NUM' is used, with NUM set to the smallest number that avoids name conflicts.
  • --addon-alias=ALIAS — set repo alias to ALIAS. If unset, an alias based on the repo name is generated.
  • --addon-prio=NUM — set add-on repository priority to NUM (default: 60). Lower NUM means higher priority.
  • --joliet — use Joliet extensions (default).
  • --no-joliet — don’t use Joliet extensions. This is useful when there are file names longer than 103 chars — which Joliet does not support.
  • --volume=VOLUME_ID — set ISO volume id to VOLUME_ID.
  • --vendor=VENDOR_ID — set ISO publisher id to VENDOR_ID.
  • --preparer=PREPARER_ID — set ISO data preparer id to PREPARER_ID.
  • --application=APPLICATION_ID — set ISO application id to APPLICAION_ID. (that exact spelling is from the page, bestie — keeping it 100.)
  • --volume1=VOLUME_ID — specify ISO volume id of the entire image — in case it should differ from the ISO volume id used for the partition. See Hybrid mode notes below.
  • --uefi — make ISO UEFI bootable (default). See UEFI boot notes below.
  • --no-uefi — don’t make ISO UEFI bootable. See UEFI boot notes below.
  • --uefi-image — make UEFI boot image visible in ISO9660 file system (default if it exists). See UEFI boot notes below.
  • --no-uefi-image — hide UEFI boot image in ISO9660 file system (default if it does not exist). See UEFI boot notes below.
  • --zipl — make image zIPL bootable (default on s390x).
  • --no-zipl — don’t make image zIPL bootable (default if not on s390x).
  • --gpt — add GPT when in isohybrid mode.
  • --mbr — add MBR when in isohybrid mode (default).
Note: when both --mbr and --gpt are specified both MBR and GPT are written — which looks nice but is against the UEFI spec. pretty privilege but illegal, basically.
  • --prot-mbr — when writing a GPT, write a protective MBR (default).
  • --no-prot-mbr — when writing a GPT, don’t write a protective MBR.
  • --mbr-code — include x86 MBR boot code (default).
  • --no-mbr-code — don’t include x86 MBR boot code.
  • --mbr-chs — fill in sensible CHS values in MBR partition table (default).
  • --no-mbr-chs — use 0xffffff instead of CHS values in MBR partition table.
  • --no-iso — don’t make image accessible as ISO9660 file system.
  • --hybrid — create an image which is both an ISO and a disk (default).
  • --no-hybrid — create a regular ISO image without extra gimmicks.
  • --hybrid-fs=FS — okay so this one picks the file system FS for the disk partition that gets created in hybrid mode. FS can be either "" (yes, an empty string) which makes a partition starting at offset 0 and stretching across the entire ISO image — and bestie, partitioning tools really do not vibe with that — or it can be 'iso' or 'fat', in which case you get a regular partition with an ISO960 or FAT file system. Default: 'iso'. 💅
  • --fat — creates an image that’s suitable to be put on a USB disk. The image holds a single FAT32 partition, and it can NOT be used to write a DVD. You can adjust the file system size with the --size option. Technically an alias for --hybrid-fs=fat --no-efi --no-iso. 🫶
  • --size=SIZE_SPEC — when you’re using a FAT file system or the --crypto option, you can set the intended size of the disk image. SIZE_SPEC can be a number, optionally followed by a unit ('b', 'k', 'm', 'g', 't') indicating blocks, kiB, MiB, GiB, or TiB, respectively. SIZE_SPEC can also be a device name like /dev/sda, in which case the size of the device is used. ✨
  • --merge-repos — when mkmedia detects repositories in SOURCES, it will try to make them all available and create a common media.1/products file. This is the default. See Product module notes below. 👑
  • --no-merge-repos — skips the special treatment of repositories and just merges all SOURCES. Lowkey the "no thoughts, just merge" option. 💀
  • --include-repos=LIST — comma-separated list of repository names to include in the final image. 🎀
  • --enable-repos=WHEN — if WHEN is set to 'auto' or 'yes', the included repositories are automatically added. If set to 'ask', the user may interactively deselect repositories. The default is not to add any repository. Instead, the user is expected to add the medium as 'add-on' during the installation. 🌸
  • --create-repo — re-create and sign the repository. Default: don’t. 🦋
  • --net=URL — use URL as the default network repository. See Repository notes below. 🌈
  • --instsys-url=URL — load the installation system from the specified URL. See Repository notes below. ⭐
  • --instsys-in-repo — load installation system from repository. This is the default. The option --instsys-url overrides this setting. See Repository notes below. 💖
  • --no-instsys-in-repo — do not load installation system from repository, but search for it on local disks. The option --instsys-url overrides this setting. See Repository notes below. 🔥
  • --defaultrepo=URL_LIST — list of comma (,) separated URLs. The installer will try each URL in turn to check for an installation repository. See Repository notes below. 🧚
  • --boot=OPTIONS — add OPTIONS to default boot options. See Boot option and initrd config option notes below. 👑
  • --add-entry=BOOT_ENTRY — instead of modifying the default boot files, create a new boot entry. This also means that in case initrd or kernel have to be changed, the originals are not overwritten but new files added. BOOT_ENTRY is the name used for this new entry. 🎀
  • --crypto — if set, an encrypted disk image is created. See Crypto notes below. 💜
  • --password=PASSWORD — use PASSWORD for encrypting the disk image. 🤫
  • --luks=OPTIONS — pass OPTIONS to the cryptsetup luksFormat command when creating the encrypted volume. For example, --luks="--iter-time 1000". 🔥
  • --title=TITLE — the password query screen uses TITLE as title. Default: openSUSE. ✨
  • --top-dir=DIR — the installation files are placed into subdir DIR. This helps keeping the directory structure nice and clean in case you are using the image also for other things. The boot config is adjusted accordingly. 🗂️
  • --filesystem=FS — use file system FS for the encrypted image. Default: ext4. Don’t be too creative here — the file system must be supported by grub2. No cap. 💅

🐞 Debug options 🐞

  • --mount-iso — mount ISO images to access them. This is the default if run as root. 🌟
  • --no-mount-iso — unpack ISO images to access them. This is the default if run as normal user. Note: the ISO image is unpacked into a temporary directory below /tmp. Make sure that your file system has enough free space. > 🚨 bestie please check your free space before this one, fr fr. 😭

🌈 Sources 🌈

Sources can be:

  • existing installation media
  • skelcd-installer-<PRODUCT> packages
  • tftpboot-installation-<PRODUCT> packages
  • directories with additional or modified files that should be added/merged into the image

Sources can be used either as ISO image or RPM file directly, or they can be unpacked into a directory. 🫶

The order of sources is important. Files from later sources will replace the same files in previous sources. Periodt. 👑

If you pass a skelcd-installer-<PRODUCT> or tftpboot-installation-<PRODUCT> RPM (or a directory with the same layout), mkmedia will handle these specially. These packages contain the complete installation system and mkmedia will extract the relevant parts to update the installer on the medium. ✨

🧬 Hybrid mode notes 🧬

Hybrid mode means the image can be used both as an ISO for a DVD or directly as a disk image. In other words, there is a partition table added to the ISO image, either GPT or MBR or both. 💿

If you need UEFI support, you will get two partitions: one for the UEFI image (the EFI System Partition), one for the entire DVD. Without UEFI support, you get only one partition covering all files. 🦋

There are two variants this script supports:

  1. Partition 1 is the data partition starting at offset 0 and covering the entire ISO. With UEFI support, partition 2 is the EFI System Partition pointing somewhere inside the first partition to the UEFI boot image file. This produces an obviously inconsistent partition table and partitioning tools really don’t like it. 💀
  2. Without UEFI support, partition 1 is a data partition not starting at offset 0 but still holding all data files. When you mount it, you see either an ISO9660 or a FAT filesystem. With UEFI support, partition 1 is the EFI System Partition and points to the UEFI boot image. Partition 2 is the data partition. Partition 1 and 2 don’t overlap. In this variant a consistent partition table is written. 🌟

Normally the file system of the whole image and the file system of the main partition have identical data and meta data. If you need to have separate labels (volume ids) for both file system variants, you can use the --volume1 option to set a different label to be used for the whole image. 🏷️

For a detailed technical description of the ISO image layout in hybrid mode, see https://github.com/openSUSE/mkmedia/blob/master/layout.md. 🧚

There are several options to control the hybrid mode layout:

  • partition table type: use --gpt for a GPT, or --mbr for a MBR, or use both --gpt --mbr to get a combined GPT and MBR
  • --hybrid-fs= to get a partition at offset 0 (as described in point 1. above)
  • --hybrid-fs=iso to get non-overlapping partitions (as described in point 2. above)
  • --no-hybrid to get a regular ISO, not suitable to boot as disk image
  • --no-iso to get a plain disk image, not usable as DVD image

✍️ Signing notes ✍️

On all media there is a file /CHECKSUMS (or /content with the old SUSE layout) holding sha256 sums of all files relevant during installation. The file is signed and is used to ensure the integrity of the installation environment. 🔐

If you modify any file mentioned there (e.g. replacing it or implicitly as a result of the --initrd or --boot options), /CHECKSUMS is updated and must be re-signed. Otherwise the installer will complain when it starts up. For this, mkmedia will re-sign the file and add the public part of the signing key to the initrd. 😭

You can specify the key to use with either the --sign-key or --sign-key-id option. --sign-key must point to a private key file, --sign-key-id is a key id recognized by gpg. 🔑

If both --sign-key and --sign-key-id are specified, --sign-key-id wins. 👑

You can specify a file which contains the passphrase to the key specified with --sign-key or --sign-key-id to avoid an interactive dialog to enter the passphrase. 🤫

If there’s neither a --sign-key nor a --sign-key-id option, a transient key is created. The public part is added to the initrd and the root directory of the image and the key is deleted. ✨

The key file is named gpg-pubkey-xxxxxxxx-xxxxxxxx.asc. 🎀

🖊️ Image signing notes 🖊️

mkmedia can also embed a signature of the checksum metadata into the image. This can be used by the checkmedia tool to verify the integrity of the image. 💖

The signature is stored in a special file that can be set with the --signature-file option. The default for SUSE-style media is /.signature. If you set the file name to '' (empty string), the file is still created but not visible in the file system (this is the default on older SUSE media). 🌸

For RH-style media, no signature file is used by default. Instead, if signing is requested, a signature block is created outside the data area of the ISO image. This way signing does not interfere with integrity checks by checkisomd5. 🦋

You can use tagmedia to display the embedded meta data. ⭐

The details of this embedding are described in the checkmedia documentation at https://raw.githubusercontent.com/openSUSE/checkmedia/master/README.adoc. 🌈

Note that this special signature file is always prepared. But actually signing the image is not the default and you have to explicitly request it with --sign-image. You can also add a signature later using tagmedia. 👑

🥾 Boot option and initrd config option notes 🥾

The argument to --boot is a space-separated list of boot options, e.g. --boot "foo=1 bar zap=2". If an option is already used in the existing boot config, the option is modified in place. If it is a new option, it is appended to the list of boot options. You can also remove options by prefixing them with a minus sign, for example --boot "-foo -bar zap=123" would remove options foo and bar and add/modify option zap. 💅

The boot config is modified in all boot loader config files on the medium. Notably, on s390x, all parmfiles are adjusted. 🌟

Okay so here’s the ✨special magic✨ for boot options that can validly be specified more than once. Like, say, --boot "console=ttyS0 console=ttyS1". If a boot option is specified at least twice, it’s assumed the intention is to have them all added to the kernel command line. In this case, these options are all added without replacing any existing option of the same name. If you actually intend to replace an existing old option of the same name, remove the old entry explicitly with -OPTION.

For example, assuming there’s an existing boot loader config with options "console=ttyS0", then:

  1. --boot "console=ttyS1" results in "console=ttyS1"
  2. --boot "console=ttyS1 console=ttyS2" results in "console=ttyS0 console=ttyS1 console=ttyS2"
  3. --boot "-console console=ttyS1 console=ttyS2" results in "console=ttyS1 console=ttyS2"

This magic is turned off if there are quotes ("") used in any place in the boot options. For example --boot "foo=\"X\"". In this case, the entire boot option string is simply appended to any existing options verbatim.

Boot options are often options intended for the installation program. For example, passing an AutoYaST profile. In some situations this might add up to quite a lot of lengthy options.

It is, however, possible to place these options not in the boot loader config but put them in config files in the initrd. This gives you a pre-configured initrd that can be used in various places without having to worry about getting all the boot options right.

This is also a possible way to avoid lengthy parmfiles on s390x.

Instead of --boot foo=123 you can use --initrd-config foo=123. But watch out for the different syntax if you set more than one option: --boot "foo=123 bar=abc" vs. --initrd-config foo=123 --initrd-config bar=abc.

Be aware that boot options always take precedence over initrd config options (so the user can always override settings at the boot prompt). This means that if you intend to move an existing setting from boot config to initrd config, make sure you remove the option from the boot config.

For example, Fedora media set inst.stage2 (the installer root file system location) as a boot option. To move it to the initrd, unset it there:

--boot -inst.stage2 --initrd-config inst.stage2=http://example.com/foo

🚗 Driver update notes

Driver updates (DUDs) are archives (typically compressed cpio archives) that describe modifications to the installation system. In particular a DUD can:

  • update kernel modules
  • change files in the initrd of the installation medium
  • change files in the installation system / live root of the installation medium
  • change files on the installation medium
  • change boot options
  • change installer config options
  • provide updated packages to be installed
  • add scripts to be run before and after the installer runs

Not everything is possible in all situations — check out the driver update documentation in the link list below for details.

There are two ways mkmedia can integrate DUDs into installation media:

  1. By adding the DUD (the archive file) to the initrd — the installer will automatically look for DUDs in the initrd and apply them. Use option --initrd for this.
  2. By interpreting the DUD content and applying the necessary changes to the installation medium. Use option --apply-dud for this. mkmedia logs the changes in files .update.ID (in live root) and .update.initrd.ID (in initrd).

The difference between both ways is that the first method applies the DUD during the installation (the same as using inst.dud=URL / dud=URL boot options) while the second has everything done before the installation begins.

This matters for example for kernel modules: in the first method the original modules are loaded and then the driver update unloads them and loads the updated modules. While with the second way the updated modules are loaded right away.

Also, changes to boot options, the initrd content, or general installation media changes can only be applied successfully with the second method.

🧠 Kernel update notes

Normally, the --kernel option will do what you expect but there are situations where it may subtly go wrong. So here is a more in-depth explanation how kernel updates work.

The --kernel option accepts a mix of kernel packages and kernel firmware packages. That is, you can update both kernel firmware and kernel modules. But there must be at least one kernel package.

As a special case if there are no kernel firmware packages specified in --kernel, then the old kernel firmware files are kept (kernel firmware is typically not kernel version dependent).

The initrd typically uses a limited set of kernel modules. mkmedia will try to keep the exact list of modules but that may not be possible due to kernel package changes. mkmedia output will display the differences.

If you have to adjust the kernel module list, use the --modules option. Kernel module dependencies are automatically resolved.

Note that there may be not just a single package containing kernel modules (e.g. kernel-default) but several others (e.g. kernel-default-extra, kernel-default-optional) or even kmp packages with individual modules. If you see missing modules, you might need some of these packages as well.

mkmedia will not add all kernel firmware files to the initrd but only those that are required by the kernel modules used in the initrd.

For Live media, kernel modules and firmware are also present in the Live root file system. Kernel modules and firmware are also updated there but the complete packages are used.

There are two cases: 1. the "normal" case (--rebuild-initrd is active) and 2. --no-rebuild-initrd is active.

Note that since mkmedia 3.0 --rebuild-initrd is automatically activated if --kernel is used.
  1. Old kernel modules / firmware files are removed and only files from packages specified in --kernel are used. This makes initrd and Live root smaller and exactly reproduces the original initrd and Live root file system layouts. This also means that if you forgot to add sufficient kernel firmware packages in --kernel, kernel firmware files might be missing.
  2. New kernel modules / firmware files are added to initrd and Live root. This means your initrd and Live root file system contain both the old kernel tree and the new one (making it noticeably larger). If you included kernel firmware packages in --kernel then kernel firmware files from these packages are added as well, possibly replacing old kernel firmware files with the same name.

In both cases, if you run out of space in the Live root file system, use --instsys-size to increase the file system size as needed.

Note on usrmerge kernels: kernel packages (and kernel firmware packages) come in two variants: older packages with files stored in /lib and (typically) newer packages with files stored in /usr/lib. mkmedia will accept both and adjust the package layout to the one expected in initrd and Live root.

🗜️ Kernel compression notes

For SUSE installation media, kernel modules and firmware files are kept in a separate squashfs image (parts/00_lib) within the initrd.

Usually, kernel firmware files and kernel modules are compressed to reduce size.

In certain situations it may be better to keep individual kernel modules or kernel firmware files uncompressed and rely on the squashfs file system compression instead.

Or use no squashfs file system compression and rely on the initrd compression.

To fine-tune this, use the --no-compression option.

Setting it to modules will uncompress all kernel modules. firmware will uncompress firmware files and squashfs will turn off squashfs file system compression.

The current setting is stored in the .no_compression file in the initrd.

For example, --no-compression=firmware,modules,squashfs turns off compression everywhere. This results in the smallest compressed initrd size — but it also results in the largest uncompressed initrd size.

Note that any new --no-compression setting replaces the old setting entirely. For example, --no-compression=modules will not additionally turn off compression for kernel modules but means only kernel modules are uncompressed.

Note also that you almost certainly do not want to use --no-compression together with --no-rebuild-initrd.

🎁 Add-on notes

The add-on created here is just a repository, not a full add-on product. If you need the latter, you will have to create that on your own and add it to the iso.

Although it auto-generates a name for the repository, it’s not a very creative one and it’s probably a good idea to choose one explicitly using the --addon-name option.

The default installation repositories have priority 99. Any smaller number for the add-on repository will prefer the add-on packages even though the package version number is smaller than in the standard repository.

The default priority of 60 is chosen to be between the priority of the default installation repositories (99) and the repositories created by driver updates (50).

📦 Repository notes

mkmedia supports media with three different installers:

  1. YaST (SLE-15, Leap-15, Tumbleweed)
  2. Agama (SLE-16, Leap-16, Tumbleweed)
  3. Anaconda (Multi-Linux, Fedora, RHEL)

Starting an installation is a three-stage process: (a) kernel and initrd are loaded, then (b) a program in the initrd (dracut or linuxrc) loads the installation system and starts the installer and then (c) the installer runs an installation using a software repository.

Each of the three installation programs has its own way of setting the installation system and software repository locations.

1. Repository notes (YaST)

YaST supports two types of repositories:

  1. The "classical" (old) variant which has a /content file with product meta data and file checksums at the repo location and package meta data in a sub-directory suse/setup/descr.
  2. A repo-md repository which uses /.treeinfo for product meta data, /CHECKSUMS for file checksums, and has package meta data in a repodata sub-directory.

A repository usually also contains the installation system. If so, the image files are placed in a boot/<ARCH> sub-directory and the installer can simply be loaded from the repository.

But if it is just a plain repository without the installation system the installer has to be loaded from somewhere else.

Use the --no-instsys-in-repo option to tell mkmedia that it can be loaded from a local disk or dvd. It will be searched for on any mountable local device at startup.

okay so you can totally override this with the --instsys-url option and load the installation system from literally anywhere you want ✨ but bestie, please peek at the linuxrc docs at https://en.opensuse.org/SDB:Linuxrc for the deets before you go using it, mwah 💋

The installer normally has its own internal list of repo locations that it tries one after another. You can switch that up with --defaultrepo. Example era: --defaultrepo=cd:/,http://foo/bar means "check the local dvd drive first, then try the network at http://foo/bar" — iconic behavior honestly 🎀

heads up! SLE-15 uses a registration server, and it does not use the --defaultrepo setting to find the installation repository. periodt.

And the --net option is just a cute shorthand for --defaultrepo=cd:/,hd:/,<NET_URL>. slay 💅

🌈 2. Repository notes (Agama)

Use the root=live:<URL> setting to point at the installation system. That installation system is a squashfs file system image (usually LiveOS/squashfs.img) chillin' on the installation media 🦋

The default setting loads it from the local disk or dvd you booted from. But you can also plop it on a server and load it via network if that's your vibe.

Use either --boot root=live:... or --initrd-config root=live:... to set this option.

The software repository location can be changed using inst.install_url=<URL>. Set it either via --boot or --initrd-config. easy ✨

🧚 3. Repository notes (Anaconda)

Use the inst.stage2=<URL> setting to point at an unpacked installation medium. The installation system is a squashfs file system image (usually images/install.img) that gets located automatically inside the unpacked installation medium tree 🔥

The default setting loads it from the local disk or dvd you booted from. You can place it on a server and load it via network if you want — main character energy 🌸

Use either --boot root=live:... or --initrd-config root=live:... to set this option.

important vibe check: inst.stage2 is typically set as a boot option. You must remove it from the boot options if you want to set it via --initrd-config. no cap.

See Boot option and initrd config option notes.

The software repository location can be changed using inst.repo=<URL>. Set it either via --boot or --initrd-config.

💜 Product module notes

In SLE 15 the product is split into several repositories called 'modules' (and pls don't confuse this with kernel modules, they are literally not the same thing 😭). These modules are distributed over several media or in separate directories on a network installation server.

mkmedia lets you combine the installation medium together with the modules you need into a single medium. obsessed 🫶

Check the available modules with --list-repos and then pick the ones you need with --include-repos. iykyk 💅

🍓 Fedora/RHEL notes

mkmedia will by default create media with a Fedora/RHEL-style hybrid mode (hybrid GPT+MBR, data partition starting at offset 0). You can change that to create a SUSE-style hybrid mode (partition table with non-overlapping partitions) by adding option --hybrid-fs=iso.

See Hybrid mode notes above for more details.

✨ Notes

  • You can use --sign-image to create signed images 💖 The image signature can be verified with checkmedia. checkisomd5 can only verify the embedded MD5 sums.
  • You can use other digests instead of MD5 using --digest DIGEST but checkisomd5 cannot verify these images. You will have to use checkmedia instead. fr fr.

🌈 UEFI boot notes

There are two ways UEFI firmware finds boot files on our media:

  1. by running the boot loader located below the /EFI directory
  2. by locating a FAT file system image via the El-Torito standard and running the boot loader stored there; this FAT file system image contains the same /EFI directory structure

The --uefi option refers to method 2. noted 👑

heads up: this FAT file system image might not be visible on the medium (e.g. KIWI produced media hide the file 🙈). If it is visible, it has names like /boot/x86_64/efi, /boot/x86_64/loader/efiboot.img, /images/efiboot.img, or similar.

You can control the visibility of this image with option --uefi-image (to make it visible) or --no-uefi-image (to hide it). If this option is not given, mkmedia will try to keep the visibility as it was on the source medium. keeping the vibes consistent, love that 💅

If this FAT file system image is missing (or hidden) or files in the /EFI directory (on the medium) have changed, mkmedia will create a new FAT file system image based on the updated /EFI directory content. glow up ✨

🔐 Crypto notes

The --crypto option lets you create an encrypted installation disk 😳 Note that this image is explicitly not bootable as cd/dvd (no hybrid image). It is both legacy BIOS and UEFI bootable, though. slay.

Everything except the plain grub2 binaries is encrypted on a LUKS partition. Including the installer specific boot config. So if you for example put some password into the default boot options via --boot this is also stored in the encrypted part. 🔒 (yes, that means it's encrypted too, bestie.)

At the moment only x86_64 is supported. And you have to run mkmedia on a machine that has grub2-i386-pc installed (to get the legacy BIOS setup). no skipping this one 💀

Unlike the usual setup, grub2 is used for both legacy BIOS and UEFI booting. So the boot screen really looks identical in both cases. iconic 🌈

The default image size is chosen to leave only minimal free space. To adjust the image size to your needs, use the --size option.

Important 💀 For this to work, the cryptsetup tools must be available in the installer's initrd. This is not the case for older media (prior to recent Tumbleweed and SLE/Leap 15).

If you work with these old media you must also add the following two packages to the initrd explicitly:

  • cryptsetup
  • libpwquality1

You can find the required versions on the install medium in either the /suse/x86_64 or /x86_64 directory. Copy them to some temporary location and add:

--initrd cryptsetup.rpm --initrd libpwquality1.rpm

to the mkmedia command line. easy peasy 🎀

🎀 Configuration file

mkmedia reads $HOME/.mkmediarc at startup. ur personal config era 💅

  • sudo=COMMAND — To access existing ISO image files you will need root privileges. (It will be mounted.) This entry lets you specify a command granting you root privileges.
  • sign-key=FILE — File name of the private key file with the signing key. The same as the --sign-key option. See Signing notes above.
  • sign-key-id=KEY_ID — Key id of the signing key. The same as the --sign-key-id option. See Signing notes above.

🔥 EXAMPLES 🔥

like, just copy these, they ate:

# create foo.iso from /foo_dir
mkmedia --create foo.iso /foo_dir

# create foo.iso from bar.iso and integrate files from /foo_dir
mkmedia --create foo.iso bar.iso /foo_dir

# create foo.iso from /foo_dir, no hybrid mode
mkmedia --create foo.iso --no-hybrid /foo_dir

# create foo.iso from old.iso and add some boot option
mkmedia --create foo.iso --boot 'debug=1' old.iso

# create foo.iso from old.iso and add content of directory foo_bar to the initrd
mkmedia --create foo.iso --initrd foo_bar old.iso

# create foo.iso from old.iso and add package bar to the initrd
mkmedia --create foo.iso --initrd bar.rpm old.iso

# create foo.iso from old.iso and add a driver update to the initrd
mkmedia --create foo.iso --initrd bar.dud old.iso

# create foo.iso from old.iso and add package bar to rescue system
mkmedia --create foo.iso --rescue bar.rpm old.iso

# create foo.iso from live.iso and add package bar to Live system
mkmedia --create foo.iso --instsys bar.rpm live.iso

# create foo.iso from live.iso and update kernel to kernel-default.rpm
mkmedia --create foo.iso --kernel kernel-default.rpm -- live.iso

# create foo.iso from live.iso and increase Live root file system by 1 GiB
mkmedia --create foo.iso --live-root-size +1G live.iso

# create new iso from sles.iso taking an updated installer from tftpboot-installation-* package
mkmedia --create new.iso sles.iso tftpboot-installation-SLE.rpm

Find more usage examples here 🦋 https://github.com/openSUSE/mkmedia/blob/master/HOWTO.md

⭐ SEE ALSO ⭐

verifymedia(1), checkmedia(1), tagmedia(1), mkdud(1). go read those too bestie 💖

and that's the whole page, bestie 🫶 this edition is mkmedia 5.3, dated 2026-03-26, and it lives at MKMEDIA(1) — go make some iconic media 💅✨

📦 where this page comes from