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

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

.SH NAME

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

.SH SYNOPSIS

.B dphys3kernel
\fB-dgr\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.
.PP
\fBWARNING: making custom kernel images not yet supported in this version of
dphys3\fP

.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 \-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
\fIdphys3\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.
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_KERNEL_OWN
Filename of kernel .tar.gz or .tar.bz2 archive to be unpacked to compile the
custom kernel. Defaults to empty (= use original binary Debian kernel). In that
case you do not need to use \fBdphys3kernel\fP at all. So this needs to be set
if you want an own kernel
.TP
.B CONF_KERNEL_CONFIG
Filename of config file for kernel compilation. Defaults to empty (= use the
fitting original Debian config from their kernel). Needs to be set if your
want an own config (not using Debians config)
.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

.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_KERNEL_OWN=linux-2.4.26.tar.bz2
  CONF_KERNEL_CONFIG=config-2.4.26.user-foo
  CONF_DISKSVERSION=user-foo
.fi
.PP
Note that this custom kernel must fullfill a few requirements:
.RS
.PP
- \fBNOT ALLOWED\fP to have devfs (CONFIG_DEVFS_FS), as old style /dev/* names
are used and needed
.PP
- \fImust have\fP 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
- \fImust have\fP loopback devide (CONFIG_BLK_DEV_LOOP), for extracting kernel
from boot image
.PP
- \fImust have\fP RAM disk device (CONFIG_BLK_DEV_RAM), for root filesystem
while install
.PP
- \fImust have\fP initrd support (CONFIG_BLK_DEV_INITRD), for loading root
filesystem (only needed if you are going to make an boot CD)
.PP
- \fImust have\fP FAT filesystem (CONFIG_FAT_FS + CONFIG_MSDOS_FS), for
extracting kernel from boot 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 \fIdphys3kernel\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/