--- name: "bucardo_ctl" section: "1p" platform: "linux" package: "bucardo" version: "4.4.0-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/bucardo_ctl" --- # bucardo\_ctl(1p) utility script for controlling the Bucardo program ## NAME bucardo\_ctl - utility script for controlling the Bucardo program ## VERSION This document describes version 4.4.0 of bucardo\_ctl ## SYNOPSIS ``` ./bucardo_ctl install ./bucardo_ctl list dbs ./bucardo_ctl add sync testsync source=herd1 type=pushdelta targetdb=B ./bucardo_ctl add sync testsync source=herd1 type=pushdelta targetdb=B tables=tab1,tab2,tab3 ./bucardo_ctl add database newdb name=internal_name port=5432 host=myserver ./bucardo_ctl add all tables db=foo ./bucardo_ctl add all sequences db=foo ./bucardo_ctl add herd newherd table1 table2 table3 ... ./bucardo_ctl add dbgroup name db1 db2 db3 ... ./bucardo_ctl start "Starting up - Greg" ./bucardo_ctl stop "Bringing down for debugging - Raul E." ./bucardo_ctl ping ./bucardo_ctl status ./bucardo_ctl status sync1 sync2 ./bucardo_ctl kick sync1 sync2 ./bucardo_ctl kick sync1 0 ./bucardo_ctl reload_config ./bucardo_ctl upgrade ./bucardo_ctl reload sync ./bucardo_ctl validate sync ./bucardo_ctl message "Your message here" ./bucardo_ctl config show ./bucardo_ctl config set foo=bar baz=123 ``` ## DESCRIPTION The bucardo\_ctl 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\_ctl 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\_ctl upgrade Upgrades an existing Bucardo installation to the current version of the bucardo\_ctl script. Requires that the bucardo\_ctl 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\_ctl 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\_ctl 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\_ctl list \ \ Lists summary information about databases, tables, sequences, syncs, or herds. Adding anything after the type will look up all matching entries. - **add** Usage: add \ \ Usage: add database \ name=internal\_name port=xxx host=xxx user=xxx pass=xxx service=xxx conn=xxx sourcelimit=xxx targetlimit=xxx ssp=1/0 Usage: add table \[schema\].table db=internal\_db\_name ping=bool standard\_conflict=xxx makedelta=bool herd=xxx Usage: add all tables herd=xxx Usage: add sequence \[schema\].table herd=xxx Usage: add all sequences herd=xxx Usage: add sync syncname options Usage: add herd name Usage: add dbgroup name db1 db2 db3 ... 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 \ \ Removes one or more items from the Bucardo database. Valid item types are database, dbgroup, herd, sync, table, and sequence. - **kick** Usage: ./bucardo\_ctl kick \ \[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\_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. 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\_ctl show \ \[setting2..\] Shows the current values in the bucardo\_config table. Use the keyword 'all' to see all the settings, or specify one or more search terms. - **set** Usage: ./bucardo\_ctl 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\_ctl status \[syncname(s)\] \[--sort=#\] \[--daysback=#\] \[--showdays\] Shows the current status of all known syncs in a tabular format. If given one or more syncnames, shows detailed information for each one. When showing all syncs, the columns are: - 1\. **Name** The name of the sync - 2\. **Type** The type of the sync. `"F"` = fullcopy, `"S"` = swap, `"P"` = pushdelta. In addition, if a sync is overdue, a `"O!"` will appear, and if it is expired, a `"E!"` will appear. - 3\. **State** The current status of this sync. If no sync is running, `"idle"` will appear. If a sync has been requested, but has not started yet, `"WAIT"` will appear, along with how long since the sync was requested. If a sync is currently running, `"RUN"` 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. - 4\. **PID** The PID of the current sync's controller (CTL). Note that if this is not a persistent sync and the state is `"idle"`, this is merely a historical record and does not represent an active process. - 5\. **Last\_good** How long since this sync last ran successfully. Remember that this is affected by the --daysback parameter. - 6\. **Time** The amount of time the last successful sync took to run. - 7\. **I/U/D** The number of inserts. updates, and deletes performed by the last successful sync. - 8\. **Last\_bad** How long since this sync failed to run successfully. Strongly affected by the --daysback parameter. - 9\. **Time** The amount of time the last failed sync took before it was aborted. - **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\_ctl run verbosely. Default is off. - **--quiet** Tells bucardo\_ctl to be as quiet as possible. Default is off. - **--help** Shows a brief summary of usage for bucardo\_ctl. ### 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: - **--daysback=#** Sets how many days backwards to search the old 'q' logs for information. Defaults to 3 days. - **--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\_ctl 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\_ctl will refuse to run unless that file can be read. ## ENVIRONMENT VARIABLES The bucardo\_ctl script uses *$ENV{HOME}* to look for a *.bucardorc* file. ## BUGS The 'status' command does not yet return current information, and the start time in particular should be taken with a grain of salt. 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-2009 Greg Sabino Mullane \ This program is free to use, subject to the limitations in the LICENSE file.