lustre/doc/llbackup.8

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