.\" /usr/share/man/man1/dphys3kernel.1(.gz)
.\" author Neil Franklin, last modification 2006.11.16
.\" copyright ETH Zuerich Physics Departement
.\"   use under either modified/non-advertising BSD or GPL license

.TH DPHYS3KERNEL 1 "2006.11.16" "dphys3 Installation Tools"

.SH NAME

dphys3kernel \- generate, upload and install disks with custom kernel

.SH SYNOPSIS

.B dphys3kernel
\fB-d\fP [\fB-qvD\fP]
.PP
.B dphys3kernel
\fB-g\fP [\fB-k\fP \fIkernel-archive\fP] [\fB-c\fP \fIconfig-file\fP]
[\fB-p\fP \fIlibdiscover-patch-file\fP] [\fB-qvD\fP]
.PP
.B dphys3kernel
\fB-u\fP [\fB-qvD\fP]
.PP
.B dphys3kernel
\fB-r\fP [\fB-qvD\fP]
.PP
.B dphys3kernel
\fB-h\fP

.SH DESCRIPTION

dphys3kernel downloads, generates, uploads, and removes custom kernel based
boot floppy images and drivers archives.

.SH COMMAND/FUNCTION/ACTION LETTERS

One or multiple of the following commands must be used, else dphys3kernel
defaults to doing nothing. If one or multiple of these are selected, only those
actions are taken, no other default action.
.PP
If multiple of these are used, they are always processed in the row they appear
here, not the row they are typed on the command line.
.TP
.B \-d
download: Download original Debian boot and root floppy images and drivers
archive file from an Debian distribution server or mirror
.TP
.B \-g
generate: Generate dphys3 boot and root floppy images, compiling an custom
kernel and its modules for including in them
.TP
.B \-u
upload: Upload generated dphys3 boot and root floppy images to local install
server. These are then needed for \fIdphys3preseed\fP(1) downloading
.TP
.B \-r
remove: Delete Debian and dphys3 files, use this after uploading

.SH OPTIONS

[only for -g generate]
.TP
.BI \-s \ source-dir
sourcedir: Find all input files (kernel/config/patch) to use in this
directory. Defaults to current directory
.TP
.BI \-k \ kernel-archive
kernel: use this kernel archive. Defaults to last file fitting
\fIlinux-*.tar.bz2\fP or \fIlinux-*.tar.gz\fP
.TP
.BI \-c \ config-file
config: use this config file. Defaults to last file fitting \fIconfig*\fP or
\fI.config*\fP
.TP
.BI \-p \ libdiscover-patch-file
patch: use this libdiscover patch file. Defaults to last file fitting
\fI*.diff\fP
.PP
[for all commands]
.TP
.B \-q
quiet: Don't produce an running report of activities
.TP
.B \-v
verbose: Give large volume output, where sensible
.TP
.B \-D
Debug: Activate an debug option. See source for how to use this.
.TP
.B \-h
help: Output help text, and then abort operation

.SH CONFIG

The config files \fI/etc/dphys3\fP (sitewide), \fI~/.dphys3\fP (personal) and
\fI./dphys3\fP (particular project) allow the admin and users to set up the
working environment for dphys3kernel (and all other dphys3 tools).
.PP
These config files are sh script fragments full of assignments, which are
sourced, in above row, later config files assignments overriding earlier ones.
Standard sh syntax rules apply. Assignments relevant for dphys3kernel are:
.TP
.B CONF_DEBSERVER
Base URL from which all Debian images can be downloaded. Defaults to
\fIhttp://ftp.debian.org/debian\fP. Needs to be set if you want to use an
mirror.
.TP
.B CONF_SOURCEDIR
Set where all input files (kernel/config/patch) are to be found. Defaults to
\fI./\fP (current directory). Option \fB-s\fP override this. \fB-k\fP, \fB-c\fP
and \fB-m\fP override this partially.
.TP
.B CONF_UPLOAD_SERVER
The install server to connect to, to upload the generated boot and root floppy
images to, so that \fBdphys3preseed\fP can download them. Must have the format
user@server:/directory for remote copying. The directory should match the
DocumentRoot of the HTTP VirtualHost. Defaults to error message generating
invalid \fInot-configured-user@server:/dir\fP, as there is no sensible default
possible. Your admin or each user must set this.
.TP
.B CONF_UPLOAD_GROUP
Make all uploaded files writable by any user in this group. For use so that all
members of this group can work on the install server (adding or replacing
files). Defaults to nothing, as this is usable for single user and no sensible
group value can be defaulted. Usually your admin will set this.
.TP
.B CONF_DISKSVERSION
Subdirectory on server where to upload floppy images. Path below
dists/sarge/local/main/installer-${SYS_ARCH}. Defaults to \fIdphys3-custom\fP.
Can be left if you only have one configuration, else needs to be set different
for each one.

.SH FILES

.TP
.B /etc/dphys3
site admin config
.TP
.B ~/.dphys3
users personal config
.TP
.B ./dphys3
individual projects config
.TP
.B ${CONF_SOURCEDIR}/linux-*.tar.bz2
or
.TP
.B ${CONF_SOURCEDIR}/linux-*.tar.gz
Linux source code archive to be used. If multiple fitting files are present,
the last one (ASCII sorted) will be used. Files with *.bz2 are tested before
*.gz, and so override these. These must contain an directory linux-* with all
the stuff in it.
.TP
.B ${CONF_SOURCEDIR}/config*
or
.B ${CONF_SOURCEDIR}/.config*
Base kernel config to be used, must be manually produced. Configure it for an
Pentium1 processor, no SMP, standard <1G memory size. Debian installer specific stuff is auto-added. If multiple fitting files are present, the last one
(filenames ASCII sorted) will be used.
.TP
.B ${CONF_SOURCEDIR}/*.diff
Patch file for libdiscover to be used, must be manually produced by diffing an
existing standard Debian and users extended /usr/share/discover/pci.lst file.

.SH EXAMPLES

The following allows the sysadmin to tell all users how to get Debian stuff:
.PP
In \fI/etc/dphys3\fP:
.PP
.nf
  CONF_DEBSERVER=http://debian.ethz.ch/mirror/debian
.fi
.PP
The following allows the sysadmin to tell how all users upload to the
install server:
.PP
In \fI/etc/dphys3\fP:
.PP
.nf
  CONF_UPLOAD_SERVER=upload@debian.ethz.ch:/pub/debian-local
.fi
.PP
Alternatively the following then allows an single user to use his specific
account for all of his uploads:
.PP
In \fI~/.dphys3\fP:
.PP
.nf
  CONF_UPLOAD_SERVER=franklin@pomfrey.ethz.ch:/pub/debian-local
  CONF_UPLOAD_GROUP=isg
.fi
.PP
The following then allows the user to specify where on the server the produced
boot and root images are to be placed:
.PP
In \fI./dphys3\fP:
.PP
.nf
  CONF_DISKSVERSION=user-foo
.fi
.PP
Note that this custom kernel will automatically have its config modified to:
.RS
.PP
- have RAM disk device (CONFIG_BLK_DEV_RAM), for root filesystem while install
.PP
- have initrd support (CONFIG_BLK_DEV_INITRD), for loading root filesystem, as
Debians installer wants this
.PP
- have floppy device (CONFIG_BLK_DEV_FD), for reading 2nd/root floppy (only
needed if you are going to make boot floppies, ignore for CD or PXE bootserver
install)
.PP
- have FAT filesystem (CONFIG_FAT_FS + CONFIG_MSDOS_FS), for extracting initrd
from boot image
.PP
- have loopback devide (CONFIG_BLK_DEV_LOOP), for mounting initrd
.PP
- have devfs (CONFIG_DEVFS_FS), as the Debian installer needs this
.PP
- have \fIauto-disabled\fP a whole lot of stuff not needed while installation
(such as CPU features, IPC, accounting, PCMCIA, ACPI, parport, PNP, MD, LVM,
packet filtering, phone stuff, non-disk IDE and SCSI, Firewire, I2O, tunneling,
IRDA, ISDN, mouse, joystick, serial, printer, I2C, AGP, DRM, video, qouta, most
filesystems, sound, USB, Bluetooth), to make the kernel and its module set as
small as possible, to fit onto the boot and root floppy images
.RE
.PP
The user now can generate and upload floppy images and tidy up with:
.PP
\fIdphys3kernel \-dgur\fP
.PP
After this continue with \fIdphys3preseed\fP.

.SH SEE ALSO

\fIdphys3\fP(7), \fIdphys3boot\fP(1), \fIdphys3cd\fP(1),
\fIdphys3preseed\fP(1), \fIdphys3pxe\fP(1), \fIdphys3root\fP(1)

.SH AUTHOR

franklin@phys.ethz.ch, http://www.phys.ethz.ch/~franklin/