forked from bucardo/bucardo
-
Notifications
You must be signed in to change notification settings - Fork 0
/
bucardo_ctl.html
433 lines (376 loc) · 17.9 KB
/
bucardo_ctl.html
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
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>bucardo_ctl - utility script for controlling the Bucardo program</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#version">VERSION</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#commands">COMMANDS</a></li>
<li><a href="#options">OPTIONS</a></li>
<ul>
<li><a href="#kick_arguments">Kick arguments</a></li>
<li><a href="#status_arguments">Status arguments</a></li>
<li><a href="#startup_arguments">Startup arguments</a></li>
</ul>
<li><a href="#files">FILES</a></li>
<li><a href="#environment_variables">ENVIRONMENT VARIABLES</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>bucardo_ctl - utility script for controlling the Bucardo program</p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>This documents describes bucardo_ctl version 3.2.7</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
./bucardo_ctl start "Starting up - Greg"</pre>
<pre>
./bucardo_ctl stop "Bringing down for debugging - Raul E."</pre>
<pre>
./bucardo_ctl list dbs</pre>
<pre>
./bucardo_ctl add sync testsync source=herd1 type=pushdelta targetdb=B</pre>
<pre>
./bucardo_ctl add database newdb name=internal_name port=5432 host=myserver user=postgres</pre>
<pre>
./bucardo_ctl add table some_schema.some_table db=internal_db_name ping=bool standard_conflict=source</pre>
<pre>
./bucardo_ctl add herd newherd</pre>
<pre>
./bucardo_ctl add dbgroup name db1 db2 db3 ...</pre>
<pre>
./bucardo_ctl ping</pre>
<pre>
./bucardo_ctl status</pre>
<pre>
./bucardo_ctl status sync1 sync2</pre>
<pre>
./bucardo_ctl kick sync1 sync2</pre>
<pre>
./bucardo_ctl kick sync1 0 --retry=10</pre>
<pre>
./bucardoctl reload_config</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The bucardo_ctl script is used to control the operation of a Bucardo process. Primarily it is
used for stopping and starting Bucardo, viewing current information, and for kicking off named
syncs. The script needs to know how to connect to the Bucardo database: this information can
be passed as arguments or hard-coded into the script itself. If you have multiple Bucardos
running, it is recommended that you create aliases for each database.</p>
<p>
</p>
<hr />
<h1><a name="commands">COMMANDS</a></h1>
<dl>
<dt><strong><a name="item_start"><strong>start</strong></a></strong></dt>
<dd>
<p>Usage: ./bucardo_ctl start "Reason --name"</p>
<p>Restarts Bucardo cleanly by first issuing the equivalent of a stop to ask any existing Bucardo
proceses to exit, and then starting a new Bucardo MCP process. A short reason and name should
be provided - these are logged in the reason_file file and sent in the email sent when Bucardo
has been started up.</p>
<p>Before attempting to kill any old processes, a ping command with a timeout of 5 seconds is issued.
If this returns successfully (indicating an active MCP process already running), the script will
exit with a return value of 2.</p>
</dd>
<dt><strong><a name="item_stop"><strong>stop</strong></a></strong></dt>
<dd>
<p>Usage: ./bucardo_ctl stop "Reason --name"</p>
<p>Forces Bucardo to quit by creating a stop file which all MCP, CTL, and KID processes should
detect and cause them to exit. Note that active syncs will not exit right away, as they
will not look for the stop file until they have finished their current run. Typically,
you should scan the list of processes after running this program to make sure that all Bucardo
processes have stopped. One should also provide a reason for issuing the stop - usually
this is a short explanation and your name. This is logged in the reason_file file and
is also used by Bucardo when it exits and sends out mail about its death.</p>
</dd>
<dt><strong><a name="item_list"><strong>list</strong></a></strong></dt>
<dd>
<p>Usage: ./bucardo_ctl list <type> <regex></p>
<p>Lists summary information about databases, goats, herds, or syncs. Adding anything after the
type will look up all matching entries.</p>
</dd>
<dt><strong><a name="item_add"><strong>add</strong></a></strong></dt>
<dd>
<p>Usage: add <item_type> <item_name></p>
<p>Usage: add database <dbname> name=internal_name port=xxx host=xxx user=xxx pass=xxx service=xxx conn=xxx sourcelimit=xxx targetlimit=xxx</p>
<p>Usage: add table [schema].table db=internal_db_name ping=bool standard_conflict=xxx</p>
<p>Usage: add sync syncname options</p>
<p>Usage: add herd name</p>
<p>Usage: add dbgroup name db1 db2 db3 ...</p>
<p>Tells Bucardo about new objects it should know about. These commands can
replace direct manipulation of the tables in the bucardo schema for the
supported object types (you'll still need to add things like the mappings between objects on your own).</p>
</dd>
<dt><strong><a name="item_kick"><strong>kick</strong></a></strong></dt>
<dd>
<p>Usage: ./bucardo_ctl kick <syncname(s)> [timeout]</p>
<p>Tells one or more named syncs to fire as soon as possible. Note that this simply sends a request that
the sync fire: it may not start right away if the same sync is already running, or if the source or
target database has exceeded the number of allowed Bucardo connections. If the final argument is a
number, it is treated as a timeout. If this number is zero, the bucardo_ctl command will not return
until the sync has finished. For any other number, the sync will wait at most that number of seconds.
If any sync has not finished before the timeout, a false value is returned. In all other cases, a
true value is returned.</p>
<p>If a timeout is given, the total completion time in seconds is also displayed. If the sync is going to
multiple targets, the time that each target takes from the start of the kick is also shown as each
target finishes.</p>
</dd>
<dt><strong><a name="item_reload_config"><strong>reload_config</strong></a></strong></dt>
<dd>
<p>Forces Bucardo to reload the bucardo_config file, and then restart all processes to ensure that the new
information is loaded.</p>
</dd>
<dt><strong><a name="item_ping"><strong>ping</strong></a></strong></dt>
<dd>
<p>Sends a ping notice to the MCP process to see if it will respond. By default, it will wait 15 seconds. A
numeric argument will change this timeout. Using a 0 as the timeout indicates waiting forever. If a response
was returned, the program will exit with a value of 0. If it times out, the value will be 1.</p>
</dd>
<dt><strong><a name="item_status"><strong>status</strong></a></strong></dt>
<dd>
<p>Usage: ./bucardo_ctl status [syncname(s)] [--sort=#] [--daysback=#] [--showdays]</p>
<p>Shows the current status of all known syncs in a tabular format. If given one or more syncnames,
shows detailed information for each one.</p>
<p>When showing all syncs, the columns are:</p>
<ol>
<li><strong><a name="item_name"><strong>Name</strong></a></strong>
<p>The name of the sync</p>
</li>
<li><strong><a name="item_type"><strong>Type</strong></a></strong>
<p>The type of the sync. <code>F</code> = fullcopy, <code>S</code> = swap, <code>P</code> = pushdelta. In addition, if a sync is overdue, a <code>O!</code> will
appear, and if it is expired, a <code>E!</code> will appear.</p>
</li>
<li><strong><a name="item_state"><strong>State</strong></a></strong>
<p>The current status of this sync. If no sync is running, <code>idle</code> will appear. If a sync has been rquested, but has not
started yet, <code>WAIT</code> will appear, along with how long since the sync was requested. If a sync is
currently running, <code>RUN</code> will appear, followed by the amount of time the sync has been running, followed by which
target the sync is running against. Note that syncs running to more than one database at a time will only show
the one most recently started.</p>
</li>
<li><strong><a name="item_pid"><strong>PID</strong></a></strong>
<p>The PID of the current sync's controller (CTL). Note that if this is not a persistent sync and the state is <code>idle</code>,
this is merely a historical record and does not represent an active process.</p>
</li>
<li><strong><a name="item_last_good"><strong>Last_good</strong></a></strong>
<p>How long since this sync last ran succesfully. Remember that this is affected by the --daysback parameter.</p>
</li>
<li><strong><a name="item_time"><strong>Time</strong></a></strong>
<p>The amount of time the last successful sync took to run.</p>
</li>
<li><strong><a name="item_i_"><strong>I/U/D</strong></a></strong>
<p>The number of inserts. updates, and deletes performed by the last successful sync.</p>
</li>
<li><strong><a name="item_last_bad"><strong>Last_bad</strong></a></strong>
<p>How long since this sync failed to run successfully. Strongly affected by the --daysback parameter.</p>
</li>
<li><strong><strong>Time</strong></strong>
<p>The amount of time the last failed sync took before it was aborted.</p>
</li>
</ol>
</dd>
<dt><strong><a name="item_activate_syncname__5bsyncname2_syncname3__2e_2e_2e"><strong>activate</strong> syncname [syncname2 syncname3 ...] [timeout]</a></strong></dt>
<dd>
<p>Activates one or more named syncs. If given a timeout argument, it will wait until it has received
confirmation from Bucardo that each sync has been successfully activated.</p>
</dd>
<dt><strong><a name="item_deactivate_syncname__5bsyncname2_syncname3__2e_2e_"><strong>deactivate</strong> syncname [syncname2 syncname3 ...] [timeout]</a></strong></dt>
<dd>
<p>Deactivates one or more named syncs. If given a timeout argument, it will wait until it has received
confirmation from Bucardo that the sync has been successfully deactivated.</p>
</dd>
<dt><strong><a name="item_upgrade"><strong>upgrade</strong></a></strong></dt>
<dd>
<p>Performs an upgrade of Bucardo itself, by making sure the connected Bucardo database has a copy of the
latest schema. This should always be run after upgrading Bucardo, and will prompt you before making
any permanent changes.</p>
</dd>
<dt><strong><a name="item_message"><strong>message</strong></a></strong></dt>
<dd>
<p>Adds a message to the running Bucardo logs. This message will appear prefixed with "MESSAGE: ". If
Bucardo is not running, the message will go to the logs the next time Bucardo is running and someone
adds another message.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="options">OPTIONS</a></h1>
<p>It is usually easier to set most of these options at the top of the script, or make an alias for them,
as they will not change very often if at all.</p>
<dl>
<dt><strong><a name="item__2d_2ddbport_3dnumber"><strong>--dbport=number</strong></a></strong></dt>
<dt><strong><a name="item__2d_2ddbhost_3dstring"><strong>--dbhost=string</strong></a></strong></dt>
<dt><strong><a name="item__2d_2ddbname_3dstring"><strong>--dbname=string</strong></a></strong></dt>
<dt><strong><a name="item__2d_2ddbuser_3dstring"><strong>--dbuser=string</strong></a></strong></dt>
<dt><strong><a name="item__2d_2ddbpass_3dstring"><strong>--dbpass=string</strong></a></strong></dt>
<dd>
<p>The port, host, and name of the Bucardo database, the user to connect as, and the password to use.</p>
</dd>
<dt><strong><a name="item__2d_2dverbose"><strong>--verbose</strong></a></strong></dt>
<dd>
<p>Tells Bucardo (not bucardo_ctl) to run in verbose mode. Default is on. Turning this off is not recommended.</p>
</dd>
<dt><strong><a name="item__2d_2dctlverbose"><strong>--ctlverbose</strong></a></strong></dt>
<dd>
<p>Makes bucardo_ctl run verbosely. Default is off.</p>
</dd>
<dt><strong><a name="item__2d_2dctlquiet"><strong>--ctlquiet</strong></a></strong></dt>
<dd>
<p>Tells bucardo_ctl to be as quiet as possible. Default is off.</p>
</dd>
<dt><strong><a name="item__2d_2dhelp"><strong>--help</strong></a></strong></dt>
<dd>
<p>Shows a brief summary of usage for bucardo_ctl.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="kick_arguments">Kick arguments</a></h2>
<p>The following arguments are only used with the 'kick' command:</p>
<dl>
<dt><strong><a name="item__2d_2dretry_3d_23"><strong>--retry=#</strong></a></strong></dt>
<dd>
<p>The number of times to retry a sync if it fails. Defaults to 0.</p>
</dd>
<dt><strong><a name="item__2d_2dretrysleep"><strong>--retrysleep</strong></a></strong></dt>
<dd>
<p>How long to sleep, in seconds, between each retry attempt.</p>
</dd>
<dt><strong><a name="item__2d_2dnotimer"><strong>--notimer</strong></a></strong></dt>
<dd>
<p>By default, kicks with a timeout argument give a running real-time summary of time elapsed by
using the backspace character. This may not be wanted if running a kick, for example,
via a cronjob, so turning --notimer on will simply print the entire message without backspaces.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="status_arguments">Status arguments</a></h2>
<p>The following arguments are only used with the 'status' command:</p>
<dl>
<dt><strong><a name="item__2d_2ddaysback_3d_23"><strong>--daysback=#</strong></a></strong></dt>
<dd>
<p>Sets how many days backwards to search the old 'q' logs for information. Defaults to 3 days.</p>
</dd>
<dt><strong><a name="item__2d_2dshowdays"><strong>--showdays</strong></a></strong></dt>
<dd>
<p>Specifies whether or not do list the time interval with days, or simply show the hours. For example,
"3d 12h 6m 3s" vs. "48h 6m 3s"</p>
</dd>
<dt><strong><a name="item__2d_2dcompress"><strong>--compress</strong></a></strong></dt>
<dd>
<p>Specifies whether or not to compress the time interval by removing spaces. Mostly used to limit
the width of the 'status' display.</p>
</dd>
<dt><strong><a name="item__2d_2dsort_3d_23"><strong>--sort=#</strong></a></strong></dt>
<dd>
<p>Requests sorting of the 'status' output by one of the nine columns. Use a negative number to reverse
the sort order.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="startup_arguments">Startup arguments</a></h2>
<p>The following arguments are only applicable when using the "start" command:</p>
<dl>
<dt><strong><a name="item__2d_2dsendmail"><strong>--sendmail</strong></a></strong></dt>
<dd>
<p>Tells Bucardo whether or not to send mail on interesting events: startup, shutdown, and errors. Default is on.
Only applicable when using ./bucardo_ctl start.</p>
</dd>
<dt><strong><a name="item__2d_2dextraname_3dstring"><strong>--extraname=string</strong></a></strong></dt>
<dd>
<p>A short string that will be appended to the version string as output by the Bucardo process names. Mostly
useful for debugging.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugfilesep"><strong>--debugfilesep</strong></a></strong></dt>
<dd>
<p>Forces creation of separate log files for each Bucardo process of the form "log.bucardo.X.Y",
where X is the type of process (MCP, CTL, or KID), and Y is the process ID.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugstderr"><strong>--debugstderr</strong></a></strong></dt>
<dd>
<p>Sends all log messages to standard error. Off by default.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugstdout"><strong>--debugstdout</strong></a></strong></dt>
<dd>
<p>Sends all log messages to standard out. Off by default.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugsyslog"><strong>--debugsyslog</strong></a></strong></dt>
<dd>
<p>Sends all log messages to the syslog daemon. On by default. The facility used is controlled by
the row "syslog_facility" in the bucardo_config table, and defaults to "LOG_LOCAL1".</p>
</dd>
<dt><strong><a name="item__2d_2ddebugfile"><strong>--debugfile</strong></a></strong></dt>
<dd>
<p>If set, writes detailed debugging information to one or more files.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugdir_3ddirectory_name"><strong>--debugdir=directory name</strong></a></strong></dt>
<dd>
<p>Directory where the debug files should go.</p>
</dd>
<dt><strong><a name="item__2d_2ddebugname_3dstring"><strong>--debugname=string</strong></a></strong></dt>
<dd>
<p>Appends the given string to the end of the default debug file name, "log.bucardo". A dot is added
before the name as well, so a debugname of "rootdb" would produce a log file named "log.bucardo.rootdb".</p>
</dd>
<dt><strong><a name="item__2d_2dcleandebugs"><strong>--cleandebugs</strong></a></strong></dt>
<dd>
<p>Forces removal of all old debug files before running.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="files">FILES</a></h1>
<p>In addition to command-line configurations, you can put any options inside of a file. The file <em>.bucardorc</em> in
the current directory will be used if found. If not found, then the file <em>~/.bucardorc</em> will be used. The format
of the file is option = value, one per line. Any line starting with a '#' will be skipped. Any values loaded
from a .bucardorc file will be overwritten by command-line options.</p>
<p>
</p>
<hr />
<h1><a name="environment_variables">ENVIRONMENT VARIABLES</a></h1>
<p>The bucardo_ctl script uses <em>$ENV{HOME}</em> to look for a <em>.bucardorc</em> file.</p>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>The 'status' command does not yet return current information, and the start time in particular should be
taken with a grain of salt.</p>
<p>Bug reports and feature requests are always welcome, please visit <a href="http://bucardo.org">http://bucardo.org</a> or email <a href="mailto:bucardo-general@bucardo.org.">bucardo-general@bucardo.org.</a></p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>Bucardo</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2006-2009 Greg Sabino Mullane <<a href="mailto:greg@endpoint.com">greg@endpoint.com</a>></p>
<p>This program is free to use, subject to the limitations in the LICENSE file.</p>
</body>
</html>