mksusecd(1) Manual Page

Name

mksusecd - create and modify bootable media.

Synopsis

mksusecd [OPTIONS]… SOURCES…

Description

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

mksusecd 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 the kernel)
integrate driver updates
integrate add-on repositories
create a small network boot medium

General Options

--verbose: Show more detailed messages. Can be repeated to log even more.
--version: Show mksusecd version.
--save-temp: 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.
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.

Media type related options

--micro: Create image with just enough files to run the installer. But you can’t actually install as all packages have been removed.
Note: this is only useful for testing.
--nano: Create image with just enough files for a network based installation.
--pico: Even less than --nano, keep just the bootloader (for testing).

Media integrity related options

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

Initrd/instsys update related options

--initrd=DIR|RPM|DUD: Add content of DIR, RPM, or DUD to initrd (can be repeated).
--rebuild-initrd: Rebuild the entire initrd instead of appending changes.
This makes the initrd smaller but requires to run mksusecd 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 mksusecd with root permissions.
See Kernel update 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: Aias for --instsys-size.
--no-docs: Don’t include package documentation files (default).
--keep-docs: Include package documentation files.

Kernel/module update related options

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

Add-on related options

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

ISO file system related options

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

General image layout related options

--uefi: Make ISO UEFI bootable (default).
See UEFI boot notes below.
--no-uefi: Don’t make ISO UEFI bootable.
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.
--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: Use file system FS for the disk partition created in hybrid mode.
FS can be either "" (empty string) producing a partition starting at offset 0 and extending across the entire ISO image (partitioning tools don’t really like this) or 'iso' or 'fat' in which case you get a regular partition with an ISO960 or FAT file system (default: 'iso').
--fat: Create 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 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 casee the size of the device is used.

Media repository related options

--merge-repos: When mksusecd detects repositories in SOURCES it will try to make them all available and create a common media.1/products file (default).
See Product module notes below.
--no-merge-repos: Skip the special treatment of repositories and just merge all SOURCES.
--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).

Repository location related options

--net=URL: Use URL as 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 (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.

Boot menu related options

--boot=OPTIONS: Add OPTIONS to default boot options.
--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.

Image encryption related options

--crypto: If set, an encrypted disk image is created.
See Crypto notes below.
--password=PASSWORD: Use PASSWORD for encrypting the disk image.
--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.

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

either as image/RPM file or 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) - mksusecd will handle these specially. These packaged contain the complete installation system and mksusecd willl 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 written on the ISO image, either GPT or MBR.

If you need UEFI support you will get two paritions: one for the UEFI image, one for the entire DVD. If not, you get just one partition covering all files.

There are two variants this script supports:

Partition 1 is the data partition starting at offset 0 and covering the entire ISO, partition 2 is the UEFI system partition pointing somwhere inside the first partition. This produces an obviously inconsistent partition table and partitioning tools really don’t like it.
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. If you need UEFI support this partition becomes partition 2 and partition 1 points to the UEFI image. Partition 1 and 2 don’t overlap. In this variant a consistent partition table is written.

Normally the file system of the entire 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 entire 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, mksusecd 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

mksusecd 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 is '/.signature'. If you set the file name to '' (empty string) the file is still created but not visible (the default on many SUSE installation media).

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.

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. mksusecd will try to keep the exact list of modules but that may not be possible due to kernel package changes. mksusecd 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.

mksusecd 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 mksusecd 3.0 --rebuild-initrd is automatically acivated if --kernel is used.

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.
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'. mksusecd 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 want to use --no-compression together with --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

The installer supports two types of repositories:

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'.
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 mksusecd 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.

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

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.

mksusecd 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

Not all options apply to media with Fedora/RHEL layout. It doesn’t make sense to add a SUSE driver update to a RHEL iso, for example.

mksusecd will by default create media with a SUSE-like hybrid mode (MBR partition table with non-overlapping partitions). You can change that to create the Fedora/RHEL hybrid mode (hybrid GPT+MBR, partition starting at offset 0) by adding these options:
--gpt --mbr --hybrid-fs "".

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.

UEFI boot notes

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

by running the boot loader located below the '/EFI' directory
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.

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.

If this FAT file system image is missing or files in the '/EFI' directory (on the medium) have changed, mksusecd will create a new FAT file system image based on the updated '/EFI' directory content. This generated FAT file system image will always be visible on the medium.

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

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 mksusecd command line.

Configuration file

mksusecd reads $HOME/.mksusecdrc at startup.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mksusecd_man.adoc

mksusecd_man.adoc

mksusecd(1) Manual Page

Name

Synopsis

Description

General Options

Show available repositories

Create new image

Sources

Hybrid mode notes

Signing notes

Image signing notes

Kernel update notes

Kernel compression notes

Add-on notes

Repository notes

Product module notes

Fedora/RHEL notes

UEFI boot notes

Crypto notes

Configuration file

Examples

See Also

Files

mksusecd_man.adoc

Latest commit

History

mksusecd_man.adoc

File metadata and controls

mksusecd(1) Manual Page

Name

Synopsis

Description

General Options

Show available repositories

Create new image

Media type related options

Media integrity related options

Initrd/instsys update related options

Kernel/module update related options

Add-on related options

ISO file system related options

General image layout related options

Media repository related options

Repository location related options

Boot menu related options

Image encryption related options

Sources

Hybrid mode notes

Signing notes

Image signing notes

Kernel update notes

Kernel compression notes

Add-on notes

Repository notes

Product module notes

Fedora/RHEL notes

UEFI boot notes

Crypto notes

Configuration file

Examples

See Also