Skip to content

INSTALL.md

Latest commit

 

History

History
535 lines (381 loc) · 13.1 KB

INSTALL.md

File metadata and controls

535 lines (381 loc) · 13.1 KB

Installation

The default installation uses sqlite3 for the django database. To configure mysql or postgresql instead, see the database configuration section.

Supported Server Installation Options

Ubuntu 24.04 (noble)

curl -sS https://repo.openbytes.ie/openbytes.gpg > /usr/share/keyrings/openbytes.gpg
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/ubuntu noble-backports main" > /etc/apt/sources.list.d/patchman.list
apt update
apt -y install python3-patchman patchman-client
patchman-manage createsuperuser

Debian 13 (trixie)

curl -sS https://repo.openbytes.ie/openbytes.gpg > /usr/share/keyrings/openbytes.gpg
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/debian trixie main" > /etc/apt/sources.list.d/patchman.list
apt update
apt -y install python3-patchman patchman-client
patchman-manage createsuperuser

Rocky 10

Server installation is currently broken due to missing upstream packages: #669 Client installation should work as expected.

This also applies to Alma, RHEL, etc.

curl -sS https://repo.openbytes.ie/openbytes-2.gpg > /etc/pki/rpm-gpg/RPM-GPG-KEY-openbytes
cat <<EOF >> /etc/yum.repos.d/openbytes.repo
[openbytes]
name=openbytes
baseurl=https://repo.openbytes.ie/patchman/el10
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-openbytes
EOF
dnf -y install epel-release
dnf makecache
dnf -y install patchman-client
#dnf -y install patchman
systemctl restart httpd
patchman-manage createsuperuser

virtualenv + pip

apt -y install python3-venv        # (debian/ubuntu)
dnf -y install python3-virtualenv  # (rocky/alma/redhat)
mkdir /srv/patchman
cd /srv/patchman
python3 -m venv .venv
. .venv/bin/activate
pip install patchman gunicorn whitenoise
patchman-manage migrate
patchman-manage createsuperuser
gunicorn patchman.wsgi -b 0.0.0.0:80

Source

Ubuntu 24.04 (noble)

  1. Install dependencies
apt -y install python3-django python3-django-tagging python3-django-extensions \
python3-djangorestframework python3-defusedxml python3-lxml python3-requests \
python3-rpm python3-debian python3-colorama python3-humanize python3-magic \
apache2 libapache2-mod-wsgi-py3 python3-pip python3-progressbar
  1. Install django-bootstrap3
pip3 install django-bootstrap3
  1. Clone git repo to e.g. /srv/patchman
cd /srv
git clone https://github.com/furlongm/patchman
  1. Copy server settings example file to /etc/patchman
mkdir /etc/patchman
cp /srv/patchman/etc/patchman/local_settings.py /etc/patchman/

Configuration

Patchman Server Settings

Modify /etc/patchman/local_settings.py to configure the patchman server.

If installing from source or using virtualenv, the following settings should be configured:

  • ADMINS - set up an admin email address
  • SECRET_KEY - create a random secret key
  • STATIC_ROOT - should point to /srv/patchman/run/static if installing from source

The default settings for errata downloading may include operating systems that are not relevant to a given deployment. If this is the case, modify the ERRATA_OS_UPDATES setting in /etc/patchman/local_settings.py. Further distribution-specific settings are also available to only download errata for specific versions/codenames.

Patchman Client Settings

The client comes with a default configuration that will attempt to upload the reports to a server at patchman.example.com. This configuration needs to be updated to connect to the correct patchman server.

Change the following lines in /etc/patchman/patchman-client.conf:

# Patchman server
server=https://patchman.example.com

# Options to curl
curl_options="--insecure --connect-timeout 60 --max-time 300"
  • server needs to point the URL where the patchman server is running
  • --insecure in the curl options tells the client to ignore certificates. If the patchman server is set up correctly with certificates this flag can be removed to increase security.

Patchman supports two report protocols:

Protocol 1 (text)

The original text-based protocol. Uses multipart form data to upload package and repository information. No additional dependencies required on the client.

Protocol 2 (json)

A JSON-based REST API. Provides better error handling, structured validation, and easier debugging. Requires jq on the client.

To use Protocol 2, update your patchman-client.conf:

protocol=2

Or use the -p 2 command line option:

$ patchman-client -s http://patchman.example.org -p 2

Configure Database

The default database backend is sqlite. However, this is not recommended for production deployments. MySQL or PostgreSQL are better choices.

SQLite

To configure the sqlite database backend:

  1. Create the database directory specified in the settings file, touch the database file and set the journal mode to WAL:
mkdir -p /var/lib/patchman/db
touch /var/lib/patchman/db/patchman.db
sqlite3 /var/lib/patchman/db/patchman.db 'PRAGMA journal_mode=WAL;'
  1. Modify /etc/patchman/local_settings.py as follows:
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': '/var/lib/patchman/db/patchman.db',
    }
}
  1. Proceed to syncing database.

MySQL

To configure the mysql database backend:

  1. Ensure mysql-server and the python mysql bindings are installed:
apt -y install default-mysql-server python3-mysqldb
  1. Create database and users:
$ mysql

mysql> CREATE DATABASE patchman CHARACTER SET utf8 COLLATE utf8_general_ci;
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER patchman@localhost IDENTIFIED BY 'changeme';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL PRIVILEGES ON patchman.* TO patchman@localhost;
Query OK, 0 rows affected (0.00 sec)
  1. Modify /etc/patchman/local_settings.py as follows:
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'patchman',
        'USER': 'patchman',
        'PASSWORD': 'changeme',
        'HOST': '',
        'PORT': '',
        'STORAGE_ENGINE': 'INNODB',
        'CHARSET': 'utf8',
    }
}
  1. Proceed to syncing database.

PostgreSQL

To configure the postgresql database backend:

  1. Ensure the postgresql server and the python postgres bindings are installed:
apt -y install postgresql python3-psycopg2
  1. Create database and users:
$ sudo su - postgres
$ psql

postgres=# CREATE DATABASE patchman;
CREATE DATABASE
postgres=# CREATE USER patchman WITH PASSWORD 'changeme';
CREATE ROLE
postgres=# ALTER ROLE patchman SET client_encoding TO 'utf8';
ALTER ROLE
postgres=# ALTER ROLE patchman SET default_transaction_isolation TO 'read committed';
ALTER ROLE
postgres=# ALTER ROLE patchman SET timezone TO 'UTC';
ALTER ROLE
postgres=# GRANT ALL PRIVILEGES ON DATABASE patchman to patchman;
GRANT
postgres=# GRANT ALL ON SCHEMA public TO patchman;
GRANT
ALTER DATABASE patchman OWNER TO patchman;
ALTER DATABASE
  1. Modify /etc/patchman/local_settings.py as follows:
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'patchman',
        'USER': 'patchman',
        'PASSWORD': 'changeme',
        'HOST': '127.0.0.1',
        'PORT': '',
        'CHARSET': 'utf8',
    }
}
  1. Proceed to syncing database.

Sync Database

After configuring a database backend, the django database should be synced:

  1. Initialise the database, perform migrations, create the admin user and collect static files:
patchman-manage migrate --run-syncdb
patchman-manage createsuperuser
patchman-manage collectstatic

N.B. To run patchman-manage when installing from source, run ./manage.py

  1. Restart the web server after syncing the database.

Migrate from sqlite to another database backend

The prebuilt package installations use sqlite as the default database backend, but this is not recommended in production. To migrate from sqlite to another database backend, use the following procedure:

  1. Dump the sqlite database to a json file
patchman-manage dumpdata --exclude packages.Packagestring -e contenttypes -e auth.Permission --natural-foreign --natural-primary --indent 4 > patchman-db.json

  1. Create the new database and add the new database settings to /etc/patchman/local_settings.py

  2. Sync the new database and load the existing data:

patchman-manage migrate --run-syncdb
patchman-manage loaddata patchman-db.json

Configure Web Server

Apache

  1. If installing from source, enable mod-wsgi and copy the apache conf file:
a2enmod wsgi
cp /srv/patchman/etc/patchman/apache.conf.example /etc/apache2/conf-available/patchman.conf
a2enconf patchman
  1. Edit the networks allowed to report to apache and reload apache.
vi /etc/apache2/conf-available/patchman.conf
systemctl reload apache2
  1. If installing from source, allow apache access to the settings and to the sqlite db:
chown -R :www-data /etc/patchman
chmod -R g+r /etc/patchman
chown -R :www-data /var/lib/patchman
chmod -R g+w /var/lib/patchman/db

The django interface should be available at http://127.0.0.1/patchman/

Optional Configuration Items

Cronjobs

Daily cronjob on patchman server

A daily cronjob on the patchman server can be run to process reports, perform database maintenance, check for upstream updates, and find updates for clients. Alternatively, run celery as outlined below for finer granularity over the timing of these tasks and for increased concurrency.

patchman -a

Daily cronjob on client to send reports to patchman server

patchman-client

Celery

Install Celery for realtime processing of reports from clients and for periodic maintenance tasks. The celery configuation file is in /etc/patchman/celery.conf

Ubuntu / Debian

apt -y install python3-celery redis python3-redis python-celery-common
/usr/bin/celery --broker redis://127.0.0.1:6379/0 --app patchman worker --loglevel info --beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --task-events --pool threads

Rocky / Alma / RHEL

Currently waiting on https://bugzilla.redhat.com/show_bug.cgi?id=2032543

dnf -y install python3-celery redis python3-redis
systemctl restart redis
semanage port -a -t http_port_t -p tcp 6379
setsebool -P httpd_can_network_connect 1
/usr/bin/celery --broker redis://127.0.0.1:6379/0 --app patchman worker --loglevel info --beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --task-events --pool threads

Persistence

There is a systemd unit file for celery to make the service persistent over reboot:

etc/systemd/system/patchman-celery.service

If installing from prebuilt packages, this should be enabled by default.

Caching

Memcached or Redis can optionally be run to reduce the load on the server. Note that caching may result in the web interface showing results that are out of date with the database, so this is disabled by default.

Redis

Install Redis:

apt -y install redis python3-redis  # (debian/ubuntu)
dnf -y install redis python3-redis  # (rocky/alma/redhat)
systemctl restart redis/redis-server

and add the following to /etc/patchman/local_settings.py

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379',
        'TIMEOUT': 30,
    }
}

Memcacached

Install Memcached

apt -y install memcached python3-pymemcache  # (debian/ubuntu)
dnf -y install memcached python3-pymemcache  # (rocky/alma/redhat)
systemctl restart memcached

and add the following to /etc/patchman/local_settings.py

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.PyMemcacheCache',
        'LOCATION': '127.0.0.1:11211',
        'TIMEOUT': 30,
        'OPTIONS': {
            'ignore_exc': True,
        },
    }
}

API Key Authentication

API key authentication is available. Keys are hashed in the database and cannot be retrieved after creation.

Server-side setup

  1. Create an API key:
$ patchman-manage create_api_key "clients"
Created API key: clients

  Key: abc123...

Add this to your patchman-client.conf:
  api_key=abc123...

Save this key as it cannot be retrieved later.
  1. List existing keys:
$ patchman-manage list_api_keys
  1. Revoke a key:
$ patchman-manage revoke_api_key <prefix-or-name>

API keys can also be managed via the Django admin interface.

Client-side setup

Add the API key to patchman-client.conf:

protocol=2
api_key=abc123...

Or use the -k command line option:

$ patchman-client -s http://patchman.example.org -p 2 -k abc123...

Test Installation

To test the installation, run the client locally on the patchman server:

patchman-client -s http://127.0.0.1/patchman/