lustre/doc/llbackup.8

   1 .\" -*- nroff -*-
   2 .\" Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
   3 .\" This file may be copied under the terms of the GNU Public License, v2.
   4 .\"
   5 .TH llbackup 8 "2008 Mar 15" Lustre "System management commands"
   6 .SH NAME
   7 llbackup \- backup a list of files, maybe running on multiple nodes
   8 .SH SYNOPSIS
   9 .B llbackup -c
  10 .RB [ -hjvxz "] [" -C
  11 .IR directory ]
  12 .RB [ -e
  13 .IR rsh ]
  14 .RB [ -i
  15 .IR inputlist ]
  16 .RB [ -l
  17 .IR logdir ]
  18 .RB [ -n
  19 .IR nodes ]
  20 .RB [ -s
  21 .IR splitmb ]
  22 .RB [ -S
  23 .IR splitcount ]
  24 .RB [ -T
  25 .IR tar ]
  26 .BI -f outputfilebase
  27 .br
  28
  29 .B llbackup
  30 .RB { -x | -t }
  31 .RB [ -chjvz "] [" -C
  32 .IR directory ]
  33 .RB [ -e
  34 .IR rsh ]
  35 .RB [ -l
  36 .IR logdir ]
  37 .RB [ -n
  38 .IR nodes ]
  39 .RB [ -T
  40 .IR tar ]
  41 .BI -f tarfilelist
  42 .SH DESCRIPTION
  43 .B llbackup
  44 takes a list of files to backup or restore, either from standard input, or
  45 from a list of files supplied as a parameter and produces one or more archive
  46 files containing the files.
  47 .B llbackup
  48 uses the
  49 .BR tar (1)
  50 or
  51 .BR htar (1)
  52 programs to produce archive files, and has many of the same options (though
  53 not identical in some cases).  The reason for using llbackup instead of those
  54 programs directly is that llbackup can run in parallel on multiple
  55 nodes to do high-speed backups on clustered or distributed filesystems and
  56 will split the work among multiple client nodes to increase performance.
  57 .br
  58
  59 The archive files produced by
  60 .B llbackup
  61 are identical to normal tar files (having been created by the local tar
  62 command) and can be extracted or listed by
  63 .B tar
  64 directly.
  65 .br
  66
  67 The clients will pause and print status messages if they think there is not
  68 enough free space in the output directory to avoid running out of space.
  69 Backup tarfiles should be moved to offline storage or otherwise purged to
  70 allow the backups to continue.  If the client is doing a restore it will
  71 similarly pause and print status messages if the tarfile it was asked to
  72 restore is not available on that node.
  73 .SH OPERATIONS
  74 The following options control what operation
  75 .B llbackup
  76 will perform:
  77 .TP
  78 .B -c
  79 create archive.  This is the default operation if no other is given.
  80 .TP
  81 .B -x
  82 extract tarfiles from the
  83 .I tarfilelist
  84 given to
  85 .B -f
  86 instead of backing them up.
  87 .TP
  88 .B -t
  89 list table of contents of the
  90 .I tarfilelist
  91 given by
  92 .BR -f .
  93 .SH OPTIONS
  94 .TP
  95 .BI -C directory
  96 change the backup command to run in
  97 .I directory
  98 instead of the current working directory so filenames given in the input
  99 file are backed up or restored relative to
 100 .IR directory .
 101 Note that this affects all pathname components used during backup and restore
 102 so the
 103 .I inputlist
 104 and
 105 .I outputbase
 106 should be specified by absolute pathname if they are not also in
 107 .IR directory .
 108 .TP
 109 .BI -e rsh
 110 specify the passwordless remote shell command (default
 111 .BR ssh (1)).
 112 .TP
 113 .BI -f outputbase
 114 specify base output filename for backup tar archives, to which a suffix will
 115 be appended to ensure that multiple clients doing backup into the same
 116 directory do not have conflicting filenames.  The
 117 .I outputbase
 118 file can be a tape or disk device, but must be the same device on each client
 119 running the backup, in which case only a single process can run on each client.
 120 Specifying
 121 .B -
 122 means write to standard output.
 123 .TP
 124 .BI -f tarfilelist
 125 specify a file containing a list of tarfiles, one per line, to restore or
 126 list the table of contents of.  Specifying
 127 .B -
 128 means read the list of tarfiles from standard input.  The
 129 .I tarfilelist
 130 can also be a tape or disk device, but since the individual tarfiles are
 131 sent to individual clients, the same files must be accessible on all clients.
 132 .TP
 133 .B -h
 134 print this help message and exit.  Use
 135 .B -x
 136 .B -h
 137 or
 138 .B -t
 139 .B -h
 140 to get the help options for restore or list operations.
 141 .TP
 142 .BI -i inputlist
 143 list of files to backup when creating an archive.  If no
 144 .B -i
 145 option is specified or if
 146 .I inputlist
 147 is - then the list of files to back up is read from standard input.  The input
 148 file list is a list of pathnames, one file per line, as generated by
 149 .BR find (8),
 150 .BR "lfs find" (8),
 151 or
 152 .BR e2scan (8)
 153 for example.  For restore this option is currently unused.
 154 .TP
 155 .B -j
 156 use
 157 .BR bzip2 (1)
 158 compression on input or output tar file(s).  This option is not
 159 currently supported by the underlying
 160 .BR htar (8)
 161 implementation.
 162 .TP
 163 .BI -l logdir
 164 directory for output logs.
 165 .TP
 166 .BI -n nodes
 167 comma-separated list of client nodes to run backups.  It is possible to
 168 specify the same client node multiple times in order to have multiple
 169 instances of the backup or restore running in parallel on that node.
 170 This is useful to maximize the bandwidth of the backup or restore process
 171 and avoid client nodes underutilizing their bandwidth while generating
 172 file lists or compressing files.
 173 .TP
 174 .BI -s splitmb
 175 target size for backup chunks in megabytes (default 8192MiB).  Increasing this
 176 size can improve performance and compression ratios, but may cause
 177 underutilization of clients if the files are not evenly distributed.
 178 This option has no meaning for restore or list operations.
 179 .TP
 180 .BI -S splitcount
 181 number of files sent to each client before sending files to the next client
 182 (default 200).  Increasing the
 183 .I splitcount
 184 keeps more related files together in individual tar files (meaning fewer
 185 archives need to be processed when restoring files for a particular
 186 subdirectory), but can lead to performance imbalance if files vary greatly
 187 in size and one client has to back up many of them due to proximity of
 188 filenames in the input list, while other clients back up smaller files.
 189 Decreasing the
 190 .I splitcount
 191 means a more uniform distribution of files and usage among clients, but
 192 means nearly every archive will have to be extracted to get only a subset
 193 of files needed.
 194 This option has no meaning for restore or list operations.
 195 .TP
 196 .BI -T tar
 197 specify the backup command (default tar).  Optionally the
 198 .BI htar (8)
 199 command can be used to back up directly to an HPSS archive, if available.
 200 .TP
 201 .B -v
 202 be verbose - list all files being processed.  By default, individual files
 203 being backed up or restored are only reported in the log files because they
 204 would all be intermixed coming from multiple clients in parallel and the
 205 overall progress would be hard to determine.
 206 .TP
 207 .B -V
 208 print version number and exit.
 209 .TP
 210 .B -z
 211 use gzip compression on input or output tar file(s).  This option is not
 212 currently supported by the underlying
 213 .BR htar (8)
 214 implementation.
 215 .SH EXAMPLES
 216 .TP
 217 .B lfs find /home -mtime -7 | llbackup -c -n c1,c2 -f /bkup/bk2008-03-15
 218 Create a backup of the
 219 .B /home
 220 filesystem finding files modified in the last 7 days, compress the output
 221 using
 222 .B gzip
 223 and run on client nodes
 224 .B c1
 225 nodes, putting the output tar files into the
 226 .B /bkup
 227 directory using filenames starting with
 228 .BR bk2008-03-15 .
 229 .TP
 230 .B find /bkup -name bk2007-11-28* | llbackup -x -n c1,c1,c2,c2 -C /tmp -f-
 231 Restore
 232 .B gzip
 233 compressed files from the
 234 .B bk2007-11-28
 235 backup from the
 236 .B /bkup
 237 directory, using two restore processes on each of the client nodes
 238 .B c1
 239 and
 240 .BR c2 ,
 241 reading the list of tar files to restore from standard input and restoring
 242 into the
 243 .B /tmp
 244 directory.
 245 .SH BUGS
 246 It is currently not possible to extract only a subset of files from the
 247 tarfiles.  If that is necessary, then tar should be run directly on the
 248 individual tar files after checking in the backup logs which tarfiles
 249 have the relevant files.
 250 .SH SEE ALSO
 251 .BR lustre (7),
 252 .BR tar (8),
 253 .BR htar (8),
 254 .BR ssh (1),
 255 .BR rsh (1),
 256 .BR find (1),
 257 .BR lfs "(1) " find ,
 258 .BR e2scan (8).