1STAR(1) Schily´s USER COMMANDS STAR(1)
2
6 star - unique standard tape archiver
7
9 star command [options] [-find] file1 ... filen [find_expr]
10 ustar command [options] [-find] file1 ... filen [find_expr]
11 tar command [options] file1 ... filen
12 star -copy [options] [-find] file1 ... [f_expr] directory
13 star -copy [options] -C from_directory . to_directory
14
16 Star is a very fast tar(1) like tape archiver with improved functional‐
17 ity.
18 Star archives and extracts multiple files to and from a single file
20 called a tarfile. A tarfile is usually a magnetic tape, but it can be
21 any file. In all cases, appearance of a directory name refers to the
22 files and (recursively) subdirectories of that directory.
23 Star's actions are controlled by the mandatory command flags from the
25 list below. The way star acts may be modified by additional options.
26 Note that unpacking tar archives may be a security risk because star
28 may overwrite existing files. See SECURITY NOTES for more information.
29
31 Star includes the first free implementation of POSIX.1-2001 extended
32 tar headers. The POSIX.1-2001 extended tar headers define a new stan‐
33 dard way for going beyond the limitations of the historic tar format.
34 They allow (among others) to archive all UNIX time stamps in sub-second
35 resolution, files of arbitrary size and filenames without length limi‐
36 tation using UNICODE UTF-8 coding for best exchange compatibility.
37 Star by default uses a fifo to optimize data flow from/to tape. This
39 results in a normally streaming tape during the whole backup. See
40 -fifo and fs= option to get information on how to find the best fifo
41 size.
42 Star includes a pattern matcher to control the list of files to be pro‐
44 cessed. This gives a convenient interface for archiving and restoring
45 complex lists of files. In conjunction with the -w flag it is easy to
46 merge a tar archive into an existing file tree. See also -U option. In
47 create mode use the pat= option to specify either select or exclude
48 patterns (depending on the -V flag). In extract or list mode all file
49 type arguments are interpreted as select patterns while the patterns
50 specified with the pat= option may be used as select or exclude pat‐
51 terns (depending on the -V flag). Have a look at the description of
52 the -C option to learn how to fetch files from a list of directories
53 (in create mode) or to distribute files to a list of directories (in
54 extract mode). A substitute option allows ed(1) like pattern substitu‐
55 tion in file names.
56 Star includes an enhanced function that is similar to the find(1) com‐
58 mand (see sfind(1)). This allows to use find expressions, even in
59 extract or list mode, directly on the content on an archive. The
60 extensions to find(1) allow to modify the file metadata.
61 Star includes a sophisticated diff command. Several diff options allow
63 user tailorable functionality. Star won't show you differences you are
64 not interested in. Check the diffopts= option for more details.
65 Star has no limitation on filename length. Pathnames and linknames up
67 to PATH_MAX (1023 bytes with old OS versions and 4095 bytes with
68 POSIX.1-2001) may be archived. Later versions may be able to deal with
69 longer pathnames.
70 Star deals with all 3 times, available for files on UNIX systems if the
72 archive format is either chosen from the star specific formats or is a
73 format that uses POSIX.1-2001 extended headers. This is either done in
74 second resolution by using a star specific POSIX.1-1988 compatible
75 extension or in sub second resolution by using POSIX.1-2001 extended
76 headers. Star is able to store and restore all 3 times (mtime, atime
77 and even ctime). On Solaris 2.x systems, star is able to do backups
78 without changing any of the 3 the times.
79 If used with the H=ustar option, or if called as ustar or tar while the
81 H=headertype option is not used, star is 100% POSIX compliant.
82 Star's default format (if called as star) is xstar and is as posix com‐
84 pliant as possible. Enhancements to the standard that prevent correct
85 extraction of single files when using a different tar implementation
86 that is only POSIX.1-1988 compliant may occur, but they only affect
87 single files with a pathname that is longer than 100+130 chars or when
88 archiving sparse files with the -sparse option in effect. All other
89 files will extract correctly. See the description for the H=headertype
90 option below for more information on archive formats and possible ar‐
91 chive interchange problems.
92 Star makes it easy to repair corrupted filesystems. After a fsck -y has
94 been run on the filesystem, star is able to restore only the missing
95 files automatically. Use then star -diff to check for differences (see
96 EXAMPLES for more information).
97 Star automatically recognizes the type of the archive. Star therefore
99 is able to handle features and properties of different archive types in
100 their native mode, if it knows about the peculiarities of the archive
101 type. See the H=headertype option for more details. To be able to do
102 this, star adds hidden fingerprints to the archive header that allows
103 to recognise all star specific archive formats. The GNU tar format is
104 recognised by the way it deviates from the standard.
105 Star automatically recognizes and handles byte swapped archives. There
107 is no option to manually control byte swapping.
108 Star automatically recognizes and handles compressed archives inside
110 plain files.
111 Star is able to archive and restore Access Control Lists for files
113 using POSIX.1-2001 extended headers.
114
116 In native mode, star is compatible to the command line syntax of a typ‐
117 ical POSIX command and for this reason expects commands and options to
118 start with a single dash (-). In this case, commands and options may be
119 specified separately, all boolean or increment type options may be
120 specified either separately or combined. For compatibility with GNU
121 programs, long options may alternatively start with a double dash. In
122 compatibility mode to POSIX tar, star expects commands and options to
123 appear as one single string that does not start with a dash. In POSIX
124 tar compatibility mode, additional non POSIX options may be specified
125 but must appear after the POSIX options and their args and need to
126 start with a dash.
127 -c Create a new tarfile and write named files into it. Writing
129 starts at the beginning of tarfile. See -v option for informa‐
130 tion on how to increase verbosity while the archive is written.
131 -copy Copy named files to the target directory which is the last file
133 type argument. The target directory must exist. The shorthand
134 -cx instead of -copy is not allowed because this could be a
135 result of a typo.
136 If the option -diff has been specified in addition, star per‐
138 forms a one pass directory tree compare instead of copying
139 files. The shorthand -c -diff instead of -copy -diff is also
140 allowed.
141 On operating systems with slow file I/O (such as Linux), it may
143 help to use -no-fsync in addition, but then star is unable to
144 detect all error conditions; so use with care.
145 If the option -t has been specified in addition, the last file
147 type argument is not a target directory and star is performing a
148 one pass listing instead of copying files. This makes sense as
149 the listing from star may be better readable than the output
150 from ls -lR. The shorthand -c -t or -ct instead of -copy -t is
151 also allowed.
152 The job is by default done in the best archive mode. This
154 implies that it defaults to H=exustar -dump. When in -copy
155 mode, star forks into two processes and data exchange is done
156 via the shared memory from the FIFO. This gives the best possi‐
157 ble performance. Without FIFO, the -copy mode will not work.
158 The list= option, patterns and substitutions apply only to the
160 create side of the copy command.
161 -diff Compare the content and the attributes of the files from the ar‐
163 chive in tarfile to the filesystem. This may also be used to
164 compare two file trees in the filesystem. If you use a set of
165 diffopts that fits your needs, it will give - in many cases - a
166 more readable output than diff -r. If you use star's dump
167 extensions for the tar archive, the -diff option allows to find
168 even if the directory in the file tree contains more files than
169 the archive. This way, it is possible to compare all properties
170 of two file trees in one run. See diffopts for more details.
171 Adding one or more -v options increases the verbosity. With -vv
172 and above, the directory content is compared also if star is
173 reading a tar archive that has been created in -dump mode.
174 -n No extraction. Show what star would do, in case the -x command
176 had been specified.
177 -r Replace files in a tarfile. The named files are written to the
179 end of tarfile. This implies that later, the appropriate files
180 will be found more than once on the tarfile.
181 -t Table of contents. List the contents of the tarfile. If the -v
183 flag is used, the listing is similar to the format of ls -l out‐
184 put. With this option, the flags -a, -atime and -ctime have a
185 different meaning if the archive is in star, xstar, xustar,
186 exustar, or pax format. The option -a or -atime lists the
187 access time instead of the modification time, the option -ctime
188 lists the file creation time instead of the modification time.
189 The option -tpath may be used in addition to modify the output
190 so it may be used in shell scripts.
191 -u Update a tarfile. The named files are written to the end of
193 tarfile if they are not already there or if the files are newer
194 than the files of the same name found in the archive. The -r
195 and -u command only work if the tar archives is a regular file
196 or if the tar archive is an unblocked tape that may backspace.
197 -x Extract the named files from the tarfile. If no filename argu‐
199 ment or pattern is specified, the entire content of the tarfile
200 is restored. If the -U flag is not used, star extracts no file
201 which is older than the corresponding file on disk.
202 On operating systems with slow file I/O (such as Linux), it may
204 help to use -no-fsync in addition, but then star is unable to
205 detect all error conditions; so use with care.
206 Except for the shorthands documented above, exactly one of the commands
208 above must be specified.
209 If one or more patterns or substitution commands have been specified,
211 they apply to any of the command listed above. In copy mode, all pat‐
212 terns and substitute commands apply to the create side.
213
216 -help Print a summary of the most important options for star(1).
217 -xhelp Print a summary of the less important options for star(1).
219 -/ Don't strip leading slashes from file names when extracting an
221 archive. Tar archives containing absolute pathnames are usually
222 a bad idea. With other tar implementations, they may possibly
223 never be extracted without clobbering existing files. Star for
224 that reason, by default strips leading slashes from filenames
225 when in extract mode. As it may be impossible to create an ar‐
226 chive where leading slashes have been stripped while retaining
227 correct path names, star does not strip leading slashes in cre‐
228 ate mode.
229 See SECURITY NOTES for more information.
231 -.. Don't skip files that contain /../ in the name. Tar archives
233 containing names with /../ could be used to compromise the sys‐
234 tem. If they are unpacked together with a lot of other files,
235 this would in most cases not even be noticed. For this reason,
236 star by default does not extract files that contain /../ in the
237 name if star is not in interactive mode (see -w option).
238 See SECURITY NOTES for more information.
240 -7z run the input or output through a p7zip pipe - see option -z
242 below.
243 Note that the p7zip program currently does not operate on a pipe
245 but on a /tmp file copy and thus limits the maximum archive
246 size.
247 -0
250 -1
252 -2
254 -3
256 -4
258 -5
260 -6
262 -7 Select an archive entry from /etc/default/star. The format for
264 the archive entries is the same as the format in
265 /etc/default/tar in Solaris.
266 -acl Handle Access Control List (ACL) information in create and
268 extract mode. If -acl has been specified, star is in create
269 mode and the header type is exustar, star will add ACL informa‐
270 tion to the archive using POSIX.1-2001 extended headers. If
271 -acl has been specified and star is in extract mode, star will
272 try to restore ACL information. If there is no ACL information
273 for one or all files in the archive, star will clear the ACL
274 information for the specific file. Note that if -acl has not
275 been specified, star will not handle ACL information at all and
276 files may inherit ACL information from the parent directories.
277 If the -acl option has been specified, star assumes that the -p
278 option has been specified too.
279 Star currently supports the withdrawn POSIX.1e ACLs and NFSv4
281 ACLs. To check which ACL flavors are supported on the current
282 platform, call star -version. Whether POSIX.1e ACLs can be con‐
283 verted into NFSv4 ACLs depends on the local ACL support library.
284 artype=headertype
286 Generate a tape archive in headertype format. If this option is
287 used in extract/list mode this forces star to interpret the
288 headers to be of type headertype. As star even in case of a
289 user selected extract archive format does format checking, it
290 may be that you will not be able to unpack a specific archive
291 with all possible forced archive formats. Selecting the old tar
292 format for extraction will always work though. Valid parameter
293 for headertype are:
294 help Print a help message about possible header types.
296 v7tar Old UNIX V7 tar format. This archive format may only
298 store plain files. Pathnames or linknames longer than
299 99 chars may not be archived.
300 If the v7tar format has been selected, star will not
302 use enhancements to the historic UNIX V7 tar format.
303 File size is limited to 2 GB - 2 bytes, uid/gid is
304 limited to 262143. Sparse files will be filled up
305 with zeroes.
306 tar Old BSD UNIX tar format. This archive format may only
308 store plain files, directories and symbolic links.
309 Pathnames or linknames longer than 99 chars may not be
310 archived. See also the -d option as a note to some
311 even older tar implementations.
312 If the tar format has been selected, star will not use
314 enhancements to the historic tar format. File size is
315 limited to 2 GB - 2 bytes, uid/gid is limited to
316 262143. Sparse files will be filled up with zeroes.
317 star Old star standard format. This is an upward/downward
319 compatible enhancement of the old (pre Posix) UNIX tar
320 format. It has been introduced in 1985 and therefore
321 is not Posix compliant. The star format allows to ar‐
322 chive special files (even sockets) and records access
323 time and creation time besides the modification time.
324 Newer versions of the old star format allow very long
325 filenames (100+155 chars and above), linknames > 100
326 chars and sparse files (if -sparse is used). This
327 format is able to copy the device nodes on HP-UX that
328 have 24 bits in the minor device number, which is more
329 then the 21 bits that are possible with the
330 POSIX-1003.1-1988 archive format.
331 The nonstandard extensions are located in the space
333 between the link name and the POSIX file name prefix.
334 As the star format does not use a POSIX magic string,
335 the extensions do not interfere with the POSIX tar
336 formats. The last 4 bytes of the tar header contain a
337 'tar\0' signature.
338 gnutar This is a commonly used, but unfortunately not Posix
340 compliant (although designed after 1987) enhancement
341 to the old tar format. The gnutar format has been
342 defined between 1989 and 1994. Do not use the gnutar
343 archive format unless you want to create an archive
344 for a target system that is known to have only the
345 gnutar program available. The gnutar archive format
346 violates basic rules for any (even the historic) tar
347 archive format, in special when sparse files are
348 archived using the -sparse option. Using the gnutar
349 archive format causes a high risk that the resulting
350 archive may only be read by gnutar or by star. The
351 implementation of the gnutar archive format within
352 star is not complete, but sufficient for most gnutar
353 archives. See NOTES for more information.
354 ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data Inter‐
356 change format. With this option in effect, star will
357 generate 100% POSIX.1-1988 compliant tar archives.
358 Files with pathnames longer than 100+155 chars or
359 linknames longer than 100 chars may not be archived.
360 If star is called as ustar the default archive format
361 is ustar.
362 If the ustar format has been selected, star will not
364 use enhancements to the POSIX.1-1988 tar format, the
365 archive will be strictly conforming. File size is
366 limited to 8 GB, uid/gid/major/minor is limited to
367 2097151. Sparse files will be filled up with zeroes.
368 pax The IEEE/Posix1003/IEC-9945-1-1988 successor is the
370 POSIX-1003.1-2001 Standard Data Interchange format.
371 It is called the pax archive format.
372 If the pax format has been selected, star will not use
374 enhancements to the POSIX.1-2001 tar format, the ar‐
375 chive will be strictly conforming. File size is
376 unlimited, uid/gid/uname/gidname is unlimited,
377 major/minor is limited to 2097151. Sparse files will
378 be filled up with zeroes.
379 xstar The extended standard tar format has been introduced
381 in 1994. Star uses the xstar format as default ar‐
382 chive format. This is an upward/downward compatible
383 enhancement of the IEEE/Posix1003/IEC-9945-1 Standard
384 Data Interchange format. It allows among others very
385 long filenames (100+130 chars and above) and records
386 access time and creation time. Sparse files will be
387 archived correctly (if -sparse is used).
388 The access time and creation time are stored at the
390 end of the POSIX file name prefix (this limits the
391 prefix to 130 chars). These extensions do not inter‐
392 fere with the POSIX standard as the fields for mtime
393 and ctime field are always separated from the POSIX
394 file name prefix by a null byte. The last 4 bytes of
395 the tar header contain a 'tar\0' signature.
396 The xstar format is the default format when star is
398 neither called as tar nor called as ustar.
399 xustar A new format introduced 1998, that omits the 'tar\0'
401 signature at the end of the tar header. It is other‐
402 wise identical to the xstar format. As some tar
403 implementations do not follow the POSIX rules and com‐
404 pute the checksum for less than 512 bytes of the tar
405 header, this format may help to avoid problems with
406 these broken tar implementations. The main other dif‐
407 ference to the xstar format is that the xustar format
408 uses POSIX.1-2001 extended headers to overcome limita‐
409 tions of the historic tar format while the xstar for‐
410 mat uses proprietary extensions. The xustar format is
411 the default format when star is called as tar.
412 File size is unlimited, uid/gid/uname/gidname is
414 unlimited, major/minor is unlimited. Sparse files
415 will be archived correctly (if -sparse is used).
416 exustar A format similar to the xustar format but with forced
418 POSIX.1-2001 extended headers. If this format is used
419 together with the -acl option, star records Access
420 Control Lists (ACLs) in POSIX.1-2001 extended headers.
421 The exustar format allows to archive all file types
423 but it does not archive more than the POSIX.1-1988 set
424 by default. If the -dump option is used or if star is
425 otherwise on dump mode, star archives all file types
426 and in addition archives more meta data then usual.
427 File size is unlimited, uid/gid/uname/gidname is
429 unlimited, major/minor is unlimited. Sparse files
430 will be archived correctly (if -sparse is used).
431 suntar The extended header format found on Solaris 7/8/9.
433 This format is similar to the pax format but does not
434 handle atime and ctime and in addition uses 'X' as the
435 typeflag for the extended headers instead of the stan‐
436 dard 'x'.
437 File size is unlimited, uid/gid/uname/gidname is
439 unlimited, major/minor is unlimited. Sparse files
440 will be filled up with zeroes.
441 bin The cpio UNIX V7 binary format. This is a format with
443 big interoperability problems. Try to avoid this for‐
444 mat. It is only present to make the scpio command
445 SVr4 compliant.
446 cpio The POSIX.1-1988 cpio format. This format uses octal
448 ascii headers. A similar format is created by calling
449 cpio -o -c on pre SYSVr4 systems and by calling cpio
450 -o -Hodc on SYSVr4 systems. The POSIX.1-1988 cpio
451 format allows a file name length up to 262142 charac‐
452 ters and allows to archive nearly any file type. File
453 size is limited to 8 GB, uid/gid/st_dev is limited to
454 262143. The way major and minor device numbers are
455 stored inside the st_dev field is implementation
456 dependent.
457 Even though this archive format is covered by the
459 POSIX.1-1988 standard, it has a lower portability than
460 the ustar format. Try to avoid the cpio archive for‐
461 mat.
462 odc This archive format is similar to the The POSIX.1-1988
464 cpio format but the file name length is limited to 255
465 characters and the socket file type is not allowed.
466 This archive format has been introduced to allow non
467 POSIX cpio implementations such as the cpio program on
468 SYSV to accept the archive. Use this format whenever
469 you are not sure if the target system offers a fully
470 POSIX compliant cpio program.
471 Even though this archive format is covered by the
473 POSIX.1-1988 standard, it has a lower portability than
474 the ustar format. Try to avoid the odc archive format.
475 asc Tell star to create a cpio archive in the ascii format
477 that is created with cpio -o -c on SYSVr4 systems. It
478 uses extended (32 bit) numbers for uid's, gid's and
479 device numbers but limits the file size to 4 GB - 2
480 bytes although the format has been specified after the
481 POSIX.1-1988 cpio format. Try to avoid the asc ar‐
482 chive format because of its limited portability.
483 crc This format is similar to the asc cpio format but in
485 addition uses a simple byte based checksum called here
486 as CRC. This algorithm is simple Sum32 -- not a poly‐
487 nomial CRC. Try to avoid the crc archive format
488 because of its limited portability.
489 All tar archive formats may be interchanged if the archive con‐
492 tains no files that may not be archived by using the old tar
493 format. Archives in the xstar format may be extracted by any
494 100% POSIX compliant tar implementation if they contain no files
495 with pathnames > 100+130 chars and if they contain no sparse
496 files that have been archived by using the -sparse option.
497 -ask_remove
500 obsoleted by -ask-remove
501 -ask-remove
503 Ask to remove non writable files on extraction. By default,
504 star will not overwrite files that are read only. If this
505 option is in effect, star will ask whether it should remove
506 these files to allow the extraction of a file in the following
507 way:
508 remove 'filename' ? Y(es)/N(o) :
510 -atime, -a
512 Reset access time of files after storing them to tarfile. On
513 Solaris 2.x, (if invoked by root) star uses the _FIOSATIME ioctl
514 to do this. This enables star not to trash the ctime while
515 resetting the atime of the files. If the -atime option is used
516 in conjunction with the list command, star lists access time
517 instead of modification time. (This works only in conjunction
518 with the star, xstar, xustar, exustar, and with the pax format.)
519 Another option to retain the access time for the the files that
520 are going to be archives is to readonly mount a UFS snapshot and
521 to archive files from the mount point of the UFS snapshot.
522 -B Force star to perform multiple reads (if necessary) to fill a
524 block. This option exists so that star can work across the Eth‐
525 ernet, since pipes and sockets return partial blocks even when
526 more data is coming. If star uses stdin as archive file, star
527 behaves as if it has been called with the -B option. For this
528 reason, the option -B in practice is rarely needed.
529 -block-number
531 Print the archive block number (archive offset / 512) at the
532 beginning of each line when in verbose mode. This allows to
533 write backup scripts that archive the offsets for files and that
534 use
535 mt fsr blockno
537 to skip to the tape block number of interest in a fast way if a
539 single file needs to be restored.
540 blocks=#, b=#
542 Set the blocking factor of the tarfile to # times 512 bytes
543 (unless a different multiplication factor has been specified -
544 see bs= option for possible multiplication factors). Changing
545 the blocking factor only makes sense when the archive is located
546 on a real tape device or when the archive is accessed via the
547 remote tape protocol (see f= option below). The default is to
548 use a blocking factor of 20 i.e. 10 kBytes. Increasing the
549 blocksize will speed up the backup. For portability with very
550 old tar implementations (pre BSD 4.2 or pre AT&T SVR4), block‐
551 size should not be more than 10 kBytes. For POSIX.1-1988 com‐
552 patibility, blocksize should be no more than 10 kBytes. For
553 POSIX.1-2001 compatibility, blocksize should be no more than
554 32 kBytes. Most systems also have a hardware limitation for the
555 blocksize, 32 kBytes and 63 kBytes are common limits on many
556 systems. The upper limit in any case is the size of the buffer
557 RAM in the tape drive. Make a test if you want to make sure
558 that the target system will handle the intended blocksize. If
559 you use star for data exchange via tape, it is a good idea to
560 use a blocksize of 10 kBytes unless you are sure that the read‐
561 ing system will handle a larger blocksize. If you use star for
562 backup purposes with recent hardware (e.g. DLT tape drives), a
563 blocksize of 256 kBytes results in sufficient speed and seems to
564 be a good choice. Star allows block sizes up to 2 GByte if the
565 system does not impose a smaller limit. If you want to deter‐
566 mine the blocking factor when reading an unknown tar archive on
567 tape, specify a blocking factor that is higher than the supposed
568 blocking factor of the tape. Star then will determine the
569 blocking factor by reading the first record of the tape and
570 print a message:
571 star: Blocksize = # records.
573 Where # is the blocking factor in multiples of 512 bytes. The
575 blocks= option and the bs= option are equivalent methods to
576 specify the tape block size. The blocks= option is preferred by
577 people who like to use an option that behaves similar to the
578 interface of the historic tar(1) implementations.
579 bs=# Set output block size to #. You may use the same method as in
581 dd(1) and sdd(1). The number representing the size is taken in
582 bytes unless otherwise specified. If a number is followed
583 directly by the letter `.', `w', `b', `k', `m', `g', `t', or
584 `p', the size is multiplied by 1, 2, 512, 1024, 1024*1024,
585 1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024.
586 If the size consists of numbers separated by `x' or `*', multi‐
587 plication of the two numbers is performed. Thus bs=7x8k will
588 specify a blocksize of 56 kBytes. Blocksize must be a multiple
589 of 512 bytes. See also the description of the blocks= option
590 for more details on blocksizes. The option bs= is preferred by
591 people who like to use an option that behaves similar to the
592 interface used by dd(1) and sdd(1).
593 -bsdchdir
595 Switch the behavior of the C= option to BSD style. The default
596 behavior of star is to stay in a working directory until a new
597 C= is seen. With BSD tar, the C= option is only related to the
598 next file type argument.
599 -bz run the input or output through a bzip2 pipe - see option -z -Z
601 and -j below. As the -bz the -j the -Z and the -z option are
602 non standard, it makes sense to omit the -bz the -j the -Z and
603 the -z options inside shell scripts if you are going to extract
604 a compressed archive that is located inside a plain file as star
605 will auto detect compression and choose the right decompression
606 option to extract.
607 C=dir
609 -C dir Perform a chdir(2) operation to dir before storing or extracting
611 the next files. In all cases, star will perform the chdir(2)
612 operation relative to the current working directory of the
613 shell.
614 · In list mode (with the -t flag), star ignores all -C
616 options.
617 · In create mode (with the -c, -r and -u flag), star walks
619 through all -C options and file type arguments. While a
620 BSD derived tar(1) implementation goes back to the cur‐
621 rent working directory after storing one file argument
622 that immediately follows the -C option, star changes the
623 directory only if a new -C option follows. To emulate
624 the behavior of a BSD derived tar(1), add a -C . option
625 after the file argument.
626 · In extract mode (with the -x, -n and -diff flag), star
628 builds a pattern list together with corresponding direc‐
629 tories from previous C=dir options and performs a
630 chdir(2) to the corresponding directory of a matching
631 pattern. All pat= options that do not follow a C=dir
632 option are interpreted as if they were preceded by a -C .
633 option. See EXAMPLES for more information.
634 compress-program=name
636 Set a named compress program. The program must compress in a
637 pipe when called without parameters and decompress when run with
638 the -d option in a pipe. This option is otherwise similar to
639 the -z the -j the -Z and the -bz option.
640 -copydlinks
642 Try to recursively copy the content of linked directories
643 instead of creating the link. This is an experimental feature
644 that may help to unpack archives on DOS.
645 -copyhardlinks
647 This option allows to copy hardlinked targets rather than creat‐
648 ing the link. It helps to extract tar files on systems that do
649 not implement hardlinks (e.g. BeOS).
650 -copylinks
652 This option allows to copy both, hard- and symlinked targets
653 rather than creating a link. It helps to extract tar files on
654 systems that do not implement links (e.g. OS/2). To extract and
655 copy all symlinks correctly, you may need to call star twice as
656 star cannot copy files that appear in the archive later than a
657 symlink pointing to them.
658 -copysymlinks
660 This option allows to copy symlinked targets rather than creat‐
661 ing a symbolic link. It helps to extract tar files on systems
662 that do not implement links (e.g. OS/2). To extract and copy
663 all symlinks correctly, you may need to call star twice as star
664 cannot copy files that appear in the archive later than a sym‐
665 link pointing to them.
666 -cpio-statistics
668 Instead of the star flavor of the statistics, print statistics
669 in cpio flavor.
670 -ctime If used with the list command, this lists ctime rather than
672 mtime if the archive format is star, xstar, xustar, exustar, or
673 pax.
674 If star is run as root and if -ctime is used with the extract
676 command and the same archive formats, this causes star to try to
677 restore even the ctime of a file by generating time storms. You
678 should not do this when in multi user mode because this may con‐
679 fuse programs like cron and the news system. Although star
680 tries to eliminate the accumulative effects of the time storm,
681 there is a tendency for the system clock to slow down a bit.
682 The clock typically lags about one millisecond per extracted
683 file. Use with care and check the system clock after using this
684 feature.
685 If used with the create command this changes the behavior of the
687 newer= option. Star, in this case compares the ctime of all
688 files to the mtime of the stamp file rather then comparing the
689 mtimes of both files.
690 -cumulative
692 A shorthand for -dump-cumulative. See -dump-cumulative for more
693 information.
694 -D Do not descend directories when in create mode. Normally, star
696 descends the whole tree if it encounters a directory in in its
697 file parameters. The option -D is in effect by default if the
698 list=file option is used. If you like star to descend directo‐
699 ries found in the list file, use the -dodesc option (see below).
700 -d Do not store/create directories. Old versions of tar such as
702 published with the seventh edition of UNIX are not able to deal
703 with directories in tar archives. If a tar archive is generated
704 without directories this avoids problems with tar implementa‐
705 tions found on SYSVr3 and earlier. If used during extract, no
706 intermediate missing directories are created.
707 -data-change-warn
709 If the size of a file changes while the file is being archived,
710 treat this condition as a warning only that does not cause a non
711 zero exit code. A warning message is still written if the con‐
712 dition is not otherwise ignored by another rule from an errctl=
713 option. The -data-change-warn option works as if the last error
714 control option was
715 errctl="WARN|GROW|SHRINK *"
717 The -e option or an ABORT entry in a condition set up by errctl=
719 has a higher precedence than the -data-change-warn option. This
720 option is ignored in extract or list mode.
721 -debug Print debug messages. Among other things, this gives debug mes‐
723 sages for header type recognition, tar type properties, EOF
724 recognition, opening of remote archives and fifo internals.
725 diffopts=optlst
727 Comma separated list of diffopts. Valid members in optlst are:
728 help Print a summary of possible members of the diffopts
730 list.
731 ! Invert the meaning of the following string. No comma
733 is needed after the exclamation mark.
734 not Invert the meaning of all members in the diffopts list
736 i.e. exclude all present options from an initially
737 complete set compare list. When using csh(1) you
738 might have problems to use ! due to its strange
739 parser. This is why the not alias exists.
740 perm Compare file permissions. With this option in effect,
742 star compares the low order 12 bits of the st_mode
743 field.
744 mode Same as perm.
746 symperm Compare permissions even in case the target file on
748 the local filesystem is a symbolic link. By default,
749 star will not compare the permission of symbolic links
750 as most systems cannot set the permission of symbolic
751 links. Star compares symperm only if perm is compared
752 also.
753 type Compare file type. Note that star cannot compare the
755 file type in case of a hard link.
756 nlink Compare link count on hardlinks. This only works if
758 the archive is in exustar format and contains star's
759 dump extensions.
760 uid Compare numerical user id of file.
762 gid Compare numerical group id of file.
764 uname Compare ASCII version of user id of file. The user
766 name is mapped via the file /etc/passwd.
767 gname Compare ASCII version of group id of file. The group
769 name is mapped via the file /etc/group.
770 id Shorthand for: uid,gid,uname,gname. Compare all
772 user/group related info of file. Note that this will
773 always find differences if the source and target sys‐
774 tem use different user or group mappings.
775 size Compare file size. Note that star cannot compare the
777 file size in case of a hard link.
778 data Compare content of file. If star already found that
780 the size of the files differ, it will not compare the
781 content anymore. If the size of the files differ,
782 star will always report different data.
783 cont Same as data.
785 rdev Compare major/minor numbers for device nodes.
787 hardlink Compare target of hardlinks.
789 symlink Compare target of symlinks. This evaluates the paths
791 returned by the readlink(2) call.
792 Two symlinks are considered equal, it they either have
794 a characterwise identical link-name, or if they either
795 both use an absolute path name or both use a relative
796 path name and the following is true: Both symlinks
797 point to the same file that must exist or both path‐
798 names look similar enough.
799 sympath Compare the target pathnames of symlinks. This charac‐
801 terwise compares the strings returned from the read‐
802 link(2) call.
803 sparse Compare if either both files are sparse or not. If
805 only one of both files is sparse, then a difference is
806 flagged. This only works with if the archive format
807 is star, xstar, xustar, exustar, or gnutar.
808 atime Compare access time of file. This only works with if
810 the archive format is star, xstar, xustar, exustar, or
811 pax.
812 mtime Compare modification time of file.
814 ctime This only works with if the archive format is star,
816 xstar, xustar, exustar, or pax.
817 lmtime Compare the modification time even in case the target
819 file on the local filesystem is a symbolic link. By
820 default, star will not compare the modification time
821 of symbolic links as most systems cannot set the modi‐
822 fication time of symbolic links. Star compares lmtime
823 only if mtime is compared also.
824 times Shorthand for: atime,mtime,ctime.
826 dir Compare the content of directories. This only works
828 if the archive is in exustar format and contains
829 star's dump extensions. Together with increased ver‐
830 bose level (-vv) this will print a list of files that
831 are only in the archive and a list of files that are
832 only on the current filesystem.
833 xtimes Shorthand for: atime,mtime,ctime,lmtime.
835 acl Compare access control lists. This only works if the
837 archive is in exustar format and has been created with
838 star's -acl option. You need to specify the -acl
839 option in addition when running the diff.
840 xattr Compare extended file attributes. This only works if
842 the archive is in exustar format and has been created
843 with star's -xattr option. You need to specify the
844 -xattr option in addition when running the diff.
845 fflags Compare extended file flags. This only works if the
847 archive is in exustar format and has been created with
848 star's -xfflags option. You need to specify the
849 -xfflags option in addition when running the diff.
850 If optlst starts with a ! the meaning of all members in optlst
852 is inverted as with the not optlist member. In this case, star
853 starts with a complete list that includes atime and lmtime.
854 Reasonable diff options to use when comparing against a copy of
855 a directory tree are diffopts=!atime,ctime,lmtime.
856 If diffopts are not specified, star compares everything but the
858 access time of the files and the modification time of symbolic
859 links.
860 dir-group=group
862 If star extracts archives as root, this option allows to control
863 the group id of intermediate directories created by star.
864 dir-owner=user
866 If star extracts archives as root, this option allows to control
867 the owner of intermediate directories created by
868 -dirmode
870 If in create mode (i.e. when storing files to archive), star
871 stores directories past the corresponding files. This guarantees
872 that even old tar implementations without a directory cache will
873 be able to restore the correct times of directories. The option
874 -dirmode should only be used if the archive needs to be
875 extracted by an old tar implementation. If star is used to
876 extract an archive that has been created with -dirmode the
877 directories will not get an old time stamp unless the option -U
878 is used while extracting the archive.
879 -dodesc
881 Force star to descend directories found in a list=file. See
882 also the -D option above. The -dodesc option only works in cre‐
883 ate mode.
884 -dump Allows to create archives with the same number of attributes as
886 an archive that has been created with the level= option but
887 without the restrictions that apply to a true dump.
888 The resultant archive may be seen as a level-less dump which
890 includes similar attributes as a level 0 dump but may span more
891 than a single file system and does not need to use a -C option.
892 It has been originally introduced to make it easier to implement
893 a star version that supports true incremental dumps, but it is
894 kept as it gives additional benefits. Star currently sets the
895 archive type to exustar and, in addition archives more inode
896 meta data inside POSIX.1-2001 extended headers. See also level=
897 option and the section INCREMENTAL BACKUPS for more information
898 on true incremental dumps.
899 -dump-cumulative
901 instructs star to perform incremental dumps relatively to the
902 last incremental dump of the same level. Incremental dumps with
903 a level higher than 0 are normally done relatively to the con‐
904 tent of a previous dump with lower level. If incremental dumps
905 and restores are going to be used to synchronize filesystem con‐
906 tent, every successive incremental dump will increase in size if
907 -dump-cumulative is not used. See section SYNCHRONIZING
908 FILESYSTEMS for more information.
909 dumpdate=name
912 Tells star to use the mtime of the time stamp file name instead
913 of using the start time of star. This is needed when star is
914 run on file system snapshots. If star would use the the start
915 time with snapshots, all files that have been modified between
916 the setup of the snapshot and the start of star would be missing
917 on the backup.
918 -dumpmeta
920 changes the behavior of star in incremental dump mode. If
921 -dumpmeta is used and only the inode change time (st_ctime) of a
922 file has been updated since the last incremental dump, star will
923 archive only the meta data of the file (e.g. uid, permissions,
924 ...) but not the file content. Using -dumpmeta will result in
925 smaller incremental dumps, but files that have been created
926 between two incrementals and set to an old date in st_mtime
927 (e.g. as a result from a tar extract) will not be archived with
928 full content. Using -dumpmeta thus may result in incomplete
929 incremental dumps, use with extreme care.
930 -e Exit immediately with exit status -3 (253) if any unexpected
932 error occurs. The -e option works as if the last error control
933 option was
934 errctl="ABORT|ALL|DIFF *"
936 This allows to use the errctl= option together with the -e
938 option and thus to ignore some error conditions while aborting
939 on all other conditions.
940 errctl= name
942 errctl= error control spec
944 Add the content from file name to the error control definitions
945 or add error control spec to the error control definitions.
946 More than one error control file and more than one error control
947 spec as well as a mixture of both forms is possible.
948 The reason for using error control is to make star quiet about
950 error conditions that are known to be irrelevant on the quality
951 of the archive or restore run or to tell star to abort on cer‐
952 tain error conditions instead of trying to continue with the ar‐
953 chive.
954 A typical reason to use error control is to suppress warnings
956 about growing log files while doing a backup on a live file sys‐
957 tem. Another typical reason to use error control is to tell
958 star to abort if e.g. a file could not be archived instead of
959 continuing to archive other files from a list.
960 The error control file contains a set of lines, each starting
962 with a list of error conditions to be ignored followed by white
963 space followed by a file name pattern (see match(1) or pat‐
964 match(3) for more information). The error control spec uses the
965 same syntax as a single line from the error control file. If
966 the file name pattern needs to start with white space, use a
967 backslash to escape the start of the file name. It is not possi‐
968 ble to have new line characters in the file name pattern. When‐
969 ever an error situation is encountered, star checks the lines in
970 the error control file starting from the top. If the current
971 error condition is listed on a line in the error control file,
972 then star checks whether the pattern on the rest of the line
973 matches the current file name. If this is the case, star uses
974 the current error control specification to control the current
975 error condition.
976 The list of error conditions to be handled may use one or more
978 (in this case separated by a '|' character) identifiers from the
979 list below:
980 ABORT If this meta condition is included in an error con‐
982 dition, star aborts (exits) as soon as possible
983 after this error condition has been seen instead of
984 making star quiet about the condition. This error
985 condition flag may only be used together with at
986 another error condition or a list of error condi‐
987 tions (separated by a '|' character).
988 WARN If this meta condition is included in an error con‐
990 dition, star prints the warning about the error con‐
991 dition but the error condition does not affect the
992 exit code of star and the error statistics (which is
993 printed to the end) does not include the related
994 errors. This error condition flag may only be used
995 together with at another error condition or a list
996 of error conditions (separated by a '|' character).
997 The WARN meta condition has a lower precedence than
998 ABORT.
999 DIFF Suppress output in case that star -diff did
1001 encounter any differences.
1002 ALL This is a shortcut for all error conditions below.
1004 STAT Suppress warnings that star could not stat(2) a
1006 file.
1007 GETACL Suppress warnings about files on which star had
1009 problems to retrieve the ACL information.
1010 OPEN Suppress warnings about files that could not be
1012 opened.
1013 READ Suppress warnings read errors on files.
1015 WRITE Suppress warnings write errors on files.
1017 READLINK Suppress warnings readlink(2) errors on symbolic
1019 links.
1020 GROW Suppress warnings about files that did grow while
1022 they have been archived.
1023 SHRINK Suppress warnings about files that did shrink while
1025 they have been archived.
1026 MISSLINK Suppress warnings about files for which star was
1028 unable to archive all hard links.
1029 NAMETOOLONG Suppress warnings about files that could not be
1031 archived because the name of the file is too long
1032 for the archive format.
1033 FILETOOBIG Suppress warnings about files that could not be
1035 archived because the size of the file is too big for
1036 the archive format.
1037 SPECIALFILE Suppress warnings about files that could not be
1039 archived because the file type is not supported by
1040 the archive format.
1041 GETXATTR Suppress warnings about files on that star could not
1043 retrieve the extended file attribute information.
1044 SETTIME Suppress warnings about files on that star could not
1046 set the time information during extraction.
1047 SETMODE Suppress warnings about files on that star could not
1049 set the access modes during extraction.
1050 SECURITY Suppress warnings about files that have been skipped
1052 on extraction because they have been considered to
1053 be a security risk. This currently applies to all
1054 files that have a '/../' sequence inside when -..
1055 has not been specified.
1056 LSECURITY Suppress warnings about links that have been skipped
1058 on extraction because they have been considered to
1059 be a security risk. This currently applies to all
1060 link names that start with '/' or have a '/../'
1061 sequence inside when -secure-links has been speci‐
1062 fied. In this case, star tries to match the link
1063 name against the pattern in the error control file.
1064 SAMEFILE Suppress warnings about links that have been skipped
1066 on extraction because source and target of the link
1067 are pointing to the same file. If star would not
1068 skip these files, it would end up with removing the
1069 file completely. In this case, star tries to match
1070 the link name against the pattern in the error con‐
1071 trol file.
1072 BADACL Suppress warnings access control list conversion
1074 problems.
1075 SETACL Suppress warnings about files on that star could not
1077 set the ACL information during extraction.
1078 SETXATTR Suppress warnings about files on that star could not
1080 set the extended file attribute information during
1081 extraction.
1082 If a specific error condition is ignored, then the error condition is
1084 not only handled in a silent way but also excluded from the error sta‐
1085 tistics that are printed at the end of the star run.
1086 Be very careful when using error control as you may ignore any error
1088 condition. If you ignore the wrong error conditions, you may not be
1089 able to see real problems anymore.
1090 -exclude-from name
1092 Exclude from named file, this is an alias for the -X option. See
1093 -X option for more information.
1094 -F,-FF ...
1096 Fast and simple exclude option for create mode. With one -F
1097 argument, star ignores all directories called SCCS and RCS.
1098 With two -F arguments, star in addition ignores all files called
1099 core errs a.out all files ending with .o. OBJ/. With three -F
1100 arguments, star ignores all sub trees starting from a directory
1101 that includes a file .mirror or .exclude and all object files
1102 and files called core errs a.out all files ending with .o. With
1103 four -F arguments, star ignores all sub trees starting from a
1104 directory that includes a file .mirror or .exclude the latter
1105 files are excluded too as well as and all object files and files
1106 called core errs a.out all files ending with .o. With five -F
1107 arguments, star in addition again excludes all directories
1108 called SCCS and RCS.
1109 -fifo Use a fifo to optimize data flow from/to tarfile. This option
1111 is in effect by default (it may be changed at compile time).
1112 The default fifo size is 8 MBytes on all platforms except Linux
1113 versions that do not support mmap() (4 MB because kernels before
1114 2.4 did not handle big shared memory areas) and Sun/mc68000 (1
1115 MB). This will star make even work on a tiny machine like a Sun
1116 3/50. The fifo size may be modified with the fs= option. A rule
1117 of dumb for the fifo size is to use more than the buffer size of
1118 the tape drive and less then half of the real memory of the
1119 machine. A good choice would be to use a fifo size between 8
1120 and 256 MB. This may increase backup speed up to 5% compared to
1121 the speed achieved with the default fifo size. Note that with a
1122 DLT drive that gives 12MB/s transfer rate, a fifo of 256 MB size
1123 will keep the tape at least streaming in units of 20 seconds.
1124 All options that start with the -f sequence are sensitive to
1125 typo problems, see BUGS section for more information.
1126 -fifostats
1128 Print fifo statistics at the end of a star run when the fifo has
1129 been in effect. All options that start with the -f sequence are
1130 sensitive to typo problems, see BUGS section for more informa‐
1131 tion.
1132 file=tarfilename, f=tarfilename
1134 Use tarfilename as the name for the tar archive. Currently up to
1135 100 file= options are possible. Specifying more then one file=
1136 option make sense in multi volume mode. In this case star will
1137 use the next name in the list every time a media change is
1138 needed. To make star behave consistent with the single file
1139 case, star loops over the list of known archive files. Note
1140 that if star is installed suid root and the first tarfile is a
1141 remote archive, only the connection to this archive will be cre‐
1142 ated with root privileges. After this connection has been
1143 established as root, star switches back to the id of the caller.
1144 If any of the other archives in the list is located on a differ‐
1145 ent host, star will not be able to open this archive later on,
1146 unless run by root.
1147 Star normally uses stdin/stdout for the tar archive because the
1149 most common way to use star is in conjunction with pipes. If
1150 star is installed suid root or if it has been called by root,
1151 tarfilename may be in remote syntax: user@host:filename as in
1152 rcp(1) even if invoked by non root users. See SUID NOTES for
1153 more information.
1154 To make a file local although it includes a colon (:), the file‐
1156 name must start with: '/', './' or '../'
1157 Note that if star talks to an old rmt remote tape server that
1159 does not support symbolic open modes, it does not open a remote
1160 tape with the O_CREAT open flag because this would be extremely
1161 dangerous. If the rmt server on the other side is the rmt
1162 server that comes with star or the GNU rmt server, star may use
1163 the symbolic mode for the open flags. Only the symbolic open
1164 modes allow to send all possible open modes in a portable way to
1165 remote tape servers.
1166 It is recommended to use the rmt server that comes with star.
1168 It is the only rmt server that gives platform independent com‐
1169 patibility with BSD, Sun and GNU rmt clients and it includes
1170 security features that may be set up in /etc/default/rmt. All
1171 options that start with the -f sequence are sensitive to typo
1172 problems, see BUGS section for more information.
1173 See ENVIRONMENT section for information on how to use ssh(1) to
1175 create a remote tape server connection.
1176 Note that if file=- has been specified, it is no longer possible
1178 to use the -find -exec primary.
1179 -find This option acts a separator. If it is used, all star options
1181 must be to the left of the -find option. To the right of the
1182 -find option, star accepts the find command line syntax only.
1183 The find expression acts as a filter between the source of file
1185 names and the consumer, which may either be the archiving engine
1186 or list/extract engine. If the find expression evaluated as
1187 TRUE, then the related file is selected for processing, other‐
1188 wise it is omited.
1189 In order to make the evaluation of the find expression more con‐
1191 venient, star implements additional find primaries that have
1192 side effects on the file meta data. Star implements the follow‐
1193 ing additional find primaries:
1194 -chgrp gname
1196 The primary always evaluates as true; it sets the group
1197 of the file to gname.
1198 -chmod mode
1200 The primary always evaluates as true; it sets the permis‐
1201 sions of the file to mode. Octal and symbolic permis‐
1202 sions are accepted for mode as with chmod(1).
1203 -chown uname
1205 The primary always evaluates as true; it sets the owner
1206 of the file to uname.
1207 -false The primary always evaluates as false; it allows to make
1209 the result of the full expression different from the
1210 result of a part of the expression.
1211 -true The primary always evaluates as true; it allows to make
1213 the result of the full expression different from the
1214 result of a part of the expression.
1215 The command line:
1217 star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d
1219 lists all directories and archives all non-directories to the
1221 archive o.tar.
1222 The command line:
1224 star -c f=o.tar -find . ( -type d -chown root -o true )
1226 archives all directories so they appear to be owned by root in
1228 the archive, all non-directories are archived as they are in the
1229 file system.
1230 Note that the -ls, -exec and the -ok primary cannot be used if
1232 stdin or stdout has been redirected by the list=- of by the
1233 file=- options.
1234 -force_hole
1236 obsoleted by -force-hole
1237 -force-hole
1239 Try to extract all files with holes. This even works with files
1240 that are created without the -sparse option. Star, in this case
1241 examines the content of the files in the archive and replaces
1242 writes to parts containing binary zeroes with seeks.
1243 If used together with the -sparse option in create mode, star
1245 assumes all files to be sparse and archives files with blocks of
1246 nulls as sparse files.
1247 This option should be used with extreme care because you some‐
1249 times get in trouble when files get unattended holes. All
1250 options that start with the -f sequence are sensitive to typo
1251 problems, see BUGS section for more information.
1252 -force_remove
1254 obsoleted by -force-remove
1255 -force-remove
1257 Force to remove non writable files on extraction. By default,
1258 star will not overwrite files that are read only. If this
1259 option is in effect, star will silently remove these files to
1260 allow the extraction of a file. All options that start with the
1261 -f sequence are sensitive to typo problems, see BUGS section for
1262 more information.
1263 -force-restore
1265 Force an incremental restore even if the incremental dump is
1266 only a partial dump. See -wtardumps, level= and section INCRE‐
1267 MENTAL BACKUPS for more information.
1268 fs=# Set fifo size to #. See bs= for the possible syntax. The
1270 default size of the fifo is 1 Mbyte on Sun mc68000 systems, 4
1271 Mbytes on non mmap() aware Linux systems and 8 Mbytes on all
1272 other systems. See -fifo option for hints on using the right
1273 fifo size.
1274 fs-name=mount_point
1277 Use mount_point when recording information in /etc/tardumps and
1278 when comparing against information in /etc/tardumps for incre‐
1279 mental backups. This makes sense when backups are made using
1280 file system snapshots and allows /etc/tardumps and the archive
1281 to contain the real name of the file system instead of the tem‐
1282 porary mount point that is used for the snapshot device.
1283 H=headertype
1286 See artype=headertype option. Note that POSIX.1-2001 defines an
1287 option -H that follows symbolic links that have been encountered
1288 on the command line. For this reason, the old star option
1289 H=headertype option may go away in the future even though this
1290 option has been in use by cpio since 1989.
1291 -h, -L Follow symbolic links as if they were files. Normally star will
1293 not follow symbolic links but stores their values in tarfile.
1294 See also the -L option.
1295 -hardlinks
1297 In extract mode, this option tells star to try to create a
1298 hardlink whenever a symlink is encountered in the archive. In
1299 create mode, this option tells star to try to archive a hardlink
1300 whenever a symlink is encountered in the file system.
1301 -hpdev Allow 24 bits for the minor device number using 8 octal digits.
1303 Note that although it allows to create tar archives that can be
1304 read with HP-UX tar, this creates tar archives which violate
1305 POSIX.1-1988. This option is only needed if you like to use a
1306 POSIX.1-1988 based archive format that does not include exten‐
1307 sions. If you use the xstar format, star will use a base 256
1308 extension that allows bigger major/minor numbers by default, if
1309 you use the xustar or the exustar format there is no limitation
1310 at all as these formats use POSIX.1-2001 extended headers to ar‐
1311 chive the major/minor numbers by default.
1312 -i Ignore checksum errors on tar headers. If this option is speci‐
1314 fied, star will not exit if a header with a bad checksum is
1315 found but search for the next valid header.
1316 -install
1318 Carefully replace existing files when extracting files. This is
1319 done similar to install(1) by first extracting the files into a
1320 temporary name and renaming the file to the final name after the
1321 extraction of that file was successful.
1322 As star by default does not remove non-empty directories, an
1324 install that needs to remove existing non-empty directories may
1325 also need the options -force-remove and -remove-recursive.
1326 -j run the input or output through a bzip2 pipe - see option -z -Z
1328 and -bz below. As the -bz the -j the -Z and the -z option are
1329 non standard, it makes sense to omit the -bz the -j the -Z and
1330 the -z options inside shell scripts if you are going to extract
1331 a compressed archive that is located inside a plain file as star
1332 will auto detect compression and choose the right decompression
1333 option to extract.
1334 -keep-nonempty-dirs
1336 Do not complain about trying to remove nonempty directories in
1337 case that -remove-recursive has not been specified.
1338 -keep_old_files
1340 obsoleted by -keep-old-files
1341 -keep-old-files, -k
1343 Keep existing files rather than restoring them from tarfile.
1344 This saves files from being clobbered even if tarfile contains a
1345 more recent version of the corresponding file.
1346 See SECURITY NOTES for more information.
1348 -L, -h Follow symbolic links as if they were files. Normally star will
1350 not follow symbolic links but stores their values in tarfile.
1351 See also the -h option.
1352 -l Do not print a warning message if not all links to hard linked
1354 files could be dumped. This option is evaluated in the opposite
1355 way to historic tar(1) implementations and to POSIX.1. POSIX.1
1356 requests that by default no warning messages will be printed and
1357 -l will enable warning messages when not all links could be
1358 archived.
1359 level=dumplevel
1361 Set level for incremental dumps. This option is used to switch
1362 star into true incremental dump mode. The dumplevel may be in
1363 the range between 0..99.
1364 In true incremental dump mode, a -C option which is followed by
1366 the name a mount point and a dot ('.') as starting directory
1367 name is required. Only a single file system may be handled at a
1368 time. If the directory following the -C option is not referring
1369 to a root directory of a file system, the dump is called a par‐
1370 tial dump. If the directory following the -C option is refer‐
1371 ring to a root directory of a file system and no other restric‐
1372 tions apply that exclude certain files from the dump, the dump
1373 is called a full dump.
1374 By default, the tardumps database is not written. See also the
1376 tardumps=name and -wtardumps options and the section INCREMENTAL
1377 BACKUPS for more information.
1378 -link-data
1380 In create mode, include the data for files even if these files
1381 are hard links. This feature in create mode is currently only
1382 available for the exustar archive format and only in case
1383 -sparse has not been specified.
1384 In extract mode, allow star to deal with data in hard linked
1386 files even if the standard would not allow this for the used ar‐
1387 chive format.
1388 -link-dirs
1390 When in create mode, try to find hard linked directories. Using
1391 -link-dirs will force star to keep track of all directories that
1392 will go into the archive and thus causes a lot more memory to be
1393 allocated than in the default case.
1394 If you like to extract a cpio archive that contains hard linked
1396 directories, you also need to specify -link-dirs in extract or
1397 diff mode. This is needed because many cpio implementations
1398 create buggy archives with respect to hard links. If star would
1399 look for hard linked directories in all cases, it would detect
1400 many pseudo hard links to directories. Use -link-dirs with care
1401 if you extract cpio archives.
1402 Note that not all filesystem allow to create hard links to
1404 directories. Also note that even though a non-root user is able
1405 detect and archive hard linked directories, all known operating
1406 systems require the extraction to be done as root in order to be
1407 able to create or remove hard links to directories. For this
1408 reason its only recommended to use this option when doing accu‐
1409 rate backups and when hard links to directories are expected.
1410 When the option -link-dirs is not used and hard links to direc‐
1412 tories are present, the appendant sub-tree will appear more than
1413 once on the archive and star will print Linkcount below zero
1414 warnings for non directory hard links inside the sub-tree.
1415 list=filename
1417 Read filenames for store/create/list/diff command from filename.
1418 The file filename must contain a list of path names, each on a
1419 separate line. This option implies the -D option. To force
1420 star to descend directories, use the -dodesc option in this
1421 case. See also the -X option.
1422 Note that if list=- has been specified, it is no longer possible
1424 to use the -find -exec primary.
1425 -lowmem
1427 Try to run with reduced memory requirements. This causes star
1428 to default to 1 MB of FIFO memory. Instead of allocating memory
1429 to hold the directory content and reading the directory at once,
1430 star reads the directory name by name. This may cause star to
1431 close the directory if it rans out of file descriptors because
1432 of deeply nested directories. If a directory then does not sup‐
1433 port telldir(3)/seekdir(3), star will fail.
1434 -lzip run the input or output through a lzip pipe - see option -z
1436 below.
1437 -lzo run the input or output through a lzop pipe - see option -z
1439 below.
1440 -M, -xdev
1442 Do not descend mount points. This is useful when doing backups
1443 of complete file systems. See NOTES for more information.
1444 -m Do not restore access and modification time. (Access time is
1446 only available if star is reading star, xstar, xustar, exustar,
1447 or pax archives). If star extracts other archive types, the -m
1448 flag only refers to the modification time.
1449 -match-tree
1452 If in create mode a pattern does not match a directory, and
1453 -match-tree has been specified, the whole directory tree is
1454 excluded from the archive and from further directory scans. By
1455 default, star excludes the directory but still recursively scans
1456 the content of this directory as complex patterns could allow
1457 files inside the directory tree to match. Using -match-tree
1458 allows to efficiently exclude whole trees from scanning. This
1459 helps to avoid scannings directory trees that are on remote file
1460 systems or contain excessive bad blocks.
1461 maxsize=#
1463 Do not store files in tarfile if they are bigger than #. See
1464 bs= for the possible syntax. By default, the number is multi‐
1465 plied by 1024, so the value counts in units of kBytes. If the
1466 size specifier ends with a valid multiplication character (e.g
1467 '.' for bytes or 'M' for MB) the specified size is used as spec‐
1468 ified and not multiplied by 1024. See bs= option for all possi‐
1469 ble multipliers.
1470 -meta In create mode, -meta causes star to archive all meta data of
1472 the file (e.g. uid, permissions, ...) but not the file content.
1473 In extract mode, it causes star to restore all meta data but not
1474 the file content. In addition, in extract mode no plain file,
1475 special file or directory will be created. Meta files are
1476 needed to support incremental backups.
1477 Warning: Do not try to extract star archives containing meta
1479 files using other tar implementations if they are not aware of
1480 the meta file extensions of star. Star tries to force all tar
1481 implementations that are not standard compliant to abort. Star
1482 also tries to make all non POSIX.1-2001 compliant tar implemen‐
1483 tations unable to find a valid filename. However when other
1484 POSIX.1-2001 aware tar implementations come up and don't know
1485 about meta files, they will destroy files on disk.
1486 The problems result from the only current fallback in the POSIX
1488 standard that tells tar implementations to treat all unknown
1489 file types as if they were plain files. As meta files are needed
1490 for incremental backups, I am looking for people and companies
1491 who like to support me to be able to add the meta file concept
1492 to the POSIX.1-2005 standard.
1493 -modebits
1495 This options allows you to create tar archives that include more
1496 than 12 bits from st_mode. Note this create tar archives that
1497 violate POSIX but some tar implementations insist in reading
1498 such nonstandard archives.
1499 -multivol
1501 Switch to multi volume mode. In multi volume mode, there will
1502 be no logical EOF marker written to the end of a single tape. If
1503 -multivol is used in read mode, a hard EOF on input (if not pre‐
1504 ceded by a logical EOF) triggers a medium change operation.
1505 Specifying -multivol tells star to split files across volumes if
1507 needed. This way, a virtual archive is created that spans more
1508 than one medium. Multi volume mode is needed whenever it is not
1509 possible to split the archiving or extracting into several logi‐
1510 cally independent tasks. This is true for e.g. incremental
1511 dump/restore operations where inode numbers need to be traced
1512 for the whole task.
1513 When tsize=# has been specified, but star is not in multi volume
1515 mode, files cannot be split across volumes.
1516 When -multivol has been specified in create mode together with
1518 tsize=# then a media change is initiated exactly after an amount
1519 of tsize data has been written. When -multivol has been speci‐
1520 fied in create mode and tsize=# has not been specified, then the
1521 medium change is triggered by a EOT condition from writing the
1522 medium. This allows to use media where the size cannot be known
1523 in advance (e.g. tapes with build in compression); it does not
1524 work if the EOT condition is not returned in sync with the
1525 related write operation. For this reason, it is expected that
1526 data buffering inside a device driver cannot be used.
1527 Depending on the selected archive format, star writes a volume
1529 header at the beginning of a new medium. This medium header
1530 allows to verify the correct volume after a change during read
1531 back. It is recommended to use the exustar format for best
1532 results. In create mode, -multivol is only supported for ar‐
1533 chives types that allow to write reliable multi volume header
1534 information.
1535 See tsize=# option for more information.
1537 Note that -multivol is an interactive option that prevents star
1539 from being used in non-interactive environments. If you like to
1540 use it in a non-interactive environment, you need to specify
1541 new-volume-script=script in addition in order to automate the
1542 media change procedure.
1543 newer=filename
1545 Do not store files to tarfile if their modification time is not
1546 newer than the modification time of filename. See -ctime option
1547 for changing this behavior.
1548 -newest
1550 In conjunction with the list command this lists you only the
1551 newest file in tarfile.
1552 -newest_file
1554 obsoleted by -newest-file
1555 -newest-file
1557 In conjunction with the list command this lists you only the
1558 newest regular file in tarfile.
1559 new-volume-script=script
1561 Call script at end of each tape if in multi volume mode. If
1562 this option is not in effect, star will ask the user to confirm
1563 the volume change. The script is called with two parameters.
1564 The first parameter is the next volume number and the second
1565 parameter is the next archive file name.
1566 -nodump
1568 If this option is set, star will not dump files that have the
1569 nodump flag set. Note that this currently only works on BSD-4.4
1570 derivates and on Linux. On Linux, using this option will cause
1571 a performance degradation (the system time increases by 10%)
1572 because of the unlucky kernel interface.
1573 -no-dirslash
1575 Do not add a slash to the end of directory names if writing to
1576 an archive. Historic tar archive formats did only allow to
1577 specify plain files and hard links. Around 1980, BSD added a
1578 feature to specify a directory on tape by adding a slash to the
1579 end of the name. POSIX.1-1988 defined the first official tar ar‐
1580 chive format that had a clean method to specify the type of a
1581 directory. As old tar formats need the slash to recognize a
1582 directory, -no-dirslash may not be used if archives should be
1583 compatible with the old tar format.
1584 -no_fifo
1586 obsoleted by -no-fifo
1587 -no-fifo
1589 Don't use a fifo to optimize data flow from/to tarfile. Cur‐
1590 rently the -fifo option is used as default. (This may be changed
1591 at compile time.)
1592 -no-fsync
1594 Do not call fsync(2) for each file that has been extracted from
1595 the archive. Using -no-fsync may speed up extraction on operat‐
1596 ing systems with slow file I/O (such as Linux), but includes the
1597 risk that star may not be able to detect extraction problems
1598 that occur after the call to close(2). A typical cause for such
1599 problems is a NFS file system that fills up before the buffer
1600 cache is synced or a write error that occurs while the buffer
1601 cache is synced. There may be other reasons. Use with extreme
1602 care.
1603 -nochown, -o
1605 Do not restore owner and group of files. This may be used if
1606 super user privileges are needed to overwrite existing files but
1607 the local ownership of the existing files should not change.
1608 -no-p Do not restore files and directories to their original permis‐
1610 sions. This option is needed only if star is called by the
1611 super user and the permissions should not be restored from the
1612 archive. See also the -p option. The -p options has a higher
1613 precedence than the -no-p option.
1614 -no_statistics
1616 obsoleted by -no-statistics
1617 -no-statistics
1619 Do not print statistic messages at the end of a star run.
1620 -no-xheader
1622 Do not create or extract POSIX.1-2001 extended headers. This
1623 option may be used if you like to read an archive with broken
1624 extended headers.
1625 -not, -V
1627 Invert the meaning of the pattern list. i.e. use those files
1628 which do not match any of the pattern. Note that this option
1629 only applies to patterns that have been specified via the pat‐
1630 tern=pattern or pat=pattern option. Patterns specified as file
1631 type arguments will not be affected.
1632 -notarg, -pax-c
1634 Match all file or archive members except those specified by the
1635 pattern or file operands.
1636 -nowarn
1638 Do not print warning messages. This sometimes is useful to make
1639 the output more readable (e.g. when hundreds of files that are
1640 going to be extracted are not newer in the archive then on the
1641 filesystem).
1642 -numeric
1644 Use the numeric user/group fields in the listing rather than the
1645 default. The default allows to list the ASCII version of
1646 user/group of the file and to extract the owners of the files
1647 based on numeric values rather than the names. In create mode,
1648 no user/groups names are put on the archive. The -numeric
1649 option also applies when ACLs are going to be archived or
1650 extracted.
1651 -O Be compatible to old versions of tar. If star is invoked with
1653 this option, star generates archives which are fully compatible
1654 with old UNIX tar archives. If in extract mode, star ignores any
1655 additional info in the headers. This implies neither that ar‐
1656 chives generated with this option are binary equal with archives
1657 generated by old tar versions nor that star is trying to compre‐
1658 hend all bugs that are found in old tar versions. The bug in
1659 old tar versions that cause a reversal of a space and a NULL
1660 byte in the checksum field is not repeated. If you want to have
1661 signed checksums you have to specify the -signed-checksum option
1662 too. If you want directories not to be archived in order to be
1663 compatible to very old historic tar archives, you need to spec‐
1664 ify the -d option too.
1665 This option is superseeded by the H=headertype option.
1667 -o, -nochown
1669 Do not restore owner and group of files. This may be used if
1670 super user privileges are needed to overwrite existing files but
1671 the local ownership of the existing files should not change.
1672 -onull, -nullout
1674 Do not actually write to the archive but compute and add the
1675 sizes. This is useful when trying to figure out if a tape may
1676 hold the current backup. Please only use the -onull option as
1677 it is a similar option as used by the sdd(1) command.
1678 -P Allow star to write a partial record as the last record. Nor‐
1680 mally, star writes each record with the same size. This option
1681 is useful on unblocked tapes i.e. cartridge tapes like QIC tapes
1682 as well as with archives that are located in files. If you use
1683 this option on local files, the size of the archive will be
1684 smaller. If you use this option on cartridge tapes, is makes
1685 sure that later - in extract mode - star will read up to the end
1686 of file marker on the tape and the next call to star will read
1687 from the next archive on the same tape.
1688 -p Restore files and directories to their original permissions.
1690 Without this option, they are created using the permissions in
1691 the archive and the present umask(2). If star is called by the
1692 super user, star behaves as if it has been called with the -p
1693 option. See also -no-p option. If the archive contains Access
1694 Control Lists (ACLs) in POSIX.1-2001 extended headers, star will
1695 restore the access control lists from the archive for files if
1696 the -acl option is specified. If the option -acl has not been
1697 specified, ACLs are not restored at all.
1698 pattern=pattern, pat=pattern
1700 Set matching pattern to pattern. A maximum of 100 pattern=pat
1701 options may be specified. As each pattern is unlimited in
1702 length, this is no real limitation. If more than one pattern is
1703 specified, a file matches if any of the specified pattern
1704 matches. Patterns may be used in create mode to select or
1705 exclude files from the list of file type arguments or the files
1706 located in a sub tree of a file type argument directory. By
1707 default, star scans the whole directory tree underneath a direc‐
1708 tory that is in the argument list. This may be modified by using
1709 the -match-tree option. In extract or list mode, all file type
1710 arguments are interpreted to be select pattern and all option
1711 type patterns may be either select or exclude patterns depending
1712 on the presence or absence of the -not option. If you use file
1713 type select patterns, they work exactly like the method used by
1714 other (non pattern aware) tar(1) implementations. File type
1715 select patterns do not offer pattern matching but allow to
1716 restore subtrees. To extract a complete sub tree from the
1717 directory dir with star using the pattern= option, use pattern=
1718 dir/\* if you like to select a subtree by using the historic
1719 method, use dir as file type argument. If you only like to
1720 extract the directory itself, use dir/ as file type argument.
1721 See manual page for match(1) for more details of the pattern
1722 matcher. All patterns are selection patterns by default. To
1723 make them exclude patterns, use the -not or the -V option.
1724 pkglist=file
1726 This is (for now) an internal interface for the Schily Source
1727 Package System (sps). It only works in create mode and behaves
1728 similar to the list= option, but it allows to overwrite the per‐
1729 missions, the uid and gid values from the content of the
1730 pkglist= file. Each line from the pkglist= file contains a file
1731 name followed by the permission, a user name and a group name.
1732 The permission is an octal character string. Each value that is
1733 not used to overwrite the original values may be replaced by a
1734 '?'. The fields are separated by spaces, so the pkglist= option
1735 does not allow files that contain newline or space characters.
1736 -pax-c, -notarg
1738 Match all file or archive members except those specified by the
1739 pattern or file operands.
1740 -pax-H Follow symbolic links that have been encountered on the command
1742 line. If the referenced file does not exist, the file informa‐
1743 tion and type will be for the link itself. If the link is ref‐
1744 erencing a file type that cannot be archived with the current
1745 archive format, the file information and type will be for the
1746 link itself.
1747 -pax-i Do interactive renaming in a way that has been defined for POSIX
1749 pax. Star will print the original filename and prompt for a
1750 reply. If you type just RETURN, than the file is skipped. If
1751 you type '.', then the original file name is retained. If you
1752 type anything else, then this is taken as the new file name.
1753 Note that -pax-i is an interactive option that prevents star
1755 from being used in non-interactive environments.
1756 -pax-L Follow symbolic links. If the referenced file does not exist,
1758 the file information and type will be for the link itself. If
1759 the link is referencing a file type that cannot be archived with
1760 the current archive format, the file information and type will
1761 be for the link itself.
1762 -pax-ls
1764 Switch listing format to the format defined for POSIX pax and
1765 ls.
1766 -pax-match
1768 Allow file type arguments to be recognised as regular expres‐
1769 sions in a way that has been defined for POSIX pax.
1770 -pax-n Allow each pattern to match only once. If a pattern matches a
1772 directors, then the whole sub tree matches the pattern.
1773 -pax-p string
1775 PAX style privileges string. Several characters (each has its
1776 own meaning). The following characters are defined:
1777 a Do not preserve file access times. This option is cur‐
1779 rently ignored.
1780 e Preserve the user ID, group ID, file mode bits. This is
1782 equivalent to calling star -p -acl -xfflags.
1783 m Do not preserve file modification times. This is cur‐
1785 rently equivalent to calling star -m.
1786 o Preserve the user ID and group ID. This is the default
1788 for star if called as root.
1789 p Preserve the file mode bits. This is equivalent to call‐
1791 ing star -p.
1792 -prinodes
1794 Print inode numbers in verbose list mode if the archive contains
1795 inode numbers.
1796 -print-artype
1798 Check the type of the archive, print the archive and compression
1799 type on a single line and exit.
1800 -qic24 Set tape volume size to 61440 kBytes. See tsize=# option for
1802 more information.
1803 -qic120
1805 Set tape volume size to 128000 kBytes. See tsize=# option for
1806 more information.
1807 -qic150
1809 Set tape volume size to 153600 kBytes. See tsize=# option for
1810 more information.
1811 -qic250
1813 Set tape volume size to 256000 kBytes. See tsize=# option for
1814 more information.
1815 -qic525
1817 Set tape volume size to 512500 kBytes. See tsize=# option for
1818 more information.
1819 -read0 Read null terminated file names from the file specified with the
1821 list= option.
1822 -refresh_old_files
1824 obsoleted by -refresh-old-files
1825 -refresh-old-files
1827 -refresh
1829 Do not create new files. Only already existing files may be
1830 overwritten from tarfile if either newer versions are present in
1831 the archive or if the -U flag is used. This allows to overwrite
1832 files by more recent files from an archive that contains more
1833 files than the target directory should contain. The option
1834 -refresh-old-files is the same as the -refresh option.
1835 -remove_first
1837 obsoleted by -remove-first
1838 -remove-first
1840 Remove files before extraction. If this option is in effect,
1841 star will remove files before extracting a file from the ar‐
1842 chive. This is needed if you want to change the file type or if
1843 you need to break a hard link. If you do not use either
1844 -ask-remove or -force-remove together with -remove-first, this
1845 option is useless and no files will be removed.
1846 -remove_recursive
1848 obsoleted by -remove-recursive
1849 -remove-recursive
1851 Remove files recursive. If removing of a file is permitted,
1852 star will only remove files, specials and empty directories. If
1853 this option is in effect, star will be allowed to recursively
1854 removes non empty directories too.
1855 -restore
1857 switches star into true incremental restore mode. A file named
1858 star-symtable and a directory named star-tmpdir is created in
1859 the root directory of the file system where the extraction takes
1860 place. If -restore has been specified, star behaves as if -xdot
1861 has been specified too. See also level= option and section
1862 INCREMENTAL BACKUPS for more information.
1863 Note: Do not use the -restore option if you only like to restore
1865 a single file or a list of selected files.
1866 -S Do not store/create special files. A special files is any file
1868 except plain files, symbolic links and directories. You need to
1869 be super user to extract special files.
1870 -s replstr
1872 Modify file or archive member names named by a pattern according
1873 to the substitution expression replstr. The format of replstr
1874 is:
1875 -s /old/new/[gp]
1877 The old pattern may use regular expressions and the new string
1879 may contain the special character '&'. The character '&' is sub‐
1880 stituted by the string that matches the old pattern. The
1881 optional trailing 'g' means global substitution. If 'g' is not
1882 used, a substitution pattern is only used once on a name. If
1883 the optional trailing 'p' is used, the substitution is printed
1884 to standard error.
1885 Up to 100 substitute options may be used. If more than one sub‐
1887 stitute option has been specified, star will loop over all sub‐
1888 stitute patterns until one matches.
1889 If the name substitutes to the empty string, the file is
1891 skipped.
1892 -secure-links
1894 Do not extract hard links or symbolic links if the link name
1895 (the target of the link) starts with a slash (/) or if /../ is
1896 contained in the link name. Tar archives containing such links
1897 could be used to compromise the system. If they are unpacked
1898 together with a lot of other files, this may not even be
1899 noticed.
1900 As the usability of a tar archiver would be limited if
1902 -secure-links checking would be done by default, star makes link
1903 checking optional.
1904 If you unpacked a tar archive using the -secure-links and did
1906 not get a security warning at the end of the star run, all files
1907 and links have been extracted. If you get a warning, you should
1908 unpack the archive a second time and specify the options -k, -w
1909 and -nowarn in addition to the options used for the first run.
1910 See SECURITY NOTES for more information.
1911 -shm Use System V shared memory for fifo. Normally star is compiled
1913 to use mapped /dev/zero pages for the fifo, if the operating
1914 system supports this. If star is compiled to have both code for
1915 mapped pages and for System V shared memory, star will use
1916 shared memory instead of the default. If the -help menu doesn't
1917 show the -shm flag you have no choice. When using System V
1918 shared memory, you may have to raise the system's internal limit
1919 for shared memory resources to get enough shared memory for
1920 star.
1921 -signed_checksum
1923 obsoleted by -signed-checksum
1924 -signed-checksum
1926 Use signed chars to calculate checksums. This violates the tar
1927 specs but old versions of tar derived from the seventh edition
1928 of UNIX are implemented in this way. Note: Only filenames and
1929 linknames containing chars with the most significant bit set may
1930 trigger this problem because all other fields only contain 7 bit
1931 ASCII characters, octal digits or binary zeroes.
1932 -silent
1934 Suppress informational messages like foobar is sparse.
1935 -sparse
1937 Handle files with holes effectively on store/create. Note that
1938 sparse files may not be archived this way if the archive format
1939 is tar, ustar, suntar, pax, or any cpio variant. On Solaris-2.3
1940 ... Solaris-2.5.1 there is a special ioctl() called _FIOAI that
1941 allows root to get the allocation info more efficiently. On
1942 Solaris 11 there is an enhanced lseek(2) call with addidional
1943 whence values SEEK_HOLE and SEEK_DATA that allow to find holes
1944 in an efficient way. Other operating systems lack support to
1945 get the real allocation list and force star to scan the files to
1946 look for blocks that only contain null characters. This may
1947 star cause to assume more holes to be present than the number
1948 that the file really contains.
1949 -symlinks
1951 This option tells star in extract mode to try to create a sym‐
1952 link whenever a hardlink is encountered in the archive.
1953 -T If the option file= or f= is omitted and the -T option is
1955 present, star will use the device indicated by the TAPE environ‐
1956 ment variable, if set.
1957 tardumps=name
1959 Set the file name for tar dump dates database to name. The
1960 default name is /etc/tardumps. Use in combination with the
1961 level= option to create true incremental dumps. See also -wtar‐
1962 dumps option and section INCREMENTAL BACKUPS for more informa‐
1963 tion.
1964 -time Print timing info. See DIAGNOSTICS for more information.
1966 -to_stdout
1968 obsoleted by -to-stdout
1969 -to-stdout
1971 Extract files to stdout. This option may be used to extract
1972 tarfiles containing tarfiles (see examples below).
1973 -tpath Use this option together with the -t option or with -cv (verbose
1975 create) to get only a list of the pathnames of the files in the
1976 archive. This may be used in shell scripts to generate a name
1977 list. If used together with the -diff option, star will only
1978 print the names of the files that differ. A second run of star
1979 may then be used to restore all files that had differences to
1980 the archive. Use the list= option to specify the namelist in
1981 this case.
1982 tsize=#
1984 Set tape volume size to # to enable multi volume tape support.
1985 The value refers to the archive size without compression. See
1986 bs= for the possible syntax. By default, the number is multi‐
1987 plied by 512, so the value counts in units of 512 byte blocks.
1988 If the size specifier ends with a valid multiplication character
1989 (e.g '.' for bytes or 'M' for MB) the specified size is used as
1990 specified and not multiplied by 512. With this option in
1991 effect, star is able to archive filesystems that are bigger then
1992 the tape size. If the option tsize=# without -multivol then no
1993 file will be split across volumes and each volume may in theory
1994 be read back separately. Files that do not fit on a single tape
1995 may not be stored in this mode. If -multivol has been specified
1996 in addition, star will split files when the maximum allowed tape
1997 size has been reached. If the tape volume size is not a multi‐
1998 ple of the tape block size, the tape volume size is silently
1999 rounded down to a value that is a multiple of the tape block
2000 size.
2001 See -multivol option for more information.
2003 -U Restore files unconditionally. By default, an older file from
2005 the archive will not replace a corresponding newer file on disk.
2006 umask=mask
2008 Set star's umask to mask. This allows to control the permis‐
2009 sions for intermediate directories that are created by star in
2010 extract mode. See also -p option.
2011 -uncond-rename
2013 When in interactive restore mode or when the -s option was spec‐
2014 ified, unconditionally ask for a new name or apply a substitu‐
2015 tion. This happens even when the current path name would be
2016 skipped otherwise because the file in the archive is not newer
2017 than the file with the original name on disk.
2018 -v Increment verbose level by one. This normally results in more
2020 output during operation. See also in the description for the -t
2021 flag. Normally, star does its work silently. If the verbose
2022 level is 2 or more and star is in create or update mode, star
2023 will produce a listing to the format of the ls -l output.
2024 -V, -not
2026 Invert the meaning of the pattern list. i.e. use those files
2027 which do not match any of the pattern. Note that this option
2028 only applies to patterns that have been specified via the pat‐
2029 tern=pattern or pat=pattern option. Patterns specified as file
2030 type arguments will not be affected.
2031 -version
2033 Print version information and exit.
2034 VOLHDR=name
2036 Use name to generate a volume header.
2037 -w Do interactive creation, extraction or renaming. For every file
2039 that matches the list of patterns and that has a more recent
2040 modification time in the tar archive (if in extract mode and the
2041 -U option is not specified) star prints its name and asks:
2042 get/put ? Y(es)/N(o)/C(hange name) :
2044 You may answer either `N' for No or <Return> to skip this file.
2046 If you answer `Y' the file is extracted or archived on tape with
2047 its original name. If you answer `C', you are prompted for a
2048 new name. This name is used for the filename on disk if star is
2049 in extract mode or for the archive name if star is in create
2050 mode.
2051 See SECURITY NOTES for more information.
2053 Note that -w is an interactive option that prevents star from being
2055 used in non-interactive environments.
2056 -wready
2058 This option tells Star to wait up to two minutes for the drive
2059 to become ready. It has been added as a hack for a bug in the
2060 SunOS/Solaris st device driver. This driver has problems to
2061 sense the loading time with Exabyte drives with factory set‐
2062 tings. It also makes sense to use -wready if multiple remote
2063 backups are made. In this case, the remote connection is closed
2064 while the remote tape server is still writing a file mark. If
2065 another remote backup is initiated before the old remote server
2066 did finish to write the file mark, it would be impossible to
2067 open the tape driver unless -wready is specified to tell star to
2068 wait for the drive to become ready again.
2069 -wtardumps
2071 Tell star to update the file that contains the tar dump dates
2072 data base if in dump mode. If the dump is not a full dump, the
2073 tar dump dates data base file is not written. See also tar‐
2074 dumps=name and -C option or INCREMENTAL BACKUPS section for more
2075 information.
2076 -X filename
2078 Use the file filename as a file containing a list of path names
2079 to be excluded from the store/create/list/diff operation. The
2080 file filename must contain a list of path names, each on a sepa‐
2081 rate line. Be careful with white space and note that path names
2082 in the list may not contain new lines. Multiple -X options may
2083 be used. Each argument must refer to a file containing path
2084 names. The -X option has precedence before other options that
2085 select files to be included in the operation. See also list=
2086 option.
2087 -xattr
2089 -xattr-linux
2091 Store and extract extended file attributes as found on Linux
2092 systems. This option only makes sense when creating or extract‐
2093 ing exustar archives as it is based on POSIX.1-2001 extended tar
2094 headers.
2095 The method used in the current implementation could be used to
2097 store and extract extended file attributes from BSD too. Note
2098 that the current implementation is not generic enough to cover
2099 more general extended file attribute implementations as found on
2100 Solaris. If star starts to implement a method that covers
2101 extended file attributes on Solaris, the new method will be used
2102 then -xattr has been specified and -xattr-linux will refer to
2103 the old method. The method used with -xattr-linux may go away
2104 in the future.
2105 -xcopy An alias for -copy -sparse -acl
2107 xdebug=#, xd=#
2109 Set extended debug level to #.
2110 -xdev, -M
2112 Do not descend mount points. This is useful when doing backups
2113 of complete file systems. See NOTES for more information.
2114 -xdir Extract directories even if the corresponding directories on the
2116 archive are not newer. This is useful when for some reason, the
2117 directories are recorded after their content (see -dirmode
2118 option), or when the permissions of some directories must be set
2119 in any case. As the classical UNIX cpio program does not imple‐
2120 ment delayed directory permission and time stamp setting, cpio
2121 users often create archives in reverse order (directories past
2122 their content). For this reason, it makes sense to use -xdir
2123 while extracting cpio archives.
2124 -xdot Unconditionally extract the first directory in the archive if
2126 the name of this directory is either '.' or './'. This helps to
2127 extract archives in an expected way if the target directory is a
2128 newly created empty directory. As this directory is newer than
2129 the top level directory in the archive, star would usually skip
2130 this directory during extraction. The effect of this directory
2131 is as if -xdir has been specified but is switched off after the
2132 first directory has been found.
2133 -xfflags
2135 Store and extract extended file flags as found on BSD and Linux
2136 systems. This option only makes sense when creating or extract‐
2137 ing exustar archives as it is based on POSIX.1-2001 extended tar
2138 headers. See NOTES section for problems with -xfflags on Linux
2139 systems.
2140 -xmeta Extract meta files as if they were files. Meta files in ar‐
2142 chives are plain files that do not contain any content data in
2143 the archive. They may be created by using the -meta option in
2144 star's create mode. Existing files are not overwritten. If a
2145 file is missing, a zero sized file is created. If the option
2146 -meta is used together with the option -force-hole, missing
2147 plain files are created as sparse empty files of the original
2148 size.
2149 -xz run the input or output through a xz pipe - see option -z below.
2151 -Z run the input or output through a compress pipe - see option -z
2153 below.
2154 -z run the input or output through a gzip pipe. This is currently
2156 a quick and dirty hack, that mainly will cover the most common
2157 usage to compress the tar output if it is a file. No reblocking
2158 will be done, so this option will currently only make sense on
2159 plain files. As the -bz the -j the -Z and the -z option are non
2160 standard, it makes sense to omit the -bz the -j the -Z and the
2161 -z options inside shell scripts if you are going to extract a
2162 compressed archive that is located inside a plain file as star
2163 will auto detect compression and choose the right decompression
2164 option to extract. The environment variable STAR_COMPRESS_FLAG
2165 may be used to specify one option for gzip. If you want to
2166 write write compressed archives to tape, you should use
2167 star -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
2168 or
2169 star -c . | gzip | sdd ibs=4k obs=32k -fill ovsize=60m
2170 of=/dev/rmt/1bn
2171 if the tape can hold 60 MB.
2172
2174 Star is able to back up file system in full and incremental mode. To
2175 allow incremental backups, the file system must implement POSIX seman‐
2176 tics.
2177 To be more verbose:
2179 · The filesystem needs to uniquely identify files by the two num‐
2181 bers st_dev (The device ID of the device containing the file)
2182 and st_ino (The file serial number). If a file is renamed,
2183 these numbers need to be retained. Both numbers need to be a
2184 cardinal scalar that is expressible in a decimal number.
2185 · The filesystem needs to implement at least two time stamps,
2187 st_mtime the file's last modification time and st_ctime the
2188 file's last status change time. Both time stamps need to be
2189 dealt with as documented by the POSIX standard. Both numbers
2190 need to be a cardinal scalar that is expressible in a decimal
2191 number.
2192 · The filesystem needs to allow to rename files and directories by
2194 either calling rename(2), or link(2) and unlink(2).
2195 · The filesystem needs to honor and preserve the case of file
2197 names.
2198 The incremental backup method used by star depends on comparing the
2200 time stamps of all files against the time of the last backup. Note that
2201 this method only works correctly if the level 0 backup and all higher
2202 level incrementals include the whole file system. As star archives all
2203 inode meta data, star is able to detect renamed files by comparing the
2204 inode numbers of all files while in incremental restore mode.
2205 Detecting renamed files only works if star, while in backup mode, scans
2207 the whole file system tree for each full and incremental backup. This
2208 will work in case no files are excluded and the dump starts at the root
2209 directory of a file system. In case that no files are renamed from
2210 excluded parts to included parts, partial backups may be taken also.
2211 Partial backups only make sense if a complete directory sub tree is
2212 excluded (e.g. by using the pat= option) or if a partial backup starts
2213 at a sub directory that is not the root directory of the file system.
2214 To create a level 0 dump call:
2216 star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2218 f=archive-name -C /filestem-mount-point .
2219 To create a level 1 dump call:
2221 star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
2223 f=archive-name -C /filestem-mount-point .
2224 Do not forget the dot at the end of the command line that specifies the
2226 directory to start the operation.
2227 Backups from live filesystems should be avoided. On operating systems
2229 that support file system snapshots, backups should be made from a read-
2230 only mount of a snapshot. Be careful that all files that have been cre‐
2231 ated between setting up a snapshot and starting an incremental backup
2232 may be missing from all backups unless the dumpdate=name option is
2233 used.
2234 If the system that is going to be backed up is not acting as a file
2236 server, it makes sense to shut down all services that may result in
2237 inconsistent file states before setting up the filesystem snapshot.
2238 After the filesystem snapshot has been set up, the services may be
2239 restarted.
2240 If the the system that is going to be backed up is acting as a file
2242 server, it may be that services on remote clients cause inconsistent
2243 file states unless all such services that remotely access files are
2244 shut down before the snapshot is set up.
2245 Star includes options that help to deal with file system snapshots.
2247 The following example backs up a file system on Solaris using a file
2248 system snapshot:
2249 echo > /tmp/snapstamp
2251 mount -r `fssnap -F ufs -o \
2253 backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs` /mnt
2254 star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2256 f=archive-name dumpdate=/tmp/snapstamp \
2257 fs-name=/export/nfs -C /mnt .
2258 First a file with a current time stamp is created, then a snapshot for
2260 /export/nfs is created and mounted on /mnt. The following star command
2261 then creates a level 0 backup from the file system using the time the
2262 snapshot was created and the original mount point of the file system
2263 for /etc/tardumps and the archive header.
2264 Note that if the backup is done on a live file system, it may be unre‐
2266 liable. A typical problem problem in this context is caused by growing
2267 log files. As growing files are not a real problem with backups, the
2268 best way of dealing with growing files is to set up a star error con‐
2269 trol file (see errctl= option) and to tell star to ignore growing
2270 files.
2271
2273 Full (level 0) dumps should be made on a regular base (e.g. once a
2274 month). As a full dump may take a long time and takes a lot of tape,
2275 it is wise to make higher level incremental dumps with shorter inter‐
2276 vals. The next table shows a dump level list that may be used if
2277 monthly full dumps take place:
2278 Sun Mon Tue Wed Thu Fri
2280 Week 1: 0 10 10 10 10 5
2281 Week 2: 10 10 10 10 10 5
2282 Week 3: 10 10 10 10 10 5
2283 Week 4: 10 10 10 10 10 5
2284 The level 10 dumps made between Monday and Friday accumulate all
2286 changes made within the week. If you don't like this, use the following
2287 backup schedule:
2288 Sun Mon Tue Wed Thu Fri
2290 Week 1: 0 20 30 40 50 5
2291 Week 2: 10 20 30 40 50 5
2292 Week 3: 10 20 30 40 50 5
2293 Week 4: 10 20 30 40 50 5
2294 Note that in this case, 7 dumps need to be restored if the a crash hap‐
2296 pens at the worst case date (just before the Friday dump in week 2 or
2297 later).
2298
2301 Incremental restores should be made to an empty file system (except for
2302 the lost+found directory). Star is currently unable to perform incre‐
2303 mental restores to a file system that contains active mount points.
2304 The incremental restore procedure starts with restoring the last full
2306 (level 0) dump. Then the latest incremental dump of each dump level
2307 (with ascending order of dump levels) need to be restored.
2308 Let us assume the first example from the section BACKUP SCHEDULES for
2310 the backup schedule. If a disk crash happens before the Thursday dump
2311 of week 3 has been made, the following restore procedure needs to be
2312 applied:
2313 level 0
2315 starting with an empty disk, the full (level 0) dump from week 1
2316 is restored.
2317 level 5
2319 after the level 0 restore has been finished, the level 5 dump
2320 from Friday in week 2 is restored.
2321 level 10
2323 after the level 5 restore has been finished, the level 10 dump
2324 from Wednesday in week 3 is restored.
2325 The disk now contains the same files as it did when the level 10 dump
2327 has been made on Wednesday of week 3.
2328 To extract a level 0 dump call:
2330 cd /filestem-mount-point
2332 star -xpU -restore f=archive-name
2333 This creates the directory star-tmpdir and the database star-symtable
2335 in the root directory of the new file system. Subsequent restores with
2336 higher level backups depend on these files.
2337 To extract a level 1 (or higher) dump call:
2339 cd /filestem-mount-point
2341 star -xpU -restore f=archive-name
2342 Note that the environment variable STAR_DEBUG exists, star does not
2344 remove files with link count 1 that have been removed between incremen‐
2345 tal dumps. These files are moved to the directory star-tmpdir. Before
2346 you start to extract the next incremental, you need to remove all files
2347 in star-tmpdir.
2348
2351 Star may be used to synchronize filesystem content. To do this, an
2352 initial copy of the current content of the source filesystem needs to
2353 be performed first.
2354 To create an initial copy of a filesystem call:
2356 star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
2358 -C /filestem-mount-point . | \
2359 star -xpU -restore -C /extract-target-dir
2360 In order to perform subsequent synchronization of the target filesystem
2362 with the content of the source filesystem, a modified incremental
2363 dump/restore procedure may be used.
2364 To copy incremental content of a filesystem call:
2366 star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
2368 -cumulative -C /filestem-mount-point . | \
2369 star -xpU -restore -C /extract-target-dir
2370 Note that like with backups in general, copies from a live filesystem
2372 should be avoided. On operating systems that support file system snap‐
2373 shots, copies should be made from a read-only mount of a snapshot. Be
2374 careful that all files that have been created between setting up a
2375 snapshot and starting an incremental copy may be missing from all
2376 copies unless the dumpdate=name option is used.
2377 See section INCREMENTAL BACKUPS to learn how to modify the command line
2379 in case file system snapshots are used.
2380
2382 If star handles a signal, it first prints the statistics. Star handles
2383 the following signals:
2384 SIGINT usually generated by ^C from the controlling tty. Upon
2386 receipt of a SIGINT, star prints statistics and exits. If in
2387 create mode i.e. storing files to archive, star finishes with
2388 the current file to ensure that no partial file is written to
2389 the archive, write an eof record and then exits.
2390 SIGHUP not to be generated from a tty. The actions are the same as
2392 upon receipt of a SIGINT.
2393 SIGQUIT usually generated by ^\ from the controlling tty. Upon
2395 receipt of a SIGQUIT, star prints statistics and continues
2396 with the current operation. This is useful to watch the
2397 progress of the current operation.
2398
2400 The following exit values are returned:
2401 0 All files were processed successfully.
2403 -3 / 253
2405 Star has been called with the option -e, or the errctl= option
2406 has been used to mark the current error fatal.
2407 -2 / 254
2409 One or more files could not be processed successfully.
2410 -1 / 255
2412 Command line parsing error.
2413 >0 Other positive exit codes: The errno of the call that caused the
2415 fatal error.
2416
2418 To get a listing in a way similar to ls -l one might use:
2419 example% star -tv f=/dev/rmt/1bn
2421 The same command as listed above in a POSIX tar command line syntax
2423 compliant way is:
2424 example% star tvf /dev/rmt/1mbn
2426 To copy the directory tree in /home/someuser to the directory /home/fs
2428 use:
2429 example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
2431 or by using the change directory option of star:
2433 example% star -c -C /home/someuser . | star -xp -C /home/fs
2435 Note that both examples above are not the optimum way to copy a direc‐
2437 tory tree. A more efficient way to copy a directory tree is to use the
2438 -copy option.
2439 example% star -copy -p -xdot -C /home/someuser . /home/fs
2441 To copy a file tree including the Access Control List entries for all
2443 files and to correctly copy sparse (holey) files use:
2444 example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
2446 To compare the content of a tape to the filesystem one might use:
2448 example% star -diff -v f=/dev/rmt/1bn
2450 To compare two directory trees one might use:
2452 example% star -c . | star -C todir -diff -v diffopts=!times
2454 or better by using a method similar to the -copy method above:
2456 example% star -c -diff -v diffopts=!times -C fromdir . todir
2458 To compare all properties of two file trees, use:
2460 example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
2462 To extract a backup of the /usr tree without all files residing below
2464 /usr/openwin one might use:
2465 example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
2467 To extract all .c files to src, all .o files to obj and all other files
2469 to /tmp one might use:
2470 example% star -xp -C src '*.c' -C obj '*.o' -C /tmp '*' f=/dev/rmt/1bn
2472 To extract files from a zipped tar archive that is located on a read
2474 only filesystem e.g. a CD while having the shell's working directory on
2475 the CD one might use:
2476 example% star -zxp -C /tmp f=star-1.1.tar.gz
2478 to extract the files from the tar archive to the /tmp directory.
2480 To backup a list of files generated by the find(1) command:
2482 example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
2484 Note that this does not work if the file names from output of the find
2486 command include new line characters.
2487 To extract a tarfile that contains a tarfile one might use:
2489 example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
2491 Pat, in this case should match the tarfile in the tarfile on tape that
2493 should be extracted.
2494 To make a backup of the root filesystem to a tape drive connected to a
2496 remote machine, one might use:
2497 example# cd /
2499 example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
2500 You need a line in /etc/passwd like the following to enable this:
2502 tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
2504 And a .rhosts file in /etc/tapehome to allow remote connections from
2506 the appropriate hosts. Make sure that the file /etc/default/rmt exists
2507 and allows remote access to the requested tape drive.
2508 To use a ssh(1) connection for a backup to a remote tape server, one
2510 might use:
2511 example# env RSH=/usr/bin/ssh star -cM fs=128m bs=63k
2513 f=tape@remotehost:/dev/rmt/1bn .
2514 To repair a corrupted filesystem for which no recent backup exists, do
2517 the following:
2518 example# fsck -y /filesys
2520 example# mount /filesys
2521 example# cd /filesys
2522 example# star -xpk f=/dev/rmt/1bn
2523 example# mt -f /dev/rmt/1bn rewind
2524 example# star -diff -v diffopts=!times f=/dev/rmt/1bn
2525 Now check the differences and decide whether to restore additional
2527 files. This may be done by generating a list containing the needed
2528 filenames and using the list= option or by using the interactive mode
2529 (see -w option).
2530 If you want a list that only contains all filenames from files with
2532 differences you may use:
2533 example# star -diff -tpath diffopts=!times f=/dev/rmt/1bn
2535 If you are looking for files that changed the type or the access per‐
2537 mission because this is a common case on still corrupted files, use:
2538 example# star -diff -tpath diffopts=type,perm f=/dev/rmt/1bn
2540 If you like to archive all directories only that are part of the direc‐
2542 tory tree under ".", use:
2543 example# star -c f=archive-name -find . -type d
2545 If you like to archive all files as owner root and group root and make
2547 all files world readable in the archive, use:
2548 example# star -c f=archive-name -find . -chown root -chgrp root
2550 -chmod o+r
2551 If you like to list all files in an archive in a way like sfind(1),
2553 instead of the way used by star, use:
2554 example# star -t f=archive-name -find . -ls -false
2556
2559 STAR_COMPRESS_FLAG
2560 If you like star to always create compressed files that use max‐
2561 imum compression, you may set the environment variable STAR_COM‐
2562 PRESS_FLAG to -9.
2563 STAR_DEBUG
2565 If this environment variable is present, star will not remove
2566 temporary files from ./star-tmpdir. The files in this directory
2567 are files that have been removed by users before the last incre‐
2568 mental dump did take place on the master filesystem.
2569 STAR_FIFOSIZE
2571 If you like to by default let star use a different fifo size,
2572 set this environment variable to the desired size.
2573 TAPE Unlike other tar(1) implementations, star defaults to use
2575 stdin/stdout for the archive. If you like star to use the file
2576 name from the TAPE environment instead, you need to specify the
2577 -T option too.
2578 RSH If the RSH environment is present, the remote connection will
2580 not be created via rcmd(3) but by calling the program pointed to
2581 by RSH. Use e.g. RSH=/usr/bin/ssh to create a secure shell
2582 connection.
2583 Note that this forces star to create a pipe to the rsh(1) pro‐
2585 gram and disallows star to directly access the network socket to
2586 the remote server. This makes it impossible to set up perfor‐
2587 mance parameters and slows down the connection compared to a
2588 root initiated rcmd(3) connection.
2589 See BUGS section for more information.
2591 RMT If the RMT environment is present, the remote tape server will
2593 not be the program /etc/rmt but the program pointed to by RMT.
2594 Note that the remote tape server program name will be ignored if
2595 you log in using an account that has been created with a remote
2596 tape server program as login shell.
2597
2599 /etc/default/star
2600 Default values can be set for the following options in
2601 /etc/default/star. For example: CDR_FIFOSIZE=64m
2602 STAR_FIFOSIZE
2604 Sets the default size of the FIFO (see also fs=# option).
2605 STAR_FIFOSIZE_MAX
2607 Sets the maximum size of the FIFO (see also fs=# option).
2608 Setting STAR_FIFOSIZE_MAX in /etc/default/star allows to
2609 overwrite global values from backup scripts for machines
2610 with less memory.
2611 archive0=
2613 archive1=
2615 archive2=
2617 archive3=
2619 archive4=
2621 archive5=
2623 archive6=
2625 archive7=
2627 Archive entries for the -[0..7] option.
2628 A correct archive?= line has 3..4 space separated
2630 entries. The first is the device entry (e.g. ar‐
2631 chive0=/dev/tape). The second is the blocking factor in
2632 512 byte units. The third is the maximum media size in
2633 1024 byte units. If this entry contains a 0, then the
2634 media size is unlimited. The fourth entry is optional.
2635 If it contains a 'n' or a 'N', then the archive device is
2636 not a tape.
2637 Examples:
2639 archive0=/dev/tape 512 0 y
2641 archive1=/dev/fd0 1 1440 n
2642 archive2=/dev/rmt/0mbn 512 0
2643 If the default file does not need to be shared with the
2645 tar program from Solaris, any number may be used like a
2646 generic size option like bs=.
2647 Example:
2649 archive0=/dev/tape 256k 40G y
2651 /etc/tardumps
2653 The default name for the dump level archive. The default name is
2654 used whenever the tardumps=name option has not been specified.
2655 The file is written or updated when -wtardumps is used.
2656 The file holds one or more lines, each specifying a dump level
2658 entry. Each dump level entry starts with a mount point name
2659 followed by a TAB and one or more spaces, followed by the deci‐
2660 mal dump level, a space and the dump time.
2661 If the dump level is directly followed by a 'P', then the dump
2663 refers to a partial dump (a dump that does not include the whole
2664 filesystem).
2665 The dump time itself includes the decimal representation of the
2667 UTC seconds since Jan 01 1970, a space and the textual local
2668 time representation of the dump time.
2669 The numerical decimal dump time representation may be followed
2671 by a dot and a sub second value. The textual local time repre‐
2672 sentation is for informational use by humans only and not evalu‐
2673 ated by star.
2674 ./star-symtable
2676 Contains a database that is needed in incremental restore mode.
2677 ./star-symdump
2679 Contains an intermediate dump of restore database after a fatal
2680 error condition was met during an incremental restore operation.
2681 ./star-tmpdir
2683 Is the temporary directory that is used as intermediate file
2684 storage by star if in incremental restore mode.
2685 ./star-lock
2687 Is a lock file created by star when doing an incremental
2688 restore. If this file is present, it prevents star from running
2689 another incremental restore operation. This helps to avoid more
2690 than one restore operation at a time (e.g. from a cron script).
2691 /dev/tty
2693 Is used for the intercative user interface.
2694
2696 spax(1), tar(1), cpio(1), pax(1), rcp(1), mt(1), rmt(8), match(1),
2697 dd(1), sdd(1), rsh(1), ssh(1), star(4), rcmd(3), fssnap(1m)
2698
2700 star: f records + p bytes (total of x bytes = d.nnk).
2701 The number of full records, the number of bytes in partial records and
2703 the total amount of data in KBytes.
2704 star: Total time x.yyysec (z kBytes/sec)
2706 The time used and the transfer speed from/to the archive.
2708 If there have been non fatal errors during the archive processing, star
2710 will display a delayed error summary before exiting.
2711
2714 The command line syntax for the tar command (as defined in SUSv2 -
2715 UNIX-98) deviates from the command line syntax defined for all other
2716 commands. While the POSIX command line syntax requests all options to
2717 start with a dash (-) and allows to either write options separately or
2718 combined (in case of boolean flags), the tar command line syntax
2719 requires all options to be combined into a single string that does not
2720 start with a dash. Star by default assumes a command line syntax like
2721 a typical POSIX command and includes a compatibility mode that allows
2722 to specify a command line syntax as documented for the UNIX-98 tar com‐
2723 mand. If you believe that you found a bug in the way star parses the
2724 command line, please first check your command line for correctness
2725 before you make a bug report for star.
2726 If you like to write portable shell scripts that call tar, use the
2728 UNIX-98 tar command line syntax (i.e. a single option string and no
2729 dash), choose the commands and options from the following set of char‐
2730 acters ( rxtuc vxfblmo ) and check the shell script with both, your
2731 local tar and star for correct behavior. It you expect the script to
2732 call gnutar, do not include the -o option as gnutar implements this
2733 option in a way that violates UNIX-98.
2734 Star strips leading ./ sequences from pathnames. This lets star in many
2736 cases store longer pathnames than other implementations.
2737 The POSIX.1-1988 method (ustar format) of storing files with pathnames
2739 that are longer than 100 chars has some limitations:
2740 The name field (100 chars) an inserted slash (`/') and the pre‐
2742 fix field (155 chars) produce the pathname of the file. When
2743 recreating the original filename, name and prefix are concate‐
2744 nated, using a slash character in the middle. If a pathname does
2745 not fit in the space provided or may not be split at a slash
2746 character so that the parts will fit into 100 + 155 chars, the
2747 file may not be archived. Linknames longer than 100 chars may
2748 not be archived too.
2749 The star, xstar, xustar, exustar, pax, and gnutar archive formats don't
2751 have these limitations. While gnutar uses a method that makes it impos‐
2752 sible for other tar implementations (except star) to restore filenames
2753 that are longer than 100 chars, the xstar, xustar, exustar and pax ar‐
2754 chive format uses a method that allows an POSIX.1-1988 compliant way of
2755 storing filenames, if the POSIX method would allow this. When the ar‐
2756 chive format is xustar, exustar or pax very long filenames are stored
2757 using extended headers from the POSIX.1-2001 standard.
2758 Some buggy tar implementations will generate incorrect filenames during
2760 a restore operation if the archive contains pathnames or linknames of
2761 exactly 100 chars length.
2762 Star adds a tar signature in the last four bytes of each tar header if
2764 the archive format is star or xstar. This is no problem with the star
2765 archive format as it is an extension of the old pre POSIX.1-1988 tar
2766 format. On the other side, the xstar archive format claims to be as
2767 POSIX.1-1988 compliant as possible. Inserting this tar signature is a
2768 minor deviation from the standard that has the last 12 bytes of each
2769 header reserved for future use. On the other side, tar implementations
2770 such as some pax implementations that only compute checksums on the
2771 first 500 bytes of the header are violating the standard that requests
2772 the checksum to be computed on all 512 bytes of the tar header. All tar
2773 implementations that are 100% Posix compliant will be able to extract
2774 xstar archives as long as no new standard is defined that claims the
2775 last 12 bytes of the header for a different use. But then the ustar
2776 version number should be changed from `00' to `01'. Now, that the
2777 POSIX-2001 standard has been accepted, it is even predictable that all
2778 extensions to the standard tar format will go into the POSIX.1-2001
2779 extended headers which are extensible to include any feature without
2780 future limitation. The only known tar implementation that also uses
2781 the last 12 bytes of the tar header is Sun's tar which uses these 12
2782 bytes for files that are split over several archives. Such archives
2783 created by Sun's tar are not readable by the buggy pax implementation
2784 too. The Sun extension is not incompatible to the star signature
2785 because Sun expects an octal number at the beginning of the 12 byte
2786 field which is a null character in the star case.
2787 Star uses these four bytes since 1985 without problems. If you need a
2789 100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive, you may
2790 use the xustar, exustar or the pax archive format. The probability of
2791 falsely detecting other tar formats as xustar or exustar format however
2792 is higher.
2793 There is no way to ask for the n-th occurrence of a file.
2795 The way EOF is handled by star differs, whether the fifo is in effect
2797 or not. If the fifo is not used, star stops reading the archive if it
2798 encounters a logical EOF record in the archive. If the fifo is used,
2799 star may read until the fifo is full or until the real EOF mark on tape
2800 is reached. How much data star actually reads depends on the time when
2801 the star foreground process sends a fifo shutdown signal to the back‐
2802 ground fifo read process.
2803 Gnu tar often creates tar archives with incorrect logical EOF marks.
2805 The standard requires two blocks that are completely zeroed, whereas
2806 gnutar often only adds one of them.
2807 Old versions of tar found on SYSVr3 and earlier cannot read tar ar‐
2809 chives with a blocksize greater than 10 kBytes.
2810 The method of storing sparse files currently used with the star and
2812 xstar format is not guaranteed to be used in later versions of star.
2813 If the author decides to change this method, later versions of star may
2814 not be able to restore sparse files from tar archives made by the cur‐
2815 rent version of star.
2816 Some tar implementations violate the standard in using only the first
2818 500 Bytes of the header for checksum computation. These tar implementa‐
2819 tions will not accept star and xstar type tar archives.
2820 Sun's Solaris 2.x tar implementation violates the Posix standard. Tar
2822 archives generated by star cause Sun's tar to print tar: impossible
2823 file type messages. You may ignore these messages.
2824 Gnutar's dumpdirs are non standard and are currently not implemented.
2826 If gnutar archives sparse files with more than four holes, it produces
2828 archives that violate the standard in a way that prevents other tar
2829 implementations to read these archives. Star knows about that and is
2830 able to handle these gnutar archives.
2831 The filetype N (LF_NAMES) from gnutar (an obsolete method of storing
2833 long names) will never be implemented.
2834 Note that on operating systems (like DOS) that do not implement real
2836 pipes, star implements compression via a temporary file. Using com‐
2837 pression thus is limited by the maximum file size and the available
2838 disk space.
2839 The extended file flags implementation (see -xfflags option) on Linux
2841 is buggy by design. In order to retrieve the needed information, every
2842 file needs to be opened. If the /dev directory is included in create
2843 mode, every possible driver will be loaded which may hang the system
2844 for a long time. In the worst case, unwanted side effects from opening
2845 devices (such as causing tape drives to rewind the media) may be
2846 caused.
2847
2850 If you unpack a tar archive in a non empty directory, any file in that
2851 directory may be overwritten unless you specify the -k option. If the
2852 archive contains symbolic links or hard links, star may even overwrite
2853 files outside the current directory. If the directory where the ar‐
2854 chive is been unpacked is not empty and contains contains symbolic
2855 links or hard links to directories outside that directory, star may
2856 also overwrite files outside the current directory. As many other com‐
2857 mands, star usually has all possible permissions when run as root.
2858 Unpacking archives as root thus may have fatal results to any file on
2859 your system. Be very careful when you try to extract an archive that
2860 has not been created by you. It is possible to create hand crafted tar
2861 archives that may overwrite critical files (like /etc/passwd) on your
2862 system. In addition all tar archives that have been created with the
2863 list= option and tar archives where the C= option was not specified
2864 before all file type arguments may be critical.
2865 A good advise is to extract all doubtful archives as non root in an
2867 empty directory and to specify the -secure-links option. If you get a
2868 warning, you should unpack the archive a second time and specify the
2869 options -k, -w and -nowarn in addition to the options used for the
2870 first run.
2871
2873 If star is installed suid root, star is able to make connections to
2874 remote archives for non root users. This is done by using the rcmd(3)
2875 interface to get a connection to a rmt(8) server.
2876 Star resets its effective uid back to the real user id immediately
2878 after setting up the remote connection to the rmt server and before
2879 opening any other file.
2880 If star has not been installed suid root and not called by root, it
2882 will try to create the remote connection via rsh(1) or ssh(1) (in case
2883 the environment RSH has been set to ssh). Note that in this case, the
2884 throughput to the remote tape server will be much lower than with a
2885 connection that has been initiated via rcmd(3).
2886
2888 If star is running on a large file aware platform, star is able to han‐
2889 dle files up to 8 GB in a mode that is compliant to the POSIX.1-1988
2890 ustar format. With a nonstandard star specific extension, up to 95 bits
2891 may be used to code the filesize. This will handle files up to
2892 200,000,000 TB. With the new POSIX.1-2001 extended headers used by the
2893 xustar, exustar and pax format, any filesize may be archived.
2894
2896 The fact that the -f option has to be implemented in a way that is com‐
2897 patible with old tar implementations gives several problems. The
2898 options -fifostats, -force-hole, -force-remove and -fifo interfere with
2899 the -f option and the fact that they exist prevents users from using
2900 filenames like e.g. ifo using the traditional way where the filename
2901 directly follows the string -f without any space between the option
2902 name and the file name. However, there is no problem to use a file
2903 named ifo by by calling -f ifo, f=ifo, -f=ifo or -f= ifo. Be careful
2904 not to make typos with the above options. The result could be that a
2905 file is created as a result of the mistyped option.
2906 There is currently no way to set the fifo lowwater and highwater marks.
2908 There is currently no way to automatically delete files in the target
2910 file tree if they are obsolete. Star should implement something simi‐
2911 lar to gnutar's dumpdirs.
2912 If not invoked by the super user star may not be able to extract files
2914 if they reside in read only directories.
2915 Star is not able to make a complete backup of a filesystem if files are
2917 hidden by a mount that is in effect on a directory of this filesystem.
2918 This may be avoided in case of the ufs filesystem if the backup is made
2919 off a ufs snapshot (see the man page for fssnap(1m) It could be avoided
2920 for any filesystem if the loopback filesystem had an option that tells
2921 lofs not to traverse mountpoints.
2922 For now (late 2002), we know that the following programs are broken and
2924 do not implement signal handling correctly:
2925 rsh on SunOS-5.0...SunOS-5.9
2927 ssh from ssh.com
2929 ssh from openssh.org
2931 Sun already did accept a bug report for rsh(1)/[22mssh(1). Openssh.org
2933 accepted and fixed a bug for their implementation of ssh(1).
2934 If you use star to create a remote connection via an unfixed rsh(1) or
2936 ssh(1), be prepared that terminal generated signals may interrupt the
2937 remote connection.
2938
2941 Star was first created in 1982 to extract tapes on a UNIX clone that
2942 had no tar command. In 1985 the first fully functional version has
2943 been released as mtar.
2944 When the old star format extensions have been introduced in 1985, it
2946 was renamed to star (Schily tar). In 1994, Posix 1003.1-1988 exten‐
2947 sions were added and star was renamed to star (Standard tar).
2948
2951 Joerg Schilling
2952 Seestr. 110
2953 D-13353 Berlin
2954 Germany
2955 Mail bugs and suggestions to:
2957 schilling@fokus.fraunhofer.de or js@cs.tu-berlin.de or
2959 joerg@schily.isdn.cs.tu-berlin.de
2960Joerg Schilling 13/11/08 STAR(1)