General Options¶

--verbose

--version

--tmp-dir=TMPDIR

--save-tmp

--help

Show available repositories¶

--list-repos

Create new image¶

-c, --create=FILE

Media type related options¶

--micro

--nano

--pico

Media integrity related options¶

--check

--no-check

--digest=DIGEST

--no-digest

--sign-image

--no-sign-image

--signature-file=FILE

--sign

--no-sign

--sign-key=KEY_FILE

--sign-key-id=KEY_ID

--sign-pass-file

Initrd/instsys update related options¶

--apply-dud=DUD

--initrd=DIR|RPM|DUD

--rebuild-initrd

--no-rebuild-initrd

--initrd-config=KEY=VALUE

--instsys=DIR|RPM

--live-root=DIR|RPM

--rescue=DIR|RPM

--instsys-size=SIZE_SPEC

--live-root-size=SIZE_SPEC

--no-docs

--keep-docs

Kernel/module update related options¶

--kernel=RPM_LIST

--modules=MODULE_LIST

--no-compression=LIST

Add-on related options¶

--addon=RPM_LIST

--addon-name=NAME

--addon-alias=ALIAS

--addon-prio=NUM

ISO file system related options¶

--joliet

--no-joliet

--volume=VOLUME_ID

--vendor=VENDOR_ID

--preparer=PREPARER_ID

--application=APPLICATION_ID

--volume1=VOLUME_ID

General image layout related options¶

--uefi

--no-uefi

--uefi-image

--no-uefi-image

--zipl

--no-zipl

--gpt

--mbr

--prot-mbr

--no-prot-mbr

--mbr-code

--no-mbr-code

--mbr-chs

--no-mbr-chs

--no-iso

--hybrid

--no-hybrid

--hybrid-fs=FS

--fat

--size=SIZE_SPEC

Media repository related options¶

--merge-repos

--no-merge-repos

--include-repos=LIST

--enable-repos=WHEN

--create-repo

Repository location related options¶

--net=URL

--instsys-url=URL

--instsys-in-repo

--no-instsys-in-repo

--defaultrepo=URL_LIST

Boot menu related options¶

--boot=OPTIONS

--add-entry=BOOT_ENTRY

Image encryption related options¶

--crypto

--password=PASSWORD

--luks=OPTIONS

--title=TITLE

--top-dir=DIR

--filesystem=FS

Debug options¶

--mount-iso

--no-mount-iso

Sources¶

Sources can be

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.

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 packaged 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 paritions: 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:

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/mksusecd/blob/master/layout.md>.

There are several options to control the hybrid mode layout:

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 existng 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 opion zap.

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.

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 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:

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:

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 acivated if --kernel is used.

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 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:

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:

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.

You can override this using the --instsys-url option to load the installation system from any location. Please look at the linuxrc documentation at
<https://en.opensuse.org/SDB:Linuxrc>
for details before using this option.

The installer normally uses an internal list of repository locations that are tried in turn. You can change it using the --defaultrepo option. For example, --defaultrepo=cd:/,http://foo/bar means to check the local dvd drive first and then try via network at <http://foo/bar>.

SLE-15 uses a registration server, it does not use the --defaultrepo setting to locate the installation repository.

The --net option is just a short hand for --defaultrepo=cd:/,hd:/,<NET_URL>.

2. Repository notes (Agama)¶

Use the root=live:<URL> setting to point to the installation system. The installation system is a squashfs file system image (ususally 'LiveOS/squashfs.img') found on the installation media.

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.

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.

3. Repository notes (Anaconda)¶

Use the inst.stage2=<URL> setting to point to an unpacked installation medium. The installation system is a squashfs file system image (usually 'images/install.img') that is located automatically in 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.

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

Note that inst.stage2 is typically set as boot option. You must remove it from the boot options if you want to set it via --initrd-config.

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' (don’t confuse this with kernel modules). 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.

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

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

UEFI boot notes¶

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

The --uefi option refers to method 2.

Note that 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.

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.

Crypto notes¶

The --crypto option allows you to 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.

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.

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).

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

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:

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.

Configuration file¶

mkmedia reads $HOME/.mkmediarc at startup.

sudo=COMMAND

sign-key=FILE

sign-key-id=KEY_ID