1PG_AUTOCTL CREATE POSTGRES(1)  pg_auto_failover  PG_AUTOCTL CREATE POSTGRES(1)
2
3
4

NAME

6       pg_autoctl create postgres - pg_autoctl create postgres
7
8       pg_autoctl  create  postgres  -  Initialize a pg_auto_failover postgres
9       node
10

SYNOPSIS

12       The command pg_autoctl create postgres initializes a  standalone  Post‐
13       gres  node  to a pg_auto_failover monitor. The monitor is then handling
14       auto-failover for this Postgres node (as soon as a secondary  has  been
15       registered too, and is known to be healthy).
16
17          usage: pg_autoctl create postgres
18
19            --pgctl           path to pg_ctl
20            --pgdata          path to data directory
21            --pghost          PostgreSQL's hostname
22            --pgport          PostgreSQL's port number
23            --listen          PostgreSQL's listen_addresses
24            --username        PostgreSQL's username
25            --dbname          PostgreSQL's database name
26            --name            pg_auto_failover node name
27            --hostname        hostname used to connect from the other nodes
28            --formation       pg_auto_failover formation
29            --monitor         pg_auto_failover Monitor Postgres URL
30            --auth            authentication method for connections from monitor
31            --skip-pg-hba     skip editing pg_hba.conf rules
32            --pg-hba-lan      edit pg_hba.conf rules for --dbname in detected LAN
33            --ssl-self-signed setup network encryption using self signed certificates (does NOT protect against MITM)
34            --ssl-mode        use that sslmode in connection strings
35            --ssl-ca-file     set the Postgres ssl_ca_file to that file path
36            --ssl-crl-file    set the Postgres ssl_crl_file to that file path
37            --no-ssl          don't enable network encryption (NOT recommended, prefer --ssl-self-signed)
38            --server-key      set the Postgres ssl_key_file to that file path
39            --server-cert     set the Postgres ssl_cert_file to that file path
40            --candidate-priority    priority of the node to be promoted to become primary
41            --replication-quorum    true if node participates in write quorum
42            --maximum-backup-rate   maximum transfer rate of data transferred from the server during initial sync
43

DESCRIPTION

45       Three  different modes of initialization are supported by this command,
46       corresponding to as many implementation strategies.
47
48          1. Initialize a primary node from scratch
49
50             This happens when --pgdata (or the environment  variable  PGDATA)
51             points  to  an  non-existing  or  empty directory. Then the given
52             --hostname is registered to the pg_auto_failover --monitor  as  a
53             member of the --formation.
54
55             The  monitor answers to the registration call with a state to as‐
56             sign  to  the  new  member  of  the  group,  either   SINGLE   or
57             WAIT_STANDBY.  When the assigned state is SINGLE, then pg_autoctl
58             create postgres proceedes to  initialize  a  new  PostgreSQL  in‐
59             stance.
60
61          2. Initialize an already existing primary server
62
63             This  happens  when --pgdata (or the environment variable PGDATA)
64             points to an already existing directory that belongs to  a  Post‐
65             greSQL  instance.  The standard PostgreSQL tool pg_controldata is
66             used to recognize whether the directory belongs to  a  PostgreSQL
67             instance.
68
69             In  that  case, the given --hostname is registered to the monitor
70             in the tentative SINGLE state. When  the  given  --formation  and
71             --group  is  currently empty, then the monitor accepts the regis‐
72             tration and the pg_autoctl create prepares the  already  existing
73             primary server for pg_auto_failover.
74
75          3. Initialize a secondary node from scratch
76
77             This  happens  when --pgdata (or the environment variable PGDATA)
78             points to a non-existing or empty directory, and when the monitor
79             registration call assigns the state WAIT_STANDBY in step 1.
80
81             In  that  case,  the  pg_autoctl create command steps through the
82             initial states of registering a secondary server, which  includes
83             preparing  the primary server PostgreSQL HBA rules and creating a
84             replication slot.
85
86             When the command ends successfully, a PostgreSQL secondary server
87             has  been  created  with pg_basebackup and is now started, catch‐
88             ing-up to the primary server.
89
90          4. Initialize a secondary node from an existing data directory
91
92             When the data directory pointed to by the option --pgdata or  the
93             environment variable PGDATA already exists, then pg_auto_failover
94             verifies that the system identifier matches the one of the  other
95             nodes already existing in the same group.
96
97             The  system  identifier  can be obtained with the command pg_con‐
98             troldata. All nodes in a physical replication setting  must  have
99             the  same  system  identifier, and so in pg_auto_failover all the
100             nodes in a same group have that constraint too.
101
102             When the system identifier matches the already registered  system
103             identifier  of  other  nodes  in the same group, then the node is
104             set-up as a standby and Postgres is started with the primary con‐
105             ninfo pointed at the current primary.
106
107       The  --auth  option  allows setting up authentication method to be used
108       when monitor  node  makes  a  connection  to  data  node  with  pgauto‐
109       failover_monitor  user.  As with the pg_autoctl create monitor command,
110       you could use --auth trust when playing with pg_auto_failover at  first
111       and  consider  something  production  grade later. Also, consider using
112       --skip-pg-hba if you already have your own provisioning  tools  with  a
113       security compliance process.
114
115       See Security settings for pg_auto_failover for notes on .pgpass
116

OPTIONS

118       The following options are available to pg_autoctl create postgres:
119
120       --pgctl
121              Path to the pg_ctl tool to use for the version of PostgreSQL you
122              want to use.
123
124              Defaults to the pg_ctl found in the PATH when there is a  single
125              entry  for  pg_ctl  in the PATH. Check your setup using which -a
126              pg_ctl.
127
128              When using an RPM based distribution such as RHEL or CentOS, the
129              path would usually be /usr/pgsql-13/bin/pg_ctl for Postgres 13.
130
131              When using a debian based distribution such as debian or ubuntu,
132              the path would usually be /usr/lib/postgresql/13/bin/pg_ctl  for
133              Postgres  13.   Those  distributions  also use the package post‐
134              gresql-common which provides /usr/bin/pg_config. This  tool  can
135              be automatically used by pg_autoctl to discover the default ver‐
136              sion of Postgres to use on your setup.
137
138       --pgdata
139              Location where to initialize a Postgres database cluster,  using
140              either  pg_ctl initdb or pg_basebackup. Defaults to the environ‐
141              ment variable PGDATA.
142
143       --pghost
144              Hostname to use when connecting to the local  Postgres  instance
145              from  the  pg_autoctl  process.  By  default, this field is left
146              blank in the connection string,  allowing  to  use  Unix  Domain
147              Sockets  with  the  default path compiled in your libpq version,
148              usually  provided  by  the  Operating  System.  That  would   be
149              /var/run/postgresql when using debian or ubuntu.
150
151       --pgport
152              Postgres port to use, defaults to 5432.
153
154       --listen
155              PostgreSQL's  listen_addresses  to setup. At the moment only one
156              address is supported in this command line option.
157
158       --username
159              PostgreSQL's username to use when connecting to the local  Post‐
160              gres instance to manage it.
161
162       --dbname
163              PostgreSQL's  database name to use in your application. Defaults
164              to being the same as the --username, or to postgres when none of
165              those options are used.
166
167       --name Node  name  used on the monitor to refer to this node. The host‐
168              name is a technical information, and given Postgres requirements
169              on  the  HBA  setup and DNS resolution (both forward and reverse
170              lookups), IP addresses are often used for the hostname.
171
172              The --name option allows using a  user-friendly  name  for  your
173              Postgres nodes.
174
175       --hostname
176              Hostname  or  IP  address  (both v4 and v6 are supported) to use
177              from any other node to connect to this node.
178
179              When not provided, a default value is computed  by  running  the
180              following algorithm.
181
182                 1. We  get this machine's "public IP" by opening a connection
183                    to the given monitor hostname or IP address. Then  we  get
184                    TCP/IP client address that has been used to make that con‐
185                    nection.
186
187                 2. We then do a reverse DNS lookup on the IP address found in
188                    the  previous  step  to fetch a hostname for our local ma‐
189                    chine.
190
191                 3. If the reverse DNS lookup is successful , then  pg_autoctl
192                    does a forward DNS lookup of that hostname.
193
194              When the forward DNS lookup response in step 3. is an IP address
195              found in one of our local network  interfaces,  then  pg_autoctl
196              uses  the  hostname  found in step 2. as the default --hostname.
197              Otherwise it uses the IP address found in step 1.
198
199              You may use the --hostname command line  option  to  bypass  the
200              whole  DNS lookup based process and force the local node name to
201              a fixed value.
202
203       --formation
204              Formation to register the node into on the monitor. Defaults  to
205              the default formation, that is automatically created in the mon‐
206              itor in the pg_autoctl create monitor command.
207
208       --monitor
209              Postgres URI used to connect to the monitor. Must  use  the  au‐
210              toctl_node  username  and  target  the pg_auto_failover database
211              name. It is possible to show the Postgres URI from  the  monitor
212              node using the command pg_autoctl show uri.
213
214       --auth Authentication  method used by pg_autoctl when editing the Post‐
215              gres HBA file to open connections to  other  nodes.  No  default
216              value, must be provided by the user. The value --trust is only a
217              good choice for testing and evaluation of pg_auto_failover,  see
218              Security settings for pg_auto_failover for more information.
219
220       --skip-pg-hba
221              When this option is used then pg_autoctl refrains from any edit‐
222              ing of the Postgres HBA file. Please note that editing  the  HBA
223              file  is  still needed so that other nodes can connect using ei‐
224              ther read privileges or replication streaming privileges.
225
226              When --skip-pg-hba is used, pg_autoctl still outputs the HBA en‐
227              tries it needs in the logs, it only skips editing the HBA file.
228
229       --pg-hba-lan
230              When  this option is used pg_autoctl determines the local IP ad‐
231              dress used to connect to the monitor, and retrieves its netmask,
232              and uses that to compute your local area network CIDR. This CIDR
233              is then opened for connections in the Postgres HBA rules.
234
235              For instance, when the monitor resolves to 192.168.0.1 and  your
236              local   Postgres   node   uses  an  inferface  with  IP  address
237              192.168.0.2/255.255.255.0 to connect to the  monitor,  then  the
238              LAN CIDR is computed to be 192.168.0.0/24.
239
240       --candidate-priority
241              Sets this node replication setting for candidate priority to the
242              given value (between 0 and 100) at node registration on the mon‐
243              itor. Defaults to 50.
244
245       --replication-quorum
246              Sets this node replication setting for replication quorum to the
247              given value (either true or false) at node registration  on  the
248              monitor.   Defaults  to true, which enables synchronous replica‐
249              tion.
250
251       --maximum-backup-rate
252              Sets the maximum transfer rate  of  data  transferred  from  the
253              server  during initial sync. This is used by pg_basebackup.  De‐
254              faults to 100M.
255
256       --run  Immediately run the pg_autoctl service after having created this
257              node.
258
259       --ssl-self-signed
260              Generate SSL self-signed certificates to provide network encryp‐
261              tion. This does not protect against man-in-the-middle  kinds  of
262              attacks.  See  Security  settings  for pg_auto_failover for more
263              about our SSL settings.
264
265       --ssl-mode
266              SSL Mode used by pg_autoctl when connecting to other nodes,  in‐
267              cluding when connecting for streaming replication.
268
269       --ssl-ca-file
270              Set the Postgres ssl_ca_file to that file path.
271
272       --ssl-crl-file
273              Set the Postgres ssl_crl_file to that file path.
274
275       --no-ssl
276              Don't enable network encryption. This is not recommended, prefer
277              --ssl-self-signed.
278
279       --server-key
280              Set the Postgres ssl_key_file to that file path.
281
282       --server-cert
283              Set the Postgres ssl_cert_file to that file path.
284

AUTHOR

286       Microsoft
287
289       Copyright (c) Microsoft Corporation. All rights reserved.
290
291
292
293
2941.6                              Aug 04, 2022    PG_AUTOCTL CREATE POSTGRES(1)
Impressum