Configuration Metrics News About

Getting started with pgmoneta

First of all, make sure that pgmoneta is installed and in your path by using "pgmoneta -?". You should see

pgmoneta 0.11.0
  Backup / restore solution for PostgreSQL

Usage:
  pgmoneta [ -c CONFIG_FILE ] [ -u USERS_FILE ] [ -d ]

Options:
  -c, --config CONFIG_FILE Set the path to the pgmoneta.conf file
  -u, --users USERS_FILE   Set the path to the pgmoneta_users.conf file
  -A, --admins ADMINS_FILE Set the path to the pgmoneta_admins.conf file
  -d, --daemon             Run as a daemon
      --offline            Run in offline mode
  -V, --version            Display version information
  -?, --help               Display help
    

If you don't have pgmoneta in your path see our README on how to compile and install pgmoneta in your system.

Configuration

Lets create a simple configuration file called pgmoneta.conf with the content

[pgmoneta]
host = *
metrics = 5001

base_dir = /home/pgmoneta

compression = zstd

retention = 7

log_type = file
log_level = info
log_path = /tmp/pgmoneta.log

unix_socket_dir = /tmp/

[primary]
host = localhost
port = 5432
user = repl
    

In our main section called [pgmoneta] we setup pgmoneta to listen on all network addresses. We will enable Prometheus metrics on port 5001 and have the backups live in the "/home/pgmoneta" directory. All backups are being compressed with zstd and kept for 7 days. Logging will be performed at "info" level and put in a file called "/tmp/pgmoneta.log". Last we specify the location of the "unix_socket_dir" used for management operations and the path for the PostgreSQL command line tools.

Next we create a section called [primary] which has the information about our PostgreSQL instance. In this case it is running on "localhost" on port "5432" and we will use the "repl" user account to connect.

The "repl" user must have the "REPLICATION" role and have access to the "postgres" database, so for example

CREATE ROLE repl WITH LOGIN REPLICATION PASSWORD 'secretpassword';
    

and in pg_hba.conf

local   postgres        repl                                   scram-sha-256
host    postgres        repl           127.0.0.1/32            scram-sha-256
host    postgres        repl           ::1/128                 scram-sha-256
host    replication     repl           127.0.0.1/32            scram-sha-256
host    replication     repl           ::1/128                 scram-sha-256
    

The authentication type should be based on postgresql.conf's password_encryption value.

Optionally, create a physical replication slot that can be used for Write-Ahead Log streaming, like

SELECT pg_create_physical_replication_slot('repl', true, false);
    

and add that to the pgmoneta.conf configuration under [primary], as

wal_slot = repl
    

We will need a user vault for the "repl" account, so the following commands will add a master key, and the "repl" password

pgmoneta-admin master-key
pgmoneta-admin -f pgmoneta_users.conf add-user
    

We are now ready to run pgmoneta. See Configuration for all configuration options.

Running

We will run pgmoneta using the command

pgmoneta -c pgmoneta.conf -u pgmoneta_users.conf
    

If this doesn't give an error, then we are ready to do backups.

pgmoneta is stopped by pressing Ctrl-C (^C) in the console where you started it, or by sending the SIGTERM signal to the process using "kill pid".

Run-time administration

pgmoneta has a run-time administration tool called pgmoneta-cli.

You can see the commands it supports by using "pgmoneta-cli -?" which will give

pgmoneta-cli 0.11.0
  Command line utility for pgmoneta

Usage:
  pgmoneta-cli [ -c CONFIG_FILE ] [ COMMAND ]

Options:
  -c, --config CONFIG_FILE Set the path to the pgmoneta.conf file
  -h, --host HOST          Set the host name
  -p, --port PORT          Set the port number
  -U, --user USERNAME      Set the user name
  -P, --password PASSWORD  Set the password
  -L, --logfile FILE       Set the log file
  -v, --verbose            Output text string of the result
  -V, --version            Display version information
  -?, --help               Display help

Commands:
  backup                   Backup a server
  list-backup              List the backups for a server
  restore                  Restore a backup from a server
  archive                  Archive a backup from a server
  delete                   Delete a backup from a server
  retain                   Retain a backup from a server
  expunge                  Expunge a backup from a server
  encrypt                  Encrypt a file using master-key
  decrypt                  Decrypt a file using master-key
  is-alive                 Is pgmoneta alive
  stop                     Stop pgmoneta
  status                   Status of pgmoneta
  details                  Detailed status of pgmoneta
  reload                   Reload the configuration
  reset                    Reset the Prometheus statistics
    

This tool can be used on the machine running pgmoneta to do a backup like

pgmoneta-cli -c pgmoneta.conf backup primary
    

A restore would be

pgmoneta-cli -c pgmoneta.conf restore primary  /path/to/restore
    

To stop pgmoneta you would use

pgmoneta-cli -c pgmoneta.conf stop
    

Check the outcome of the operations by verifying the exit code, like

echo $?
    

or by using the -v flag.

If pgmoneta has both Transport Layer Security (TLS) and "management" enabled then pgmoneta-cli can connect with TLS using the files ~/.pgmoneta/pgmoneta.key (must be 0600 permission), ~/.pgmoneta/pgmoneta.crt and ~/.pgmoneta/root.crt.

Administration

pgmoneta has an administration tool called pgmoneta-admin, which is used to control user registration with pgmoneta.

You can see the commands it supports by using "pgmoneta-admin -?" which will give

pgmoneta-admin 0.11.0
  Administration utility for pgmoneta

Usage:
  pgmoneta-admin [ -f FILE ] [ COMMAND ]

Options:
  -f, --file FILE         Set the path to a user file
  -U, --user USER         Set the user name
  -P, --password PASSWORD Set the password for the user
  -g, --generate          Generate a password
  -l, --length            Password length
  -V, --version           Display version information
  -?, --help              Display help

Commands:
  master-key              Create or update the master key
  add-user                Add a user
  update-user             Update a user
  remove-user             Remove a user
  list-users              List all users
    

In order to set the master key for all users you can use

pgmoneta-admin -g master-key
    

The master key must be at least 8 characters.

Then use the other commands to add, update, remove or list the current user names, f.ex.

pgmoneta-admin -f pgmoneta_users.conf add-user
    

Next Steps

Next steps in improving pgmoneta's configuration could be

• Update pgmoneta.conf with the required settings for your system
• Enable Transport Layer Security v1.2+ (TLS)

See Configuration for more information on these subjects.

Tutorials

There are a few short tutorials available to help you better understand and configure pgmoneta:

• Installing pgmoneta
• Using a replication slot
• Enabling remote management
• Enabling Prometheus metrics
• Doing backup and restore
• Creating an archive
• Deleting a backup
• Encryption and decryption
• Retention
• Enabling Grafana dashboard

Closing

The pgmoneta community hopes that you find the project interesting.

Feel free to

• Ask a question
• Raise an issue
• Submit a feature request
• Write a code submission

All contributions are most welcome !

Consider giving the project a star on GitHub if you find it useful. And, feel free to follow the project on Twitter as well.