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

.SH NAME

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

.SH SYNOPSIS

.B dphys3preseed
\fB-dgr\fP [\fB-qvD\fP]
.PP
.B dphys3preseed
\fB-u\fP [\fB-b\fP \fIbaseaddress\fP] [\fB-qvD\fP]
.PP
.B dphys3preseed
\fB-h\fP

.SH DESCRIPTION

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

.SH OPTIONS

.TP
.B \-d
download: Download original Debian or dphys3 custom kernel floppy images from
an Debian distribution server or mirror or own install server
.TP
.B \-g
generate: Generate dphys3 floppy images including drivers subset and automatic
configuration
.TP
.B \-u
upload: Upload generated dphys3 floppy images to local install server. These
are then needed for \fBdphys3boot\fP, \fBdphys3root\fP, \fBdphys3cd\fP and
\fBdphys3pxe\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 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.
Assignments relevant for dphys3preseed are:
.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
.TP
.B CONF_KERNEL_OWN
Filename used by \fBdphys3kernel\fP to compile the custom kernel. Here it just
indicates to use the resulting custom kernels floppy images instead of Debians
ones. Defaults to empty (= use original Debian kernel images).
.TP
.B CONF_INST_SERVER
The server to connect to, to upload the generated floppy images to. 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 download from and upload own floppy images to.
Defaults to \fIcustom\fP. Can be left if you only have one configuration, else
needs to be set different for each.
.TP
.B CONF_OWNSERVER
Base URL to download dphys3 custom kernel floppy images from. Defaults also
to error message generating
\fIhttp://not-configured-server/not/configured/directory\fP.
Your admin must set this.
.TP
.B CONF_CONF_MODULESNET
Select what network drive modules 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. Defaults to empty, as we do not know your hardware. Must be set unless
using compiled in or default ones.
.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
\fIi386/qwerty/us\fP. Change if you use an non-US keyboard layout.
.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_END1STAGE
Run this script at end of the first phase of installing, chrooted to the target
system, just before the reboot. To do so set this to the filename of the
script. Defaults to nothing.
.TP
.B CONF_END2STAGE
Run this script at end of the second phase of installing, just before the user
gets the login prompt. To do so set this to the filename of the script.
Defaults to nothing. 2 example scripts are provided: an simple standalone
\fIend2stage.simple\fP, and an complex one \fIend2stage.dphys-admin\fP which
uses the \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

.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 or \fI./dphys3\fP:
.PP
.nf
  CONF_USER=user-foo
.fi
.PP
The following then allows the user to specify using an custom kernel and
where on the server the boot image and drivers archive for this are:
.PP
In \fI./dphys3\fP:
.PP
.nf
  CONF_KERNEL_OWN=anything-here-for-custom
  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/