.\" /usr/share/man/man1/dphys3preseed.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 DPHYS3PRESEED 1 "2006.11.16" "dphys3 Installation Tools"

.SH NAME

dphys3preseed \- generate, upload and automatic install disks with preseeding

.SH SYNOPSIS

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

.SH DESCRIPTION

dphys3preseed downloads, generates, uploads, and removes automatic installer
based root floppy images including driver subsets.

.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, or download
dphys3kernel boot and root floppy images from an own images server. There
is never an dphys3kernel drivers archive file, as none is produced
.TP
.B \-g
generate: Generate dphys3 boot and root floppy images, including drivers subset
and automatic configuration and preseeding
.TP
.B \-u
upload: Upload generated and preseeded dphys3 boot and root floppy images to
local install server. These are then needed for \fIdphys3boot\fP(1),
\fIdphys3root\fP(1), \fIdphys3cd\fP(1) and \fIdphys3pxe\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) 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
config: use this config file. Defaults to last file fitting \fIconfig*\fP or
\fI.config*\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 dphys3preseed (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 dphys3preseed 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) are to be found. Defaults to \fI./\fP
(current directory). Option \fB-s\fP override this. \fB-k\fP and \fB-c\fP
override this partially. These are only used to see if \fBdphys3kernel\fP will
have made own images, and that therefore those are to be used, instead of the
Debian ones.
.TP
.B CONF_UPLOAD_SERVER
The install server to connect to, to upload the generated boot and root floppy
images to, so that \fBdphys3boot\fP, \fBdphys3root\fP, \fBdphys3cd\fP and
\fBdphys3pxe\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}. Also where to download floppy
images from. Defaults to \fIdphys3-custom\fP. Can be left if you only have one
configuration, else needs to be set different for each one.
.TP
.B CONF_OWNSERVER
Base URL from which all dphys3kernel generated images can be downloaded.
Defaults also to error message generating
\fIhttp://not-configured-server/not/configured/directory\fP.
Your admin must set this.
.TP
.B CONF_MODULESNET
Select what network drive modules from Debian drivers archive are to be
included in the drivers subset on the root floppy image. Failling to install
the ones you need will leave you unable to install, unless you have compiled
your network drivers into an custom kernel. Is not allowed to be set, if you
are using an dphys3kernel generated floppy image set, as no drivers archive is
generated. Defaults to empty, as we do not know your hardware.
.TP
.B CONF_SILENCE_DEBCONF
Sets \fIdebconf\fP(7) to ask as few questions as possible. Priority is set to
\fIcritical\fP and frontend to \fInoninteractive\fP. Defaults to \fByes\fP, as
most people will want this.
.TP
.B CONF_KEYBD
Which keyboard layout to use. This is a file path relative to
\fB/usr/share/keymaps/\fP, without the \fB.kmap.gz\fP name ending. Defaults to
\fIus\fP. Change if you use an non-US keyboard layout.
.TP
.B CONF_IF
Set which network interface to use. Defaults to \fIauto\fP, as most people use
that. Can be set to \fIeth0\fP or \fIeth1\fP or similar.
.TP
.B CONF_SWAP_SIZE
Make an swap partition of this size in MBytes. Setting this to 0 will disable
making an swap partition, as it is wanted for using an swapfile, such as with
the \fBdphys-swapfile\fP package. We prefer swapfiles. Defaults to \fI0\fP.
.TP
.B CONF_TIMEZONE_AREA, CONF_TIMEZONE_PLACE
Set what time zone you are in. These are parts of an file path relative to
\fB/usr/share/zoneinfo/\fP. These default to error message producing
\fInot-configured-area\fP and \fInot-configured-place\fP.
.TP
.B CONF_PASSWORD_ROOT
Set the root accounts password. Defaults also to empty, as we really do not
know your passwords :-).
.TP
.B CONF_USE_CONTRIB, CONF_USE_NON_FREE, CONF_USE_SECURITY
Allow usage of these extra non-main packages and updates. Most people want
these. Defaults to \fByes\fP.
.TP
.B CONF_END0STAGE
Run this script at end of the "zeroth" stage of installing, that is while
generating the root floppy image, with / being the install system (the target
system not existing yet), just before finalising the floppy image. To do so
set this to the filename of the script to be run at generate time. An example
script is provided: \fIend0stage.dphys\fP which disables (re-)partitioning
and (re-)formatting, and instead just deletes the old system, retaining data
directories /scratch and /export.
.TP
.B CONF_END1STAGE
Run this script at end of the first stage of installing, just before the
reboot, with / being the install system and /target the final system. To do so,
set this to the filename of the script to be included at image generation time.
If an URL such as http://* or ftp://* is given, the script will be fetched at
host install time. Defaults to nothing. An example script is provided:
\fIend1stage.dphys\fP which installs our custom kernels, replacing Debians. It
shows the recommended technique to run an end1stage script chrooted with / set
to /target.
.TP
.B CONF_END2STAGE
Run this script at end of the second stage of installing, just before the user
gets the login prompt. To do so, set this to the filename of the script to be
included at image generation time. If an URL such as http://* or ftp://* is
given, the script will be fetched at host install time. Defaults to nothing. 2
example scripts are provided: an simple standalone \fIend2stage.simple\fP, and
an complex one \fIend2stage.dphys\fP which uses the
\fIhttp://www.phys.ethz.ch/~franklin/Projects/dphys-config/\fP configuration
manager and \fIhttp://www.phys.ethz.ch/~franklin/Projects/dphys-admin/\fP
package manager.

.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
and
.TP
.B ${CONF_SOURCEDIR}/config*
or
.B ${CONF_SOURCEDIR}/.config*
Linux source code archive and base kernel config to be used by dphys3kernel.
Both of these files are only used by dphys3preseed as flag files, to tell it
that dphys3kernel has been used to make own floppy images, and so to fetch the
resulting images instead of the original Debian ones.

.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_UPLOAD_SERVER=upload@debian.ethz.ch:/pub/debian-local
  CONF_OWNSERVER=http://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 or \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 boot and
root images are to be found, and where on the server the produced boot and root
images are to be placed:
.PP
In \fI./dphys3\fP:
.PP
.nf
  CONF_OWN_KERNEL=yes
  CONF_DISKSVERSION=user-foo
.fi
.PP
The following then allows the user to specify what installation to do for an
example machine:
.PP
In \fI./dphys3\fP:
.PP
.nf
  CONF_KEYBD=sg-latin1
  # for directories containing drivers: just directory name without .o
  CONF_MODULESNET="forcedeth.o wireless"
  CONF_TIMEZONE_AREA=Europe
  CONF_TIMEZONE_PLACE=Zurich
  # of course we do not use this :-)
  CONF_PASSWORD_ROOT=secret
.fi
.PP
The user now can generate and upload floppy images and tidy up with:
.PP
\fIdphys3preseed \-dgur\fP
.PP
After this continue with \fIdphys3boot\fP and \fIdphys3root\fP (for floppies),
with \fIdphys3\fP (for CD) or with \fIdphys3\fP (for PXE/TFTP netboot).

.SH SEE ALSO

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

.SH AUTHOR

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