BUCARDO(1p) User Contributed Perl Documentation BUCARDO(1p)
NAME
bucardo - utility script for controlling the Bucardo program
VERSION
This document describes version 4.99.5 of bucardo
SYNOPSIS
./bucardo install
./bucardo list dbs
./bucardo add sync testsync source=herd1 type=pushdelta targetdb=B
./bucardo add sync testsync source=herd1 type=pushdelta targetdb=B tables=tab1,tab2,tab3
./bucardo add database newdb dbname=internal_name port=5432 host=myserver
./bucardo add all tables db=foo [herd=x] [pkonly]
./bucardo add all sequences db=foo [herd=x]
./bucardo add herd newherd table1 table2 table3 ...
./bucardo add dbgroup name db1 db2 db3 ...
./bucardo start "Starting up - Greg"
./bucardo stop "Bringing down for debugging - Raul E."
./bucardo ping
./bucardo status
./bucardo status sync1 sync2
./bucardo kick sync1 sync2
./bucardo kick sync1 0
./bucardo reload_config
./bucardo upgrade
./bucardo reload sync
./bucardo validate sync
./bucardo message "Your message here"
./bucardo config show
./bucardo config set foo=bar baz=123
DESCRIPTION
The bucardo script is the main interaction to a running Bucardo instance. It can be used to start and stop Bucardo, add new items, kick
syncs, and even install and upgrade Bucardo itself. For more complete documentation, please view the wiki at:
http://bucardo.org/
COMMANDS
install
Usage: ./bucardo install
Attempts to install the Bucardo schema from the file 'bucardo.schema' into an existing Postgres cluster. The user 'bucardo' and
database 'bucardo' will be created first as needed. This is an interactive installer, but you can supply the following values from the
command line:
--dbuser (defaults to postgres)
--dbname (defaults to postgres)
--dbport (defaults to 5432)
--piddir (defaults to /var/run/bucardo/)
upgrade
Usage: ./bucardo upgrade
Upgrades an existing Bucardo installation to the current version of the bucardo script. Requires that the bucardo script and the
bucardo.schema file be the same version. All changes should be backwards compatible, but you may need to re-validate existing scripts
to make sure changes get propagated to all databases.
start
Usage: ./bucardo start "Reason --name"
Restarts Bucardo cleanly by first issuing the equivalent of a stop to ask any existing Bucardo processes 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.
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.
stop
Usage: ./bucardo stop "Reason --name"
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.
list
Usage: ./bucardo list <type> <regex>
Lists summary information about dbs, dbgroups, tables, sequences, syncs, herds, customnames, customcols or customcode. Adding anything
after the type will look up all matching entries.
add Usage: add <item_type> <item_name>
Usage: add db <dbname> dbname=internal_name port=xxx host=xxx user=xxx pass=xxx service=xxx conn=xxx ssp=1/0
Usage: add dbgroup name db1 db2 db3 ...
Usage: add table [schema].table db=internal_db_name ping=bool standard_conflict=xxx herd=xxx
Usage: add all tables [herd=xxx] [pkonly]
Usage: add sequence [schema].table herd=xxx
Usage: add all sequences herd=xxx
Usage: add sync syncname options
Usage: add herd name
Usage: add customname tablename newtablename [sync=x db=x]
Usage: add customcols tablename select_clause [sync=x db=x]
Usage: add customcode <name> <whenrun=value> <src_code=filename> [optional information]
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).
remove
Usage: remove <item_type> <item_name>
Removes one or more items from the Bucardo database. Valid item types are database, dbgroup, herd, sync, table, and sequence.
kick
Usage: ./bucardo kick <syncname(s)> [timeout]
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 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.
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.
reload_config
Forces Bucardo to reload the bucardo_config file, and then restart all processes to ensure that the new information is loaded.
show
Usage: ./bucardo show <all|setting1> [setting2..]
Shows the current settings in the bucardo_config table. Use the keyword 'all' to see all the settings, or specify one or more search
terms.
set Usage: ./bucardo set setting1=value [setting2=value]
Sets one or more items inside the bucardo_config table. Setting names are case-insensitive.
ping
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.
status
Usage: ./bucardo status [syncname(s)] [--sort=#] [--showdays] [--compress]
Shows the brief status of all known syncs in a tabular format. If given one or more syncnames, shows detailed information for each one.
To see detailed information for all syncs, simply use 'status all'.
When showing brief information, the columns are:
1. Name The name of the sync
2. State
The state of the sync. Can be 'Good', 'Bad', 'Empty', or 'No records found'
3. Last good
When the sync last successfully ran.
4. Time How long it has been since the last sync success
5. Last I/U
The number of insert and deletes performed by the last successful sync. May also show the number of rows truncated (T) or
conflicted (C), if applicable.
6. Last bad
When the sync last failed.
7. Time How long it has been since the last sync failure
activate syncname [syncname2 syncname3 ...] [timeout]
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.
deactivate syncname [syncname2 syncname3 ...] [timeout]
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.
message
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.
OPTIONS
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.
--dbport=number
--dbhost=string
--dbname=string
--dbuser=string
--dbpass=string
The port, host, and name of the Bucardo database, the user to connect as, and the password to use.
--verbose
Makes bucardo run verbosely. Default is off.
--quiet
Tells bucardo to be as quiet as possible. Default is off.
--help
Shows a brief summary of usage for bucardo.
Kick arguments
The following arguments are only used with the 'kick' command:
--retry=#
The number of times to retry a sync if it fails. Defaults to 0.
--retrysleep
How long to sleep, in seconds, between each retry attempt.
--notimer
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.
Status arguments
The following arguments are only used with the 'status' command:
--showdays
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"
--compress
Specifies whether or not to compress the time interval by removing spaces. Mostly used to limit the width of the 'status' display.
--sort=#
Requests sorting of the 'status' output by one of the nine columns. Use a negative number to reverse the sort order.
Startup arguments
The following arguments are only applicable when using the "start" command:
--sendmail
Tells Bucardo whether or not to send mail on interesting events: startup, shutdown, and errors. Default is on. Only applicable when
using ./bucardo start.
--extraname=string
A short string that will be appended to the version string as output by the Bucardo process names. Mostly useful for debugging.
--debugfilesep
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.
--debugsyslog
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".
--debugfile
If set, writes detailed debugging information to one or more files.
--debugdir=directory name
Directory where the debug files should go.
--debugname=string
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".
--cleandebugs
Forces removal of all old debug files before running.
FILES
In addition to command-line configurations, you can put any options inside of a file. The file .bucardorc in the current directory will be
used if found. If not found, then the file ~/.bucardorc will be used. Finally, the file /etc/bucardorc will be used if available. 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. All bucardorc files can be ignored by supplying a "--no-bucardorc" argument. A specific file
can be forced with the "--bucardorc=file" option; if this option is set, bucardo will refuse to run unless that file can be read.
ENVIRONMENT VARIABLES
The bucardo script uses $ENV{HOME} to look for a .bucardorc file.
BUGS
Bug reports and feature requests are always welcome, please visit http://bucardo.org or email bucardo-general@bucardo.org.
SEE ALSO
Bucardo
COPYRIGHT
Copyright 2006-2012 Greg Sabino Mullane <greg@endpoint.com>
This program is free to use, subject to the limitations in the LICENSE file.
perl v5.14.2 2012-06-04 BUCARDO(1p)