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

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

.SH NAME

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

.SH SYNOPSIS

.B dphys3kernel
\fB-dr\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-b\fP \fIbaseaddress\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 OPTIONS

.TP
.B \-d
download: Download original Debian boot image and drivers archive
files from an Debian distribution server or mirror
.TP
.B \-g
generate: Generate dphys3 boot image and drivers archive, compiling an
custom kernel and its modules for including in them
.TP
.B \-s
sourcedir: Find all input files (kernel/config/patch) to use in this
directory.
.TP
.BI \-k \ kernel-archive
kernel: use this kernel archive. Defaults to last \fIlinux-*.tar.[bz2|gz]\fP
.TP
.BI \-c \ config-file
config: use this config file. Defaults to last \fIconfig*\fP
.TP
.BI \-p \ libdiscover-patch-file
patch: use this libdiscover patch file. Defaults to last \fI*.diff\fP
.TP
.B \-u
upload: Upload generated dphys3 floppy images to local install server. These
are then needed for \fBdphys3preseed\fP downloading
.TP
.BI \-b \ baseaddr
base: Install files are found relative to this base directory. Overrides the
CONF_INST_BASE config variable
.TP
.B \-r
remove: Delete Debian and dphys3 files, after installing
.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
.PP
If multiple of \fB-d\fP \fB-g\fP \fB-u\fP or \fB-r\fP are used, they are
processed in the order they appear here in the man page section, not the order
they are typed on the command line. Other options modify behaviour.

.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 stuff 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_INST_SERVER
The server to connect to, to upload the generated boot floppy image and
drivers archive to, so that \fBdphys3preseed\fP can download them. Defaults to
error message generating invalid \fInot-configured-server\fP, as there is no
sensible default possible. Your admin must set this.
.TP
.B CONF_USER
The user to login as on above server. Defaults also to error message generating
\fInot-configured-user\fP. Each user must set this.
.TP
.B CONF_GROUP
Make all uploaded files and directories 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 the admin will set
this.
.TP
.B CONF_INST_BASE
Base directory on above server for all uploads to go into. Overridable with
\fB-b\fP (base). This should match the DocumentRoot of the HTTP VirtualHost.
Defauls also to error message generating \fI/not/configured/directory\fP.
Your admin must set this.
.TP
.B CONF_DISKSVERSION
Subdirectory on server where to upload floppy images. Defaults to \fIcustom\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
and
.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*
Base configuration 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
Libdiscover patch file 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, and how the installers will then download it:
.PP
In \fI/etc/dphys3\fP:
.PP
.nf
  CONF_INST_SERVER=pomfrey.ethz.ch
  CONF_USER=luser-failled-to-set-username
  CONF_GROUP=isg
  CONF_INST_BASE=/pub/debian-local
  CONF_OWNSERVER=http://debian.ethz.ch/pub/debian-local
.fi
.PP
Note that CONF_USER has been set to make user ommission highly visible in ssh
login faillure logs. And CONF_INST_BASE should be the DocumentRoot of the HTTP
VirtualHost which will be offering your install files.
.PP
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_USER=user-foo
.fi
.PP
The following then allows the user to make an custom 2.4.26 kernel and specify
where on the server the boot image and drivers archive for this will appear:
.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 (PCMCIA, ACPI, parport, MD,
USB, Firewire, I2O, IRDA, ISDN, extended serial, I2C, video, sound, qouta,
exotic filesystems), to make the kernel small as possible, to fit onto an boot
floppy image
.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/