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

.TH DPHYS2ROOT 1 "2004.10.14" "dphys2 Installation Tools"

.SH NAME

dphys2root \- generate, upload and automatic install root disks

.SH SYNOPSIS

.B dphys2root
\fB-dfir\fP [\fB-D\fP]
.PP
.B dphys2root
\fB-g\fP [\fB-w\fP \fIworkdir\fP] [\fB-D\fP]
.PP
.B dphys2root
\fB-u\fP [\fB-b\fP \fIbaseaddress\fP] [\fB-D\fP]
.PP
.B dphys2root
\fB-h\fP

.SH DESCRIPTION

dphys2root downloads, generates, uploads, fetches, installs and removes
automatic installer root floppy images including drivers subsets.

.SH OPTIONS

.TP
.B \-d
download: Download original Debian or dphys2 root image and drivers archive
files from an Debian distribution server or mirror or own install server
.TP
.B \-g
generate: Generate dphys2 root image including drivers subset
.TP
.BI \-w \ workdir
workdir: Select work directory for doing all compiling and image generating.
Defaults to \fI./.dphys2root\fP
.TP
.B \-n
nodelete: Do not delete work directory after generating. Usefull for debugging
.TP
.B \-u
upload: Upload generated dphys2 root image file to local
install server. This is then needed for the \fB-f\fP option fetching and for
\fBdphys2cd\fP/\fBdphys2pxe\fP downloading.
.TP
.BI \-b \ baseaddr
base: Install files are found relative to this base directory. Overrides the
CONF_INST_BASE config variable
.TP
.TP
.B \-f
fetch: fetch dphys2 root image from local install server. This is usefull if
installing to floppy (needs floppy drive) on an different system than
generating (needs CPU power for compiling) was done on, or for installing on
an second set of floppys later without new generate
.TP
.B \-i
install: install dphys2 (or if none the original Debian) root image onto
an floppy
.TP
.B \-r
remove: Delete Debian and dphys2 files, after installing
.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 \fB-f\fP \fB-i\fP \fB-r\fP or
\fB-i\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/dphys2\fP (normal style), \fI/etc/default/dphys2\fP
(Debian style), \fI~/.dphys2\fP (personal) and \fI./dphys2\fP (particular
project) allow the admin and users to set up the working environment for
dphys2root (and all other dphys2 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 dphys2root 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_24
Whether we are generating an 2.2 (no) or 2.4 (yes) style kernel. Defaults to
\fIno\fP. Needs to be set if you are using any form of 2.4 based stuff, leave
it for 2.2 based
.TP
.B CONF_KERNEL_OWN
Filename used by \fBdphys2rescue\fP to compile the custom kernel. Here it just
indicates to use the custom kernels rescue floppy image and drivers archive
instead of Debians ones. Defaults to empty (= use original Debian kernels).
.TP
.B CONF_INST_SERVER
The server to connect to, to upload the generated root floppy image
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_OWNSERVER
Base URL to download dphys2 rescue floppy image and drivers archive from and
fetch the uploaded root floppy image from (by \fB-f\fP option). Defaults also
to error message generating
\fIhttp://not-configured-server/not/configured/directory\fP.
Your admin must set this.
.TP
.B CONF_DISKSVERSION
Subdirectory on server where to upload and download or fetch root floppy image.
Defaults to \fIcustom\fP. Can be left if you only have one
configuration, else needs to be set different for each.
.TP
.B CONF_ENDFIRSTRUN
Run this program (usually an script) at end of first phase of installing, just
before the reboot. Typical usage is to add one or multiple more scripts to the
base-config process, which runs at the end of the second install phase, just
before the login appears. To do so set this to the filename of the program.
Defaults to nothing. 2 example scripts are provided: an simple standallone
\fIendfirstrun.simple\fP, and an complex one \fIendfirstrun.dphys-admin\fP
which uses the \fIhttp://www.phys.ethz.ch/~franklin/Projects/dphys-admin/\fP
package manager.
.TP
.B CONF_INST_FLOPPY
Drive where to install root floppy image onto. Defaults to \fI/dev/fd0\fP.
.PP
In addition to those above options \fBdphys2root\fP also copies the merged
config files onto the root floppy image it is generating, so that the install
process can be configured by them.
.PP
So these muss include all the settings that replace all the user input while
using the official Debian install program. These are the central reason for
using the entire \fIdphys2\fP installer. Assignments relevant for installation
are:
.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_DISK
Set which drive to install onto. If left unset use auto-selection
(\fB/dev/hda\fP if existant, else \fB/dev/sda\fP). Defaults to empty, as that
is usually what you want.
.TP
.B CONF_DISK_IDEDMA
Forcedly set IDE disk into DMA mode. Speeds up install on systems with broken
IDE drives that fail to remember their DMA settings. Defaults to \fIno\fP, as
setting this can crash some systems.
.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. Defaults to \fI0\fP.
.TP
.B CONF_CONF_MODULESNET
Select what network drive modules are to be included in the drivers archive
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.
.TP
.B CONF_IF
Set which network interface to use. Defaults to \fIeth0\fP, as most people use
that.
.TP
.B CONF_DHCP
Use DHCP to get network configuration. Defaults to \fIyes\fP, as most sites
have this these days.
.TP
.B CONF_DOMAIN, CONF_NAMESERVER1, CONF_NAMESERVER2, CONF_NAMESERVER3, CONF_NAMESERVER4, CONF_NETMASK, CONF_NETWORK, CONF_GATEWAY, CONF_BROADCAST
Set the obvious networking stuff. Only used if no DHCP. Default to error
message generating \fInot-configured-*\fP, as you must set these to your
specific network. If you have multiple networks you will have to generate an
different root image for each one. These can share the same rescue floppy
image (inclusive same \fBCONF_DISKSVERSION\fP upload, unless you also upload
the multiple root floppy images, which would then collide).
.TP
.B CONF_PASSWORD_LILO
Set an LILO password to prevent users easily subverting boot process. Defaults
to empty, as we do not know your password :-). \fIBecause of this and
\fBCONF_PASSWORD_ROOT\fP your config files should be chmod 600.\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_MD5
Set the use of MD5 style passwords instead of Crypt stayle ones. Defaults to
\fByes\fP, as nearly everyone uses these.
.TP
.B CONF_PASSWORD_SHADOW
Set the use of \fB/etc/shadow\fP password file instead of passwords in
\fB/etc/passwd\fP. Defaults to \fByes\fP, as nearly everyone uses this.
.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_PCMCIA_REMOVE
Remove the PCMCIA support which is not needed on most peoples desktop system.
Defaults to \fByes\fP. Change if you have an laptop system with PCMCIA.
.TP
.B CONF_USE_CONTRIB, CONF_USE_NON_FREE
Allow usage of these extra non-main packages. Most people want these. Defaults
to \fByes\fP.
.TP
.B CONF_USE_PROPOSED
In addition to the standard woody packages also use the woody-proposed-updates
ones. Defaults to \fByes\fP.
.TP
.B CONF_DEBSERVER_NON_US
Allow use of non-US packages. For this you must give the server name where
to fetch them from. Defaults to \fIhttp://non-us.debian.org/debian-non-US\fP.
.TP
.B CONF_DEBSERVER_SECURITY
Make use of the security updates. For this you must give the server name where
to fetch them from. Defaults to \fIhttp://security.debian.org/\fP.
.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.

.SH FILES

.TP
.B /etc/dphys2
normal style site config
.TP
.B /etc/default/dphys2
Debian style site config
.TP
.B ~/.dphys2
users personal config
.TP
.B ./dphys2
individual projects config

.SH EXAMPLES

The following allows the sysadmin to tell all users how to get Debian stuff:
.PP
In \fI/etc/dphys2\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 installer will then fetch it:
.PP
In \fI/etc/dphys2\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~/.dphys2\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 rescue image and drivers archive for this are:
.PP
In \fI./dphys2\fP:
.PP
.nf
  CONF_KERNEL_24=yes
  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./dphys2\fP:
.PP
.nf
  CONF_KEYBD=i386/qwertz/sg-latin1
  CONF_DISK_IDEDMA=yes
  # tulip is a directory, containing incidently only one file tulip.o
  CONF_MODULESNET="3c59x.o eepro100.o 8139too.o tulip mii.o"
  CONF_PASSWORD_LILO=secret
  CONF_TIMEZONE_AREA=Europe
  CONF_TIMEZONE_PLACE=Zurich
  CONF_PASSWORD_ROOT=${CONF_PASSWORD_LILO}
  CONF_DEBSERVER_NON_US=${CONF_DEBSERVER}-non-US
  CONF_DEBSERVER_SECURITY=${CONF_DEBSERVER}-security
.fi
.PP
The user now can generate and install on floppy and delete an root image with:
.PP
\fIdphys2root \-dgir\fP
.PP
Or in 2 steps: first generate and upload an root image with:
.PP
\fIdphys2root \-dgu\fP
.PP
And second install it onto an floppy and delete it with:
.PP
\fIdphys2root \-ir\fP
And later fetch the deleted root image to re-install it onto an floppy with:
.PP
\fIdphys2root \-fi\fP

.SH SEE ALSO

\fIdphys2\fP(7), \fIdphys2rescue\fP(1), \fIdphys2cd\fP(1), \fIdphys2pxe\fP(1)

.SH AUTHOR

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