summaryrefslogtreecommitdiff
path: root/doc/src/sgml/ref/gtm.sgml
blob: b7e8f40bc30390caf93bb4861c728fde6b4a90a9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416

<refentry id="APP-GTM">
 <indexterm zone="app-gtm">
  <primary>gtm</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>gtm</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>gtm</refname>
  <refpurpose>
   provides global transaction management for the <productname>Postgres-XL</productname>
   across the entire cluster.
  </refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>gtm</command>
   <arg rep="repeat"><replaceable>option</></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-GTM-1">
  <title>
   Description
  </title>
  <para>
   The GTM provides consistent transaction management fully compatible with
   vanilla PostgreSQL. It is highly advised to start and stop the GTM
   using gtm_ctl(8).
  </para>

  <para>
   You must provide a GTM configuration
   file <filename>gtm.conf</filename> placed in the GTM working directory
   as specified by <literal>-D</literal> command line option. The
   configuration file specifies the GTM running environment and resources.
  </para>

  <para>
   Some of the parameters specified in the control file can be overridden by 
   command line options.
  </para>

  <para>
   As with other cluster components, the recommended method of
   configuring and managing them is with the <xref linkend="pgxc-ctl"> utility.
 </para>

 </refsect1>

 <refsect1>
  <title>Configuration File</title>

  <para>
   <literal>GTM</literal> configuration parameters are specified in the configuration file 
   <filename>gtm.conf</filename><indexterm><primary>gtm.conf</></> placed in the working directory
   specified as <literal>-D</literal> option
   of <application>gtm</application> command line option as described
   in the next section.
  </para>
  <para>
   The format of the configuration file is patterned after the <filename>postgresql.conf</filename>.
   The options are as follows.
  </para>

<!-- Add description of each gtm.conf entry -->
<!-- Notice
   The following options are found in the source code (gtm_opt.c) but is only for
   internal use and will not be presented in the following list.

    1. data_di
    2. config_file

   Also the following options are for high-availability hook.  This will be
   documented later.

   1. error_reporter
   2. status_reader
-->
  <variablelist>

   <varlistentry id="gtm-opt-active-host" xreflabel="gtm_opt_active_host">
    <term><varname>active_host</varname> (<type>string</type>)
     <indexterm>
      <primary><varname>active_host</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the listen addresses (host name or IP address) of active <application>gtm</application>.  This
      parameter is effective only when this <application>gtm</application>
      is specified as a standby.  There is no default value for this parameter.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-active-port" xreflabel="gtm_opt_active_port">
    <term><varname>active_port</varname> (<type>integer</type>)
     <indexterm>
      <primary><varname>active_port</varname> configuration parameter</primary>
     </indexterm>
    </term>
    <listitem>
     <para>
      Specifies the port number of active <application>gtm</application>.  This
      parameter is effective only when this <application>gtm</application>
      is specified as a GTM standby. The standby connects to the primary gtm
      to obtain a stream of updates of transaction status values.
      There is no default value for this parameter.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-keepalives-count" xreflabel="gtm_opt_keepalives_count">
    <term><varname>keepalives_count</varname> (<type>integer</type>)
    <indexterm>
     <primary><varname>keepalives_count</varname> (<type>integer</type>)</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies <literal>keepalives_count</literal> option for the
      connection to <application>gtm</application>.  This option is
      effective only when it runs as a GTM Standby.
      The default value is zero and keepalives feature is disabled.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-keepalives-idle" xreflabel="gtm_opt_keepalives_idle">
    <term><varname>keepalives_idle</varname> (<type>integer</type>)
    <indexterm>
     <primary><varname>keepalives_idle</varname> (<type>integer</type>)</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies <literal>keepalives_idle</literal> option for the
      connection to <application>gtm</application>.  This option is
      effective only when it runs as a GTM Standby.
      The default value is zero and keepalives feature is disabled.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-keepalives-interval" xreflabel="gtm_opt_keepalives_interval">
    <term><varname>keepalives_interval</varname> (<type>integer</type>)
    <indexterm>
     <primary><varname>keepalives_interval</varname> (<type>integer</type>)</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies <literal>keepalives_interval</literal> option for the
      connection to <application>gtm</application>.  This option is
      effective only when it runs as a GTM Standby.
      The default value is zero and keepalives feature is disabled.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-listen-addresses" xreflabel="gtm_opt_listen_addresses">
    <term><varname>listen_addresses</varname> (<type>string</type>)
    <indexterm>
     <primary><varname>listen_addresses</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies listen addresses (host name or IP address) of
      this <application>gtm</application>
      or <application>gtm</application> standby.
      Default value is '*'.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-log-file" xreflabel="gtm_opt_log_file">
    <term><varname>log_file</varname> (<type>string</type>)
    <indexterm>
     <primary><varname>log_file</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies <filename>log</filename> file name.  This file will be
      created in the working directory of
      this <application>gtm</application> as specified
      by <literal>-D</literal> command line option.
      The default is <filename>gtm.log</filename>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-log-min-messages" xreflabel="gtm_opt_log_min_messages">
    <term><varname>log_min_messages</varname> (<type>enum</type>)
    <indexterm>
     <primary><varname>log_min_messages</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Controls which message levels are written to the log. 
      Valid values are <literal>DEBUG</literal>, <literal>DEBUG5</literal>, 
      <literal>DEBUG4</literal>, <literal>DEBUG3</literal>, <literal>DEBUG2</literal>, 
      <literal>DEBUG1</literal>, <literal>INFO</literal>, <literal>NOTICE</literal>, 
      <literal>WARNING</literal>, <literal>ERROR</literal>, <literal>LOG</literal>, 
      <literal>FATAL</literal> and <literal>PANIC</literal>.  
      Each level includes all the levels that follow it.   
      The later the level, the fewer messages are sent.   
      The default is <literal>WARNING</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-nodename" xreflabel="gtm_opt_nodename">
    <term><varname>nodename</varname> (<type>string</type>)
    <indexterm>
     <primary><varname>nodename</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies the name of this <application>gtm</application> or <application>gtm</application> standby.
      There is no default value for this parameter.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-port" xreflabel="gtm_opt_port">
    <term><varname>port</varname> (<type>integer</type>)
    <indexterm>
     <primary><varname>port</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies the port number of <application>gtm</application> or <application>gtm</application> standby.
      Default value is 6666.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-startup" xreflabel="gtm_opt_startup">
    <term><varname>startup</varname> (<type>enum</type>)
    <indexterm>
     <primary><varname>startup</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies the startup mode of this <application>gtm</application>.
      Valied values are <literal>act</literal> or <literal>standby</literal>.
      <literal>act</literal> means to start up
      this <application>gtm</application> as usual so
      that <application>gtm</application> clients (Coordinators, data
      nodes or gtm-proxies) can connect for transaction
      management.  <literal>standby</literal> means
      this <application>gtm</application> starts up as a backup
      of <literal>act</literal>
      gtm.  <literal>standby</literal> <literal>gtm</literal> can be
      promoted to <literal>act</literal> when <literal>act</literal>
      fails.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry id="gtm-opt-synchronous-backup" xreflabel="gtm_opt_synchronous_backup">
    <term><varname>synchronous-backup</varname> (<type>boolean</type>)
    <indexterm>
     <primary><varname>synchronous-backup</varname> configuration parameter</primary>
    </indexterm></term>
    <listitem>
     <para>
      Specifies if the backup to the GTM-Standby is taken synchronously.   If
      this is turned on, the GTM will send and receive synchronize message to
      make sure that all the backups reached to the standby.
     </para>
     <para>
      If it is turned off, all the backup information will be sent without
      checking they reached the GTM-Standby.
     </para>
     <para>
      Default value is off.
     </para>
    </listitem>
   </varlistentry>


  </variablelist>

 </refsect1>


 <refsect1>
  <title>Options</title>

  <para>
   Options are specified with preceding '<literal>-</literal>', each
   option may be associated with a value. They can be specified
   in <literal>-o</literal> option of gtm_ctl(8).
  </para>

  <para>
   Parameters specified as command line options override these specified in the configuration file described
   in the previous section.
  </para>

  <para>
   Options are as follows:
  </para>

  <para>
   <variablelist>
    <varlistentry>
     <term><option>D</option></term>
     <listitem>
      <para>
       Specify a directory which holds data for gtm or gtm_proxy
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>l</option></term>
     <listitem>
      <para>
       Specify a log file for gtm_ctl.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>x</option></term>
     <listitem>
      <para>
       Specify the global transaction ID to start with. This is needed
       when you start gtm for the first time
       because <command>initdb</command> consumes XID locally and gtm
       should start to give GXID greater than the last one
       each <command>initdb</command> consumed locally. If gtm has
       been shut down gracefully, then this value will be taken from
       the last run.
      </para>
      <para>
       If <literal>-x</literal> option is not specified at the first
       run, initial global transaction ID value will be set to a
       default initial value which is considered to be safe enough (in
       version &version;, it is 10000).  If many statements are
       involved in initdb, you should consider to increasing this
       value.
      </para>
      <para>
       To find the precise value to start with, you should
       run <application>pg_controldata</application> to
       find <literal>Latest checkpoint's NextXID</literal> of all the
       Coordinators and Datanodes and choose the value larger than or
       equals to the maximum value found.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>h</option></term>
     <listitem>
      <para>
       Specify host name or IP address used.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>p</option></term>
     <listitem>
      <para>
       Specify port number to listen.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>

  <para>
    When starting a GTM as a standby instance, the following options can also be provided.
  </para>

  <para>
   <variablelist>
    <varlistentry>
     <term><option>s</option></term>
     <listitem>
      <para>
       Specify if the GTM starts as a standby
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>i</option></term>
     <listitem>
      <para>
       Specify host name or IP address of the active GTM instance to connect to
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>q</option></term>
     <listitem>
      <para>
       Specify port number of the active GTM instance to connect to
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
</refentry>