.\" /usr/share/man/man8/dphys-admin.8(.gz)
.\" author Neil Franklin, last modification 2006.11.24
.\" copyright ETH Zuerich Physics Departement
.\"   use under either modified/non-advertising BSD or GPL license

.TH DPHYS-ADMIN 8 "2006.11.24" "D-PHYS Administration Tools"

.SH NAME

dphys-admin \- automatically install/update/remove packages on an Debian system

.SH SYNOPSIS

.B dphys-admin
[\fBinit\fP|\fBcron\fP|\fBnone\fP]

.SH DESCRIPTION

Part of the D-PHYS automatic system operation and maintenance.
.PP
dphys-admin installs new packages, updates existing ones, or removes obsolete
ones. Selection and install order are controlled by an package list file.

.SH OPTIONS

There is only one parameter, the mode, which can be either of these or missing:
.TP
.B init
Tells dphys-admin to run in init.d script mode. It is allowed to immediately
reboot, if the postinst script of any package it has just installed or updated
has generated an \fI/root/NEED-REBOOT\fP file.
.TP
.B cron
Tells dphys-admin to run in cron job mode. This disallows reboots and instead
just sends an mail to the sysadmin to shedule an reboot, which allows automatic
updates without disturbing working users. This also tells dphys-admin to
randomly delay execution by up to 1 hour, to spread the load of 100s of
updating machines on the packages server.
.TP
.B none
(or no parameter) Tells dphys-admin to run in no special mode. In this case
\fBcron\fP-style non-reboot behaviour will be executed, but without the delay.
This is intended for manual or test runs, where one does not want to wait,
which is why no parameter defaults to this mode.

.SH CONFIG

The config file \fI/etc/dphys-admin\fP allows the user to set up the
working environment for dphys-admin.
.PP
This config file is a perl (not sh!) script fragment full of assignments, which
are read in by the  require;  command. So they can contain any valid perl code.
.TP
.B $conf_listfile
Sets where the package list is expected to be. This defaults to
\fI/etc/dphys-admin.list\fP. You most likely want to leave this.
.TP
.B $conf_mailaddress
Sets where to mail error/warning/info/log messages to. This defaults to
\fIroot@localhost\fP. You may want to change this to separate out mails, or
even send maisl form all machines to an centrat mailbox. Setting this to ''
disables sending mails.
.PP
Note: You must use '' and not "" in conf_mailaddress, else perl will get
digestion problems with the @ in the email address.

.SH FILES

.TP
.B /etc/dphys-admin
config file
.TP
.B /etc/dphys-admin.list
package list file

.SH PACKAGE LIST

The package list is used for checking what packages need to be installed or
removed. Format of the list file consists of single lines of following types:
.RS
.TP
.B ? \fIblah blah ..\fP
write this text out to user (mnemonic: whats up?)
.TP
.B | \fIcmd param param ..\fP
execute this command by an shell (mnemonic: pipe)
.TP
.B - \fIpack1 pack2 ..\fP
delete this set of packages, if installed (mnemonic: subtract)
.TP
.B * \fIpack1 pack2 ..\fP
delete this set of packages, if installed, running apt-get with --purge
(mnemonic: splat, as in squashing an insect)
.TP
.B + \fIpack1 pack2 ..\fP
install this set of packages, if not installed (mnemonic: add)
.TP
.B ! \fIpack1 pack2 ..\fP
install this set of packages, even if already installed (mnemonic: yes
really!), this allows forcing early upgrade
.TP
.B < \fIinput pack1 pack2 ..\fP
install packages, if not installed, with  yes \fIinput\fP (mnemonic: stdin),
this allows satisfying broken packages that ask questions
.TP
\fIpack1 pack2 ..\fP
install packages, old syntax for \fB+\fP, deprecated
.RE
.PP
Anything after an # (inclusive the #) is a comment and is ignored. Same for
any empty lines.
.PP
Lines containing one or multiple sections limited by `` characters, are treated
as command sections. Each of them are run in an subshell, and their stdout is
substituted for the section. This is analog to shell command substitution.


.SH EXAMPLES

The following allows you to send all mails to dphys-admin-logs@example.org:
.PP
In \fI/etc/dphys-admin\fP:
.PP
.nf
$conf_mailaddress = 'dphys-admin-logs@example.org';
.fi
.PP
Note: You must use '' and not "" in conf_mailaddress, else perl will get
digestion problems with the @ in the email address.
.PP
For dphys-admin to be usefull you then need to make an package list for it.
.PP
In \fI/etc/dphys-admin.list\fP:
.PP
.nf
# just a bunch of example stuff, for our exemplaric site
+ dphys-config                   # fetches/updates dphys-admin listfile
+ dphys-admin                    # strictly superfluous as already here
+ dphys-swapfile
+ dphys-pkgtools
+ ssh
+ xterm
+ ash bash bash-doc tcsh tcsh-i18n zsh zsh-doc
| rm -f some-silly-config   # else some-package screwed on install
+ some-package
+ less
+ vim
+ emacs20 emacs21                # both for touchy users
+ cdrecord
+ gcc g++ g77-2.95 gdb
+ fetchmail
# get rid of this crap
- bogosoft
* bogosoft-largeconfigs          # this needs purging
# and so on, the stuff you want
.fi
.PP
To then run dphys-admin by hand (say for tests), type:
.PP
\fIdphys-admin\fP
.PP
But usually you will want to run dphys-admin automatically, every night or at
every boot. For every night you best use an cron job, like this one:
.PP
0 6 * * *	root	/usr/sbin/dphys-admin cron > /dev/null 2>&1
.PP
For at every boot, to catch machines not running over night, you will want an
init.d script, like this one:
.PP
.nf
#!/bin/sh\!
# /etc/init.d/dphys-admin - boot time trigger automatic updates\!
case "$1" in\!
  start)\!
    /usr/sbin/dphys-admin init\!
    ;;\!
esac\!
exit 0\!
.fi
Or look at the cron.d.exampel and init.d.example files for more details.

.SH AUTHOR

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