Patchman
========

Summary
-------

Patchman is a django-based patch status monitoring tool for linux systems, that
provides a web interface for monitoring host package updates.

Patchman clients send a list of installed packages and enabled repositories to
the patchman server. The patchman server updates its package list for each
repository and determines which hosts require updates, and whether those updates
are normal or security updates. The web interface also gives information on
potential issues, such as installed packages that are not from any repository.

Hosts, packages, repositories and operating systems can all be filtered (using
features or arbitrary tags). For example, it is possible to find out which hosts
have a certain version of a package installed, and which repository it comes
from.

Patchman does not install update packages on hosts, it determines and records
what updates are available for each host.

Yum and apt plugins can send reports to the patchman server every time packages
are installed or removed on a host.


Source
------

The current code is available on github:

   https://github.com/furlongm/patchman


Server-side dependencies
------------------------

python-django-tagging
python-django-south
python-django-extensions
python-debian
python-rpm
python-progressbar
python-lxml
python-argparse

The server can optionally make use of celery to asynchronously process the
reports send by hosts. The appropriate python database library bindings are
also required.


Client-side dependencies
------------------------

The client-side dependencies are kept to a minimum. rpm and dpkg are required
to report packages, yum and apt are required to report repositories. These
packages are normally installed by default on most systems.

rpm-based OS's can tell if a reboot is required to install a new kernel by
looking at uname -r and comparing it to the highest installed kernel version.

deb-based OS's do not always change the kernel version when a kernel update is
installed, so these clients need the 'update-notifier-common' package installed
to enable this functionality.


Usage
-----

The web interface contains a dashboard with items that need attention, and various
pages to manipulate packages, repositories, operating systems and hosts.

To populate the web interface, run the client on some hosts, this should
provide some initial data to work with.

On the server, the command line utility can be used to run certain maintenance
tasks, e.g. processing the reports sent from hosts. Run 'patchman -h' for a
rundown of the usage.

Depending on your setup, there may be some initial work required to logically
organise the data sent in the host reports. The following explanations may help
in this case.

Repositories can be linked to an OSGroup, or to a host itself. If the
use_host_repos variable is set to True for a host, then updates are found by
looking only at the repositories that belong to that host. This is the default
behaviour and does not require OSGroups to be configured.

If use_host_repos is set to False, the update-finding process looks at the
OSGroup that the host is in, and uses the OSGroup's repositories to determine
applicable updates. This is useful in environments where many hosts are
homogeneous (e.g. cloud/cluster environments).

An OSGroup is a collection of OS's. For example, a "Debian 7" OSGroup would be
comprised of the following OS's -> "Debian 7.0", "Debian 7.3", "Debian 7.4".
These OS names are obtained from the hosts, so they will probably differ
depending on which updates have been installed, even though they run the same
operating system. Likewise, a "CentOS 6" OSGroup covers "CentOS 6.0" through
"CentOS 6.5".

For repositories, each repository URL is counted as a separate mirror, unless
the repositories are linked together. For Red Hat based hosts, this occurs
automatically. Currently, for Debian-based hosts, you may need to link all
mirrors that form a repository. This is not strictly necessary but may reduce
the time to find updates.