PG_AUTOCTL_CREATE_MONITOR(1)

📦
version 2.1 · 2 versions
, in fedora 43, fedora 44

💖 PG_AUTOCTL CREATE MONITOR 💖

okay bestie, so this is pg_autoctl create monitor from the pg_auto_failover manual — and it's literally the moment your whole cluster gets its main character monitor node. no cap.

✨ NAME ✨

pg_autoctl create monitor — pg_autoctl create monitor

pg_autoctl create monitor — Initialize a pg_auto_failover monitor node

🎀 SYNOPSIS 🎀

This command initializes a PostgreSQL cluster and installs the pgautofailover extension so that it's possible to use the new instance to monitor PostgreSQL services:

usage: pg_autoctl create monitor  [ --pgdata --pgport --pgctl --hostname ]

--pgctl           path to pg_ctl
--pgdata          path to data directory
--pgport          PostgreSQL's port number
--hostname        hostname by which postgres is reachable
--auth            authentication method for connections from data nodes
--skip-pg-hba     skip editing pg_hba.conf rules
--run             create node then run pg_autoctl service
--ssl-self-signed setup network encryption using self signed certificates (does NOT protect against MITM)
--ssl-mode        use that sslmode in connection strings
--ssl-ca-file     set the Postgres ssl_ca_file to that file path
--ssl-crl-file    set the Postgres ssl_crl_file to that file path
--no-ssl          don't enable network encryption (NOT recommended, prefer --ssl-self-signed)
--server-key      set the Postgres ssl_key_file to that file path
--server-cert     set the Postgres ssl_cert_file to that file path

🌸 DESCRIPTION 🌸

So pg_autoctl is the client tool that ships with pg_auto_failover, and its whole job is creating and managing Postgres nodes plus the pg_auto_failover monitor node. she's built out of a bunch of sub-commands and every single one of them has its own manual page. very organized, very demure. 💅

👑 OPTIONS 👑

The following options are available to pg_autoctl create monitor:

  • --pgctl — Path to the pg_ctl tool you wanna use for whichever version of PostgreSQL you're running. Defaults to the pg_ctl found in the PATH — but only when there's exactly one pg_ctl entry in the PATH. peep your setup with which -a pg_ctl to check. 🔍 On an RPM based distribution like RHEL or CentOS, the path is usually /usr/pgsql-13/bin/pg_ctl for Postgres 13. On a debian based distribution like debian or ubuntu, it's usually /usr/lib/postgresql/13/bin/pg_ctl for Postgres 13. Those distros also ship the package postgresql-common, which gives you /usr/bin/pg_config — and pg_autoctl can use that tool automatically to discover the default version of Postgres to use on your setup. 🦋
  • --pgdata — Where to initialize a Postgres database cluster, using either pg_ctl initdb or pg_basebackup. Defaults to the environment variable PGDATA.
  • --pgport — Postgres port to use, defaults to 5432.
  • --hostname — Hostname or IP address (both v4 and v6 are supported, inclusivity icon ✨) to use from any other node to connect to this node.

When you don't provide it, a default value gets computed by running the following algorithm:

  1. We get this machine's "public IP" by opening a connection to the 8.8.8.8:53 public service. Then we get the TCP/IP client address that has been used to make that connection.
  2. We then do a reverse DNS lookup on the IP address found in the previous step to fetch a hostname for our local machine.
  3. If the reverse DNS lookup is successful, then pg_autoctl does a forward DNS lookup of that hostname.

When the forward DNS lookup response in step 3. is an IP address found in one of our local network interfaces, then pg_autoctl uses the hostname found in step 2. as the default --hostname. Otherwise it uses the IP address found in step 1.

You may use the --hostname command line option to bypass the whole DNS lookup based process and force the local node name to a fixed value. 🫶

  • --auth — Authentication method used by pg_autoctl when editing the Postgres HBA file to open connections to other nodes. No default value, must be provided by the user. The value --trust is only a good choice for testing and evaluation of pg_auto_failover, see Security settings for pg_auto_failover for more information.
bestie pls. --trust is a testing/evaluation vibe only. do not run that in prod, i am begging 😭
  • --skip-pg-hba — When this option is used then pg_autoctl refrains from any editing of the Postgres HBA file. Please note that editing the HBA file is still needed so that other nodes can connect using either read privileges or replication streaming privileges.

When --skip-pg-hba is used, pg_autoctl still outputs the HBA entries it needs in the logs, it only skips editing the HBA file. so like, the receipts are there, she just isn't touching the file herself. 🙈

  • --run — Immediately run the pg_autoctl service after having created this node.
  • --ssl-self-signed — Generate SSL self-signed certificates to provide network encryption. This does not protect against man-in-the-middle kinds of attacks. See Security settings for pg_auto_failover for more about our SSL settings. 💀
  • --ssl-mode — SSL Mode used by pg_autoctl when connecting to other nodes, including when connecting for streaming replication.
  • --ssl-ca-file — Set the Postgres ssl_ca_file to that file path.
  • --ssl-crl-file — Set the Postgres ssl_crl_file to that file path.
  • --no-ssl — Don't enable network encryption. This is not recommended, prefer --ssl-self-signed.
  • --server-key — Set the Postgres ssl_key_file to that file path.
  • --server-cert — Set the Postgres ssl_cert_file to that file path.

🌈 ENVIRONMENT 🌈

  • PGDATA — Postgres directory location. Can be used instead of the --pgdata option.
  • PG_CONFIG — Can be set to the absolute path to the pg_config Postgres tool. This is mostly used in the context of building extensions, though it can be a useful way to select a Postgres version when several are installed on the same system.
  • PATH — Used the usual way mostly. Some entries that are searched in the PATH by the pg_autoctl command are expected to be found only once, to avoid mistakes with Postgres major versions.
  • PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ... — See the Postgres docs about Environment Variables for details.
  • TMPDIR — The pgcopydb command creates all its work files and directories in ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb.
  • XDG_CONFIG_HOME — The pg_autoctl command stores its configuration files in the standard place XDG_CONFIG_HOME. See the XDG Base Directory Specification.
  • XDG_DATA_HOME — The pg_autoctl command stores its internal states files in the standard place XDG_DATA_HOME, which defaults to ~/.local/share. See the XDG Base Directory Specification.

💜 AUTHOR 💜

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page, bestie 🎀 version 2.1, dated Jan 18, 2025, living in the pg_auto_failover manual — go make that monitor node, she's gonna slay 💅✨🦋

📦 where this page comes from