Systemd

Installation

To operate pglift with systemd, set the systemd setting to a non-null value, e.g.:

File ~/.config/pglift/settings.yaml

 systemd: {}

Then use the site-configure command to install systemd unit templates:

(.venv) $ pglift site-configure install
INFO     installing systemd template unit for PostgreSQL
INFO     installed pglift-postgresql@.service systemd unit at
         ~/.local/share/systemd/user/pglift-postgresql@.service
INFO     installing systemd template unit for Prometheus postgres_exporter
INFO     installed pglift-postgres_exporter@.service systemd unit at
         ~/.local/share/systemd/user/pglift-postgres_exporter@.service
INFO     installing systemd template unit and timer for PostgreSQL backups
INFO     installed pglift-backup@.service systemd unit at
         ~/.local/share/systemd/user/pglift-backup@.service
INFO     installed pglift-backup@.timer systemd unit at
         ~/.local/share/systemd/user/pglift-backup@.timer

If systemd is set, we assume that you want to use it for service_manager and scheduler. To disable it, you have to explicitly set either setting to null.

Note

Use pglift site-configure uninstall to uninstall those templates.

How it works

By default, systemd is used in user mode, by running systemctl --user commands. This way, the operator can install systemd units in their home directory (typically in $HOME/.local/share/systemd/user).

Warning

Running systemctl --user commands requires a “real” login: i.e. the user manager unit user@UID.service to be active. Simply switching users (using, e.g., sudo) is not enough, but an SSH connection usually is. When in doubt, querying loginctl list-sessions can help.

Several services are set up at instance creation; these can be listed as follows for an instance with 13-main identifier:

$ systemctl --user list-units "*13-main*"
  UNIT                                     LOAD   ACTIVE SUB     DESCRIPTION
  pglift-postgres_exporter@13-main.service loaded active running Prometheus exporter for PostgreSQL 13-main database server metrics
  pglift-postgresql@13-main.service        loaded active running PostgreSQL 13-main database server
  pglift-backup@13-main.timer              loaded active waiting Backup 13-main PostgreSQL database instance
$ systemctl --user list-timers "*13-main*"
NEXT                         LEFT     LAST                         PASSED       UNIT                            ACTIVATES
Sat 2021-08-07 00:00:00 CEST 10h left Fri 2021-08-06 12:21:07 CEST 1h 25min ago postgresql-backup@13-main.timer pglift-backup@13-main.service

Overriding

systemd.service and systemd.timer shipped with pglift may be overridden using standard methods, as described in systemd.unit(5).

Here is how to obtain the definition of built-in units (in user mode here):

$ systemctl --user list-unit-files pglift-\*
UNIT FILE                         STATE    VENDOR PRESET
pglift-backup@.service            static   -
pglift-postgres_exporter@.service indirect enabled
pglift-postgresql@.service        indirect enabled
pglift-backup@.timer              indirect enabled

$ systemctl --user cat pglift-postgresql@.service
[Unit]
Description=PostgreSQL %i database server
After=network.target

[Service]
Type=notify

# Disable OOM kill on the postmaster
OOMScoreAdjust=-1000
Environment=PG_OOM_ADJUST_FILE=/proc/self/oom_score_adj
Environment=PG_OOM_ADJUST_VALUE=0

ExecStart=/usr/bin/pglift postgres %i
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=default.target

system mode

Operating pglift with systemd in system mode (i.e. through systemctl --system commands) is possible with a few configuration and installation steps.

First assume we’re working in the /srv/pglift prefix directory, where all instances data and configuration would live, and set ownership to the current user:

$ sudo mkdir /srv/pglift
$ sudo chown -R $(whoami): /srv/pglift

A typical site settings file would contain:

File /etc/pglift/settings.yaml

 systemd:
   unit_path: /etc/systemd/system
   user: false
   sudo: true
 sysuser: [postgres, postgres]
 prefix: /srv/pglift

• systemd is configured to have its unit files in /etc/systemd/system,

• the systemd.user setting is unset (meaning --system option will be passed to systemctl),

• the systemd.sudo setting can optionally be set in order to invoke systemctl command with sudo,

• a sysuser (user name, group name) is set to define the system user operating PostgreSQL (typically whoami),

• the global prefix is set to previously created directory.

Note

Check that the overall settings correspond to what’s expected by running: pglift site-settings.

Next the site needs to be configured.

Note

This may be done at package installation step, if installed from a distribution package.

The following command will create systemd service and/or timer files:

 $ env SYSTEMD='{"unit_path": "/srv/pglift/systemd"}' pglift site-configure install
 INFO     installing systemd template unit for PostgreSQL
 INFO     installed pglift-postgresql@.service systemd unit at
          /srv/pglift/pglift-postgresql@.service

By temporarily changing the unit_path setting, we ensure that the user has the sufficient permissions to write the unit files.

Then these systemd files need to be moved to the actual unit files path:

$ sudo mv /srv/pglift/systemd/* /etc/systemd/system

Also, in order to operate pglift with such settings, the user needs permissions to invoke the sudo systemctl command without being asked to provide a password. All systemd units managed by pglift are named with a pglift- prefix (e.g. pglift-postgresql@15-main.service). Accordingly, the site administrator should add a sudoers entry allowing such commands, taking care to use the absolute path to systemctl.

Finally, operations are performed as usual but using configured sysuser, e.g.:

$ pglift instance create --port=5455 main
INFO     initializing PostgreSQL instance
INFO     configuring PostgreSQL authentication
INFO     configuring PostgreSQL instance
INFO     creating role 'replication' on instance 15/main
$ pglift instance list
┏━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ name ┃ version ┃ port ┃ datadir                            ┃ status  ┃
┡━━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ main │ 15      │ 5455 │ /srv/pglift/srv/pgsql/15/main/data │ running │
└──────┴─────────┴──────┴────────────────────────────────────┴─────────┘
$ sudo systemctl status --system pglift-\*
● pglift-postgresql@15-main.service - PostgreSQL 15-main database server
     Loaded: loaded (/etc/systemd/system/pglift-postgresql@.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2022-12-16 14:16:31 CET; 14s ago
   Main PID: 83348 (postgres)
      Tasks: 7 (limit: 6871)
     Memory: 48.3M
        CPU: 444ms
     CGroup: /system.slice/system-pglift\x2dpostgresql.slice/pglift-postgresql@15-main.service
             ├─83348 /usr/lib/postgresql/15/bin/postgres -D /srv/pglift/srv/pgsql/15/main/data
             ├─83349 postgres: main: logger
             ├─83350 postgres: main: checkpointer
             ├─83351 postgres: main: background writer
             ├─83353 postgres: main: walwriter
             ├─83354 postgres: main: autovacuum launcher
             └─83355 postgres: main: logical replication launcher

Uninstallation follows the same logic as the installation:

$ sudo pglift site-configure uninstall
INFO     uninstalling systemd template unit for PostgreSQL
INFO     removing pglift-postgresql@.service systemd unit
         (/etc/systemd/system/pglift-postgresql@.service)