1<refentry id="repmgr-primary-register">
2  <indexterm>
3    <primary>repmgr primary register</primary>
4  </indexterm>
5
6  <refmeta>
7    <refentrytitle>repmgr primary register</refentrytitle>
8  </refmeta>
9
10  <refnamediv>
11    <refname>repmgr primary register</refname>
12    <refpurpose>initialise a repmgr installation and register the primary node</refpurpose>
13  </refnamediv>
14
15
16  <refsect1>
17    <title>Description</title>
18    <para>
19      <command>repmgr primary register</command> registers a primary node in a
20      streaming replication cluster, and configures it for use with &repmgr;, including
21      installing the &repmgr; extension. This command needs to be executed before any
22      standby nodes are registered.
23    </para>
24
25    <note>
26      <para>
27        &repmgr; will attempt to install the &repmgr; extension as part of this command,
28        however this will fail if the <literal>repmgr</literal> user is not a superuser.
29      </para>
30      <para>
31        It's possible to install the &repmgr; extension manually before executing
32        <command>repmgr primary register</command>; in this case &repmgr; will
33        detect the presence of the extension and skip that step.
34      </para>
35
36    </note>
37
38  </refsect1>
39
40  <refsect1>
41    <title>Execution</title>
42    <para>
43      Execute with the <option>--dry-run</option> option to check what would happen without
44      actually registering the primary.
45    </para>
46
47    <note>
48      <para>
49        If providing the configuration file location with <option>-f/--config-file</option>,
50        avoid using a relative path, as &repmgr; stores the configuration file location
51        in the repmgr metadata for use when &repmgr; is executed remotely (e.g. during
52        <xref linkend="repmgr-standby-switchover"/>). &repmgr; will attempt to convert the
53          a relative path into an absolute one, but this may not be the same as the path you
54          would explicitly provide (e.g. <filename>./repmgr.conf</filename> might be converted
55          to <filename>/path/to/./repmgr.conf</filename>, whereas you'd normally write
56          <filename>/path/to/repmgr.conf</filename>).
57      </para>
58    </note>
59
60	<para>
61      <command>repmgr master register</command> can be used as an alias for
62      <command>repmgr primary register</command>.
63    </para>
64
65  </refsect1>
66
67  <refsect1>
68    <title>User permission requirements</title>
69    <para>
70      The <literal>repmgr</literal> user must be a superuser in order for &repmgr;
71      to be able to install the <literal>repmgr</literal> extension.
72    </para>
73    <para>
74      If this is not the case, the <literal>repmgr</literal> extension can be installed
75      manually before executing <command>repmgr primary register</command>.
76    </para>
77    <para>
78      A future &repmgr; release will enable the provision of a <option>--superuser</option>
79      name for the installation of the extension.
80    </para>
81  </refsect1>
82  <refsect1>
83
84    <title>Options</title>
85    <variablelist>
86
87      <varlistentry>
88        <term><option>--dry-run</option></term>
89        <listitem>
90          <para>
91            Check prerequisites but don't actually register the primary.
92          </para>
93        </listitem>
94      </varlistentry>
95
96      <varlistentry>
97       <term><option>-F</option>, <option>--force</option></term>
98        <listitem>
99          <para>
100            Overwrite an existing node record
101          </para>
102        </listitem>
103      </varlistentry>
104
105    </variablelist>
106  </refsect1>
107
108
109  <refsect1 id="repmgr-primary-register-events">
110    <title>Event notifications</title>
111    <para>
112      Following <link linkend="event-notifications">event notifications</link> will be generated:
113      <itemizedlist spacing="compact" mark="bullet">
114        <listitem>
115          <simpara><literal>cluster_created</literal></simpara>
116        </listitem>
117        <listitem>
118          <simpara><literal>primary_register</literal></simpara>
119        </listitem>
120      </itemizedlist>
121    </para>
122  </refsect1>
123
124</refentry>
125