pkgsrc/sysutils/mklivecd/files/mklivecd.8

.\" $NetBSD: mklivecd.8,v 1.17 2007/07/03 15:45:06 xtraeme Exp $
.\"
.\" mklivecd - Make your own NetBSD/x86 Live CD-ROM/DVD-ROM
.\"
.\" Copyright (c) 2004-2007 Juan Romero Pardines.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Juan Romero Pardines.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 3, 2007
.Dt MKLIVECD 8
.Os
.Sh NAME
.Nm mklivecd
.Nd Make your own
.Nx
/ x86 Live CD-ROM/DVD-ROM
.Sh SYNOPSIS
.Nm
.Fl v
.Fl c Ar conf_file
.Fl k Ar kernel
.Ar target
.Sh DESCRIPTION
.Nm
allows you to build your own
.Nx
Live CD/DVD, so you don't need to install
.Nx
to any disk, because it will run directly from the CD-ROM/DVD-ROM.
.Pp
To choose different kernels when booting from the CD-ROM/DVD-ROM,
two options for the bootloader are provided since version
.Pa 0.12.0 :
.Pa the GNU Grub bootloader
or the
.Nx
ISO9660 bootloader (since
.Nx 4.0 ) .
By default on i386 will use the first option:
.Pa the GNU Grub bootloader ,
and the NetBSD ISO9660 booloader on amd64. You may want to
change this by changing the option
.Pa USE_GNU_GRUB
to
.Sy no .
.Pp
The following options are recognized:
.Bl -tag -width XcXconf_file
.It Fl c Ar conf_file
Use
.Ar conf_file
as configuration file (full name expected).
Example:
.Fl c Ar foo.conf .
.El
.Bl -tag -width XkXkernel
.It Fl k Ar kernel
Overrides the
.Ar KERNEL_CONFIG
value specified in the configuration file,
.Ar KERNEL_NAME
will be modified automatically too.
.El
.Bl -tag -width XvX
.It Fl v
Show more useful messages.
.El
.Sh CONFIGURATION
.Nm
reads the parameters of the main configuration file
stored inside
.Pa $HOME/.mklivecd/mklivecd.conf ,
so be sure you have modified it with your
preferences before starting any target.
.Pp
Configuration files are simple shell scripts that define
variables.
The default values shown here are those written in the template when
issuing the
.Ar config
target.
.Bl -tag -width 15n -offset indent
.It BASEDIR
Primary directory used to store the main directories and the final ISO image.
Defaults to
.Pa $HOME/livecd .
.It FETCH_SETS
If it's set to yes, it will download the sets in the target
.Pa fetch ,
from the URL specified in
.Pa REMOTE_SETS_URL .
.It REMOTE_SETS_URL
This is the URL containing the base/x11 sets for the
.Pa fetch
target and if
.Pa FETCH_SETS
is set to yes.
.It BASE_SETS_DIR
The base sets directory.
Defaults to
.Pa $HOME/release/binary/sets .
.It BASE_SETS
Base sets which will be unpacked into
.Pa $ISODIR .
Sets used by default are:
.Pa etc.tgz base.tgz comp.tgz text.tgz .
.It CHROOT_SHELL
Default shell to use with the chroot target.
Defaults to
.Sy /bin/ksh .
.It ISODIR
Directory used to store the main
.Nx
base distribution.
Defaults to
.Pa $BASEDIR/iso .
.It PKGSRCDIR
The
.Nx
pkgsrc collection directory.
When the
.Ar chroot
target is invoked, the pkgsrc directory will be mounted via
.Xr mount_null 8 ,
and you could install any package.
Defaults to
.Pa /usr/pkgsrc .
.It PKGSRCDISTDIR
The
.Nx
distfiles pkgsrc directory.
When the
.Ar chroot
target is invoked, the distfiles directory will be mounted via
.Xr mount_null 8 .
Defaults to
.Pa /usr/pkgsrc/distfiles .
.It PACKAGESDIR
The
.Nx
packages pkgsrc directory.
When the
.Ar chroot
target is invoked, the packages directory will be mounted via
.Xr mount_null 8 .
Defaults to
.Pa /usr/pkgsrc/packages .
.It SHAREDIR
The main directory used to store the Makefiles, kernel, example configuration
files, etc.
Defaults to
.Pa @PREFIX@/share/mklivecd/ .
.It SOURCEDIR
The
.Nx
source directory.
Defaults to
.Pa /usr/src .
.It WORKDIR
Directory used to store the object files and kernel built by the target
.Ql kernel .
Defaults to
.Pa $BASEDIR/work .
.It X11_SETS
X11 sets which will be unpacked into
.Pa $ISODIR .
Sets used by default are:
.Pa xbase.tgz xcomp.tgz xfont.tgz xserver.tgz .
.It X11_SETS_DIR
The X11 sets directory.
Defaults to
.Pa $BASE_SETS_DIR .
.It KERNEL_CONFIG
Name of the
.Nx
configuration kernel (e.g. GENERIC) used for the boot image.
Defaults to
.Sy KERN-LIVECD .
.It KERNEL_NAME
Name of the built
.Nx
kernel.
Useful if you want to change the default behaviour of the build process.
Defaults to
.Sy MKLIVECD .
.It MULTIPLE_KERNELS
If set to
.Sy other thing than ``no'' ,
it will compile and install the kernels specified into
.Pa $ISODIR/boot/grub ,
and it will update automatically the
.Pa menu.lst
file for
.Pa the GNU Grub bootloader .
See below for details.
.It BLANK_BEFORE_BURN
Used in the
.Ar burn
target to blank a CD-RW before burning the
.Nx
Live CD ISO image.
Useful if you use CD-RW.
Defaults to
.Sy no .
.It CDRECORD_ARGS
Arguments passed to
.Xr cdrecord 1
when burning the
.Nx
Live CD ISO image.
Defaults to
.Sy -v .
.It CDRECORD_BIN
Name of the cdrecord binary used by
.Nm
to burn the image.
Defaults to
.Sy @PREFIX@/bin/cdrecord .
.It CDROM_DEVICE
Used in the target
.Ar burn
to specify the CD-ROM device.
Defaults to
.Sy 15,1,0 .
.It ENABLE_X11
If set to
.Sy yes
then X11 sets and configuration files will be unpacked automatically.
Defaults to
.Sy no .
.It GRUB_FILES_DIR
Directory where the grub files are stored. 
Defaults to
.Sy @LOCALBASE@/lib/grub/@MACHINE_ARCH@-/ .
.It HOSTNAME
Hostname of the live CD-ROM/DVD-ROM, it's assigned when running the
.Sy base
target.
Defaults to
.Sy MKLIVECD_0x00 .
.It IMAGE_NAME
Name of the final ISO image, e.g.:
.Pa My_NetBSD_Live_CD_ISO_Image.iso .
Defaults to
.Sy NetBSD-LiveCD .
.It MKISOFS_ARGS
Arguments passed to
.Xr mkisofs 1
when creating the
.Nx
ISO image.
Defaults to
.Sy -J -R -v .
.It MKISOFS_BIN
Name of the mkisofs binary used by
.Nm
to build the image.
Defaults to
.Sy @PREFIX@/bin/mkisofs .
.It PERSONAL_CONFIG
If set to
.Sy yes ,
then
.Pa personal_config
file will be used.
See below for details.
Defaults to
.Sy no .
.It PKG_SYSCONFDIR
Directory where the pkgsrc settings are stored, by default
.Nm
preserves this behaviour and uses
.Pa usr/pkg/etc .
.It REMOVE_DIRS
Take care with this option, because it will remove all directories when
the target
.Ar 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
.Pa altroot rescue usr/share/info .
.It USE_GNU_GRUB
Used to select the bootloader for the Live CD.
When it's disabled the
.Nx
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
.Sy yes .
.It VND_COMPRESSION
Enable this to mount
.Pa /usr ,
and
.Pa /var/db/pkg
via
.Xr vnconfig 8
with compression enabled.
Note you'll need to have
.Sy options VND_COMPRESSION
in your kernel config, at the moment
this option is only available on
.Nx 4.0
and later.
Defaults to
.Sy no .
.It MNT_RAMFS_ARGS
This specifies the arguments passed to the
.Xr mount 8
command used in the
.Pa livecd
script, when the
.Nx
Live CD is booted.
By default it will contain
.Sy -s 128m swap
to be used by
.Xr mount_mfs 8 .
If you want to use
.Xr mount_tmpfs 8
change it just to
.Sy tmpfs .
.It MNT_RAMFS_CMD
This specifies the
.Xr mount 8
command used by
.Nm
in the boot configuration stage.
Defaults to
.Pa mount_mfs .
Can be changed to
.Pa mount_tmpfs
too.
.El
.Sh TARGETS
A target specifies what
.Nm
should do (as in make).
The following list describes all supported targets,
in the logical order in which you should call them.
.Bl -tag -width 15n -offset indent
.It Ar config
Create a sample
.Pa mklivecd.conf
file.
You should edit it after the creation as you will probably want to
change the default configuration, especially paths.
.It Ar kernel
Builds the specified kernel
.Pa $KERNEL_CONFIG
into the
.Pa $ISODIR
directory.
.It Ar fetch
Downloads the sets defined in
.Pa $BASE_SETS
from
.Pa $REMOTE_SETS_URL
and if
.Pa $FETCH_SETS
is enabled.
.It Ar base
Install the
.Pa $BASE_SETS
and
.Pa $X11_SETS
into the
.Pa $ISODIR
directory and prepare the base system for the next target,
which is the most important:
.Ar chroot .
.It Ar chroot
Enters the chroot environment.
Uses
.Xr ksh 1
as default shell.
.It Ar iso
Builds the ISO image
.Pa $IMAGE_NAME
into
.Pa $BASEDIR
and removes all directories specified in
.Pa $REMOVE_DIRS
before it, to save some space.
.It Ar burn
Burns the ISO image
.Pa $IMAGE_NAME
on the CD-ROM with
.Xr cdrecord 1 .
Use the
.Pa $CDROM_DEVICE
variable to specify the default device.
.It Ar clean
Cleans the
.Pa $WORKDIR
directory and the base
.Nx
tree in
.Pa $ISODIR ,
except the mfs directories located in
.Pa /stand
and the
.Nx
kernels.
.El
.Ss What should I do in the chroot jail?
While working in the chroot environment, you can
add users, install binary packages, modify
.Pa /etc/ttys ,
etc.
You can enter the chroot as often as you want,
.Nm
will create the tarballs automatically when you leave
the chroot.
.Ss How can I use the PERSONAL_CONFIG option?
When
.Ar PERSONAL_CONFIG
is set to
.Sy yes ,
.Pa $HOME/.mklivecd/personal_config
will be used.
For example, you can copy some configuration directories
from
.Ar $HOME
to the
.Ar $ISODIR/$HOME
directory.
Please take a look at the example file located in
.Ar @PREFIX@/share/mklivecd .
.Ss How to use the MULTIPLE_KERNELS option?
An example is provided below, we have two kernels:
.Ar ACPIKERN
and
.Ar APMKERN ,
both are kernel configuration files, you'll need
to define the variables named
.Ar KERNEL_CONFIG_${foo}
and
.Ar KERNEL_NAME_${foo}
for every kernel specified on the
.Pa MULTIPLE_KERNELS
option.
The following example shows that:
.Bd -literal -offset indent
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"
.Ed
.Pp
Note that when using this option, the
.Pa KERNEL_CONFIG
and
.Pa KERNEL_NAME
variables, will don't have any effect.
After building the specified kernels, it will update the
.Pa menu.lst
file automatically for the
.Ar GNU Grub bootloader .
.Sh NOTES
.Pa PKG_SYSCONFDIR
defaults to
.Ar usr/pkg/etc
without a starting slash.
This shouldn't be added because
.Nm
adds this automatically in the script, otherwise your real PKG_SYSCONFDIR
directory will be copied instead of the one located in
.Pa $ISODIR .
.Pp
By default there's no default kernel, so you should copy
your own kernel (or kernels if MULTIPLE_KERNELS is set) config
file into
.Ar $HOME/.mklivecd .
The
.Sy KERNEL_CONFIG
variable should point at it, if you're not using
.Sy MULTIPLE_KERNELS .
The important thing about the kernel is the line:
.Bd -literal -offset indent
config netbsd root on cd0a type cd9660 dumps on none
.Ed
.Pp
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.
.Sh EXAMPLES
Below are the minimal steps to create your own Live CD-ROM/DVD-ROM:
.Bd -literal -offset indent
$ 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
.Ed
.Sh SEE ALSO
.Xr packages 7 ,
.Xr mount_mfs 8 ,
.Xr mount_null 8 ,
.Xr mount_tmpfs 8
.Sh AUTHORS
The
.Nm
utility was written by
.An Juan Romero Pardines Aq xtraeme@NetBSD.org .
.Sh BUGS
It is not perfect but at least it does its task correctly.
.Sh SUPPORT
Many Live CDs are built with this software, and sometimes
.Nm
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.