Aptitude Robot
==============

Automate package choice management

## Introduction

On an individual Debian host it is most convenient to select packages for
installation and removal within the interactive mode of aptitude.  If you do
the same for several machines the task becomes repetitive.  If you like to
maintain certain standard package choices across those machines this is not
only tedious but error prone.

The solution is to write some scripts that automate the installation/removal of
packages.  Either apt-get or the command line interface of aptitude allow you
to do this.  `aptitude-robot` is such a configurable script.  It is a thin
layer that reads in some configuration files and calls aptitude via the command
line interface with the appropriate parameters.  The configuration files allow
you to separate out common packages from host specific ones.  This way you can
keep the list packages simple to read rather than having to write custom
versions of the script for each host.

## Installation

The simplest way to install is via a Debian package

    aptitude install aptitude-robot

This works when `aptitude-robot` is available for your version in one of the
repositories (you may need to check out the backports).  If it is not in one of
the repositories you use or if you want to install a newer version follow the
instructions below on how to [build from source](#building-from-source).

## Configuration

With the exception of `/etc/default/aptitude-robot` the configuration files are
in the directory `/etc/aptitude-robot`.

### Package Lists

In `/etc/aptitude-robot/pkglist.d/` you can add one or more package lists.
Their names should conform to the run-parts(8) conventions (e.g., a dot in the
file name will disable it).  These files should contain one package name per
line preceded by an action you want to perform with this package.  The actions
are specified with the characters used by aptitude, i.e., `+` for install, `-`
for removal, etc.  Read the aptitude(8) man page under "override specifier" for
a complete list.  Comments starting with `#` are allowed.

If you have more than one package list file they are concatenated according to
the rules of run-parts(8).  If a package appears more than once the last action
mentioned applies.

Example

    #example: /etc/aptitude-robot/pkglist.d/10_mypackages
    + less
    + htop
    + build-essential
    - ppp

If you install additional packages via aptitude-robot it is up to you to set up
the configuration for those packages beforehand.  If you call `aptitude-robot`
on the command line it will ask for missing configuration information the same
way aptitude would.  The automatic invocations of `aptitude-robot` by cron or
init try to always choose the default configuration non-interactively.  Make
sure you provide the appropriate configuration files and debconf preseeds for
the packages you intend to install.

### Options

The directory `/etc/aptitude-robot/options.d/` may contain files in
which you can specify additional command-line options for aptitude.
List one option per line.  Typical options might be:

    --without-recommends
    --add-user-tag-to "aptitude-robot,?action(install)"
    -o 'Aptitude::ProblemResolver::Remove-Level=maximum'

See
[Configuring the interactive dependency resolver](http://aptitude.alioth.debian.org/doc/en/ch02s03s05.html)
for documentation about influencing automatic conflict resolution with
aptitude.

The files in this directory must adhere to `run-parts(8)` conventions.

### Triggers

The directories `/etc/aptitude-robot/triggers.pre` and
`/etc/aptitude-robot/triggers.post` may contain scripts that will be run by
aptitude-robot before and after aptitude, respectively.  They are run by
`run-parts(8)` via [`Run::Parts`](https://metacpan.org/pod/Run::Parts).

By default there are no trigger scripts.  Be careful placing scripts in these
directories as they are always run whether or not aptitude performs some
action.  For scripts that should only run upon installation, removal, or
upgrade of a specific package the relevant preinst, postinst, etc. scripts of
the package would be the right place.

In `/etc/aptitude-robot/triggers.post/90-cleanup.example` you can find an
example of the trigger script that cleans up after
upgrading/installing/removing.  Remove the `.example` suffix to enable it.

### Cron and Init Defaults

In `/etc/default/aptitude-robot` you can control the execution of
aptitude-robot by setting some variables.

    # set to "no" to prevent the daily cron run
    RUN_DAILY=yes
    # set to "no" to prevent the init run at boot time
    RUN_ON_BOOT=yes
    # location for the session log (will be deleted after aptitude-robot has ended)
    LOG_SESSION=/var/log/aptitude-robot.session.log
    # log file to keep the output of aptitude-robot
    LOGFILE=/var/log/aptitude-robot.log
    # (optional) mail address to send the session log to
    MAIL_TO=

## Running and Deployment

A default installation of aptitude-robot will run `aptitude full-upgrade '~U
!~ahold'` each time it is run.  Out of the box aptitude-robot will run daily
and at each boot.  You can call `aptitude-robot` manually whenever you need.
You may also call `aptitude-robot-session` which in addition deals with writing
to the log file and performing the installations non-interactively.

If you want to run `aptitude-robot` periodically more often than daily you can
write your own crontab entry, e.g., in `/etc/cron.d/aptitude-robot`.  In your
own cron job you most likely want to call `aptitude-robot-session`.  You may
then want to disable the daily cron jobs by setting `RUN_DAILY=no` in
`/etc/default/aptitude-robot`.

## Scenarios

### Server with Mostly Unattended Upgrades

By default aptitude-robot will upgrade all packages daily.  On a server you
want to have security upgrades deployed as soon as possible but for some
critical packages you want to test them first with your configuration before
installing an upgrade.  With aptitude-robot you can choose to keep some
packages while automatically upgrading all the others.  E.g., on a web server
with a complex configuration you may add a package list in
`/etc/aptitude-robots/pkglist.d/90_keep_web` with the contents:

    : apache2
    : apache2-mpm-prefork
    : apache2-utils
    : apache2.2-bin
    : apache2.2-common
    : libapache2-mod-php5
    #etc.

You can then concentrate on the security announcement for apache and its
plugins.  All other security announcement you can read at you leisure for
educational purposes only.

### Standardized Deployments

On a development host you can build up and test package lists.  You can then
use these lists to deploy (and maintain) hosts with a standard set of packages.
By splitting up the package list into several files according to usage patterns
you can arrange for optional installs too.

If you want to prevent automatic upgrade of certain packages but still have
them installed on initial deployment you can specify both actions, as follows:

    + foo
    : foo

During the initial deployment you would run `aptitude-robot` with the
`--force-install` option to ignore the keep action.

## Related Packages

### Just automatic upgrades or notifications

If you are just interested in automatic upgrades you should look into
[unattended-upgrades](http://packages.debian.org/unattended-upgrades),
[cron-apt](http://packages.debian.org/cron-apt), or
[apticron](http://packages.debian.org/apticron).

### Restarting services as needed

After the upgrade you may need to restart some processes. See the
[needrestart](http://packages.debian.org/stable/needrestart) package
for a way to automatically restart affected services.

If you also have desktop users, you may be also interested in the
[needrestart-session](http://packages.debian.org/sid/needrestart-session)
package which informs logged in desktop users about the necessity to
restart some of their running programs.

If you're just interested in a list of programs which should be
restarted with automatically doing so, have a look `checkrestart` from
the [debian-goodies](http://packages.debian.org/sid/debian-goodies)
package. There exists also a post-install trigger script named
[restart-services](https://github.com/tpo/debian-goodies/blob/master/restart-services)
which parses the output of `checkrestart` to automatically restart
services. See also the
[wishlist bug #676509](https://bugs.debian.org/676509) of
debian-goodies.

### Checking for severe bugs before installing updates

To prevent automatically upgrading packages to versions which are
known to be severely broken, you can use
[apt-listbugs](http://packages.debian.org/apt-listbugs). If
apt-listbugs finds release-critical bugs it will prevent
aptitude-robot from updating _any_ package.

Please be aware that you need to _manually_ upgrade the remaining
packages in this case.

Example:

    The following packages will be upgraded:
      chromium chromium-browser chromium-inspector icedove iceowl-extension
      libmysqlclient-dev libmysqlclient18 mysql-client mysql-client-5.5
      mysql-common openjdk-7-jre openjdk-7-jre-headless openjdk-7-jre-lib
      openjdk-7-jre-zero
    14 packages upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
    Need to get 0 B/123 MB of archives. After unpacking 2,011 kB will be used.
    Writing extended state information...
    grave bugs of chromium (34.0.1847.116-1~deb7u1 -> 34.0.1847.132-1~deb7u1)
     #745794 - chromium: Missing build dep[…] (Fixed: chromium-browser/34.0.1847.132-1)
    grave bugs of icedove (24.4.0-1~deb7u1 -> 24.5.0-1~deb7u1)
     #743748 - Folders are not listed, blank folder pane
    Summary:
     icedove(1 bug), chromium(1 bug)
    **********************************************************************
    ****** Exiting with an error in order to stop the installation. ******
    **********************************************************************
    E: Sub-process /usr/sbin/apt-listbugs apt || exit 10 returned an error code (10)
    E: Failure running script /usr/sbin/apt-listbugs apt || exit 10
    A package failed to install.  Trying to recover:
    Reading package lists...
    Building dependency tree...
    Reading state information...
    Reading extended state information...
    Initializing package states...
    aptitude exited with value 255
    aptitude-robot ended at 2014-05-07 03:37:17+02:00

### Monitoring and Reporting

In `/usr/share/aptitude-robot/` there are two reporting scripts which
can report `aptitude-robot-session`'s result either to a
[Xymon](http://www.xymon.com/) (formerly called Hobbit) monitoring
server (`xymon-report`) or by e-mail (`mail-log-on-error`).

If you need to, you can configure in `/etc/default/aptitude-robot`
what goes into the report and what not:

    # (optional) exclude some rather verbose output from the reporting
    REPORT_LOG_DROP='is (currently )?not installed, so it will not be|is already installed at the requested version|cannot be marked/unmarked as automatically installed'
    # (optional) Don't treat some specific warnings or errors as such
    REPORT_LOG_IGNORE='uses weak digest algorithm'

The values are used as pattern parameter to `egrep -v` on the log file
and default to the empty string.

## Building from Source

You can build `aptitude-robot` from the GIT repository as follows:

    sudo apt-get -y install autoconf autotools-dev build-essential devscripts git
    sudo apt-get -y install libmouse-perl librun-parts-perl perl-doc
    git clone https://github.com/elmar/aptitude-robot.git
    cd aptitude-robot
    autoreconf --force --install
    ./configure
    make dist
    mv *.tar.gz ../$(echo *.tar.gz | sed -e 's/robot-/robot_/' -e 's/\.tar/.orig.tar/')
    make distclean
    debuild -uc -us
    debclean
    cd ..
    ls -l *.deb

This will generate a Debian package that you can install with dpkg:

    sudo dpkg -i *.deb

## Version Numbers

aptitude-robot tries to follow
[Semantic Versioning](http://semver.org/), but usually omits the
patch/micro version if it is a zero, i.e. version "1.5" is equivalent
to "1.5.0".

## Thanks

aptitude-robot was created as a more general version of a local maintenance
script called [dphys-admin](http://nic.phys.ethz.ch/projects/dphys-admin/).
As such various people contributed in various forms, from code to bug reports
to discussions.

- Axel Beckert <abe@debian.org> (co-maintainer of aptitude-robot, last maintainer of dphys-admin)
- Neil Franklin <neil@franklin.ch.remove> (original author of dphys-admin)
- Gürkan Myczko <myczko@phys.ethz.ch>
- Claude Becker <becker@phys.ethz.ch>
- Tomas Pospisek <tpo@sourcepole.ch>
- Daniel Hartwig <mandyke@gmail.com>