Whamcloud - gitweb
LU-925 agl: trigger async glimpse lock when statahead
[fs/lustre-release.git] / 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).