pgmoneta.conf(5)

📦
version 0.21.0 · 2 versions
, in nixos 26.05

🎀 Name 🎀

pgmoneta.conf — the main configuration file for pgmoneta ✨ (yes bestie, this is pgmoneta.conf(5), and it’s kind of the main character of the whole setup).

✨ DESCRIPTION ✨

Okay so pgmoneta.conf is the main configuration file for pgmoneta. It’s split into different sections, and the section boundaries are specified by the [ and ] characters. The main section is called [pgmoneta].

Other sections specify the PostgreSQL server configuration.

All properties are in the format key = value.

The characters # and ; can be used for comments, and they must be the first character on the line. The Bool data type supports these values: on, 1, true, off, 0 and false.

💅 OPTIONS 💅

🫶 The options for the main section are 🫶

  • host — the bind address for pgmoneta. Mandatory.
  • unix_socket_dir — the Unix Domain Socket location. Mandatory.
  • base_dir — the base directory for the backup. Mandatory.
  • metrics — the metrics port. Default is 0 (disabled).
  • console — the web console port. Default is 0 (disabled).
  • metrics_cache_max_age — the time to keep a Prometheus (metrics) response in cache. If this value is specified without units, it is taken as seconds. Setting this parameter to 0 disables caching. It supports the following units as suffixes: S for seconds (default), M for minutes, H for hours, D for days, and W for weeks. Default is 0 (disabled).
  • metrics_cache_max_size — the maximum amount of data to keep in cache when serving Prometheus responses. Changes require restart. This parameter determines the size of memory allocated for the cache even if metrics_cache_max_age or metrics are disabled. Its value, however, is taken into account only if metrics_cache_max_age is set to a non-zero value. Supports suffixes: B (bytes), the default if omitted, K or KB (kilobytes), M or MB (megabytes), G or GB (gigabytes). Default is 256k.
  • management — the remote management port. Default is 0 (disabled).
  • compression — the compression type (none, gzip, client-gzip, server-gzip, zstd, client-zstd, server-zstd, lz4, client-lz4, server-lz4, bzip2, client-bzip2). Default is zstd.
  • compression_level — the compression level. Default is 3.
  • workers — the number of workers that each process can use for its work. Use 0 to disable. Maximum is CPU count. Default is 0.
  • workspace — the directory for the workspace that incremental backup can use for its work. Default is /tmp/pgmoneta-workspace/.
  • storage_engine — the storage engine type (local, ssh, s3, azure). Default is local.
  • encryption — the encryption mode. Default is none.

Available options:

  • none — no encryption (default value)
  • aes | aes-256 | aes-256-cbc — AES CBC (Cipher Block Chaining) mode with 256 bit key length
  • aes-192 | aes-192-cbc — AES CBC mode with 192 bit key length
  • aes-128 | aes-128-cbc — AES CBC mode with 128 bit key length
  • aes-256-ctr — AES CTR (Counter) mode with 256 bit key length
  • aes-192-ctr — AES CTR mode with 192 bit key length
  • aes-128-ctr — AES CTR mode with 128 bit key length
  • create_slot — create a replication slot for all server. Valid values are: yes, no. Default is no.
  • ssh_hostname — defines the hostname of the remote system for connection.
  • ssh_username — defines the username of the remote system for connection.
  • ssh_base_dir — the base directory for the remote backup.
  • ssh_ciphers — the supported ciphers for communication.
    • aes | aes-256 | aes-256-cbc — AES CBC (Cipher Block Chaining) mode with 256 bit key length
    • aes-192 | aes-192-cbc — AES CBC mode with 192 bit key length
    • aes-128 | aes-128-cbc — AES CBC mode with 128 bit key length
    • aes-256-ctr — AES CTR (Counter) mode with 256 bit key length
    • aes-192-ctr — AES CTR mode with 192 bit key length
    • aes-128-ctr — AES CTR mode with 128 bit key length

Otherwise verbatim. Default is aes-256-ctr, aes-192-ctr, aes-128-ctr.

  • ssh_public_key_file — the SSH public key file path. Supports environment variable interpolation (e.g., $HOME). Default is $HOME/.ssh/id_rsa.pub.
  • ssh_private_key_file — the SSH private key file path. Supports environment variable interpolation (e.g., $HOME). Default is $HOME/.ssh/id_rsa.
  • s3_region — the AWS region.
  • s3_access_key_id — the IAM access key ID.
  • s3_secret_access_key — the IAM secret access key.
  • s3_bucket — the IAM secret access key.
  • s3_base_dir — the base directory for the S3 bucket.
  • azure_storage_account — the Azure storage account name.
  • azure_container — the Azure container name.
  • azure_shared_key — the Azure storage account key.
  • azure_base_dir — the base directory for the Azure container.
  • retention — the retention time in days, weeks, months, years. Default is 7, - , - , -.
  • retention_interval — the retention check interval. Default is 300.
  • log_type — the logging type (console, file, syslog). Default is console.
  • log_level — the logging level, any of the (case insensitive) strings FATAL, ERROR, WARN, INFO and DEBUG (that can be more specific as DEBUG1 thru DEBUG5). Debug level greater than 5 will be set to DEBUG5. Not recognized values will make the log_level be INFO. Default is info.
  • log_path — the log file location. Default is pgmoneta.log. Can be a strftime(3) compatible string.
  • log_rotation_age — the time after which log file rotation is triggered. If this value is specified without units, it is taken as seconds. Setting this parameter to 0 disables log rotation based on time. It supports the following units as suffixes: S for seconds (default), M for minutes, H for hours, D for days, and W for weeks. Default is 0 (disabled).
  • log_rotation_size — the size of the log file that will trigger a log rotation. Supports suffixes: B (bytes), the default if omitted, K or KB (kilobytes), M or MB (megabytes), G or GB (gigabytes). A value of 0 (with or without suffix) disables. Default is 0.
  • log_line_prefix — a strftime(3) compatible string to use as prefix for every log line. Must be quoted if contains spaces. Default is %Y-%m-%d %H:%M:%S.
  • log_mode — append to or create the log file (append, create). Default is append.
  • blocking_timeout — the number of seconds the process will be blocking for a connection. If this value is specified without units, it is taken as seconds. Setting this parameter to 0 disables it. It supports the following units as suffixes: S for seconds (default), M for minutes, H for hours, D for days, and W for weeks. Default is 30.
  • max_rate — the maximum backup transfer rate in bytes per second. Use 0 to disable. Default is 0.
  • progress — enable backup progress tracking. Default is off.
  • tls — enable Transport Layer Security (TLS). Default is false.
  • tls_cert_file — certificate file for TLS.
  • tls_key_file — private key file for TLS.
  • tls_ca_file — Certificate Authority (CA) file for TLS.
  • metrics_cert_file — certificate file for TLS for Prometheus metrics.
  • metrics_key_file — private key file for TLS for Prometheus metrics.
  • metrics_ca_file — Certificate Authority (CA) file for TLS for Prometheus metrics.
  • libev — the libev backend to use. Valid options: auto, select, poll, epoll, iouring, devpoll and port. Default is auto.
  • keep_alive — have SO_KEEPALIVE on sockets. Default is on.
  • nodelay — have TCP_NODELAY on sockets. Default is on.
  • non_blocking — have O_NONBLOCK on sockets. Default is on.
  • backlog — the backlog for listen(). Minimum 16. Default is 16.
  • hugepage — huge page support. Default is try.
  • direct_io — direct I/O support for local storage (off, auto, on). When on, bypasses kernel page cache using O_DIRECT. When auto, attempts O_DIRECT and falls back to buffered I/O if unsupported. Linux only. Default is off.
  • pidfile — path to the PID file.
  • update_process_title — the behavior for updating the operating system process title. Allowed settings are:
    • never (or off) — does not update the process title.
    • strict — sets the process title without overriding the existing initial process title length.
    • minimal — sets the process title to the base description.
    • verbose (or full) — sets the process title to the full description.

Please note that strict and minimal are honored only on those systems that do not provide a native way to set the process title (e.g., Linux). On other systems, there is no difference between strict and minimal and the assumed behaviour is minimal even if strict is used. never and verbose are always honored, on every system. On Linux systems the process title is always trimmed to 255 characters, while on system that provide a natve way to set the process title it can be longer. Default is verbose.

🐘 The options for the PostgreSQL section are 🐘

  • host — the address of the PostgreSQL instance. Mandatory.
  • port — the port of the PostgreSQL instance. Mandatory.
  • user — the user name for the replication role. Mandatory.
  • extra — the source directory for retrieval on the server side.
  • wal_slot — the WAL slot. Mandatory.
  • create_slot — create a replication slot for all server. Valid values are: yes, no. Default is no.
  • follow — failover to this server if follow server fails.
  • retention — the retention for the server in days, weeks, months, years.
  • wal_shipping — the WAL shipping directory.
  • workspace — the directory for the workspace that incremental backup can use for its work. Default is /tmp/pgmoneta-workspace/.
  • hot_standby — hot standby directory. Single directory or comma separated directories up to 8 (e.g., /path/to/hot/standby1,/path/to/hot/standby2).
  • hot_standby_overrides — files to override in the hot standby directory. If multiple hot standbys are specified then this setting is separated by a |.
  • hot_standby_tablespaces — bestie this is the tablespace mapping for the hot standby 💫 and the syntax is literally [from -> to,?]+. If you've got multiple hot standbys going, separate this setting with a |. That's it, that's the vibe.
  • workers — how many workers each process gets to throw at its work 🛠️. Use 0 to disable it, -1 means "just use the global setting, don't be extra". Maximum is your CPU count, no squeezing more out of it than that. Default is -1.
  • max_rate — the maximum backup transfer rate, measured in bytes per second 🏎️💨. Use 0 to disable, -1 means use the global setting. Default is -1.
  • progress — turns backup progress tracking on or off 🎀. Use on to enable, off to disable, and -1 means use the global setting. Default is -1.
  • verification — the time between verifications of a backup ⏰. If you give this value with no units, it's taken as seconds — no cap. Setting this parameter to 0 disables verification entirely. It supports these unit suffixes: 'S' for seconds (that's the default), 'M' for minutes, 'H' for hours, 'D' for days, and 'W' for weeks. Default is 0 (disabled, so nothing gets verified until you say so).
  • tls_cert_file — the certificate file for TLS 🔐. Heads up: this file must be owned by either the user running pgmoneta or root. No random owners, okay?
  • tls_key_file — the private key file for TLS 🗝️. Same ownership deal: it must be owned by either the user running pgmoneta or root. AND the permissions have to be at least 0640 when it's owned by root, or 0600 otherwise. Not me being strict — that's just the rule, fr fr.
  • tls_ca_file — the Certificate Authority (CA) file for TLS 👑. Again: this file must be owned by either the user running pgmoneta or root.

🐛 REPORTING BUGS 🐛

Spotted a bug? Got a little "um, actually" moment? pgmoneta is maintained on GitHub at <https://github.com/pgmoneta/pgmoneta> — that's the spot, bestie 🫶

pgmoneta is licensed under the 3-clause BSD License ⚖️✨

👀 SEE ALSO 👀

Go read these too, they're all part of the lore 💜

🌸 and that's a wrap on pgmoneta.conf(5)! the little footer down there is just the source/version and date flexing on us — you know the drill, slay, stay configured, and may your backups always verify 💅🎀✨

📦 where this page comes from