"Fossies" - the Fresh Open Source Software Archive

Member "safekeep-1.5.1/doc/safekeep.txt" (16 Nov 2020, 12429 Bytes) of package /linux/misc/safekeep-1.5.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "safekeep.txt": 1.5.0_vs_1.5.1.

    1 :man source: safekeep
    2 :man version: {revnumber}
    3 :man manual: SafeKeep Manual
    4 
    5 safekeep(1)
    6 ==========
    7 
    8 NAME
    9 ----
   10 safekeep - Client/server backup script
   11 
   12 SYNOPSIS
   13 --------
   14 'safekeep' --server [-q] [-v] [--noemail] [--force] [-c file] [--cleanup] [--tempdir=<tempdir>] <clientid>*
   15 
   16 'safekeep' --keys [-q] [-v] [--noemail] [-c file] [-i file] [--status] [--print] [--deploy] <clientid>*
   17 
   18 'safekeep' --list [-q] [-v] [--noemail] [-c file] [--increments] [--parsable-output] [--sizes] [--changed=<time>] [--at-time=<time>] <clientid>*
   19 
   20 'safekeep' --client [--cleanup]
   21 
   22 'safekeep' -h | -V
   23 
   24 DESCRIPTION
   25 -----------
   26 SafeKeep is a client/server backup script which enhances the
   27 power of rdiff-backup with simple configuration and use.
   28 
   29 SafeKeep can work in server mode, client mode, SSH key management mode
   30 or list mode.
   31 
   32 In server mode, SafeKeep parses a set of configurations files which
   33 defines a set of backup clients. For each backup client, SafeKeep
   34 connects to the client host over SSH (using a public key authentification
   35 system previously set up using `safekeep --keys --deploy`), and launches
   36 `safekeep --client` onto the client host. The client does the real backup
   37 and sends the data over SSH to the SafeKeep server which stores it in
   38 the specified location.
   39 
   40 In client mode, SafeKeep does a few setup steps, depending on the
   41 client configuration (database dump, LVM device snapshot), then backups
   42 the client data using `rdiff-backup`, and then cleanups the state
   43 (removes the database dumps, deactivates the LVM snapshots)
   44 
   45 Note that the client mode of SafeKeep should never be invoked manually,
   46 this mode is meant to be used only by the server mode of SafeKeep.
   47 The only exception to this is if run with the `--cleanup` option, which
   48 is used to remove LVM snapshots and mounts created by Safekeep, after a
   49 crash or some other failure, without a connection to the server.
   50 Normally this cleanup would be performed through the server command
   51 `safekeep --server --cleanup`.
   52 
   53 The SSH key management mode is a helper mode for deploying or verifying
   54 the setup of the SSH authentification keys.
   55 
   56 In list mode, SafeKeep lists the details of existing archives.  This is
   57 basically an interface to the relevant options for `rdiff-backup`.
   58 
   59 In server, keys management and list mode, you can restrict the operation
   60 to a specific set of clients by listing the desired client IDs as
   61 arguments. If no client ID is given, SafeKeep will operate over all known
   62 clients.
   63 
   64 Each mode accepts a few options as described below.
   65 
   66 OPERATION MODE
   67 --------------
   68 --server::
   69 	Selects the server mode 
   70 
   71 --client::
   72 	Selects the client mode. This should never be invoked manually, the
   73 	clients are started automatically by the server on the client machines
   74 	using SSH.
   75 
   76 --keys::
   77 	Selects the SSH key management mode
   78 
   79 --list::
   80 	Selects the list mode
   81 
   82 Please note that you must always specify an operation mode. Earlier 
   83 versions used do default to `--server` mode, but that proved to work 
   84 out poorly in practice.
   85 
   86 GENERAL OPTIONS
   87 ---------------
   88 -c, --conf=FILE::
   89 	Specifies the configuration file location.
   90         If not specified at all, SafeKeep will default to
   91 	`/etc/safekeep/safekeep.conf`, or optionally in
   92 	`~/.safekeep/safekeep.conf` for non-root users, if it exists.
   93         Simply using this default is the recommended usage.
   94 
   95 -h, --help::
   96 	Selects the help mode, in which safekeep prints out the
   97 	online help and exits.
   98 
   99 -V, --version::
  100 	Selects the version mode, in which safekeep prints out the
  101 	version number and exits.
  102 
  103 -q, --quiet::
  104 	Decreases the verbosity level. Can be specified more than
  105 	once.
  106 
  107 -v, --verbose::
  108 	Increases the verbosity level. Can be specified more than
  109 	once.
  110 
  111 --noemail::
  112 	Disables the sending of email, no matter what the settings
  113 	within the configuration file.
  114 
  115 SERVER OPTIONS
  116 --------------
  117 --force::
  118 	Pass the `--force` option to `rdiff-backup`, allowing it
  119 	to overwrite the backup directory metadata. This option
  120 	is potentially dangerous, and should only be used if the
  121 	backup directory becomes corrupt, and `rdiff-backup` error
  122 	logs tells you to use this option.
  123 
  124 --cleanup::
  125 	Remove LVM snapshots and mounts left by Safekeep after a
  126 	crash or other failure.  This will run also run the standard
  127 	cleanup processes, such as the removal of an DB dumps, and
  128 	forces a consistency check of the `rdiff-backup` destination
  129 	directory.  This is the prefered cleanup procedure and can
  130 	be run with no danger of corrupting the system if there is
  131 	nothing to cleanup.
  132 
  133 --tempdir TEMPDIR::
  134 	Specifes a TEMPDIR for use with `rdiff-backup'.  This overrides
  135 	any TEMPDIR specified in the `safekeep.conf'.
  136 
  137 CLIENT OPTIONS
  138 --------------
  139 --cleanup::
  140 	Remove LVM snapshots and mounts left after a crash or other
  141 	failure from the local system.  Unlike the equivalent `--server`
  142 	option, it does not do any other of the standard cleanups.
  143 	This option should only be used when it is not possible to
  144 	refer to the server, for example, when the network connection
  145 	to the server is no longer available.
  146 
  147 KEYS OPTIONS
  148 ------------
  149 -i FILE::
  150 	Forces `ssh(1)` to use FILE for the identity (private key) in 
  151 	RSA/DSA authentication.  If not specified, ssh(1) will use its 
  152 	default identity files.
  153 
  154 --status::
  155 	Display the key status for the clients. It is implied if no other
  156         option is specified. In effect this option prints the steps that
  157         will be taken when the keys are deployed to the client.
  158 
  159 --print::
  160 	Display the authorization keys for the clients. This is useful in
  161         case you want to manually copy it into the client's 
  162         `~/.ssh/authorized_keys` file. This option is seldom useful.
  163 
  164 --deploy::
  165 	Deploy the authorization keys on the clients.
  166 
  167 LIST OPTIONS
  168 ------------
  169 --increments::
  170 	Pass the `--list-increments` option to `rdiff-backup`, to
  171 	list the number and date of partial incremental backups for
  172 	the given or all clients.  This is the default list option.
  173 
  174 --parseable-output::
  175 	Pass the `--parsable-output` option to `rdiff-backup` to
  176 	generate output in a format that is easily parsed by other
  177 	programs.  This currently only works with the `--increments`.
  178 
  179 --sizes::
  180 	Pass the `--list-increment-sizes` option to `rdiff-backup`,
  181 	to list the total size of all increment and mirror files by
  182 	time for the given or all clients.  Note, this may take some time.
  183 
  184 --changed=TIME::
  185 	Pass the `--list-changed-since` option for TIME to `rdiff-backup`,
  186 	to list the files changed since TIME for the given clients.
  187 	TIME is passed directly to `rdiff-backup`.  Note, this may take
  188 	some time and generate considerable output.  Also, unlike
  189 	`rdiff-backup` the is no option to select sub-directories.
  190 
  191 --at-time=TIME::
  192 	Pass the `--list-at-time` option for TIME to `rdiff-backup`,
  193 	to list the files in the archive that were present at the
  194 	given time for the given clients.  Note, this may take some
  195 	time and generate considerable output.  Also, unlike
  196 	`rdiff-backup` the is no option to select sub-directories.
  197 
  198 CONFIGURATION
  199 -------------
  200 
  201 Normally the configuration files are placed in the `/etc/safekeep/backup.d/` 
  202 directory, or optionally in `~/.safekeep/backup.d/` for non-root users,
  203 from where they will get picked up automatically by SafeKeep. 
  204 Each backup client is described by a configuration file in XML format. 
  205 The minimum configuration file is:
  206 ------------------------------------------------------------------------
  207 <backup>
  208   <host name="my_workstation" />
  209 </backup>
  210 ------------------------------------------------------------------------
  211 This will simply backup all relevant files (excluding temporary files,
  212 caches, etc) from the client with the address `my_workstation`.
  213 
  214 A more realistic example:
  215 ------------------------------------------------------------------------
  216 <backup>
  217   <host name="my_workstation" />
  218   <repo retention="10D" />
  219   <setup>
  220       <dump type="postgres" dbuser="postgres" file="/var/lib/pgsql/backups/all_dbs" />
  221       <dump type="mysql" user="mysql" dbuser="dbbackup" db="adatabase" file="/var/backups/dumps/adatabase_dbs" />
  222       <dump type="mysql" user="mysql" dbuser="dbbackup" db="mysql" file="/var/backups/dumps/mysql_dbs" cleanup="true" />
  223       <snapshot device="/dev/mapper/VolGroup00-LogVol00" size="500M" />
  224   </setup>
  225 
  226   <data>
  227     <exclude regexp=".*\.ogg"/>
  228     <exclude regexp=".*\.mp3"/>
  229 
  230     <include path="/etc"/>
  231 
  232     <exclude glob="/home/*/tmp"/>
  233     <include path="/home"/>
  234 
  235     <include path="/root"/>
  236 
  237     <include path="/srv"/>
  238 
  239     <exclude path="/var/cache"/>
  240     <exclude path="/var/lock"/>
  241     <exclude path="/var/run"/>
  242     <exclude path="/var/tmp"/>
  243     <include path="/var/named/chroot/etc"/>
  244     <include path="/var/named/chroot/var/named"/>
  245     <exclude path="/var/named/chroot"/>
  246     <include path="/var"/>
  247 
  248     <exclude path="/"/>
  249   </data>
  250 </backup>
  251 ------------------------------------------------------------------------
  252 In this case, SafeKeep will dump all databases managed by PostgreSQL,
  253 snapshot the disk via LVM, and proceed to backup `/etc`, `/home`,
  254 `/root`, `/srv`, `/var`, while excluding some unneeded files and
  255 directories. Older data will be retained for 10 days.
  256 
  257 For full reference documentation of the configuration format, see
  258 safekeep.backup(5).
  259 
  260 CLIENT IDS
  261 ----------
  262 Normally the client IDs are generated automatically from the configuration
  263 filenames without the extension. E.g. if a configuration file is named
  264 `my_workstation.conf`, the client ID becomes `my_workstation`. For more
  265 information on this topic, see safekeep.backup(5).
  266 
  267 KEY DEPLOYMENT
  268 --------------
  269 The `safekeep(1)` server needs to access the clients in order to conduct
  270 the backup. To that end, it establishes two ssh(1) pipes: one for control,
  271 and one for data. To simplify the deployment of the keys, `safekeep(1)`
  272 has a key deploy mode. 
  273 
  274 When deploying keys using the built-in key management functionality,
  275 `safekeep(1)` needs to be invoked as the user under which it will function
  276 as a server. By default, that user is 'safekeep'. For extra security,
  277 you can not login into that account, so you have to invoke `safekeep(1)`
  278 as 'root':
  279 ------------------------------------------------------------------------
  280 	[root@yourbox ~] # safekeep --keys --deploy
  281 ------------------------------------------------------------------------
  282 
  283 RESTORING
  284 ---------
  285 Since `safekeep(1)` is built around `rdiff-backup(1)`, it doesn't have any
  286 built-in restore capabilities. It simply relies on `rdiff-backup` to perform
  287 this task.
  288 
  289 To do so, you just need to know the directory where the data is actually
  290 stored. In a typical installation, for a box configured via the file
  291 `/etc/safekeep/backup.d/mybox.backup`, the data will be stored under
  292 `/var/lib/safekeep/mybox/`. Please refer to `safekeep.backup(5)` for more
  293 information on this matter.
  294 
  295 Once you have determined where the data will be stored (we'll continue
  296 the example above), all you have to do is run `rdiff-backup`:
  297 ------------------------------------------------------------------------
  298 	# rdiff-backup -r 1s /var/lib/safekeep/mybox my-restore-dir
  299 ------------------------------------------------------------------------
  300 You will be able to find more information on the restore procedure in
  301 the `rdiff-backup(1)` man page.
  302 
  303 FILE SELECTION
  304 --------------
  305 It is important to note that the `include`/`exclude` directives that
  306 control file selection are matched in the order they appear in the
  307 configuration file, and the first one that matches dictates whether
  308 the file will be included or excluded. As a result, you have to
  309 add the more specific ones first, or the more generic specifications
  310 will always win. For example:
  311 ------------------------------------------------------------------------
  312 ...
  313     <include path="/home"/>
  314     <exclude path="/home/joe"/>
  315 ...
  316 ------------------------------------------------------------------------
  317 will NOT do what you expect, because the `/home` will match before 
  318 `/home/joe`, and thus all files under `/home` will be included.
  319 The correct way is to flip the two around
  320 ------------------------------------------------------------------------
  321 ...
  322     <exclude path="/home/joe"/>
  323     <include path="/home"/>
  324 ...
  325 ------------------------------------------------------------------------
  326 
  327 Please see safekeep.backup(5) for more information on file selection.
  328 
  329 SEE ALSO
  330 --------
  331 rdiff-backup(1), safekeep.conf(5), safekeep.backup(5)
  332 
  333 AUTHOR
  334 ------
  335 Written by Dimi Paun <dimi@lattica.com> and Stelian Pop <stelian@lattica.com>.
  336