1. Manuals
  2. Tumbleweed
  3. mksusecd
  4. mksusecd(1)

Scroll to navigation

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

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

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

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

--instsys=DIR|RPM

Add content of DIR or RPM to installation system or root file system for Live media (can be repeated).

--rescue=DIR|RPM

Add content of DIR or RPM to rescue system (can be repeated).

--no-docs

Don’t include package documentation files (default).

--keep-docs

Include package documentation files.

--kernel=KERNEL_RPMS

Replace kernel and modules used for booting. KERNEL_RPMS is a list of RPMs that contain the new kernel, modules, and firmware files.
Note: this option takes a variable number of arguments. So it may be necessary to terminate the arg list with an explicit '--'.

--modules=MODULE_LIST

A list of modules to be included additionally 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 '--'.

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

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

--uefi

Make ISO UEFI bootable (default).

--no-uefi

Don’t make ISO UEFI bootable.

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

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

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

--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 (RPMs)

•tftpboot-installation-<PRODUCT> packages (RPMs)

•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 and extract the relevant parts.

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:

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

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

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:

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 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. Major options that work, are:

•--boot to add boot options

•--initrd to modify the initrd (stage1)

•--instsys to modify the Live installation system (stage2)

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.

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

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

SEE ALSO

•more documentation: /usr/share/doc/packages/mksusecd

•get latest version: <https://github.com/openSUSE/mksusecd?tab=readme-ov-file#downloads>

•mksusecd web site: <https://github.com/openSUSE/mksusecd>

•openSUSE Build Service: <https://build.opensuse.org>
2024-04-05 mksusecd 2.16