MKLIVECD(8)

NAME
mklivecd - Make your own NetBSD / x86 Live CD-ROM/DVD-ROM

SYNOPSIS
mklivecd -v -c conf_file -k kernel target

DESCRIPTION
mklivecd allows you to build your own NetBSD Live CD/DVD, so you don't need to install NetBSD to any disk, because it will run directly from the CD-ROM/DVD-ROM.

To choose different kernels when booting from the CD-ROM/DVD-ROM, two options for the bootloader are provided since version 0.12.0: the GNU Grub bootloader or the NetBSD ISO9660 bootloader (since NetBSD 4.0). By default on i386 will use the first option: the GNU Grub bootloader, and the NetBSD ISO9660 bootloader on amd64. You may want to change this by changing the option USE_GNU_GRUB to no.

The following options are recognized:

-c conf_file
    Use conf_file as configuration file (full name expected). Example: -c foo.conf.

-k kernel
    Overrides the KERNEL_CONFIG value specified in the configuration file, KERNEL_NAME will be modified automatically too.

-v  Show more useful messages.

CONFIGURATION
mklivecd reads the parameters of the main configuration file stored inside $HOME/.mklivecd/mklivecd.conf, so be sure you have modified it with your preferences before starting any target.

Configuration files are simple shell scripts that define variables. The default values shown here are those written in the template when issuing the config target.

BASEDIR
    Primary directory used to store the main directories and the final ISO image. Defaults to $HOME/livecd.

FETCH_SETS
    If it's set to yes, it will download the sets in the target fetch, from the URL specified in REMOTE_SETS_URL.

REMOTE_SETS_URL
    This is the URL containing the base/x11 sets for the fetch target and if FETCH_SETS is set to yes.

BASE_SETS_DIR
    The base sets directory. Defaults to $HOME/release/binary/sets.

BASE_SETS
    Base sets which will be unpacked into $ISODIR. Sets used by default are: etc.tgz base.tgz comp.tgz text.tgz.

CHROOT_SHELL
    Default shell to use with the chroot target. Defaults to /bin/ksh.

ISODIR
    Directory used to store the main NetBSD base distribution. Defaults to $BASEDIR/iso.

PKGSRCDIR
    The NetBSD pkgsrc collection directory. When the chroot target is invoked, the pkgsrc directory will be mounted via mount_null(8), and you could install any package. Defaults to /usr/pkgsrc.

MOUNT_PKGSRC_DIR
    Mount the pkgsrc directory specified in the $PKGSRCDIR option. Defaults to no.

PKGSRCDISTDIR
    The NetBSD distfiles pkgsrc directory. When the chroot target is invoked, the distfiles directory will be mounted via mount_null(8). Defaults to /usr/pkgsrc/distfiles.

MOUNT_PKGSRCDIST_DIR
    Mount the pkgsrc distfiles directory specified in the $PKGSRCDISTDIR option. Defaults to no.

PACKAGESDIR
    The NetBSD packages pkgsrc directory. When the chroot target is invoked, the packages directory will be mounted via mount_null(8). Defaults to /usr/pkgsrc/packages.

MOUNT_PACKAGES_DIR
    Mount the packages pkgsrc directory specified in the $PACKAGESDIR option. Defaults to no.

SHAREDIR
    The main directory used to store the Makefiles, kernel, example configuration files, etc. Defaults to /usr/pkg/share/mklivecd/.

SOURCEDIR
    The NetBSD source directory. Defaults to /usr/src.

WORKDIR
    Directory used to store the object files and kernel built by the target ‘kernel’. Defaults to $BASEDIR/work.

X11_SETS
    X11 sets which will be unpacked into $ISODIR. Sets used by default are: xbase.tgz xcomp.tgz xfont.tgz xserver.tgz.

X11_SETS_DIR
    The X11 sets directory. Defaults to $BASE_SETS_DIR.

KERNEL_CONFIG
    Name of the NetBSD configuration kernel (e.g. GENERIC) used for the boot image. Defaults to KERN-LIVECD.

KERNEL_NAME
    Name of the built NetBSD kernel. Useful if you want to change the default behavior of the build process. Defaults to MKLIVECD.

MULTIPLE_KERNELS
    If set to other thing than ``no'', it will compile and install the kernels specified into $ISODIR/boot/grub, and it will update automatically the menu.lst file for the GNU Grub bootloader. See below for details.

BLANK_BEFORE_BURN
    Used in the burn target to blank a CD-RW before burning the NetBSD Live CD ISO image. Useful if you use CD-RW. Defaults to no.

CDRECORD_ARGS
    Arguments passed to cdrecord(1) when burning the NetBSD Live CD ISO image. Defaults to -v.

CDRECORD_BIN
    Name of the cdrecord binary used by mklivecd to burn the image. Defaults to /usr/pkg/bin/cdrecord.

CDROM_DEVICE
    Used in the target burn to specify the CD-ROM device. Defaults to 15,1,0.

ENABLE_X11
    If set to yes then X11 sets and configuration files will be unpacked automatically. Defaults to no.

GRUB_FILES_DIR
    Directory where the grub files are stored. Defaults to /usr/pkg/lib/grub/i386-/.

HOSTNAME
    Hostname of the live CD-ROM/DVD-ROM, it's assigned when running the base target. Defaults to MKLIVECD_0x00.

IMAGE_NAME
    Name of the final ISO image, e.g.: My_NetBSD_Live_CD_ISO_Image.iso. Defaults to NetBSD-LiveCD.

MKISOFS_ARGS
    Arguments passed to mkisofs(1) when creating the NetBSD ISO image. Defaults to -J -R -v.

MKISOFS_BIN
    Name of the mkisofs binary used by mklivecd to build the image. Defaults to /usr/pkg/bin/mkisofs.

PERSONAL_CONFIG
    If set to yes, then personal_config file will be used. See below for details. Defaults to no.

PKG_SYSCONFDIR
    Directory where the pkgsrc settings are stored, by default mklivecd preserves this behavior and uses usr/pkg/etc.

REMOVE_DIRS
    Take care with this option, because it will remove all directories when the target iso is invoked. It could be useful if you don't want to include some directories on the CD, or your free space is small. Defaults to altroot rescue usr/share/info.

USE_GNU_GRUB
    Used to select the bootloader for the Live CD. When it's disabled the NetBSD CD Bootloader will be used. Note that you cannot use GRUB on amd64, so the option shouldn't be touched on this arch. Defaults to yes.

VND_COMPRESSION
    Enable this to mount /usr, and /var/db/pkg via vnconfig(8) with compression enabled. Note you'll need to have options VND_COMPRESSION in your kernel config, at the moment this option is only available on NetBSD 4.0 and later. Defaults to no.

MNT_RAMFS_ARGS
    This specifies the arguments passed to the mount(8) command used in the livecd script, when the NetBSD Live CD is booted. By default it will contain -s 128m swap to be used by mount_mfs(8). If you want to use mount_tmpfs(8) change it just to tmpfs.

MNT_RAMFS_CMD
    This specifies the mount(8) command used by mklivecd in the boot configuration stage. Defaults to mount_mfs. Can be changed to mount_tmpfs too.

TARGETS
A target specifies what mklivecd should do (as in make). The following list describes all supported targets, in the logical order in which you should call them.

config
    Create a sample mklivecd.conf file. You should edit it after the creation as you will probably want to change the default configuration, especially paths.

kernel
    Builds the specified kernel $KERNEL_CONFIG into the $ISODIR directory.

fetch
    Downloads the sets defined in $BASE_SETS from $REMOTE_SETS_URL and if $FETCH_SETS is enabled.

base
    Install the $BASE_SETS and $X11_SETS into the $ISODIR directory and prepare the base system for the next target, which is the most important: chroot.

chroot
    Enters the chroot environment. Uses ksh(1) as default shell.

iso Builds the ISO image $IMAGE_NAME into $BASEDIR and removes all directories specified in $REMOVE_DIRS before it, to save some space.

burn
    Burns the ISO image $IMAGE_NAME on the CD-ROM with cdrecord(1). Use the $CDROM_DEVICE variable to specify the default device.

clean
    Cleans the $WORKDIR directory and the base NetBSD tree in $ISODIR, except the mfs directories located in /stand and the NetBSD kernels.

  What should I do in the chroot jail?
While working in the chroot environment, you can add users, install binary packages, modify /etc/ttys, etc. You can enter the chroot as often as you want, mklivecd will create the tarballs automatically when you leave the chroot.

  How can I use the PERSONAL_CONFIG option?
When PERSONAL_CONFIG is set to yes, $HOME/.mklivecd/personal_config will be used. For example, you can copy some configuration directories from $HOME to the $ISODIR/$HOME directory. Please take a look at the example file located in /usr/pkg/share/mklivecd.

  How to use the MULTIPLE_KERNELS option?
An example is provided below, we have two kernels: ACPIKERN and APMKERN, both are kernel configuration files, you'll need to define the variables named KERNEL_CONFIG_${foo} and KERNEL_NAME_${foo} for every kernel specified on the MULTIPLE_KERNELS option. The following example shows that:

    MULTIPLE_KERNELS="ACPIKERN APMKERN"
    KERNEL_CONFIG_ACPIKERN="LIVECD_ACPI"
    KERNEL_CONFIG_APMKERN="LIVECD_APM"
    KERNEL_NAME_ACPIKERN="KERN_ACPI_LIVECD"
    KERNEL_NAME_APMKERN="KERN_APM_LIVECD"

Note that when using this option, the KERNEL_CONFIG and KERNEL_NAME variables, will don't have any effect. After building the specified kernels, it will update the menu.lst file automatically for the GNU Grub bootloader.

NOTES
PKG_SYSCONFDIR defaults to usr/pkg/etc without a starting slash. This shouldn't be added because mklivecd adds this automatically in the script, otherwise your real PKG_SYSCONFDIR directory will be copied instead of the one located in $ISODIR.

By default there's no default kernel, so you should copy your own kernel (or kernels if MULTIPLE_KERNELS is set) config file into $HOME/.mklivecd. The KERNEL_CONFIG variable should point at it, if you're not using MULTIPLE_KERNELS. The important thing about the kernel is the line:

    config netbsd root on cd0a type cd9660 dumps on none

This line is required in the kernel config file for the Live CD-ROM/DVD-ROM to boot correctly and without human interactivity, otherwise you'll have to enter the parameters manually when booting. If you use Grub, you will also need

    options INCLUDE_CONFIG_FILE

because mklivecd will run config -x on the kernel to determine whether the MULTIBOOT option is enabled.

EXAMPLES
Below are the minimal steps to create your own Live CD-ROM/DVD-ROM:

    $ mklivecd config
      [edit the config file]
    $ mklivecd kernel
    $ mklivecd fetch [to download the sets if enabled]
    $ mklivecd base
    $ mklivecd chroot
      [edit what you like in there, e.g. config files]
    $ mklivecd iso
    $ mklivecd burn

SEE ALSO
packages(7), mount_mfs(8), mount_null(8), mount_tmpfs(8)

AUTHORS
The mklivecd utility was written by Juan Romero Pardines <xtraeme@NetBSD.org>.

BUGS
It is not perfect but at least it does its task correctly.

SUPPORT
Many Live CDs are built with this software, and sometimes mklivecd is not even mentioned, that's not good. If you use this software to build a Live CD, please say so in your README file or FAQ. If you want more features implemented, please make a hardware or monetary donation to continue improving NetBSD development.