.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PG_AUTOCTL CREATE MONITOR" "1" "Nov 06, 2022" "2.0" "pg_auto_failover"
.SH NAME
pg_autoctl create monitor \- pg_autoctl create monitor
.sp
pg_autoctl create monitor \- Initialize a pg_auto_failover monitor node
.SH SYNOPSIS
.sp
This command initializes a PostgreSQL cluster and installs the
\fIpgautofailover\fP extension so that it\(aqs possible to use the new instance to
monitor PostgreSQL services:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: pg_autoctl create monitor  [ \-\-pgdata \-\-pgport \-\-pgctl \-\-hostname ]

\-\-pgctl           path to pg_ctl
\-\-pgdata          path to data directory
\-\-pgport          PostgreSQL\(aqs 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\(aqt 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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The pg_autoctl tool is the client tool provided by pg_auto_failover to
create and manage Postgres nodes and the pg_auto_failover monitor node. The
command is built with many sub\-commands that each have their own manual
page.
.SH OPTIONS
.sp
The following options are available to \fBpg_autoctl create monitor\fP:
.INDENT 0.0
.TP
.B  \-\-pgctl
Path to the \fBpg_ctl\fP tool to use for the version of PostgreSQL you want
to use.
.sp
Defaults to the \fBpg_ctl\fP found in the PATH when there is a single entry
for \fBpg_ctl\fP in the PATH. Check your setup using \fBwhich \-a pg_ctl\fP\&.
.sp
When using an RPM based distribution such as RHEL or CentOS, the path
would usually be \fB/usr/pgsql\-13/bin/pg_ctl\fP for Postgres 13.
.sp
When using a debian based distribution such as debian or ubuntu, the path
would usually be \fB/usr/lib/postgresql/13/bin/pg_ctl\fP for Postgres 13.
Those distributions also use the package \fBpostgresql\-common\fP which
provides \fB/usr/bin/pg_config\fP\&. This tool can be automatically used by
\fBpg_autoctl\fP to discover the default version of Postgres to use on your
setup.
.TP
.B  \-\-pgdata
Location where to initialize a Postgres database cluster, using either
\fBpg_ctl initdb\fP or \fBpg_basebackup\fP\&. Defaults to the environment
variable \fBPGDATA\fP\&.
.TP
.B  \-\-pgport
Postgres port to use, defaults to 5432.
.TP
.B  \-\-hostname
Hostname or IP address (both v4 and v6 are supported) to use from any
other node to connect to this node.
.sp
When not provided, a default value is computed by running the following
algorithm.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
We get this machine\(aqs "public IP" by opening a connection to the
8.8.8.8:53 public service. Then we get TCP/IP client address that
has been used to make that connection.
.IP 2. 3
We then do a reverse DNS lookup on the IP address found in the
previous step to fetch a hostname for our local machine.
.IP 3. 3
If the reverse DNS lookup is successful , then \fBpg_autoctl\fP does a
forward DNS lookup of that hostname.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
When the forward DNS lookup response in step 3. is an IP address found in
one of our local network interfaces, then \fBpg_autoctl\fP uses the hostname
found in step 2. as the default \fB\-\-hostname\fP\&. Otherwise it uses the IP
address found in step 1.
.sp
You may use the \fB\-\-hostname\fP command line option to bypass the whole DNS
lookup based process and force the local node name to a fixed value.
.TP
.B  \-\-auth
Authentication method used by \fBpg_autoctl\fP when editing the Postgres HBA
file to open connections to other nodes. No default value, must be
provided by the user. The value \fB\-\-trust\fP is only a good choice for
testing and evaluation of pg_auto_failover, see \fI\%Security settings for pg_auto_failover\fP for more
information.
.TP
.B  \-\-skip\-pg\-hba
When this option is used then \fBpg_autoctl\fP 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.
.sp
When \fB\-\-skip\-pg\-hba\fP is used, \fBpg_autoctl\fP still outputs the HBA
entries it needs in the logs, it only skips editing the HBA file.
.TP
.B  \-\-run
Immediately run the \fBpg_autoctl\fP service after having created this
node.
.TP
.B  \-\-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
\fI\%Security settings for pg_auto_failover\fP for more about our SSL settings.
.TP
.B  \-\-ssl\-mode
SSL Mode used by \fBpg_autoctl\fP when connecting to other nodes,
including when connecting for streaming replication.
.TP
.B  \-\-ssl\-ca\-file
Set the Postgres \fBssl_ca_file\fP to that file path.
.TP
.B  \-\-ssl\-crl\-file
Set the Postgres \fBssl_crl_file\fP to that file path.
.TP
.B  \-\-no\-ssl
Don\(aqt enable network encryption. This is not recommended, prefer
\fB\-\-ssl\-self\-signed\fP\&.
.TP
.B  \-\-server\-key
Set the Postgres \fBssl_key_file\fP to that file path.
.TP
.B  \-\-server\-cert
Set the Postgres \fBssl_cert_file\fP to that file path.
.UNINDENT
.SH ENVIRONMENT
.sp
PGDATA
.INDENT 0.0
.INDENT 3.5
Postgres directory location. Can be used instead of the \fB\-\-pgdata\fP
option.
.UNINDENT
.UNINDENT
.sp
PG_CONFIG
.INDENT 0.0
.INDENT 3.5
Can be set to the absolute path to the \fI\%pg_config\fP 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.
.UNINDENT
.UNINDENT
.sp
PATH
.INDENT 0.0
.INDENT 3.5
Used the usual way mostly. Some entries that are searched in the PATH by
the \fBpg_autoctl\fP command are expected to be found only once, to avoid
mistakes with Postgres major versions.
.UNINDENT
.UNINDENT
.sp
PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ...
.INDENT 0.0
.INDENT 3.5
See the \fI\%Postgres docs about Environment Variables\fP for details.
.UNINDENT
.UNINDENT
.sp
TMPDIR
.INDENT 0.0
.INDENT 3.5
The pgcopydb command creates all its work files and directories in
\fB${TMPDIR}/pgcopydb\fP, and defaults to \fB/tmp/pgcopydb\fP\&.
.UNINDENT
.UNINDENT
.sp
XDG_CONFIG_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its configuration files in the standard
place XDG_CONFIG_HOME. See the \fI\%XDG Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.sp
XDG_DATA_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its internal states files in the standard
place XDG_DATA_HOME, which defaults to \fB~/.local/share\fP\&. See the \fI\%XDG
Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.SH AUTHOR
Microsoft
.SH COPYRIGHT
Copyright (c) Microsoft Corporation. All rights reserved.
.\" Generated by docutils manpage writer.
.