table of contents
MKSUSECD(1) | User Commands | MKSUSECD(1) |
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
General Options¶
--verbose
--version
--save-temp
--help
Show available repositories¶
--list-repos
Create new image¶
-c, --create=FILE
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
Note: this is only useful for testing.
--nano
--pico
Media integrity related options¶
--check
--no-check
--digest=DIGEST
--no-digest
--sign-image
See Image signing notes below.
--no-sign-image
See Image signing notes below.
--signature-file=FILE
See Image signing notes below.
--sign
See Signing notes below.
--no-sign
--sign-key=KEY_FILE
See Signing notes below.
--sign-key-id=KEY_ID
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
See Signing notes below.
Initrd/instsys update related options¶
--initrd=DIR|RPM|DUD
--rebuild-initrd
This makes the initrd smaller but requires to run mksusecd with root permissions.
See Kernel update notes below.
--no-rebuild-initrd
This makes the initrd larger but does not require to run mksusecd with root permissions.
See Kernel update notes below.
--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
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
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
See Kernel compression notes below.
Add-on related options¶
--addon=RPM_LIST
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
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
If unset, an alias based on the repo name is generated.
--addon-prio=NUM
Lower NUM means higher priority.
ISO file system related options¶
--joliet
--no-joliet
--volume=VOLUME_ID
--vendor=VENDOR_ID
--preparer=PREPARER_ID
--application=APPLICATION_ID
--volume1=VOLUME_ID
See Hybrid mode notes below.
General image layout related options¶
--uefi
See UEFI boot notes below.
--no-uefi
See UEFI boot notes below.
--zipl
--no-zipl
--gpt
--mbr
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
--no-prot-mbr
--mbr-code
--no-mbr-code
--mbr-chs
--no-mbr-chs
--no-iso
--hybrid
--no-hybrid
--hybrid-fs=FS
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
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
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
See Product module notes below.
--no-merge-repos
--include-repos=LIST
--enable-repos=WHEN
--create-repo
Repository location related options¶
--net=URL
See Repository notes below.
--instsys-url=URL
See Repository notes below.
--instsys-in-repo
The option --instsys-url overrides this setting.
See Repository notes below.
--no-instsys-in-repo
The option --instsys-url overrides this setting.
See Repository notes below.
--defaultrepo=URL_LIST
Boot menu related options¶
--boot=OPTIONS
--add-entry=BOOT_ENTRY
BOOT_ENTRY is the name used for this new entry.
Image encryption related options¶
--crypto
See Crypto notes below.
--password=PASSWORD
--title=TITLE
--top-dir=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
Don’t be too creative here - the file system must be supported by grub2.
Debug options¶
--mount-iso
--no-mount-iso
Note: the ISO image is unpacked into a temporary directory below '/tmp'. Make sure that your file system has enough free space.
Sources¶
Sources can be
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:
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.
This also means that if you forgot to add sufficient kernel firmware packages in --kernel, kernel firmware files might be missing.
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:
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
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.
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:
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
sign-key=FILE
See Signing notes above.
sign-key-id=KEY_ID
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>
SEE ALSO¶
2025-02-07 | mksusecd 3.3 |