.\" $HeadURL$ $LastChangedRevision$ .\" vim: filetype=nroff .\" For ellipsis, use '\&' in front of three dots, which is a zero width space, which .\" avoids putting '.' in column 1. '\&' is in the 'man' package. See groff_man(7) for more details. .TH RDW2 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN" .SH NAME rdw2 \- backup manager .br .ne 5 .SH SYNOPSIS .B rdw2 \*[ade_standard_synopsis_component] [ .B \-\-db\-file=\fIdb\-file ] [ .B \-\-no\-update\-cron ] { .B \-\-add\-client .I client\-id .I type .I hostname .I client\-labelling\-method | .B \-\-add\-dle .I dle\-id .I set\-id .I type .I client\-id .I dle\-accesspoint .I backup\-method .I labelling\-method | .B \-\-add\-medium .I medium\-id .I type .I labelling\-method .I medium\-accesspoint | .B \-\-add\-set .I set\-id .I schedule\-id | .B \-\-backup\-dle .I dle\-id | .B \-\-backup\-set .I set\-id | .B \-\-check\-dle .I dle\-id | .B \-\-check\-set .I set\-id | .B \-\-del\-client .I client\-id | .B \-\-del\-dle .I dle\-id | .B \-\-del\-medium .I medium\-id | .B \-\-del\-set .I set\-id | .B \-\-edit | .B \-\-add\-filter \fIfilter\-regexp\fB \fIset\-id\fB \fIdle\-id\fB \fIbackup\-method\fB | .B \-\-del\-filter \fIfilter\-regexp\fB \fIset\-id\fB \fIdle\-id\fB \fIbackup\-method\fB | .B \-\-list\-all [ .I pattern \&... ] | .B \-\-list\-backups [ .I pattern \&... ] | .B \-\-list\-clients [ .I pattern \&... ] | .B \-\-list\-dle\-media .I dle\-id | .B \-\-list\-dles [ .I pattern \&... ] | .B \-\-list\-filters [ .I pattern ] | .B \-\-list\-media [ .I pattern \&... ] | .B \-\-list\-medium\-accesspoints [ .I type ] | .B \-\-list\-medium\-accesspoint .I medium\-id | .B \-\-list\-misc [ .I pattern \&... ] | .B \-\-list\-pids [ .I pattern \&... ] | .B \-\-list\-preferred\-dle\-medium .I dle\-id | .B \-\-list\-preferred\-set\-medium .I set\-id | .B \-\-list\-servers [ .I pattern \&... ] | .B \-\-list\-set\-media .I set\-id | .B \-\-list\-sets [ .I pattern \&... ] | .B \-\-upgrade } .br .ne 5 .SH DESCRIPTION .B Rdw2 manages the backup of data from remote filesystems to local backup media. The actual task of backing up the data is (eventually) delegated to another command, e.g. .B rdiff\-backup\fR(1). .PP Of course, the backup commands that .B rdw2 delegates to could just be called directly or called from .B cron\fR(8) but .B rdw2\fR: .TP 5 \(bu performs many checks at configuration-time and backup-time to ensure it is backing up what the user wants to where the user wants it; .TP \(bu is easy to extend because of the design of its configuration database design and its modular architecture (e.g. if a .B tar backup method that delegates to the .B tar\fR(1) command is missing, then only a suitable script needs to be written and registered in the configuration database). .br .ne 5 .SH CONFIGURATION See EXAMPLES below. .br .ne 5 .SH OPTIONS \*[ade_standard_options_component] .TP 25 .B \-\-db\-file=\fIdb\-file Use an alternative configuration database. This option exists primarily to support software testing. .TP .B \-\-no\-update\-cron Certain options ( .B \-\-add\-set\fR, .B \-\-del\-set\fR and .B \-\-edit ) trigger updating the .B crontab\fR(5) that invokes .B rdw2\fR. This option disables that update. It is primarily intended for use in regression tests. .TP .B \-\-add\-client \fIclient\-id\fR \fItype\fR \fIhostname\fR \fIclient\-labelling\-method\fB Register a backup client with ID .I client\-id in the configuration database. The client's operating system, fully qualified hostname and preferred client-labelling method also need to be specified; see the .B \-\-list\-misc option to determine valid values for most of these things. .TP .B \-\-add\-dle \fIdle\-id\fR \fIset\-id\fR \fItype\fR \fIclient\-id\fR \fIdle\-accesspoint\fR \fIbackup\-method\fR \fIlabelling\-method\fB Register a DLE with ID .I dle\-id in the configuration database. The DLE's owning backup set, type, owning backup client, accesspoint, preferred backup method and preferred labelling method also need to be specified; see the .B \-\-list\-misc option to determine valid values for most of these things. .TP .B \-\-add\-medium \fImedium\-id\fR \fItype\fR \fIlabelling\-method\fR \fImedium\-accesspoint\fB Register a backup medium with ID .I medium\-id in the configuration database. The backup medium's type, preferred labelling method and current accesspoint also need to be specified; see the .B \-\-list\-misc option to determine valid values for most of these things. Note that adding a backup medium does not automatically mark it as suitable for backing up any DLE or any backup set; see the CAVEATS section below. .TP .B \-\-add\-set \fIset\-id\fR \fIschedule\-id\fB Register a backup set with ID .I set\-id in the configuration database. The backup set's schedule also needs to be specified; see the .B \-\-list\-misc option to determine valid values for this. .TP .B \-\-backup\-dle \fIdle\-id\fB Back up the single DLE specified by .I dle\-id\fR. This option exists primarily to support software testing. .TP .B \-\-backup\-set \fIset\-id\fB Back up the backup set specified by .I set\-id\fR. Normally .B rdw2 \-\-backup\-set \fIset\-id is invoked by a .B crontab\fR(5) entry managed by .B rdw2 itself, but it can also be called manually like this. Disabled DLEs will not be backed up. Note that .B rdw2 will refuse to overwrite a manual modified .B crontab\fR(5) but it will advise how to resolve the situation. .TP .B \-\-check\-dle \fIdle\-id\fB Perform various pre-backup DLE checks. This option exists primarily to support software testing. .TP .B \-\-check\-set \fIset\-id\fB Perform various pre-backup backup set checks. .I set\-id\fR. Normally .B rdw2 \-\-check\-set \fIset\-id is invoked by a .B crontab\fR(5) entry managed by .B rdw2, but it can also be called manually like this. Disabled DLEs will not be checked. .TP .B \-\-del\-client \fIclient\-id\fB Delete backup client .I client\-id from the configuration database. .TP .B \-\-del\-dle \fIdle\-id\fB Delete DLE .I dle\-id from the configuration database. .TP .B \-\-del\-medium \fImedium\-id\fB Delete backup medium .I medium\-id from the configuration database. .TP .B \-\-del\-set \fIset\-id\fB Delete backup set .I set\-id from the configuration database. .TP .B \-\-edit Edit the configuration database using the user's preferred editor (default .B vi\fR(1)). This option exists primarily to support software testing but see the CAVEATS section below. The .B \-\-edit option can be used to dump the configuration database as follows: .\" '.IP \& 5' means: indented paragraph; no bullet (or rather a zero width space as bullet) before indent; indent by 5. .\" See groff_man(7)'s explanation of .IP for more details. groff_man(7) is in the groff package, not the groff-base package. .IP \& 25 .\" note the single quote in 'nf, which means switch to no fill but *don't* do a break. I found this at http://www.quut.com/berlin/ms/troff-break.html 'nf .fam C .B EDITOR=cat rdw2 --edit > rdw2.sql .fam T .fi .PP .TP 25 .B \-\-add\-filter \fIfilter\-regexp\fB \fIset\-id\fB \fIdle\-id\fB \fIbackup\-method\fB Add the specified filter. Any of .I set\-id\fR, .I dle\-id\fR or .I backup\-method\fR may be an empty string. If the backup method writes to standard output or standard error a line that matches .I filter\-regexp\fR, then that line will not be displayed, otherwise it will be displayed. .TP .B \-\-add\-filter \fIfilter\-regexp\fB \fIset\-id\fB \fIdle\-id\fB \fIbackup\-method\fB Remove the specified filter. .TP .B \-\-list\-all \fR[ \fIpattern\fR \&... ]\fB List the contents of the configuration database in tabular format. This option exists primarily to support software testing. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-backups \fR[ \fIpattern\fR \&... ]\fB List details of completed and in-progress backups. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-clients \fR[ \fIpattern\fR \&... ]\fB List details of all backup clients. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-dle\-media \fIdle\-id\fB List those media that are suitable for backing up the specified DLE. .TP .B \-\-list\-dles \fR[ \fIpattern\fR \&... ]\fB List details of all DLEs. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-filters \fR[ \fIpattern\fR \&... ]\fB List details of all filters that are applied to the output from backing up a DLE. This is intended to make real backup errors more visible. .TP .B \-\-list\-media \fR[ \fIpattern\fR \&... ]\fB List details of all backup media. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-medium\-accesspoints \fR[ \fItype\fB \fR]\fB List where each medium can currently be found. If .I type is specified then only details about media of that type is shown. .TP .B \-\-list\-medium\-accesspoint \fImedium\-id\fB Show where the specified medium can be found (e.g. which tape drive or under which temporary mountpoint). .TP .B \-\-list\-misc \fR[ \fIpattern ...\fR ] List supported server operating systems, client operating systems, server labelling methods, client labelling methods, DLE labelling methods, backup medium labelling methods, backup methods, medium locator methods, backup schedules and check schedules. If .I pattern is specified then only matching output is shown. Degrees of support vary but see the point above regarding .B rdw2\fR's modular design. .TP .B \-\-list\-pids \fR[ \fIpattern\fR \&... ]\fB List active .B rdw2 processes. If .I pattern is specified then only matching output is shown. .TP .B \-\-list\-preferred\-dle\-medium \fIdle\-id\fB Show which of the currently locatable media would be used to back up the specified DLE. .TP .B \-\-list\-preferred\-set\-medium \fIset\-id\fB Show which of the currently locatable media medium would be used to back up the specified backup set. .TP .B \-\-list\-servers \fR[ \fIpattern\fR \&... ]\fB List details of all backup servers. If .I pattern is specified then only matching output is shown. Normally there is only one backup server. .TP .B \-\-list\-set\-media \fIset\-id\fB List those media that are suitable for backing up the specified backup set. .TP .B \-\-list\-sets \fR[ \fIpattern\fR \&... ]\fB List details of all backup sets. If .I pattern is specified then only matching output is shown. .TP .B \-\-upgrade The ongoing development of .B rdw2 sometimes requires database changes that are too complicated to perform on-the-fly. This option is used to perform such changes. It need only be used when .B rdw2 says so. .br .ne 5 .SH EXIT STATUS On success .B rdw2 returns zero. On failure it returns non-zero and displays a diagnostic message. .br .ne 5 .SH FILES .TP 25 .I medium\-accesspoint\fB/.rdw2-medium-label File written by the .B df\-in\-map medium labeller and containing the medium label. ( .B df\-in\-map stands for Dot File IN Medium AccessPoint.) .TP .B /.rdw2\-client\-label File written by the .B df\-in\-cr client labeller and containing the client label. ( .B df\-in\-cr stands for Dot File IN Client Root.) .TP .I dle\-root\fB/.rdw2\-dle\-label File written by the .B df\-in\-dleap DLE labeller and containing the DLE label. ( .B df\-in\-dleap stands for Dot File IN DLE AccessPoint.) .TP .B /.rdw2\-server\-label File written by the .B df\-in\-sr server labeller and containing the server label. ( .B df\-in\-sr stands for Dot File IN Server Root.) .TP .I dle\-root\fB/.rdw2\-session\-label File written by .B rdw2 immediately prior to calling the backup method script. The file is deleted after the backup completes and then restored to /tmp in order to check that the backup worked. .TP .B \*[rdw2_state_prefix]/rdw2.sqlite Default location for .B rdw2\fR's configuration database. .br .ne 5 .SH ENVIRONMENT VARIABLES .TP 25 RDW2_DB_FILE Override the default configuration database location. See also the .B \-\-db\-file option. .br .ne 5 .SH EXAMPLES This section shows how to configure the backup server, register a formatted, mounted, empty and removable disk mounted at /mnt, mark that disk as suitable for any backup, create a backup set called test, add the client client1.example.com and add the DLE /tmp on that client to the test backup set and finally back up the backup set. The example assumes that the configuration database does not already exist. .PP The author has taken liberties regarding the formatting of this section to improve readability on narrow terminals and on paper. .PP Firstly, edit .B \*[rdw2_etc_prefix]/rdw2.py and set .IP \& 5 'nf .fam C .\" 1 lines of output coming up. .ne 1 .B rdw2_server_flag = True .fam T .fi .PP Secondly, examine what schedules are pre-defined: .IP \& 5 'nf .fam C .\" 10 lines of output coming up. .ne 10 root@backupserver# \fBrdw2 --list-misc sched\fR backup schedules: nightly:20 0 * * *; \\ daily:20 12 * * *; \\ hourly:30 * * * *; \\ weekly:40 22,10 * * *; check schedules: nightly:50 8 * * 1,3,5; \\ daily:50 9 * * 1,3,5; \\ hourly:50 10 * * 1,3,5; \\ weekly:50 11 * * 1,3,5; root@backupserver# .fam T .fi .PP That command probably ran a bit slowly; this is because it first had to initialise the backup server itself (creating an empty configuration database, labelling the server and writing details of the server into the configuration database); running the same command a second time would be faster. .PP The effects of that initialisation can be seen by running: .IP \& 5 'nf .fam C .\" 7 lines of output coming up. .ne 7 root@backupserver# \fBrdw2 --list-servers\fR server type hostname lab. method ------------ ----- ------------------------ ----------- backupserver Linux backupserver.example.com df-in-sr root@backupserver# \fBcat /.rdw2-server-label\fR 17eb41e1-9d58-4613-9326-4929397234da root@backupserver# .fam T .fi .PP Note that: .TP 5 \(bu It is not just the first .B \-\-list\-misc option that triggers the server initialisation: any option would have had the same effect. .TP \(bu If the pre-defined schedules do not suit then see the CAVEATS section below. .PP Thirdly, create the test backup set using one of the available schedules: .IP \& 5 'nf .fam C .\" 2 lines of output coming up. .ne 2 root@backupserver# \fBrdw2 --add-set test nightly\fR root@backupserver# .fam T .fi .PP The effects of that command can be seen by running: .IP \& 5 'nf .fam C .\" 5 lines of output coming up. .ne 5 root@backupserver# \fBrdw2 --list-sets\fR set schedule ---- -------- test nightly root@backupserver# .fam T .fi .PP Fourthly, look at what client types, client labelling methods, DLE types, DLE labelling methods and DLE backup methods are pre-defined: .IP \& 5 'nf .fam C .\" 10 lines of output coming up. .ne 10 root@backupserver# \fBrdw2 --list-misc\fR client labelling methods: df-in-cr, hf-in-cr dle labelling methods: df-in-dleap backup methods: noop, rdiff-backup, \\ rdiff-backup-one-fs, rsync, \\ rsync-one-fs, unison, \\ unison-one-fs dle types: dir, dir-one-fs \&... root@backupserver# .fam T .fi .PP Fifthly, use that information to add a Linux client, specifying one of the client labelling methods and to add the /tmp DLE on that client: .IP \& 5 'nf .fam C .\" 5 lines of output coming up. .ne 5 root@backupserver# \fBrdw2 --add-client client1 Linux \\ client1.example.com df-in-cr\fR root@backupserver# \fBrdw2 --add-dle client1-tmp test dir client1 \\ /tmp rsync-one-fs df-in-dleap\fR root@backupserver# .fam T .fi .PP The effects of those commands can be seen by running: .IP \& 5 'nf .fam C .\" 13 lines of output coming up. .ne 13 root@backupserver# \fBrdw2 --list-clients\fR client type hostname lab. method ------- ----- ------------------- ----------- client1 Linux client1.example.com df-in-cr root@backupserver# \fBssh client1.example.com cat /.rdw2-client-label\fR 2227f458-ad15-4dcf-8cc4-4e1c34d38b06 root@backupserver# \fBrdw2 --list-dles\fR dle set type client accesspoint backup method lab. method ----------- --- ---- ------- ----------- ------------- ----------- client1-tmp test dir client1 /tmp rsync-one-fs df-in-dleap root@backupserver# \fBssh client1.example.com cat /tmp/.rdw2-dle-label\fR 50112081-5af2-4947-99f2-fa9867f870aa root@backupserver# .fam T .fi .PP Note that: .TP 5 \(bu DLEs are usually named .I client\-id\fB\-\fIrationalised\-dle\-accesspoint\fR, but this is only a convention, not a requirement. .TP \(bu .B ssh\fR(1) access is required to label clients and DLEs. Backup methods (e.g. the .B rsync-one-fs method, which delegates to the .B rsync\fR(1) command) usually also use .B ssh\fR(1) to transfer data but they are not obliged to do so. .TP \(bu Attempting to back up now would fail because no backup media are defined. .PP Sixthly, define a medium: .IP \& 5 'nf .fam C .\" 3 lines of output coming up. .ne 3 root@backupserver# \fBrdw2 --add-medium my-usb-disk-1 \\ floating-dir df-in-map /mnt\fR root@backupserver# .fam T .fi .PP The effects of that command can be seen by running: .IP \& 5 'nf .fam C .\" 3 lines of output coming up. .ne 3 root@backupserver# \fBcat /mnt/.rdw2-medium-label\fR f2ccfcec-8f4e-45ce-9e07-b2d21dd50d67 root@backupserver# .fam T .fi .PP Note that: .TP 5 \(bu Again, attempting to back up now would fail: this time because no access to the medium for this backup set, client or DLE has been granted yet. .PP Seventhly, grant access to the medium for any backup set, for any DLE, for any client. Unfortunately, there is currently no nice way to do this (see the CAVEATS section below), so hack it using .B sqlite3\fR(1): .IP \& 5 'nf .fam C .\" 13 lines of output coming up. .ne 13 root@backupserver# \fBrdw2 -p\fR Db-File: /var/lib/rdw2/rdw2.sqlite root@backupserver# \fBsqlite3 /var/lib/rdw2/rdw2.sqlite\fR sqlite> \fBINSERT INTO medium_grants VALUES ( NULL, \\ 'my-usb-disk-1', \\ NULL, \\ NULL, \\ NULL, \\ NULL \\ );\fR sqlite> \fB.exit\fR root@backupserver# .fam T .fi .PP Note that: .TP 5 \(bu Alternatively, it is possible to use .B rdw2 \-\-edit that but is harder to explain in a man page. .PP Eighthly, either wait for .B cron\fR(8) to run the backup or run it manually: .IP \& 5 'nf .fam C .\" 2 lines of output coming up. .ne 2 root@backupserver# \fBrdw2 --backup-set test\fR root@backupserver# .fam T .fi .PP Finally, add more backup sets, more clients, more DLEs on those clients, more media and more media grants. .br .ne 5 .SH CAVEATS .B Rdw2 is still in early development; i.e. it is missing features; it is changing rapidly; it is inadequately documented, it contains bugs; you should probably not use it. .PP Features known to be missing include: .TP 5 \(bu command line access to grants (workaround: use .B rdw2 \-\-edit\fR) .TP \(bu command line access to enabled flags (workaround: use .B rdw2 \-\-edit\fR) .TP \(bu command line access to register new method scripts ((workaround: use .B rdw2 \-\-edit\fR) .TP \(bu see also the URL given below .PP In theory .B rdw2 supports the following but the code is not yet implemented: .TP 5 \(bu clients running operating systems other than Linux .TP \(bu clients running operating systems other than Linux .TP \(bu tape backup media .PP Notably, the following documentation is missing: .TP 5 \(bu the characteristics of the various labellers .br .ne 5 .SH STANDARDS This manual page documents version ADE_APP_TOKEN_RELEASE_ID of .B rdw2\fR. .br .ne 5 .SH SEE ALSO amanda(8), cron(8), crontab(5), rdiff\-backup(1), rsync(1), ssh(1), sqlite3(1), unison(1), https://openproject.pasta.freemyip.com/bugs/rdw2/, https://www.sqlite.org/ .br .ne 5 .SH AUTHOR ADE_APP_TOKEN_AUTHOR_NAME .br .ne 5 .SH COPYRIGHT & DISTRIBUTION POLICY Copyright (C) 2020-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME \*[ade_standard_copyright_component]