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

.TH DPHYS2RESCUE 1 "2004.10.08" "dphys2 Installation Tools"

.SH NAME

dphys2rescue \- generate, upload and install custom kernel rescue disks

.SH SYNOPSIS

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

.SH DESCRIPTION

dphys2rescue downloads, generates, uploads, fetches, installs and removes
custom kernel based rescue floppy images and drivers archives.

.SH OPTIONS

.TP
.B \-d
download: Download original Debian rescue image and drivers archive
files from an Debian distribution server or mirror
.TP
.B \-g
generate: Generate dphys2 rescue image and drivers archive, compiling an
custom kernel and its modules for including in them
.TP
.BI \-w \ workdir
workdir: Select work directory for doing all compiling and image generating.
Defaults to \fI./.dphys2rescue\fP
.TP
.B \-u
upload: Upload generated dphys2 rescue image and drivers archive files to local
install server. These are then needed for the \fB-f\fP option fetching and for
\fBdphys2root\fP/\fBdphys2cd\fP/\fBdphys2pxe\fP downloading and for
\fBdbootstrap\fP while installing every machine
.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 rescue 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) rescue 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
dphys2rescue (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 dphys2rescue 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 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 \fBdphys2rescue\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 2.2.20 or 2.4.18 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 rescue floppy image and
drivers archive to, so that installing machines can fetch 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_OWNSERVER
Base URL to fetch the rescue floppy image and drivers archive from (by \fB-f\fP
option and by dbootstrap when installing each host). 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 fetch rescue floppy image and
drivers archive. Defaults to \fIcustom\fP. Can be left if you only have one
configuration, else needs to be set different for each.
.TP
.B CONF_INST_FLOPPY
Drive where to install rescue floppy image onto. Defaults to \fI/dev/fd0\fP

.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 make an custom 2.4.26 kernel and specify
where on the server the rescue image and drivers archive for this will appear:
.PP
In \fI./dphys2\fP:
.PP
.nf
  CONF_KERNEL_24=yes
  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 rescue 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 rescue image
.RE
.PP
The user now can generate and upload files with:
.PP
\fIdphys2rescue \-dgu\fP
.PP
And install rescue image onto an floppy and delete it with:
.PP
\fIdphys2rescue \-ir\fP
And later fetch the deleted rescue image to re-install it onto an floppy with:
.PP
\fIdphys2rescue \-fi\fP

.SH SEE ALSO

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

.SH AUTHOR

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