Zmanda Documentation > Star
Table of contents
- 1. NAME
- 2. SYNOPSIS
- 3. DESCRIPTION
- 4. FEATURES
- 5. COMMAND
- 6. OPTIONS
- 7. INCREMENTAL BACKUPS
- 8. BACKUP SCHEDULES
- 9. INCREMENTAL RESTORES
- 10. SYNCHRONIZING FILESYSTEMS
- 11. SIGNALS
- 12. EXIT STATUS
- 13. EXAMPLES
- 14. ENVIRONMENT
- 15. FILES
- 16. SEE ALSO
- 17. DIAGNOSTICS
- 18. NOTES
- 19. SECURITY NOTES
- 20. SUID NOTES
- 21. LIMITATIONS
- 22. BUGS
- 23. HISTORY
- 24. AUTHOR
NAME
star - unique standard tape archiver
SYNOPSIS
star command [options] [-find] file1 ... filen [find_expr] ustar command [options] [-find] file1 ... filen [find_expr] tar command [options] file1 ... filen star -copy [options] [-find] file1 ... [f_expr] directory star -copy [options] -C from_directory . to_directory
DESCRIPTION
Star is a very fast tar(1) like tape archiver with improved function-
ality.
Star archives and extracts multiple files to and from a single file
called a tarfile. A tarfile is usually a magnetic tape, but it can be
any file. In all cases, appearance of a directory name refers to the
files and (recursively) subdirectories of that directory.
Star’s actions are controlled by the mandatory command flags from the
list below. The way star acts may be modified by additional options.
Note that unpacking tar archives may be a security risk because star
may overwrite existing files. See SECURITY NOTES for more informa-
tion.
FEATURES
Star includes the first free implementation of POSIX.1-2001 extended
tar headers. The POSIX.1-2001 extended tar headers define a new stan-
dard way for going beyond the limitations of the historic tar format.
They allow (among others) to archive all UNIX time stamps in sub-sec-
ond resolution, files of arbitrary size and filenames without length
limitation using UNICODE UTF-8 coding for best exchange compatibility.
Star by default uses a fifo to optimize data flow from/to tape. This
results in a normally streaming tape during the whole backup. See
-fifo and fs= option to get information on how to find the best fifo
size.
Star includes a pattern matcher to control the list of files to be
processed. This gives a convenient interface for archiving and restor-
ing complex lists of files. In conjunction with the -w flag it is easy
to merge a tar archive into an existing file tree. See also -U option.
In create mode use the pat= option to specify either select or exclude
patterns (depending on the -V flag). In extract or list mode all file
type arguments are interpreted as select patterns while the patterns
specified with the pat= option may be used as select or exclude pat-
terns (depending on the -V flag). Have a look at the description of
the -C option to learn how to fetch files from a list of directories
(in create mode) or to distribute files to a list of directories (in
extract mode). A substitute option allows ed(1) like pattern substi-
tution in file names.
Star includes an enhanced function that is similar to the find(1) com-
mand (see sfind(1)). This allows to use find expressions, even in
extract or list mode, directly on the content on an archive. The
extensions to find(1) allow to modify the file metadata.
Star includes a sophisticated diff command. Several diff options allow
user tailorable functionality. Star won’t show you differences you
are not interested in. Check the diffopts= option for more details.
Star has no limitation on filename length. Pathnames and linknames up
to PATH_MAX (1023 bytes with old OS versions and 4095 bytes with
POSIX.1-2001) may be archived. Later versions may be able to deal with
longer pathnames.
Star deals with all 3 times, available for files on UNIX systems if
the archive format is either chosen from the star specific formats or
is a format that uses POSIX.1-2001 extended headers. This is either
done in second resolution by using a star specific POSIX.1-1988 com-
patible extension or in sub second resolution by using POSIX.1-2001
extended headers. Star is able to store and restore all 3 times
(mtime, atime and even ctime). On Solaris 2.x systems, star is able to
do backups without changing any of the 3 the times.
If used with the H=ustar option, or if called as ustar or tar while
the H=headertype option is not used, star is 100% POSIX compliant.
Star’s default format (if called as star) is xstar and is as posix
compliant as possible. Enhancements to the standard that prevent cor-
rect extraction of single files when using a different tar implementa-
tion that is only POSIX.1-1988 compliant may occur, but they only
affect single files with a pathname that is longer than 100+130 chars
or when archiving sparse files with the -sparse option in effect. All
other files will extract correctly. See the description for the
H=headertype option below for more information on archive formats and
possible archive interchange problems.
Star makes it easy to repair corrupted filesystems. After a fsck -y
has been run on the filesystem, star is able to restore only the miss-
ing files automatically. Use then star -diff to check for differences
(see EXAMPLES for more information).
Star automatically recognizes the type of the archive. Star therefore
is able to handle features and properties of different archive types
in their native mode, if it knows about the peculiarities of the
archive type. See the H=headertype option for more details. To be
able to do this, star adds hidden fingerprints to the archive header
that allows to recognise all star specific archive formats. The GNU
tar format is recognised by the way it deviates from the standard.
Star automatically recognizes and handles byte swapped archives. There
is no option to manually control byte swapping.
Star automatically recognizes and handles compressed archives inside
plain files.
Star is able to archive and restore Access Control Lists for files
using POSIX.1-2001 extended headers.
COMMAND
In native mode, star is compatible to the command line syntax of a
typical POSIX command and for this reason expects commands and options
to start with a single dash (-). In this case, commands and options
may be specified separately, all boolean or increment type options may
be specified either separately or combined. For compatibility with
GNU programs, long options may alternatively start with a double dash.
In compatibility mode to POSIX tar, star expects commands and options
to appear as one single string that does not start with a dash. In
POSIX tar compatibility mode, additional non POSIX options may be
specified but must appear after the POSIX options and their args and
need to start with a dash.
-c Create a new tarfile and write named files into it. Writing
starts at the beginning of tarfile. See -v option for informa-
tion on how to increase verbosity while the archive is written.
-copy Copy named files to the target directory which is the last file
type argument. The target directory must exist. The shorthand
-cx instead of -copy is not allowed because this could be a
result of a typo.
If the option -diff has been specified in addition, star per-
forms a one pass directory tree compare instead of copying
files. The shorthand -c -diff instead of -copy -diff is also
allowed.
On operating systems with slow file I/O (such as Linux), it may
help to use -no-fsync in addition, but then star is unable to
detect all error conditions; so use with care.
If the option -t has been specified in addition, the last file
type argument is not a target directory and star is performing
a one pass listing instead of copying files. This makes sense
as the listing from star may be better readable than the output
from ls -lR. The shorthand -c -t or -ct instead of -copy -t is
also allowed.
The job is by default done in the best archive mode. This
implies that it defaults to H=exustar -dump. When in -copy
mode, star forks into two processes and data exchange is done
via the shared memory from the FIFO. This gives the best pos-
sible performance. Without FIFO, the -copy mode will not work.
The list= option, patterns and substitutions apply only to the
create side of the copy command.
-diff Compare the content and the attributes of the files from the
archive in tarfile to the filesystem. This may also be used to
compare two file trees in the filesystem. If you use a set of
diffopts that fits your needs, it will give - in many cases - a
more readable output than diff -r. If you use star’s dump
extensions for the tar archive, the -diff option allows to find
even if the directory in the file tree contains more files than
the archive. This way, it is possible to compare all properties
of two file trees in one run. See diffopts for more details.
Adding one or more -v options increases the verbosity. With -vv
and above, the directory content is compared also if in -dump
mode.
-n No extraction. Show what star would do, in case the -x command
had been specified.
-r Replace files in a tarfile. The named files are written to the
end of tarfile. This implies that later, the appropriate files
will be found more than once on the tarfile.
-t Table of contents. List the contents of the tarfile. If the
-v flag is used, the listing is similar to the format of ls -l
output. With this option, the flags -a, -atime and -ctime have
a different meaning if the archive is in star, xstar, xustar,
exustar, or pax format. The option -a or -atime lists the
access time instead of the modification time, the option -ctime
lists the file creation time instead of the modification time.
The option -tpath may be used in addition to modify the output
so it may be used in shell scripts.
-u Update a tarfile. The named files are written to the end of
tarfile if they are not already there or if the files are newer
than the files of the same name found in the archive. The -r
and -u command only work if the tar archives is a regular file
or if the tar archive is an unblocked tape that may backspace.
-x Extract the named files from the tarfile. If no filename argu-
ment or pattern is specified, the entire content of the tarfile
is restored. If the -U flag is not used, star extracts no file
which is older than the corresponding file on disk.
On operating systems with slow file I/O (such as Linux), it may
help to use -no-fsync in addition, but then star is unable to
detect all error conditions; so use with care.
Except for the shorthands documented above, exactly one of the com-
mands above must be specified.
If one or more patterns or substitution commands have been specified,
they apply to any of the command listed above. In copy mode, all pat-
terns and substitute commands apply to the create side.
OPTIONS
-help Print a summary of the most important options for star(1).
-xhelp Print a summary of the less important options for star(1).
-/ Don’t strip leading slashes from file names when extracting an
archive. Tar archives containing absolute pathnames are usu-
ally a bad idea. With other tar implementations, they may pos-
sibly never be extracted without clobbering existing files.
Star for that reason, by default strips leading slashes from
filenames when in extract mode. As it may be impossible to
create an archive where leading slashes have been stripped
while retaining correct path names, star does not strip leading
slashes in create mode.
See SECURITY NOTES for more information.
-.. Don’t skip files that contain /../ in the name. Tar archives
containing names with /../ could be used to compromise the sys-
tem. If they are unpacked together with a lot of other files,
this would in most cases not even be noticed. For this reason,
star by default does not extract files that contain /../ in the
name if star is not in interactive mode (see -w option).
See SECURITY NOTES for more information.
-0
-1
-2
-3
-4
-5
-6
-7 Select an archive entry from /etc/default/star. The format for
the archive entries is the same as the format in
/etc/default/tar in Solaris.
-acl Handle Access Control List (ACL) information in create and
extract mode. If -acl has been specified, star is in create
mode and the header type is exustar, star will add ACL informa-
tion to the archive using POSIX.1-2001 extended headers. If
-acl has been specified and star is in extract mode, star will
try to restore ACL information. If there is no ACL information
for one or all files in the archive, star will clear the ACL
information for the specific file. Note that if -acl has not
been specified, star will not handle ACL information at all and
files may inherit ACL information from the parent directories.
If the -acl option has been specified, star assumes that the -p
option has been specified too.
artype=headertype
Generate a tape archive in headertype format. If this option
is used in extract/list mode this forces star to interpret the
headers to be of type headertype. As star even in case of a
user selected extract archive format does format checking, it
may be that you will not be able to unpack a specific archive
with all possible forced archive formats. Selecting the old tar
format for extraction will always work though. Valid parameter
for headertype are:
help Print a help message about possible header types.
v7tar Old UNIX V7 tar format. This archive format may only
store plain files. Pathnames or linknames longer
than 99 chars may not be archived.
If the v7tar format has been selected, star will not
use enhancements to the historic UNIX V7 tar format.
File size is limited to 2 GB - 2 bytes, uid/gid is
limited to 262143. Sparse files will be filled up
with zeroes.
tar Old BSD UNIX tar format. This archive format may
only store plain files, directories and symbolic
links. Pathnames or linknames longer than 99 chars
may not be archived. See also the -d option as a
note to some even older tar implementations.
If the tar format has been selected, star will not
use enhancements to the historic tar format. File
size is limited to 2 GB - 2 bytes, uid/gid is limited
to 262143. Sparse files will be filled up with
zeroes.
star Old star standard format. This is an upward/downward
compatible enhancement of the old (pre Posix) UNIX
tar format. It has been introduced in 1985 and
therefore is not Posix compliant. The star format
allows to archive special files (even sockets) and
records access time and creation time besides the
modification time. Newer versions of the old star
format allow very long filenames (100+155 chars and
above), linknames > 100 chars and sparse files (if
-sparse is used). This format is able to copy the
device nodes on HP-UX that have 24 bits in the minor
device number, which is more then the 21 bits that
are possible with the POSIX-1003.1-1988 archive for-
mat.
The nonstandard extensions are located in the space
between the link name and the POSIX file name prefix.
As the star format does not use a POSIX magic string,
the extensions do not interfere with the POSIX tar
formats. The last 4 bytes of the tar header contain
a ’tar\0’ signature.
gnutar This is a commonly used, but unfortunately not Posix
compliant (although designed after 1987) enhancement
to the old tar format. The gnutar format has been
defined between 1989 and 1994. Do not use the gnutar
archive format unless you want to create an archive
for a target system that is known to have only the
gnutar program available. The gnutar archive format
violates basic rules for any (even the historic) tar
archive format, in special when sparse files are
archived using the -sparse option. Using the gnutar
archive format causes a high risk that the resulting
archive may only be read by gnutar or by star. The
implementation of the gnutar archive format within
star is not complete, but sufficient for most gnutar
archives. See NOTES for more information.
ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data Inter-
change format. With this option in effect, star will
generate 100% POSIX.1-1988 compliant tar archives.
Files with pathnames longer than 100+155 chars or
linknames longer than 100 chars may not be archived.
If star is called as ustar the default archive format
is ustar.
If the ustar format has been selected, star will not
use enhancements to the POSIX.1-1988 tar format, the
archive will be strictly conforming. File size is
limited to 8 GB, uid/gid/major/minor is limited to
2097151. Sparse files will be filled up with zeroes.
pax The IEEE/Posix1003/IEC-9945-1-1988 successor is the
POSIX-1003.1-2001 Standard Data Interchange format.
It is called the pax archive format.
If the pax format has been selected, star will not
use enhancements to the POSIX.1-2001 tar format, the
archive will be strictly conforming. File size is
unlimited, uid/gid/uname/gidname is unlimited,
major/minor is limited to 2097151. Sparse files will
be filled up with zeroes.
xstar The extended standard tar format has been introduced
in 1994. Star uses the xstar format as default
archive format. This is an upward/downward compati-
ble enhancement of the IEEE/Posix1003/IEC-9945-1
Standard Data Interchange format. It allows among
others very long filenames (100+130 chars and above)
and records access time and creation time. Sparse
files will be archived correctly (if -sparse is
used).
The access time and creation time are stored at the
end of the POSIX file name prefix (this limits the
prefix to 130 chars). These extensions do not inter-
fere with the POSIX standard as the fields for mtime
and ctime field are always separated from the POSIX
file name prefix by a null byte. The last 4 bytes of
the tar header contain a ’tar\0’ signature.
The xstar format is the default format when star is
neither called as tar nor called as ustar.
xustar A new format introduced 1998, that omits the ’tar\0’
signature at the end of the tar header. It is other-
wise identical to the xstar format. As some tar
implementations do not follow the POSIX rules and
compute the checksum for less than 512 bytes of the
tar header, this format may help to avoid problems
with these broken tar implementations. The main
other difference to the xstar format is that the xus-
tar format uses POSIX.1-2001 extended headers to
overcome limitations of the historic tar format while
the xstar format uses proprietary extensions. The
xustar format is the default format when star is
called as tar.
File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is unlimited. Sparse files
will be archived correctly (if -sparse is used).
exustar A format similar to the xustar format but with forced
POSIX.1-2001 extended headers. If this format is
used together with the -acl option, star records
Access Control Lists (ACLs) in POSIX.1-2001 extended
headers.
The exustar format allows to archive all file types
but it does not archive more than the POSIX.1-1988
set by default. If the -dump option is used or if
star is otherwise on dump mode, star archives all
file types and in addition archives more meta data
then usual.
File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is unlimited. Sparse files
will be archived correctly (if -sparse is used).
suntar The extended header format found on Solaris 7/8/9.
This format is similar to the pax format but does not
handle atime and ctime and in addition uses ’X’ as
the typeflag for the extended headers instead of the
standard ’x’.
File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is unlimited. Sparse files
will be filled up with zeroes.
bin The cpio UNIX V7 binary format. This is a format
with big interoperability problems. Try to avoid this
format. It is only present to make the scpio command
SVr4 compliant.
cpio The POSIX.1-1988 cpio format. This format uses octal
ascii headers. A similar format is created by calling
cpio -o -c on pre SYSVr4 systems and by calling cpio
-o -Hodc on SYSVr4 systems. The POSIX.1-1988 cpio
format allows a file name length up to 262142 charac-
ters and allows to archive nearly any file type.
File size is limited to 8 GB, uid/gid/st_dev is lim-
ited to 262143. The way major and minor device num-
bers are stored inside the st_dev field is implemen-
tation dependent.
Even though this archive format is covered by the
POSIX.1-1988 standard, it has a lower portability
than the ustar format. Try to avoid the cpio archive
format.
odc This archive format is similar to the The
POSIX.1-1988 cpio format but the file name length is
limited to 255 characters and the socket file type is
not allowed. This archive format has been introduced
to allow non POSIX cpio implementations such as the
cpio program on SYSV to accept the archive. Use this
format whenever you are not sure if the target system
offers a fully POSIX compliant cpio program.
Even though this archive format is covered by the
POSIX.1-1988 standard, it has a lower portability
than the ustar format. Try to avoid the odc archive
format.
asc Tell star to create a cpio archive in the ascii for-
mat that is created with cpio -o -c on SYSVr4 sys-
tems. It uses extended (32 bit) numbers for uid’s,
gid’s and device numbers but limits the file size to
2 GB - 2 bytes although the format has been specified
after the POSIX.1-1988 cpio format. Try to avoid the
asc archive format because of it’s limited portabil-
ity.
crc This format is similar to the asc cpio format but in
addition uses a simple byte based checksum called
CRC. Try to avoid the crc archive format because of
it’s limited portability.
All tar archive formats may be interchanged if the archive con-
tains no files that may not be archived by using the old tar
format. Archives in the xstar format may be extracted by any
100% POSIX compliant tar implementation if they contain no
files with pathnames > 100+130 chars and if they contain no
sparse files that have been archived by using the -sparse
option.
-ask_remove
obsoleted by -ask-remove
-ask-remove
Ask to remove non writable files on extraction. By default,
star will not overwrite files that are read only. If this
option is in effect, star will ask whether it should remove
these files to allow the extraction of a file in the following
way:
remove ’filename’ ? Y(es)/N(o) :
-atime, -a
Reset access time of files after storing them to tarfile. On
Solaris 2.x, (if invoked by root) star uses the _FIOSATIME
ioctl to do this. This enables star not to trash the ctime
while resetting the atime of the files. If the -atime option
is used in conjunction with the list command, star lists access
time instead of modification time. (This works only in conjunc-
tion with the star, xstar, xustar, exustar, and with the pax
format.) Another option to retain the access time for the the
files that are going to be archives is to readonly mount a UFS
snapshot and to archive files from the mount point of the UFS
snapshot.
-B Force star to perform multiple reads (if necessary) to fill a
block. This option exists so that star can work across the
Ethernet, since pipes and sockets return partial blocks even
when more data is coming. If star uses stdin as archive file,
star behaves as if it has been called with the -B option. For
this reason, the option -B in practice is rarely needed.
-block-number
Print the archive block number (archive offset / 512) at the
beginning of each line when in verbose mode. This allows to
write backup scripts that archive the offsets for files and
that use
mt fsr blockno
to skip to the tape block number of interest in a fast way if a
single file needs to be restored.
blocks=#, b=#
Set the blocking factor of the tarfile to # times 512 bytes
(unless a different multiplication factor has been specified -
see bs= option for posible multiplication factors). Changing
the blocking factor only makes sense when the archive is
located on a real tape device or when the archive is accessed
via the remote tape protocol (see f= option below). The
default is to use a blocking factor of 20 i.e. 10 kBytes.
Increasing the blocksize will speed up the backup. For porta-
bility with very old tar implementations (pre BSD 4.2 or pre
AT&T SVR4), blocksize should not be more than 10 kBytes. For
POSIX.1-1988 compatibility, blocksize should be no more than
10 kBytes. For POSIX.1-2001 compatibility, blocksize should be
no more than 32 kBytes. Most systems also have a hardware lim-
itation for the blocksize, 32 kBytes and 63 kBytes are common
limits on many systems. The upper limit in any case is the
size of the buffer RAM in the tape drive. Make a test if you
want to make sure that the target system will handle the
intended blocksize. If you use star for data exchange via
tape, it is a good idea to use a blocksize of 10 kBytes unless
you are sure that the reading system will handle a larger
blocksize. If you use star for backup purposes with recent
hardware (e.g. DLT tape drives), a blocksize of 256 kBytes
results in sufficient speed and seems to be a good choice.
Star allows block sizes up to 2 GByte if the system does not
impose a smaller limit. If you want to determine the blocking
factor when reading an unknown tar archive on tape, specify a
blocking factor that is higher than the supposed blocking fac-
tor of the tape. Star then will determine the blocking factor
by reading the first record of the tape and print a message:
star: Blocksize = # records.
Where # is the blocking factor in multiples of 512 bytes. The
blocks= option and the bs= option are equivalent methods to
specify the tape block size. The blocks= option is preferred
by people who like to use an option that behaves similar to the
interface of the historic tar(1) implementations.
bs=# Set output block size to #. You may use the same method as in
dd(1) and sdd(1). The number representing the size is taken in
bytes unless otherwise specified. If a number is followed
directly by the letter ‘.’, ‘w’, ‘b’, ‘k’, ‘m’, ‘g’, ‘t’, or
‘p’, the size is multiplied by 1, 2, 512, 1024, 1024*1024,
1024*1024*1024, 1024*1024*1024*1024 or
1024*1024*1024*1024*1024. If the size consists of numbers sep-
arated by ‘x’ or ‘*’, multiplication of the two numbers is per-
formed. Thus bs=7x8k will specify a blocksize of 56 kBytes.
Blocksize must be a multiple of 512 bytes. See also the
description of the blocks= option for more details on block-
sizes. The option bs= is preferred by people who like to use
an option that behaves similar to the interface used by dd(1)
and sdd(1).
-bsdchdir
Switch the behavior of the C= option to BSD style. The default
behavior of star is to stay in a working directory until a new
C= is seen. With BSD tar, the C= option is only related to the
next file type argument.
-bz run the input or output through a bzip2 pipe - see option -z -Z
and -j below. As the -bz the -j the -Z and the -z option are
non standard, it makes sense to omit the -bz the -j the -Z and
the -z options inside shell scripts if you are going to extract
a compressed archive that is located inside a plain file as
star will auto detect compression and choose the right decom-
pression option to extract.
C=dir
-C dir Perform a chdir(2) operation to dir before storing or extract-
ing the next files. In all cases, star will perform the
chdir(2) operation relative to the current working directory of
the shell.
· In list mode (with the -t flag), star ignores all -C
options.
· In create mode (with the -c, -r and -u flag), star walks
through all -C options and file type arguments. While a
BSD derived tar(1) implementation goes back to the cur-
rent working directory after storing one file argument
that immediately follows the -C option, star changes the
directory only if a new -C option follows. To emulate
the behavior of a BSD derived tar(1), add a -C . option
after the file argument.
· In extract mode (with the -x, -n and -diff flag), star
builds a pattern list together with corresponding direc-
tories from previous C=dir options and performs a
chdir(2) to the corresponding directory of a matching
pattern. All pat= options that do not follow a C=dir
option are interpreted as if they were preceded by a -C
. option. See EXAMPLES for more information.
compress-program=name
Set a named compress program. The program must compress in a
pipe when called without parameters and decompress when run
with the -d option in a pipe. This option is otherwise similar
to the -z the -j the -Z and the -bz option.
-copydlinks
Try to recursively copy the content of linked directories
instead of creating the link. This is an experimental feature
that may help to unpack archives on DOS.
-copyhardlinks
This option allows to copy hardlinked targets rather than cre-
ating the link. It helps to extract tar files on systems that
do not implement hardlinks (e.g. BeOS).
-copylinks
This option allows to copy both, hard- and symlinked targets
rather than creating a link. It helps to extract tar files on
systems that do not implement links (e.g. OS/2). To extract
and copy all symlinks correctly, you may need to call star
twice as star cannot copy files that appear in the archive
later than a symlink pointing to them.
-copysymlinks
This option allows to copy symlinked targets rather than creat-
ing a symbolic link. It helps to extract tar files on systems
that do not implement links (e.g. OS/2). To extract and copy
all symlinks correctly, you may need to call star twice as star
cannot copy files that appear in the archive later than a sym-
link pointing to them.
-ctime If used with the list command, this lists ctime rather than
mtime if the archive format is star, xstar, xustar, exustar, or
pax.
If star is run as root and if -ctime is used with the extract
command and the same archive formats, this causes star to try
to restore even the ctime of a file by generating time storms.
You should not do this when in multi user mode because this may
confuse programs like cron and the news system. Although star
tries to eliminate the accumulative effects of the time storm,
there is a tendency for the system clock to slow down a bit.
The clock typically lags about one millisecond per extracted
file. Use with care and check the system clock after using
this feature.
If used with the create command this changes the behavior of
the newer= option. Star, in this case compares the ctime of
all files to the mtime of the stamp file rather then comparing
the mtimes of both files.
-cumulative
A shorthand for -dump-cumulative. See -dump-cumulative for
more information.
-D Do not descend directories. Normally, star descends the whole
tree if it encounters a directory in in its file parameters.
The option -D is in effect by default if the list=file option
is used. If you like star to descend directories found in the
list file, use the -dodesc option (see below).
-d Do not store/create directories. Old versions of tar such as
published with the seventh edition of UNIX are not able to deal
with directories in tar archives. If a tar archive is gener-
ated without directories this avoids problems with tar imple-
mentations found on SYSVr3 and earlier. If used during
extract, no intermediate missing directories are created.
-data-change-warn
If the size of a file changes while the file is being archived,
treat this condition as a warning only that does not cause a
non zero exit code. A warning message is still written if the
condition is not otherwise ignored by another rule from an
errctl= option. The -data-change-warn option works as if the
last error control option was
errctl="WARN|GROW|SHRINK *"
The -e option or an ABORT entry in a condition set up by
errctl= has a higher precedence than the -data-change-warn
option. This option is ignored in extract or list mode.
-debug Print debug messages. Among other things, this gives debug mes-
sages for header type recognition, tar type properties, EOF
recognition, opening of remote archives and fifo internals.
diffopts=optlst
Comma separated list of diffopts. Valid members in optlst are:
help Print a summary of possible members of the diffopts
list.
! Invert the meaning of the following string. No comma
is needed after the exclamation mark.
not Invert the meaning of all members in the diffopts
list i.e. exclude all present options from an ini-
tially complete set compare list. When using csh(1)
you might have problems to use ! due to its strange
parser. This is why the not alias exists.
perm Compare file permissions. With this option in effect,
star compares the low order 12 bits of the st_mode
field.
mode Same as perm.
type Compare file type. Note that star cannot compare the
file type in case of a hard link.
nlink Compare link count on hardlinks. This only works if
the archive is in exustar format and contains star’s
dump extensions.
uid Compare numerical user id of file.
gid Compare numerical group id of file.
uname Compare ASCII version of user id of file. The user
name is mapped via the file /etc/passwd.
gname Compare ASCII version of group id of file. The group
name is mapped via the file /etc/group.
id Shorthand for: uid,gid,uname,gname. Compare all
user/group related info of file. Note that this will
always find differences if the source and target sys-
tem use different user or group mappings.
size Compare file size. Note that star cannot compare the
file size in case of a hard link.
data Compare content of file. If star already found that
the size of the files differ, it will not compare the
content anymore. If the size of the files differ,
star will always report different data.
cont Same as data.
rdev Compare major/minor numbers for device nodes.
hardlink Compare target of hardlinks.
symlink Compare target of symlinks. This evaluates the value
returned by the readlink(2) call.
sparse Compare if either both files are sparse or not. If
only one of both files is sparse, then a difference
is flagged. This only works with if the archive for-
mat is star, xstar, xustar, exustar, or gnutar.
atime Compare access time of file. This only works with if
the archive format is star, xstar, xustar, exustar,
or pax.
mtime Compare modification time of file.
ctime This only works with if the archive format is star,
xstar, xustar, exustar, or pax.
lmtime Compare the modification time of symbolic links. By
default, star will not compare the modification time
of symbolic links as most systems cannot set the mod-
ification time of symbolic links. Star compares
lmtime only if mtime is compared also.
times Shorthand for: atime,mtime,ctime.
dir Compare the content of directories. This only works
if the archive is in exustar format and contains
star’s dump extensions. Together with increased ver-
bose level (-vv) this will print a list of files that
are only in the archive and a list of files that are
only on the current filesystem.
xtimes Shorthand for: atime,mtime,ctime,lmtime.
acl Compare access control lists. This only works if the
archive is in exustar format and has been created
with star’s -acl option. You need to specify the
-acl option in addition when running the diff.
xattr Compare extended file attributes. This only works if
the archive is in exustar format and has been created
with star’s -xattr option. You need to specify the
-xattr option in addition when running the diff.
fflags Compare extended file flags. This only works if the
archive is in exustar format and has been created
with star’s -xfflags option. You need to specify the
-xfflags option in addition when running the diff.
If optlst starts with a ! the meaning of all members in optlst
is inverted as with the not optlist member. In this case, star
starts with a complete list that includes atime and lmtime.
Reasonable diff options to use when comparing against a copy of
a directory tree are diffopts=!atime,ctime,lmtime.
If diffopts are not specified, star compares everything but the
access time of the files and the modification time of symbolic
links.
dir-group=group
If star extracts archives as root, this option allows to con-
trol the group id of intermediate directories created by star.
dir-owner=user
If star extracts archives as root, this option allows to con-
trol the owner of intermediate directories created by
-dirmode
If in create mode (i.e. when storing files to archive), star
stores directories past the corresponding files. This guaran-
tees that even old tar implementations without a directory
cache will be able to restore the correct times of directories.
The option -dirmode should only be used if the archive needs to
be extracted by an old tar implementation. If star is used to
extract an archive that has been created with -dirmode the
directories will not get an old time stamp unless the option -U
is used while extracting the archive.
-dodesc
Force star to descend directories found in a list=file. See
also the -D option above.
-dump Allows to create archives with the same number of attributes as
an archive that has been created with the level= option but
without the restrictions that apply to a true dump.
The resultant archive may be seen as a level-less dump which
includes similar attributes as a level 0 dump but may span more
than a single file system and does not need to use a -C option.
It has been originally introduced to make it easier to imple-
ment a star version that supports true incremental dumps, but
it is kept as it gives additional benefits. Star currently
sets the archive type to exustar and, in addition archives more
inode meta data inside POSIX.1-2001 extended headers. See also
level= option and the section INCREMENTAL BACKUPS for more
information on true incremental dumps.
-dump-cumulative
instructs star to perform incremental dumps relatively to the
last incremental dump of the same level. Incremental dumps
with a level higher than 0 are normally done relatively to the
content of a previous dump with lower level. If incremental
dumps and restores are going to be used to synchronize filesys-
tem content, every successive incremental dump will increase in
size if -dump-cumulative is not used. See section SYNCHRONIZ-
ING FILESYSTEMS for more information.
dumpdate=name
Tells star to use the mtime of the time stamp file name instead
of using the start time of star. This is needed when star is
run on file system snapshots. If star would use the the start
time with snapshots, all files that have been modified between
the setup of the snapshot and the start of star would be miss-
ing on the backup.
-dumpmeta
changes the behavior of star in incremental dump mode. If
-dumpmeta is used and only the inode change time (st_ctime) of
a file has been updated since the last incremental dump, star
will archive only the meta data of the file (e.g. uid, permis-
sions, ...) but not the file content. Using -dumpmeta will
result in smaller incremental dumps, but files that have been
created between two incrementals and set to an old date in
st_mtime (e.g. as a result from a tar extract) will not be
archived with full content. Using -dumpmeta thus may result in
incomplete incremental dumps, use with extreme care.
-e Exit immediately with exit status -3 (253) if any unexpected
error occurs. The -e option works as if the last error control
option was
errctl="ABORT|ALL|DIFF *"
This allows to use the errctl= option together with the -e
option and thus to ignore some error conditions while aborting
on all other conditions.
errctl= name
errctl= error control spec
Add the content from file name to the error control definitions
or add error control spec to the error control definitions.
More than one error control file and more than one error con-
trol spec as well as a mixture of both forms is possible.
The reason for using error control is to make star quiet about
error conditions that are known to be irrelevant on the quality
of the archive or restore run or to tell star to abort on cer-
tain error conditions instead of trying to continue with the
archive.
A typical reason to use error control is to suppress warnings
about growing log files while doing a backup on a live file
system. Another typical reason to use error control is to tell
star to abort if e.g. a file could not be archived instead of
continuing to archive other files from a list.
The error control file contains a set of lines, each starting
with a list of error conditions to be ignored followed by white
space followed by a file name pattern (see match(1) or pat-
match(3) for more information). The error control spec uses
the same syntax as a single line from the error control file.
If the file name pattern needs to start with white space, use a
backslash to escape the start of the file name. It is not pos-
sible to have new line characters in the file name pattern.
Whenever an error situation is encountered, star checks the
lines in the error control file starting from the top. If the
current error condition is listed on a line in the error con-
trol file, then star checks whether the pattern on the rest of
the line matches the current file name. If this is the case,
star uses the current error control specification to control
the current error condition.
The list of error conditions to be handled may use one or more
(in this case separated by a ’|’ character) identifiers from
the list below:
ABORT If this meta condition is included in an error con-
dition, star aborts (exits) as soon as possible
after this error condition has been seen instead of
making star quiet about the condition. This error
condition flag may only be used together with at
another error condition or a list of error condi-
tions (separated by a ’|’ character).
WARN If this meta condition is included in an error con-
dition, star prints the warning about the error
condition but the error condition does not affect
the exit code of star and the error statistics
(which is printed to the end) does not include the
related errors. This error condition flag may only
be used together with at another error condition or
a list of error conditions (separated by a ’|’
character). The WARN meta contition has a lower
precedence than ABORT.
DIFF Suppress output in case that star -diff did
encounter any differences.
ALL This is a shortcut for all error conditions below.
STAT Suppress warnings that star could not stat(2) a
file.
GETACL Suppress warnings about files on which star had
problems to retrieve the ACL information.
OPEN Suppress warnings about files that could not be
opened.
READ Suppress warnings read errors on files.
WRITE Suppress warnings write errors on files.
READLINK Suppress warnings readlink(2) errors on symbolic
links.
GROW Suppress warnings about files that did grow while
they have been archived.
SHRINK Suppress warnings about files that did shrink while
they have been archived.
MISSLINK Suppress warnings about files for which star was
unable to archive all hard links.
NAMETOOLONG Suppress warnings about files that could not be
archived because the name of the file is too long
for the archive format.
FILETOOBIG Suppress warnings about files that could not be
archived because the size of the file is too big
for the archive format.
SPECIALFILE Suppress warnings about files that could not be
archived because the file type is not supported by
the archive format.
GETXATTR Suppress warnings about files on that star could
not retrieve the extended file attribute informa-
tion.
SETTIME Suppress warnings about files on that star could
not set the time information during extraction.
SETMODE Suppress warnings about files on that star could
not set the access modes during extraction.
SECURITY Suppress warnings about files that have been
skipped on extraction because they have been con-
sidered to be a security risk. This currently
applies to all files that have a ’/../’ sequence
inside when -.. has not been specified.
LSECURITY Suppress warnings about links that have been
skipped on extraction because they have been con-
sidered to be a security risk. This currently
applies to all link names that start with ’/’ or
have a ’/../’ sequence inside when -secure-links
has been specified. In this case, star tries to
match the link name against the pattern in the
error control file.
SAMEFILE Suppress warnings about links that have been
skipped on extraction because source and target of
the link are pointing to the same file. If star
would not skip these files, it would end up with
removing the file completely. In this case, star
tries to match the link name against the pattern in
the error control file.
BADACL Suppress warnings access control list conversion
problems.
SETACL Suppress warnings about files on that star could
not set the ACL information during extraction.
SETXATTR Suppress warnings about files on that star could
not set the extended file attribute information
during extraction.
If a specific error condition is ignored, then the error condition is
not only handled in a silent way but also excluded from the error
statistics that are printed at the end of the star run.
Be very careful when using error control as you may ignore any error
condition. If you ignore the wrong error conditions, you may not be
able to see real problems anymore.
-F,-FF ...
Fast and simple exclude option for create mode. With one -F
argument, star ignores all directories called SCCS and RCS.
With two -F arguments, star in addition ignores all files
called core errs a.out all files ending with .o. OBJ/. With
three -F arguments, star ignores all sub trees starting from a
directory that includes a file .mirror or .exclude and all
object files and files called core errs a.out all files ending
with .o. With four -F arguments, star ignores all sub trees
starting from a directory that includes a file .mirror or
.exclude the latter files are excluded too as well as and all
object files and files called core errs a.out all files ending
with .o. With five -F arguments, star in addition again
excludes all directories called SCCS and RCS.
-fifo Use a fifo to optimize data flow from/to tarfile. This option
is in effect by default (it may be changed at compile time).
The default fifo size is 8 MBytes on all platforms except Linux
versions that do not support mmap() (4 MB because kernels
before 2.4 did not handle big shared memory areas) and
Sun/mc68000 (1 MB). This will star make even work on a tiny
machine like a Sun 3/50. The fifo size may be modified with the
fs= option. A rule of dumb for the fifo size is to use more
than the buffer size of the tape drive and less then half of
the real memory of the machine. A good choice would be to use
a fifo size between 8 and 256 MB. This may increase backup
speed up to 5% compared to the speed achieved with the default
fifo size. Note that with a DLT drive that gives 12MB/s trans-
fer rate, a fifo of 256 MB size will keep the tape at least
streaming in units of 20 seconds. All options that start with
the -f sequence are sensitive to typo problems, see BUGS sec-
tion for more information.
-fifostats
Print fifo statistics at the end of a star run when the fifo
has been in effect. All options that start with the -f
sequence are sensitive to typo problems, see BUGS section for
more information.
file=tarfilename, f=tarfilename
Use tarfilename as the name for the tar archive. Currently up
to 100 file= options are possible. Specifying more then one
file= option make sense in multi volume mode. In this case star
will use the next name in the list every time a media change is
needed. To make star behave consistent with the single file
case, star loops over the list of known archive files. Note
that if star is installed suid root and the first tarfile is a
remote archive, only the connection to this archive will be
created with root privileges. After this connection has been
established as root, star switches back to the id of the
caller. If any of the other archives in the list is located on
a different host, star will not be able to open this archive
later on, unless run by root.
Star normally uses stdin/stdout for the tar archive because the
most common way to use star is in conjunction with pipes. If
star is installed suid root or if it has been called by root,
tarfilename may be in remote syntax: user@host:filename as in
rcp(1) even if invoked by non root users. See SUID NOTES for
more information.
To make a file local although it includes a colon (:), the
filename must start with: ’/’, ’./’ or ’../’
Note that if star talks to an old rmt remote tape server that
does not support symbolic open modes, it does not open a remote
tape with the O_CREAT open flag because this would be extremely
dangerous. If the rmt server on the other side is the rmt
server that comes with star or the GNU rmt server, star may use
the symbolic mode for the open flags. Only the symbolic open
modes allow to send all possible open modes in a portable way
to remote tape servers.
It is recommended to use the rmt server that comes with star.
It is the only rmt server that gives platform independent com-
patibility with BSD, Sun and GNU rmt clients and it includes
security features that may be set up in /etc/default/rmt. All
options that start with the -f sequence are sensitive to typo
problems, see BUGS section for more information.
See ENVIRONMENT section for information on how to use ssh(1) to
create a remote tape server connection.
-find This option acts a separator. If it is used, all star options
must be to the left of the -find option. To the right of the
-find option, star accepts the find command line syntax only.
The find expression acts as a filter between the source of file
names and the consumer, which may either be the archiving
engine or list/extract engine. If the find expression evaluated
as TRUE, then the related file is selected for processing, oth-
erwise it is omited.
In order to make the evaluation of the find expression more
convenient, star implements additional find primaries that have
side effects on the file meta data. Star implements the fol-
lowing additional find primaries:
-chgrp gname
The primary always evaluates as true; it sets the group
of the file to gname.
-chmod mode
The primary always evaluates as true; it sets the per-
missions of the file to mode. Octal and symbolic per-
missions are accepted for mode as with chmod(1).
-chown uname
The primary always evaluates as true; it sets the owner
of the file to uname.
-false The primary always evaluates as false; it allows to make
the result of the full expression different from the
result of a part of the expression.
-true The primary always evaluates as true; it allows to make
the result of the full expression different from the
result of a part of the expression.
The command line:
star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d
lists all directories and archives all non-directories to the
archive o.tar.
The command line:
star -c f=o.tar -find . ( -type d -chown root -o true )
archives all directories so they appear to be owned by root in
the archive, all non-directories are archived as they are in
the file system.
-force_hole
obsoleted by -force-hole
-force-hole
Try to extract all files with holes. This even works with files
that are created without the -sparse option. Star, in this
case examines the content of the files in the archive and
replaces writes to parts containing binary zeroes with seeks.
This option should be used with extreme care because you some-
times get in trouble when files get unattended holes. All
options that start with the -f sequence are sensitive to typo
problems, see BUGS section for more information.
-force_remove
obsoleted by -force-remove
-force-remove
Force to remove non writable files on extraction. By default,
star will not overwrite files that are read only. If this
option is in effect, star will silently remove these files to
allow the extraction of a file. All options that start with
the -f sequence are sensitive to typo problems, see BUGS sec-
tion for more information.
-force-restore
Force an incremental restore even if the incremental dump is
only a partial dump. See -wtardumps, level= and section INCRE-
MENTAL BACKUPS for more information.
fs=# Set fifo size to #. See bs= for the possible syntax. The
default size of the fifo is 1 Mbyte on Sun mc68000 systems, 4
Mbytes on non mmap() aware Linux systems and 8 Mbytes on all
other systems. See -fifo option for hints on using the right
fifo size.
fs-name=mount_point
Use mount_point when recording information in /etc/tardumps and
when comparing against information in /etc/tardumps for incre-
mental backups. This makes sense when backups are made using
file system snapshots and allows /etc/tardumps and the archive
to contain the real name of the file system instead of the tem-
porary mount point that is used for the snapshot device.
H=headertype
See artype=headertype option. Note that POSIX.1-2001 defines
an option -H that follows symbolic links that have been encoun-
tered on the command line. For this reason, the old star
option H=headertype option may go away in the future even
though this option has been in use by cpio since 1989.
-h, -L Follow symbolic links as if they were files. Normally star
will not follow symbolic links but stores their values in
tarfile. See also the -L option.
-hardlinks
In extract mode, this option tells star to try to create a
hardlink whenever a symlink is encountered in the archive. In
create mode, this option tells star to try to archive a
hardlink whenever a symlink is encountered in the file system.
-hpdev Allow 24 bits for the minor device number using 8 octal digits.
Note that although it allows to create tar archives that can be
read with HP-UX tar, this creates tar archives which violate
POSIX.1-1988. This option is only needed if you like to use a
POSIX.1-1988 based archive format that does not include exten-
sions. If you use the xstar format, star will use a base 256
extension that allows bigger major/minor numbers by default, if
you use the xustar or the exustar format there is no limitation
at all as these formats use POSIX.1-2001 extended headers to
archive the major/minor numbers by default.
-i Ignore checksum errors on tar headers. If this option is spec-
ified, star will not exit if a header with a bad checksum is
found but search for the next valid header.
-j run the input or output through a bzip2 pipe - see option -z -Z
and -bz below. As the -bz the -j the -Z and the -z option are
non standard, it makes sense to omit the -bz the -j the -Z and
the -z options inside shell scripts if you are going to extract
a compressed archive that is located inside a plain file as
star will auto detect compression and choose the right decom-
pression option to extract.
-keep_old_files
obsoleted by -keep-old-files
-keep-old-files, -k
Keep existing files rather than restoring them from tarfile.
This saves files from being clobbered even if tarfile contains
a more recent version of the corresponding file.
See SECURITY NOTES for more information.
-L, -h Follow symbolic links as if they were files. Normally star
will not follow symbolic links but stores their values in
tarfile. See also the -h option.
-l Do not print a warning message if not all links to hard linked
files could be dumped. This option is evaluated in the opposite
way to historic tar(1) implementations and to POSIX.1. POSIX.1
requests that by default no warning messages will be printed
and -l will enable warning messages when not all links could be
archived.
level=dumplevel
Set level for incremental dumps. This option is used to switch
star into true incremental dump mode.
In true incremental dump mode, a -C option which is followed by
the name a mount point and a dot (’.’) as starting directory
name is required. Only a single file system may be handled at
a time. If the directory following the -C option is not refer-
ring to a root directory of a file system, the dump is called a
partial dump. If the directory following the -C option is
referring to a root directory of a file system and no other
restrictions apply that exclude certain files from the dump,
the dump is called a full dump.
By default, the tardumps database is not written. See also the
tardumps=name and -wtardumps options and the section INCREMEN-
TAL BACKUPS for more information.
-link-dirs
When in create mode, try to find hard linked directories.
Using -link-dirs will force star to keep track of all directo-
ries that will go into the archive and thus causes a lot more
memory to be allocated than in the default case.
If you like to extract a cpio archive that contains hard linked
directories, you also need to specify -link-dirs in extract or
diff mode. This is needed because many cpio implementations
create buggy archives with respect to hard links. If star
would look for hard linked directories in all cases, it would
detect many pseudo hard links to directories. Use -link-dirs
with care if you extract cpio archives.
Note that not all filesystem allow to create hard links to
directories. Also note that even though a non-root user is
able detect and archive hard linked directories, all known
operating systems require the extraction to be done as root in
order to be able to create or remove hard links to directories.
For this reason its only recommended to use this option when
doing accurate backups and when hard links to directories are
expected.
When the option -link-dirs is not used and hard links to direc-
tories are present, the appendant sub-tree will appear more
than once on the archive and star will print Linkcount below
zero warnings for non directory hard links inside the sub-tree.
list=filename
Read filenames for store/create/list command from filename.
The file filename must contain a list of filenames, each on a
separate line. This option implies the -D option. To force
star to descend directories, use the -dodesc option in this
case.
-lowmem
Try to run with reduced memory requirements. This causes star
to default to 1 MB of FIFO memory. Instead of allocating mem-
ory to hold the directory content and reading the directory at
once, star reads the directory name by name. This may cause
star to close the directory if it rans out of file descriptors
because of deeply nested directories. If a directory then does
not support telldir(3)/seekdir(3), star will fail.
-M, -xdev
Do not descend mount points. This is useful when doing backups
of complete file systems. See NOTES for more information.
-m Do not restore access and modification time. (Access time is
only available if star is reading star, xstar, xustar, exustar,
or pax archives). If star extracts other archive types, the -m
flag only refers to the modification time.
-match-tree
If in create mode a pattern does not match a directory, and
-match-tree has been specified, the whole directory tree is
excluded from the archive and from further directory scans. By
default, star excludes the directory but still recursively
scans the content of this directory as complex patterns could
allow files inside the directory tree to match. Using
-match-tree allows to efficiently exclude whole trees from
scanning. This helps to avoid scannings directory trees that
are on remote file systems or contain excessive bad blocks.
maxsize=#
Do not store files in tarfile if they are bigger than #. See
bs= for the possible syntax. By default, the number is multi-
plied by 1024, so the value counts in units of kBytes. If the
size specifier ends with a valid multiplication character (e.g
’.’ for bytes or ’M’ for MB) the specified size is used as
specified and not multiplied by 1024. See bs= option for all
possible multipliers.
-meta In create mode, -meta causes star to archive all meta data of
the file (e.g. uid, permissions, ...) but not the file content.
In extract mode, it causes star to restore all meta data but
not the file content. In addition, in extract mode no plain
file, special file or directory will be created. Meta files
are needed to support incremental backups.
Warning: Do not try to extract star archives containing meta
files using other tar implementations if they are not aware of
the meta file extensions of star. Star tries to force all tar
implementations that are not standard compliant to abort. Star
also tries to make all non POSIX.1-2001 compliant tar implemen-
tations unable to find a valid filename. However when other
POSIX.1-2001 aware tar implementations come up and don’t know
about meta files, they will destroy files on disk.
The problems result from the only current fallback in the POSIX
standard that tells tar implementations to treat all unknown
file types as if they were plain files. As meta files are
needed for incremental backups, I am looking for people and
companies who like to support me to be able to add the meta
file concept to the POSIX.1-2005 standard.
-modebits
This options allows you to create tar archives that include
more than 12 bits from st_mode. Note this create tar archives
that violate POSIX but some tar implementations insist in read-
ing such nonstandard archives.
-multivol
Switch to multi volume mode. In multi volume mode, there will
be no logical EOF marker written to the end of a single tape.
If -multivol is used in read mode, a hard EOF on input (if not
preceded by a logical EOF) triggers a medium change operation.
Specifying -multivol tells star to split files across volumes
if needed. This way, a virtual archive is created that spans
more than one medium. Multi volume mode is needed whenever it
is not possible to split the archiving or extracting into sev-
eral logically independent tasks. This is true for e.g. incre-
mental dump/restore operations where inode numbers need to be
traced for the whole task.
When tsize=# has been specified, but star is not in multi vol-
ume mode, files cannot be split across volumes.
When -multivol has been specified in create mode together with
tsize=# then a media change is initiated exactly after an
amount of tsize data has been written. When -multivol has been
specified in create mode and tsize=# has not been specified,
then the medium change is triggered by a EOT condition from
writing the medium. This allows to use media where the size
cannot be known in advance (e.g. tapes with build in compres-
sion); it does not work if the EOT condition is not returned in
sync with the related write operation. For this reason, it is
expected that data buffering inside a device driver cannot be
used.
Depending on the selected archive format, star writes a volume
header at the beginning of a new medium. This medium header
allows to verify the correct volume after a change during read
back. It is recommended to use the exustar format for best
results. In create mode, -multivol is only supported for
archives types that allow to write reliable multi volume header
information.
See tsize=# option for more information.
Note that -multivol is an interactive option that prevents star
from being used in non-interactive environments. If you like
to use it in a non-interactive environment, you need to specify
new-volume-script=script in addition in order to automate the
media change procedure.
newer=filename
Do not store files to tarfile if their modification time is not
newer than the modification time of filename. See -ctime
option for changing this behavior.
-newest
In conjunction with the list command this lists you only the
newest file in tarfile.
-newest_file
obsoleted by -newest-file
-newest-file
In conjunction with the list command this lists you only the
newest regular file in tarfile.
new-volume-script=script
Call script at end of each tape if in multi volume mode. If
this option is not in effect, star will ask the user to confirm
the volume change. The script is called with two parameters.
The first parameter is the next volume number and the second
parameter is the next archive file name.
-nodump
If this option is set, star will not dump files that have the
nodump flag set. Note that this currently only works on BSD-4.4
derivates and on Linux. On Linux, using this option will cause
a performance degradation (the system time increases by 10%)
because of the unlucky kernel interface.
-no-dirslash
Do not add a slash to the end of directory names if writing to
an archive. Historic tar archive formats did only allow to
specify plain files and hard links. Around 1980, BSD added a
feature to specify a directory on tape by adding a slash to the
end of the name. POSIX.1-1988 defined the first official tar
archive format that had a clean method to specify the type of a
directory. As old tar formats need the slash to recognize a
directory, -no-dirslash may not be used if archives should be
compatible with the old tar format.
-no_fifo
obsoleted by -no-fifo
-no-fifo
Don’t use a fifo to optimize data flow from/to tarfile. Cur-
rently the -fifo option is used as default. (This may be
changed at compile time.)
-no-fsync
Do not call fsync(2) for each file that has been extracted from
the archive. Using -no-fsync may speed up extraction on oper-
ating systems with slow file I/O (such as Linux), but includes
the risk that star may not be able to detect extraction prob-
lems that occur after the call to close(2). A typical cause
for such problems is a NFS file system that fills up before the
buffer cache is synced or a write error that occurs while the
buffer cache is synced. There may be other reasons. Use with
extreme care.
-nochown, -o
Do not restore owner and group of files. This may be used if
super user privileges are needed to overwrite existing files
but the local ownership of the existing files should not
change.
-no-p Do not restore files and directories to their original permis-
sions. This option is needed only if star is called by the
super user and the permissions should not be restored from the
archive. See also the -p option. The -p options has a higher
precedence than the -no-p option.
-no_statistics
obsoleted by -no-statistics
-no-statistics
Do not print statistic messages at the end of a star run.
-no-xheader
Do not create or extract POSIX.1-2001 extended headers. This
option may be used if you like to read an archive with broken
extended headers.
-not, -V
Invert the meaning of the pattern list. i.e. use those files
which do not match any of the pattern. Note that this option
only applies to patterns that have been specified via the pat-
tern=pattern or pat=pattern option. Patterns specified as file
type arguments will not be affected.
-notarg, -pax-c
Match all file or archive members except those specified by the
pattern or file operands.
-nowarn
Do not print warning messages. This sometimes is useful to
make the output more readable (e.g. when hundreds of files that
are going to be extracted are not newer in the archive then on
the filesystem).
-numeric
Use the numeric user/group fields in the listing rather than
the default. The default allows to list the ASCII version of
user/group of the file and to extract the owners of the files
based on numeric values rather than the names. In create mode,
no user/groups names are put on the archive. The -numeric
option also applies when ACLs are going to be archived or
extracted.
-O Be compatible to old versions of tar. If star is invoked with
this option, star generates archives which are fully compatible
with old UNIX tar archives. If in extract mode, star ignores
any additional info in the headers. This implies neither that
archives generated with this option are binary equal with
archives generated by old tar versions nor that star is trying
to comprehend all bugs that are found in old tar versions. The
bug in old tar versions that cause a reversal of a space and a
NULL byte in the checksum field is not repeated. If you want
to have signed checksums you have to specify the -singed-check-
sum option too. If you want directories not to be archived in
order to be compatible to very old historic tar archives, you
need to specify the -d option too.
This option is superseeded by the H=headertype option.
-o, -nochown
Do not restore owner and group of files. This may be used if
super user privileges are needed to overwrite existing files
but the local ownership of the existing files should not
change.
-onull, -nullout
Do not actually write to the archive but compute and add the
sizes. This is useful when trying to figure out if a tape may
hold the current backup. Please only use the -onull option as
it is a similar option as used by the sdd(1) command.
-P Allow star to write a partial record as the last record. Nor-
mally, star writes each record with the same size. This option
is useful on unblocked tapes i.e. cartridge tapes like QIC
tapes as well as with archives that are located in files. If
you use this option on local files, the size of the archive
will be smaller. If you use this option on cartridge tapes, is
makes sure that later - in extract mode - star will read up to
the end of file marker on the tape and the next call to star
will read from the next archive on the same tape.
-p Restore files and directories to their original permissions.
Without this option, they are created using the permissions in
the archive and the present umask(2). If star is called by the
super user, star behaves as if it has been called with the -p
option. See also -no-p option. If the archive contains Access
Control Lists (ACLs) in POSIX.1-2001 extended headers, star
will restore the access control lists from the archive for
files if the -acl option is specified. If the option -acl has
not been specified, ACLs are not restored at all.
pattern=pattern, pat=pattern
Set matching pattern to pattern. A maximum of 100 pattern=pat
options may be specified. As each pattern is unlimited in
length, this is no real limitation. If more than one pattern
is specified, a file matches if any of the specified pattern
matches. Patterns may be used in create mode to select or
exclude files from the list of file type arguments or the files
located in a sub tree of a file type argument directory. By
default, star scans the whole directory tree underneath a
directory that is in the argument list. This may be modified by
using the -match-tree option. In extract or list mode, all
file type arguments are interpreted to be select pattern and
all option type patterns may be either select or exclude pat-
terns depending on the presence or absence of the -not option.
If you use file type select patterns, they work exactly like
the method used by other (non pattern aware) tar(1) implementa-
tions. File type select patterns do not offer pattern matching
but allow to restore subtrees. To extract a complete sub tree
from the directory dir with star using the pattern= option, use
pattern= dir/\* if you like to select a subtree by using the
historic method, use dir/ as file type argument. See manual
page for match(1) for more details of the pattern matcher. All
patterns are selection patterns by default. To make them
exclude patterns, use the -not or the -V option.
pkglist=file
This is (for now) an internal interface for the Schily Source
Package System (sps). It only works in create mode and behaves
similar to the list= option, but it allows to overwrite the
permissions, the uid and gid values from the content of the
pkglist= file. Each line from the pkglist= file contains a
file name followed by the permission, a user name and a group
name. The permission is an octal character string. Each value
that is not used to overwrite the original values may be
replaced by a ’?’. The fields are separated by spaces, so the
pkglist= option does not allow files that contain newline or
space characters.
-pax-c, -notarg
Match all file or archive members except those specified by the
pattern or file operands.
-pax-H Follow symbolic links that have been encountered on the command
line. If the referenced file does not exist, the file informa-
tion and type will be for the link itself. If the link is ref-
erencing a file type that cannot be archived with the current
archive format, the file information and type will be for the
link itself.
-pax-i Do interactive renaming in a way that has been defined for
POSIX pax. Star will print the original filename and prompt
for a reply. If you type just RETURN, than the file is
skipped. If you type ’.’, then the original file name is
retained. If you type anything else, then this is taken as the
new file name.
Note that -pax-i is an interactive option that prevents star
from being used in non-interactive environments.
-pax-L Follow symbolic links. If the referenced file does not exist,
the file information and type will be for the link itself. If
the link is referencing a file type that cannot be archived
with the current archive format, the file information and type
will be for the link itself.
-pax-ls
Switch listing format to the format defined for POSIX pax and
ls.
-pax-match
Allow file type arguments to be recognised as regular expres-
sions in a way that has been defined for POSIX pax.
-pax-n Allow each pattern to match only once. If a pattern matches a
directors, then the whole sub tree matches the pattern.
-pax-p string
PAX style privileges string. Several characters (each has it’s
own meaning). The following characters are defined:
a Do not preserve file access times. This option is cur-
rently ignored.
e Preserve the user ID, group ID, file mode bits. This is
equivalent to calling star -p -acl -xfflags.
m Do not preserve file modification times. This is cur-
rently equivalent to calling star -m.
o Preserve the user ID and group ID. This is the default
for star if called as root.
p Preserve the file mode bits. This is equivalent to
calling star -p.
-prinodes
Print inode numbers in verbose list mode if the archive con-
tains inode nubers.
-print-artype
Check the type of the archive, print the archive and compres-
sion type on a single line and exit.
-qic24 Set tape volume size to 61440 kBytes. See tsize=# option for
more information.
-qic120
Set tape volume size to 128000 kBytes. See tsize=# option for
more information.
-qic150
Set tape volume size to 153600 kBytes. See tsize=# option for
more information.
-qic250
Set tape volume size to 256000 kBytes. See tsize=# option for
more information.
-qic525
Set tape volume size to 512500 kBytes. See tsize=# option for
more information.
-read0 Read null terminated file names from the file specified with
the list= option.
-refresh_old_files
obsoleted by -refresh-old-files
-refresh-old-files
-refresh
Do not create new files. Only already existing files may be
overwritten from tarfile if either newer versions are present
in the archive or if the -U flag is used. This allows to over-
write files by more recent files from an archive that contains
more files than the target directory should contain. The
option -refresh-old-files is the same as the -refresh option.
-remove_first
obsoleted by -remove-first
-remove-first
Remove files before extraction. If this option is in effect,
star will remove files before extracting a file from the
archive. This is needed if you want to change the file type or
if you need to break a hard link. If you do not use either
-ask-remove or -force-remove together with -remove-first, this
option is useless and no files will be removed.
-remove_recursive
obsoleted by -remove-recursive
-remove-recursive
Remove files recursive. If removing of a file is permitted,
star will only remove files, specials and empty directories.
If this option is in effect, star will be allowed to recur-
sively removes non empty directories too.
-restore
switches star into true incremental restore mode. A file named
star-symtable and a directory named star-tmpdir is created in
the root directory of the file system where the extraction
takes place. If -restore has been specified, star behaves as
if -xdot has been specified too. See also level= option and
section INCREMENTAL BACKUPS for more information.
Note: Do not use the -restore option if you only like to
restore a single file or a list of selected files.
-S Do not store/create special files. A special files is any file
except plain files, symbolic links and directories. You need
to be super user to extract special files.
-s replstr
Modify file or archive member names named by a pattern accord-
ing to the substitution expression replstr. The format of
replstr is:
-s /old/new/[gp]
The old pattern may use regular expressions and the new string
may contain the special character ’&’. The character ’&’ is
substituted by the string that matches the old pattern. The
optional trailing ’g’ means global substitution. If ’g’ is not
used, a substitution pattern is only used once on a name. If
the optional trailing ’p’ is used, the substitution is printed
to standard error.
Up to 100 substitute options may be used. If more than one sub-
stitute option has been specified, star will loop over all sub-
stitute patterns until one matches.
If the name substitutes to the empty string, the file is
skipped.
-secure-links
Do not extract hard links or symbolic links if the link name
(the target of the link) starts with a slash (/) or if /../ is
contained in the link name. Tar archives containing such links
could be used to compromise the system. If they are unpacked
together with a lot of other files, this may not even be
noticed.
As the usability of a tar archiver would be limited if
-secure-links checking would be done by default, star makes
link checking optional.
If you unpacked a tar archive using the -secure-links and did
not get a security warning at the end of the star run, all
files and links have been extracted. If you get a warning, you
should unpack the archive a second time and specify the options
-k, -w and -nowarn in addition to the options used for the
first run. See SECURITY NOTES for more information.
-shm Use System V shared memory for fifo. Normally star is compiled
to use mapped /dev/zero pages for the fifo, if the operating
system supports this. If star is compiled to have both code
for mapped pages and for System V shared memory, star will use
shared memory instead of the default. If the -help menu
doesn’t show the -shm flag you have no choice. When using Sys-
tem V shared memory, you may have to raise the system’s inter-
nal limit for shared memory resources to get enough shared mem-
ory for star.
-signed_checksum
obsoleted by -signed-checksum
-signed-checksum
Use signed chars to calculate checksums. This violates the tar
specs but old versions of tar derived from the seventh edition
of UNIX are implemented in this way. Note: Only filenames and
linknames containing chars with the most significant bit set
may trigger this problem because all other fields only contain
7 bit ASCII characters, octal digits or binary zeroes.
-silent
Suppress informational messages like foobar is sparse.
-sparse
Handle files with holes effectively on store/create. Note that
sparse files may not be archived this way if the archive format
is tar, ustar, suntar, pax, or any cpio variant. On
Solaris-2.3 ... Solaris-2.5.1 there is a special ioctl() called
_FIOAI that allows root to get the allocation info more effi-
ciently. On Solaris 11 there is an enhanced lseek(2) call with
addidional whence values SEEK_HOLE and SEEK_DATA that allow to
find holes in an efficient way. Other operating systems lack
support to get the real allocation list and force star to scan
the files to look for blocks that only contain null characters.
This may star cause to assume more holes to be present than the
number that the file really contains.
-symlinks
This option tells star in extract mode to try to create a sym-
link whenever a hardlink is encountered in the archive.
-T If the option file= or f= is omitted and the -T option is
present, star will use the device indicated by the TAPE envi-
ronment variable, if set.
tardumps=name
Set the file name for tar dump dates database to name. The
default name is /etc/tardumps. Use in combination with the
level= option to create true incremental dumps. See also
-wtardumps option and section INCREMENTAL BACKUPS for more
information.
-time Print timing info. See DIAGNOSTICS for more information.
-to_stdout
obsoleted by -to-stdout
-to-stdout
Extract files to stdout. This option may be used to extract
tarfiles containing tarfiles (see examples below).
-tpath Use this option together with the -t option or with -cv (ver-
bose create) to get only a list of the pathnames of the files
in the archive. This may be used in shell scripts to generate
a name list. If used together with the -diff option, star will
only print the names of the files that differ. A second run of
star may then be used to restore all files that had differences
to the archive. Use the list= option to specify the namelist
in this case.
tsize=#
Set tape volume size to # to enable multi volume tape support.
See bs= for the possible syntax. By default, the number is
multiplied by 512, so the value counts in units of 512 byte
blocks. If the size specifier ends with a valid multiplication
character (e.g ’.’ for bytes or ’M’ for MB) the specified size
is used as specified and not multiplied by 512. With this
option in effect, star is able to archive filesystems that are
bigger then the tape size. If the option tsize=# without -mul-
tivol then no file will be split across volumes and each volume
may in theory be read back separately. Files that do not fit
on a single tape may not be stored in this mode. If -multivol
has been specified in addition, star will split files when the
maximum allowed tape size has been reached. If the tape volume
size is not a multiple of the tape block size, the tape volume
size is silently rounded down to a value that is a multiple of
the tape block size.
See -multivol option for more information.
-U Restore files unconditionally. By default, an older file from
the archive will not replace a corresponding newer file on
disk.
umask=mask
Set star’s umask to mask. This allows to control the permis-
sions for intermediate directories that are created by star in
extract mode. See also -p option.
-v Increment verbose level by one. This normally results in more
output during operation. See also in the description for the
-t flag. Normally, star does its work silently. If the ver-
bose level is 2 or more and star is in create or update mode,
star will produce a listing to the format of the ls -l output.
-V, -not
Invert the meaning of the pattern list. i.e. use those files
which do not match any of the pattern. Note that this option
only applies to patterns that have been specified via the pat-
tern=pattern or pat=pattern option. Patterns specified as file
type arguments will not be affected.
-version
Print version information and exit.
VOLHDR=name
Use name to generate a volume header.
-w Do interactive creation, extraction or renaming. For every
file that matches the list of patterns and that has a more
recent modification time in the tar archive (if in extract mode
and the -U option is not specified) star prints its name and
asks:
get/put ? Y(es)/N(o)/C(hange name) :
You may answer either ‘N’ for No or <Return> to skip this file.
If you answer ‘Y’ the file is extracted or archived on tape
with its original name. If you answer ‘C’, you are prompted
for a new name. This name is used for the filename on disk if
star is in extract mode or for the archive name if star is in
create mode.
See SECURITY NOTES for more information.
Note that -w is an interactive option that prevents star from being
used in non-interactive environments.
-wready
This option tells Star to wait up to two minutes for the drive
to become ready. It has been added as a hack for a bug in the
SunOS/Solaris st device driver. This driver has problems to
sense the loading time with Exabyte drives with factory set-
tings. It also makes sense to use -wready if multiple remote
backups are made. In this case, the remote connection is closed
while the remote tape server is still writing a file mark. If
another remote backup is initiated before the old remote server
did finish to write the file mark, it would be impossible to
open the tape driver unless -wready is specified to tell star
to wait for the drive to become ready again.
-wtardumps
Tell star to update the file that contains the tar dump dates
data base if in dump mode. If the dump is not a full dump, the
tar dump dates data base file is not written. See also tar-
dumps=name and -C option or INCREMENTAL BACKUPS section for
more information.
-xattr
-xattr-linux
Store and extract extended file attributes as found on Linux
systems. This option only makes sense when creating or
extracting exustar archives as it is based on POSIX.1-2001
extended tar headers.
The method used in the current implementation could be used to
store and extract extended file attributes from BSD too. Note
that the current implementation is not generic enough to cover
more general extended file attribute implementations as found
on Solaris. If star starts to implement a method that covers
extended file attributes on Solaris, the new method will be
used then -xattr has been specified and -xattr-linux will refer
to the old method. The method used with -xattr-linux may go
away in the future.
xdebug=#, xd=#
Set extended debug level to #.
-xdev, -M
Do not descend mount points. This is useful when doing backups
of complete file systems. See NOTES for more information.
-xdir Extract directories even if the corresponding directories on
the archive are not newer. This is useful when for some rea-
son, the directories are recorded after their content (see
-dirmode option), or when the permissions of some directories
must be set in any case. As the classical UNIX cpio program
does not implement delayed directory permission and time stamp
setting, cpio users often create archives in reverse order
(directories past their content). For this reason, it makes
sense to use -xdir while extracting cpio archives.
-xdot Unconditionally extract the first directory in the archive if
the name of this directory is either ’.’ or ’./’. This helps
to extract archives in an expected way if the target directory
is a newly created empty directory. As this directory is newer
than the top level directory in the archive, star would usually
skip this directory during extraction. The effect of this
directory is as if -xdir has been specified but is switched off
after the first directory has been found.
-xfflags
Store and extract extended file flags as found on BSD and Linux
systems. This option only makes sense when creating or
extracting exustar archives as it is based on POSIX.1-2001
extended tar headers. See NOTES section for problems with
-xfflags on Linux systems.
-Z run the input or output through a compress pipe - see option -z
below.
-z run the input or output through a gzip pipe. This is currently
a quick and dirty hack, that mainly will cover the most common
usage to compress the tar output if it is a file. No reblock-
ing will be done, so this option will currently only make sense
on plain files. As the -bz the -j the -Z and the -z option are
non standard, it makes sense to omit the -bz the -j the -Z and
the -z options inside shell scripts if you are going to extract
a compressed archive that is located inside a plain file as
star will auto detect compression and choose the right decom-
pression option to extract. The environment variable STAR_COM-
PRESS_FLAG may be used to specify one option for gzip. If you
want to write write compressed archives to tape, you should use
star -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
or
star -c . | gzip | sdd ibs=4k obs=32k -fill ovsize=60m
of=/dev/rmt/1bn
if the tape can hold 60 MB.
INCREMENTAL BACKUPS
Star is able to back up file system in full and incremental mode. To
allow incremental backups, the file system must implement POSIX seman-
tics.
To be more verbose:
· The filesystem needs to uniquely identify files by the two num-
bers st_dev (The device ID of the device containing the file)
and st_ino (The file serial number). If a file is renamed,
these numbers need to be retained. Both numbers need to be a
cardinal scalar that is expressible in a decimal number.
· The filesystem needs to implement at least two time stamps,
st_mtime the file’s last modification time and st_ctime the
file’s last status change time. Both time stamps need to be
dealt with as documented by te POSIX standard. Both numbers
need to be a cardinal scalar that is expressible in a decimal
number.
· The filesystem needs to allow to rename files and directories
by either calling rename(2), or link(2) and unlink(2).
· The filesystem needs to honor and preserve the case of file
names.
The incremental backup method used by star depends on comparing the
time stamps of all files against the time of the last backup. Note
that this method only works correctly if the level 0 backup and all
higher level incrementals include the whole file system. As star
archives all inode meta data, star is able to detect renamed files by
comparing inode numbers.
Detecting renamed files only works if star scans the whole file system
tree for each full and incremental backup. This will work in case no
files are excluded and the dump starts at the root directory of a file
system. In case that no files are renamed from excluded parts to
included parts, partial backups may be taken also. Partial backups
only make sense if a complete directory sub tree is excluded (e.g. by
using the pat= option) or if a partial backup starts at a sub direc-
tory that is not the root directory of the file system.
To create a level 0 dump call:
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
f=archive-name -C /filestem-mount-point .
To create a level 1 dump call:
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
f=archive-name -C /filestem-mount-point .
Backups from live filesystems should be avoided. On operating systems
that support file system snapshots, backups should be made from a
read-only mount of a snapshot. Be careful that all files that have
been created between setting up a snapshot and starting an incremental
backup may be missing from all backups unless the dumpdate=name option
is used.
If the system that is going to be backed up is not acting as a file
server, it makes sense to shut down all services that may result in
inconsistent file states before setting up the filesystem snapshot.
After the filesystem snapshot has been set up, the services may be
restarted.
If the the system that is going to be backed up is acting as a file
server, it may be that services on remote clients cause inconsistent
file states unless all such services that remotely access files are
shut down before the snapshot is set up.
Star includes options that help to deal with file system snapshots.
The following example backs up a file system on Solaris using a file
system snapshot:
echo > /tmp/snapstamp
mount -r ‘fssnap -F ufs -o \
backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs‘ /mnt
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
f=archive-name dumpdate=/tmp/snapstamp \
fs-name=/export/nfs -C /mnt .
First a file with a current time stamp is created, then a snapshot for
/export/nfs is created and mounted on /mnt. The following star com-
mand then creates a level 0 backup from the file system using the time
the snapshot was created and the original mount point of the file sys-
tem for /etc/tardumps and the archive header.
Note that if the backup is done on a live file system, it may be unre-
liable. A typical problem problem in this context is caused by growing
log files. As growing files are not a real problem with backups, the
best way of dealing with growing files is to set up a star error con-
trol file (see errctl= option) and to tell star to ignore growing
files.
BACKUP SCHEDULES
Full (level 0) dumps should be made on a regular base (e.g. once a
month). As a full dump may take a long time and takes a lot of tape,
it is wise to make higher level incremental dumps with shorter inter-
vals. The next table shows a dump level list that may be used if
monthly full dumps take place:
Sun Mon Tue Wed Thu Fri
Week 1: 0 10 10 10 10 5
Week 2: 10 10 10 10 10 5
Week 3: 10 10 10 10 10 5
Week 4: 10 10 10 10 10 5
The level 9 dumps made between Monday and Friday accumulate all
changes made within the week. If you don’t like this, use the follow-
ing backup schedule:
Sun Mon Tue Wed Thu Fri
Week 1: 0 20 30 40 50 5
Week 2: 10 20 30 40 50 5
Week 3: 10 20 30 40 50 5
Week 4: 10 20 30 40 50 5
Note that in this case, 7 dumps need to be restored if the a crash
happens at the worst case date (after the Friday dump in week 2 or
later).
INCREMENTAL RESTORES
Incremental restores should be made to an empty file system (except
for the lost+found directory). Star is currently unable to perform
incremental restores to a file system that contains active mount
points.
The incremental restore procedure starts with restoring the last full
(level 0) dump. Then the latest incremental dump of each dump level
(with ascending order of dump levels) need to be restored.
Let us assume the first example from the section BACKUP SCHEDULES for
the backup schedule. If a disk crash happens before the Thursday dump
of week 3 has been made, the following restore procedure needs to be
applied:
level 0
starting with an empty disk, the full (level 0) dump from week
1 is restored.
level 5
after the level 0 restore has been finished, the level 5 dump
from Friday in week 2 is restored.
level 10
after the level 5 restore has been finished, the level 10 dump
from Wednesday in week 3 is restored.
The disk now contains the same files as it did when the level 9 dump
has been made on Wednesday of week 3.
To extract a level 0 dump call:
cd /filestem-mount-point
star -xpU -restore f=archive-name
This creates the directory star-tmpdir and the database star-symtable
in the root directory of the new file system. Subsequent restores
with higher level backups depend on these files.
To extract a level 1 (or higher) dump call:
cd /filestem-mount-point
star -xpU -restore f=archive-name
Note that the environment variable STAR_DEBUG exists, star does not
remove files with link count 1 that have been removed between incre-
mental dumps. These files are moved to the directory star-tmpdir.
Before you start to extract the next incremental, you need to remove
all files in star-tmpdir.
SYNCHRONIZING FILESYSTEMS
Star may be used to synchronize filesystem content. To do this, an
initial copy of the current content of the source filesystem needs to
be performed first.
To create an initial copy of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
-C /filestem-mount-point . | \
star -xpU -restore -C /extract-target-dir
In order to perform subsequent synchronization of the target filesys-
tem with the content of the source filesystem, a modified incremental
dump/restore procedure may be used.
To copy incremental content of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
-cumulative -C /filestem-mount-point . | \
star -xpU -restore -C /extract-target-dir
Note that like with backups in general, copies from a live filesystem
should be avoided. On operating systems that support file system
snapshots, copies should be made from a read-only mount of a snapshot.
Be careful that all files that have been created between setting up a
snapshot and starting an incremental copy may be missing from all
copies unless the dumpdate=name option is used.
See section INCREMENTAL BACKUPS to learn how to modify the command
line in case file system snapshots are used.
SIGNALS
If star handles a signal, it first prints the statistics. Star han-
dles the following signals:
SIGINT usually generated by ^C from the controlling tty. Upon
receipt of a SIGINT, star prints statistics and exits. If
in create mode i.e. storing files to archive, star finishes
with the current file to ensure that no partial file is
written to the archive, write an eof record and then exits.
SIGHUP not to be generated from a tty. The actions are the same as
upon receipt of a SIGINT.
SIGQUIT usually generated by ^\ from the controlling tty. Upon
receipt of a SIGQUIT, star prints statistics and continues
with the current operation. This is useful to watch the
progress of the current operation.
EXIT STATUS
The following exit values are returned:
0 All files were processed successfully.
-3 / 253
Star has been called with the option -e, or the errctl= option
has been used to mark the current error fatal.
-2 / 254
One or more files could not be processed successfully.
-1 / 255
Command line parsing error.
>0 Other positive exit codes: The errno of the call that caused
the fatal error.
EXAMPLES
To get a listing in a way similar to ls -l one might use:
example% star -tv f=/dev/rmt/1bn
The same command as listed above in a POSIX tar command line syntax
compliant way is:
example% star tvf /dev/rmt/1mbn
To copy the directory tree in /home/someuser to the directory /home/fs
use:
example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
or by using the change directory option of star:
example% star -c -C /home/someuser . | star -xp -C /home/fs
Note that both examples above are not the optimum way to copy a direc-
tory tree. A more efficient way to copy a directory tree is to use the
-copy option.
example% star -copy -p -xdot -C /home/someuser . /home/fs
To copy a file tree including the Access Control List entries for all
files and to correctly copy sparse (holey) files use:
example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
To compare the content of a tape to the filesystem one might use:
example% star -diff -v f=/dev/rmt/1bn
To compare two directory trees one might use:
example% star -c . | star -C todir -diff -v diffopts=!times
or better by using a method similar to the -copy method above:
example% star -c -diff -v diffopts=!times -C fromdir . todir
To compare all properties of two file trees, use:
example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
To extract a backup of the /usr tree without all files residing below
/usr/openwin one might use:
example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
To extract all .c files to src, all .o files to obj and all other
files to /tmp one might use:
example% star -xp -C src ’*.c’ -C obj ’*.o’ -C /tmp ’*’ f=/dev/rmt/1bn
To extract files from a zipped tar archive that is located on a read
only filesystem e.g. a CD while having the shell’s working directory
on the CD one might use:
example% star -zxp -C /tmp f=star-1.1.tar.gz
to extract the files from the tar archive to the /tmp directory.
To backup a list of files generated by the find(1) command:
example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
Note that this does not work if the file names from output of the find
command include new line characters.
To extract a tarfile that contains a tarfile one might use:
example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
Pat, in this case should match the tarfile in the tarfile on tape that
should be extracted.
To make a backup of the root filesystem to a tape drive connected to a
remote machine, one might use:
example# cd /
example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
You need a line in /etc/passwd like the following to enable this:
tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
And a .rhosts file in /etc/tapehome to allow remote connections from
the appropriate hosts. Make sure that the file /etc/default/rmt
exists and allows remote access to the requested tape drive.
To use a ssh(1) connection for a backup to a remote tape server, one
might use:
example# env RSH=/usr/bin/ssh star -cM fs=128m bs=63k
f=tape@remotehost:/dev/rmt/1bn .
To repair a corrupted filesystem for which no recent backup exists, do
the following:
example# fsck -y /filesys
example# mount /filesys
example# cd /filesys
example# star -xpk f=/dev/rmt/1bn
example# mt -f /dev/rmt/1bn rewind
example# star -diff -v diffopts=!times f=/dev/rmt/1bn
Now check the differences and decide whether to restore additional
files. This may be done by generating a list containing the needed
filenames and using the list= option or by using the interactive mode
(see -w option).
If you want a list that only contains all filenames from files with
differences you may use:
example# star -diff -tpath diffopts=!times f=/dev/rmt/1bn
If you are looking for files that changed the type or the access per-
mission because this is a common case on still corrupted files, use:
example# star -diff -tpath diffopts=type,perm f=/dev/rmt/1bn
If you like to archive all directories only that are part of the
directory tree under ".", use:
example# star -c f=archive-name -find . -type d
If you like to archive all files as owner root and group root and make
all files world readable in the archive, use:
example# star -c f=archive-name -find . -chown root -chgrp root
-chmod o+r
If you like to list all files in an archive in a way like sfind(1),
instead of the way used by star, use:
example# star -t f=archive-name -find . -ls -false
ENVIRONMENT
STAR_COMPRESS_FLAG
If you like star to always create compressed files that use
maximum compression, you may set the environment variable
STAR_COMPRESS_FLAG to -9.
STAR_DEBUG
If this environment variable is present, star will not remove
temporary files from ./star-tmpdir. The files in this direc-
tory are files that have been removed by users before the last
incremental dump did take place on the master filesystem.
STAR_FIFOSIZE
If you like to by default let star use a different fifo size,
set this environment variable to the desired size.
TAPE Unlike other tar(1) implementations, star defaults to use
stdin/stdout for the archive. If you like star to use the file
name from the TAPE environment instead, you need to specify the
-T option too.
RSH If the RSH environment is present, the remote connection will
not be created via rcmd(3) but by calling the program pointed
to by RSH. Use e.g. RSH=/usr/bin/ssh to create a secure shell
connection.
Note that this forces star to create a pipe to the rsh(1) pro-
gram and disallows star to directly access the network socket
to the remote server. This makes it impossible to set up per-
formance parameters and slows down the connection compared to a
root initiated rcmd(3) connection.
See BUGS section for more information.
RMT If the RMT environment is present, the remote tape server will
not be the program /etc/rmt but the program pointed to by RMT.
Note that the remote tape server program name will be ignored
if you log in using an account that has been created with a
remote tape server program as login shell.
FILES
/etc/default/star
Default values can be set for the following options in
/etc/default/star. For example: CDR_FIFOSIZE=64m
STAR_FIFOSIZE
Sets the default size of the FIFO (see also fs=#
option).
STAR_FIFOSIZE_MAX
Sets the maximum size of the FIFO (see also fs=#
option). Setting STAR_FIFOSIZE_MAX in /etc/default/star
allows to overwrite global values from backup scripts
for machines with less memory.
archive0=
archive2=
archive3=
archive4=
archive5=
archive6=
archive7=
archive0=
Archive entries for the -[0..7] option.
A correct archive?= line has 3..4 space separated
entries. The first is the device entry (e.g.
archive0=/dev/tape). The second is the blocking factor
in 512 byte units. The third is the maximum media size
in 1024 byte units. If this entry contains a 0, then
the media size is unlimited. The fourth entry is
optional. If it contains a ’n’ or a ’N’, then the
archive device is not a tape.
Examples:
archive0=/dev/tape 512 0 y
archive1=/dev/fd0 1 1440 n
archive2=/dev/rmt/0mbn 512 0
If the default file does not need to be shared with the
tar program from Solaris, any number may be used like a
generic size option like bs=.
Example:
archive0=/dev/tape 256k 40G y
/etc/tardumps
The default name for the dump level archive. The default name
is used whenever the tardumps=name option has not been speci-
fied. The file is written or updated when -wtardumps is used.
The file holds one or more lines, each specifying a dump level
entry. Each dump level entry starts with a mount point name
followed by a TAB and one or more spaces, followed by the deci-
mal dump level, a space and the dump time.
If the dump level is directly followed by a ’P’, then the dump
refers to a partial dump (a dump that does not include the
whole filesystem).
The dump time itself includes the decimal representation of the
UTC seconds since Jan 01 1970, a space and the textual local
time representation of the dump time.
The numerical decimal dump time representation may be followed
by a dot and a sub second value. The textual local time repre-
sentation is for informational use by humans only and not eval-
uated by star.
./star-symtable
Contains a database that is needed in incremental restore mode.
./star-symdump
Contains an intermediate dump of restore database after a fatal
error condition was met during an incremental restore opera-
tion.
./star-tmpdir
Is the temporary directory that is used as intermediate file
storage by star if in incremental restore mode.
./star-lock
Is a lock file created by star when doing an incremental
restore. If this file is present, it prevents star from run-
ning another incremental restore operation. This helps to avoid
more than one restore operation at a time (e.g. from a cron
script).
/dev/tty
Is used for the intercative user interface.
SEE ALSO
spax(1), suntar(1), scpio(1), tar(1), cpio(1), pax(1), rcp(1), mt(1),
rmt(1), match(1), dd(1), sdd(1), rsh(1), ssh(1), star(4/5), rcmd(3),
fssnap(1m)
DIAGNOSTICS
star: f records + p bytes (total of x bytes = d.nnk).
The number of full records, the number of bytes in partial records and
the total amount of data in KBytes.
star: Total time x.yyysec (z kBytes/sec)
The time used and the transfer speed from/to the archive.
If there have been non fatal errors during the archive processing,
star will display a delayed error summary before exiting.
NOTES
The command line syntax for the tar command (as defined in SUSv2 -
UNIX-98) deviates from the command line syntax defined for all other
commands. While the POSIX command line syntax requests all options to
start with a dash (-) and allows to either write options separately or
combined (in case of boolean flags), the tar command line syntax
requires all options to be combined into a single string that does not
start with a dash. Star by default assumes a command line syntax like
a typical POSIX command and includes a compatibility mode that allows
to specify a command line syntax as documented for the UNIX-98 tar
command. If you believe that you found a bug in the way star parses
the command line, please first check your command line for correctness
before you make a bug report for star.
If you like to write portable shell scripts that call tar, use the
UNIX-98 tar command line syntax (i.e. a single option string and no
dash), choose the commands and options from the following set of char-
acters ( rxtuc vxfblmo ) and check the shell script with both, your
local tar and star for correct behavior. It you expect the script to
call gnutar, do not include the -o option as gnutar implements this
option in a way that violates UNIX-98.
Star strips leading ./ sequences from pathnames. This lets star in
many cases store longer pathnames than other implementations.
The POSIX.1-1988 method (ustar format) of storing files with pathnames
that are longer than 100 chars has some limitations:
The name field (100 chars) an inserted slash (‘/’) and the pre-
fix field (155 chars) produce the pathname of the file. When
recreating the original filename, name and prefix are concate-
nated, using a slash character in the middle. If a pathname
does not fit in the space provided or may not be split at a
slash character so that the parts will fit into 100 + 155
chars, the file may not be archived. Linknames longer than 100
chars may not be archived too.
The star, xstar, xustar, exustar, pax, and gnutar archive formats
don’t have these limitations. While gnutar uses a method that makes it
impossible for other tar implementations (except star) to restore
filenames that are longer than 100 chars, the xstar, xustar, exustar
and pax archive format uses a method that allows an POSIX.1-1988 com-
pliant way of storing filenames, if the POSIX method would allow this.
When the archive format is xustar, exustar or pax very long filenames
are stored using extended headers from the POSIX.1-2001 standard.
Some buggy tar implementations will generate incorrect filenames dur-
ing a restore operation if the archive contains pathnames or linknames
of exactly 100 chars length.
Star adds a tar signature in the last four bytes of each tar header if
the archive format is star or xstar. This is no problem with the star
archive format as it is an extension of the old pre POSIX.1-1988 tar
format. On the other side, the xstar archive format claims to be as
POSIX.1-1988 compliant as possible. Inserting this tar signature is a
minor deviation from the standard that has the last 12 bytes of each
header reserved for future use. On the other side, tar implementations
such as some pax implementations that only compute checksums on the
first 500 bytes of the header are violating the standard that requests
the checksum to be computed on all 512 bytes of the tar header. All
tar implementations that are 100% Posix compliant will be able to
extract xstar archives as long as no new standard is defined that
claims the last 12 bytes of the header for a different use. But then
the ustar version number should be changed from ‘00’ to ‘01’. Now,
that the POSIX-2001 standard has been accepted, it is even predictable
that all extensions to the standard tar format will go into the
POSIX.1-2001 extended headers which are extensible to include any fea-
ture without future limitation. The only known tar implementation
that also uses the last 12 bytes of the tar header is Sun’s tar which
uses these 12 bytes for files that are split over several archives.
Such archives created by Sun’s tar are not readable by the buggy pax
implementation too. The Sun extension is not incompatible to the star
signature because Sun expects an octal number at the beginning of the
12 byte field which is a null character in the star case.
Star uses these four bytes since 1985 without problems. If you need a
100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive, you may
use the xustar, exustar or the pax archive format. The probability of
falsely detecting other tar formats as xustar or exustar format how-
ever is higher.
There is no way to ask for the n-th occurrence of a file.
The way EOF is handled by star differs, whether the fifo is in effect
or not. If the fifo is not used, star stops reading the archive if it
encounters a logical EOF record in the archive. If the fifo is used,
star may read until the fifo is full or until the real EOF mark on
tape is reached. How much data star actually reads depends on the
time when the star foreground process sends a fifo shutdown signal to
the background fifo read process.
Gnu tar often creates tar archives with incorrect logical EOF marks.
The standard requires two blocks that are completely zeroed, whereas
gnutar often only adds one of them.
Old versions of tar found on SYSVr3 and earlier cannot read tar
archives with a blocksize greater than 10 kBytes.
The method of storing sparse files currently used with the star and
xstar format is not guaranteed to be used in later versions of star.
If the author decides to change this method, later versions of star
may not be able to restore sparse files from tar archives made by the
current version of star.
Some tar implementations violate the standard in using only the first
500 Bytes of the header for checksum computation. These tar implemen-
tations will not accept star and xstar type tar archives.
Sun’s Solaris 2.x tar implementation violates the Posix standard. Tar
archives generated by star cause Sun’s tar to print tar: impossible
file type messages. You may ignore these messages.
Gnutar’s dumpdirs are non standard and are currently not implemented.
If gnutar archives sparse files with more than four holes, it produces
archives that violate the standard in a way that prevents other tar
implementations to read these archives. Star knows about that and is
able to handle these gnutar archives.
The filetype N (LF_NAMES) from gnutar (an obsolete method of storing
long names) will never be implemented.
Note that on operating systems (like DOS) that do not implement real
pipes, star implements compression via a temporary file. Using com-
pression thus is limited by the maximum file size and the available
disk space.
The extended file flags implementation (see -xfflags option) on Linux
is buggy by design. In order to retrieve the needed information,
every file needs to be opened. If the /dev directory is included in
create mode, every possible driver will be loaded which may hang the
system for a long time. In the worst case, unwanted side effects from
opening devices (such as causing tape drives to rewind the media) may
be caused.
SECURITY NOTES
If you unpack a tar archive in a non empty directory, any file in that
directory may be overwritten unless you specify the -k option. If the
archive contains symbolic links or hard links, star may even overwrite
files outside the current directory. If the directory where the
archive is been unpacked is not empty and contains contains symbolic
links or hard links to directories outside that directory, star may
also overwrite files outside the current directory. As many other
commands, star usually has all possible permissions when run as root.
Unpacking archives as root thus may have fatal results to any file on
your system. Be very careful when you try to extract an archive that
has not been created by you. It is possible to create hand crafted tar
archives that may overwrite critical files (like /etc/passwd) on your
system. In addition all tar archives that have been created with the
list= option and tar archives where the C= option was not specified
before all file type arguments may be critical.
A good advise is to extract all doubtful archives as non root in an
empty directory and to specify the -secure-links option. If you get a
warning, you should unpack the archive a second time and specify the
options -k, -w and -nowarn in addition to the options used for the
first run.
SUID NOTES
If star is installed suid root, star is able to make connections to
remote archives for non root users. This is done by using the rcmd(3)
interface to get a connection to a rmt(1) server.
Star resets its effective uid back to the real user id immediately
after setting up the remote connection to the rmt server and before
opening any other file.
If star has not been installed suid root and not called by root, it
will try to create the remote connection via rsh(1) or ssh(1) (in case
the environment RSH has been set to ssh). Note that in this case, the
throughput to the remote tape server will be much lower than with a
connection that has been initiated via rcmd(3).
LIMITATIONS
If star is running on a large file aware platform, star is able to
handle files up to 8 GB in a mode that is compliant to the
POSIX.1-1988 ustar format. With a nonstandard star specific extension,
up to 95 bits may be used to code the filesize. This will handle
files up to 200,000,000 TB. With the new POSIX.1-2001 extended head-
ers used by the xustar, exustar and pax format, any filesize may be
archived.
BUGS
The fact that the -f option has to be implemented in a way that is
compatible with old tar implementations gives several problems. The
options -fifostats, -force-hole, -force-remove and -fifo interfere
with the -f option and the fact that they exist prevents users from
using filenames like e.g. ifo using the traditional way where the
filename directly follows the string -f without any space between the
option name and the file name. However, there is no problem to use a
file named ifo by by calling -f ifo, f=ifo, -f=ifo or -f= ifo. Be
careful not to make typos with the above options. The result could be
that a file is created as a result of the mistyped option.
There is currently no way to set the fifo lowwater and highwater
marks.
There is currently no way to automatically delete files in the target
file tree if they are obsolete. Star should implement something simi-
lar to gnutar’s dumpdirs.
There is currently no way to automatically delete files in the target
file tree if they are obsolete. Star should implement something simi-
lar to gnutar’s dumpdirs.
If not invoked by the super user star may not be able to extract files
if they reside in read only directories.
Star is not able to make a complete backup of a filesystem if files
are hidden by a mount that is in effect on a directory of this
filesystem. This may be avoided in case of the ufs filesystem if the
backup is made off a ufs snapshot (see the man page for fssnap(1m) It
could be avoided for any filesystem if the loopback filesystem had an
option that tells lofs not to traverse mountpoints.
For now (late 2002), we know that the following programs are broken
and do not implement signal handling correctly:
rsh on SunOS-5.0...SunOS-5.9
ssh from ssh.com
ssh from openssh.org
Sun already did accept a bug report for rsh(1)/ssh(1). Openssh.org
accepted and fixed a bug for their implementation of ssh(1).
If you use star to create a remote connection via an unfixed rsh(1) or
ssh(1), be prepared that terminal generated signals may interrupt the
remote connection.
HISTORY
Star was first created in 1982 to extract tapes on a UNIX clone that
had no tar command. In 1985 the first fully functional version has
been released as mtar.
When the old star format extensions have been introduced in 1985, it
was renamed to star (Schily tar). In 1994, Posix 1003.1-1988 exten-
sions were added and star was renamed to star (Standard tar).
AUTHOR
Joerg Schilling
Seestr. 110
D-13353 Berlin
Germany
Mail bugs and suggestions to:
[email protected] or [email protected] or [email protected]