Content
Dateianzeige für star (3.4.0)
usr/share/doc/star/star.txtSTAR(1) Schily´s USER COMMANDS STAR(1)
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 functionality.
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 information.
FEATURES
Star includes the first free implementation of POSIX.1-2001 extended tar
headers. The POSIX.1-2001 extended tar headers define a new standard way
for going beyond the limitations of the historic tar format. They allow
(among others) to archive all UNIX time stamps in sub-second resolution,
files of arbitrary size and filenames without length limitation using UNI-
CODE 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 pro-
cessed. This gives a convenient interface for archiving and restoring com-
plex 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 inter-
preted as select patterns while the patterns specified with the pat= option
may be used as select or exclude patterns (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 pat-
tern substitution in file names.
Star includes an enhanced function that is similar to the find(1) command
(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 ar-
chive 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 compatible 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 compli-
ant as possible. Enhancements to the standard that prevent correct extrac-
tion of single files when using a different tar implementation 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 missing 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 information 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 performs 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 possible performance. Without
FIFO, the -copy mode will not work.
The list= option, patterns and substitutions apply only to the cre-
ate 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 out-
put than diff -r. If you use star's dump extensions for the tar ar-
chive, the -diff option allows to find even if the directory in the
file tree contains more files than the archive. This way, it is pos-
sible 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 star is reading a tar archive that has been created 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 ar-
chive is an unblocked tape that may backspace.
-x Extract the named files from the tarfile. If no filename argument
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 commands
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 patterns 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 ar-
chive. Tar archives containing absolute pathnames are usually a bad
idea. With other tar implementations, they may possibly 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 con-
taining names with /../ could be used to compromise the system. 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.
-7z run the input or output through a p7zip pipe - see option -z below.
Note that the p7zip program currently does not operate on a pipe but
on a /tmp file copy and thus limits the maximum archive size.
-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 information 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 infor-
mation 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.
Star currently supports the withdrawn POSIX.1e ACLs and NFSv4 ACLs.
To check which ACL flavors are supported on the current platform,
call star -version. Whether POSIX.1e ACLs can be converted into
NFSv4 ACLs depends on the local ACL support library.
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. Path-
names 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 com-
patible enhancement of the old (pre Posix) UNIX tar for-
mat. It has been introduced in 1985 and therefore is not
Posix compliant. The star format allows to archive spe-
cial files (even sockets) and records access time and cre-
ation 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 format.
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' sig-
nature.
gnutar This is a commonly used, but unfortunately not Posix com-
pliant (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 for-
mat unless you want to create an archive for a target sys-
tem that is known to have only the gnutar program avail-
able. 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 gnu-
tar archives. See NOTES for more information.
ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data Interchange
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 for-
mat. This is an upward/downward compatible 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 cre-
ation 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 interfere 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 nei-
ther called as tar nor called as ustar.
xustar A new format introduced 1998, that omits the 'tar\0' sig-
nature at the end of the tar header. It is otherwise iden-
tical 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 implementa-
tions. The main other difference to the xstar format is
that the xustar 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 unlim-
ited, 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 other-
wise 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 unlim-
ited, 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 unlim-
ited, 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 characters and allows to ar-
chive nearly any file type. File size is limited to 8 GB,
uid/gid/st_dev is limited to 262143. The way major and
minor device numbers are stored inside the st_dev field is
implementation 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 pro-
gram.
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 format
that is created with cpio -o -c on SYSVr4 systems. It
uses extended (32 bit) numbers for uid's, gid's and device
numbers but limits the file size to 4 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 its limited portability.
crc This format is similar to the asc cpio format but in addi-
tion uses a simple byte based checksum called CRC. Try to
avoid the crc archive format because of its limited porta-
bility.
All tar archive formats may be interchanged if the archive contains
no files that may not be archived by using the old tar format. Ar-
chives in the xstar format may be extracted by any 100% POSIX com-
pliant 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 modifica-
tion time. (This works only in conjunction 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 com-
ing. 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 begin-
ning 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 sin-
gle 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 possible 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 portability 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
limitation 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 block-
ing factor that is higher than the supposed blocking factor 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 multi-
plied by 1, 2, 512, 1024, 1024*1024, 1024*1024*1024,
1024*1024*1024*1024 or 1024*1024*1024*1024*1024. If the size con-
sists of numbers separated by `x' or `*', multiplication of the two
numbers is performed. 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 blocksizes.
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 stan-
dard, 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 com-
pressed archive that is located inside a plain file as star will
auto detect compression and choose the right decompression option to
extract.
C=dir
-C dir Perform a chdir(2) operation to dir before storing or extracting 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 current work-
ing directory after storing one file argument that immedi-
ately 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 directories from
previous C=dir options and performs a chdir(2) to the corre-
sponding 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 creating
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 sym-
links 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 creating 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 cor-
rectly, you may need to call star twice as star cannot copy files
that appear in the archive later than a symlink pointing to them.
-cpio-statistics
Instead of the star flavor of the statistics, print statistics in
cpio flavor.
-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 com-
mand 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 typi-
cally 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 when in create mode. 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 pub-
lished with the seventh edition of UNIX are not able to deal with
directories in tar archives. If a tar archive is generated without
directories this avoids problems with tar implementations 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 messages
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 initially com-
plete 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.
symperm Compare permissions even in case the target file on the
local filesystem is a symbolic link. By default, star
will not compare the permission of symbolic links as most
systems cannot set the permission of symbolic links. Star
compares symperm only if perm is compared also.
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 system
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 paths
returned by the readlink(2) call.
Two symlinks are considered equal, it they either have a
characterwise identical link-name, or if they either both
use an absolute path name or both use a relative path name
and the following is true: Both symlinks point to the same
file that must exist or both pathnames look similar
enough.
sympath Compare the target pathnames of symlinks. This character-
wise compares the strings returned from 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 format 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 even in case the target file
on the local filesystem is a symbolic link. By default,
star will not compare the modification time of symbolic
links as most systems cannot set the modification 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 verbose level (-vv)
this will print a list of files that are only in the ar-
chive 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 ar-
chive 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 ar-
chive 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 control the
group id of intermediate directories created by star.
dir-owner=user
If star extracts archives as root, this option allows to control 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 guarantees 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. The -dodesc option only works in create mode.
-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 implement 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 sec-
tion 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 pre-
vious dump with lower level. If incremental dumps and restores are
going to be used to synchronize filesystem content, every successive
incremental dump will increase in size if -dump-cumulative is not
used. See section SYNCHRONIZING 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 missing 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, permissions, ...) 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 control 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 ar-
chive or restore run or to tell star to abort on certain error con-
ditions 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 ar-
chive 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 fol-
lowed by a file name pattern (see match(1) or patmatch(3) for more
information). The error control spec uses the same syntax as a sin-
gle 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 possible 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 control 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 condi-
tion, 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 condi-
tion or a list of error conditions (separated by a '|'
character).
WARN If this meta condition is included in an error condi-
tion, 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 condition 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 information.
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 considered 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 considered 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 com-
pletely. 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 prob-
lems.
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 extrac-
tion.
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 condi-
tion. If you ignore the wrong error conditions, you may not be able to see
real problems anymore.
-exclude-from name
Exclude from named file, this is an alias for the -X option. See -X
option for more information.
-F,-FF ...
Fast and simple exclude option for create mode. With one -F argu-
ment, 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 transfer 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 sen-
sitive to typo problems, see BUGS section 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 ar-
chive 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 compatibility
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 cre-
ate a remote tape server connection.
Note that if file=- has been specified, it is no longer possible to
use the -find -exec primary.
-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, otherwise it is omited.
In order to make the evaluation of the find expression more conve-
nient, star implements additional find primaries that have side
effects on the file meta data. Star implements the following addi-
tional 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 permissions
of the file to mode. Octal and symbolic permissions 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 ar-
chive 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.
Note that the -ls, -exec and the -ok primary cannot be used if stdin
or stdout has been redirected by the list=- of by the file=-
options.
-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.
If used together with the -sparse option in create mode, star
assumes all files to be sparse and archives files with blocks of
nulls as sparse files.
This option should be used with extreme care because you sometimes
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 extrac-
tion of a file. All options that start with the -f sequence are
sensitive to typo problems, see BUGS section for more information.
-force-restore
Force an incremental restore even if the incremental dump is only a
partial dump. See -wtardumps, level= and section INCREMENTAL 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 incremental back-
ups. This makes sense when backups are made using file system snap-
shots and allows /etc/tardumps and the archive to contain the real
name of the file system instead of the temporary 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 encountered 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 sym-
link 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 extensions.
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 specified,
star will not exit if a header with a bad checksum is found but
search for the next valid header.
-install
Carefully replace existing files when extracting files. This is done
similar to install(1) by first extracting the files into a temporary
name and renaming the file to the final name after the extraction of
that file was successful.
As star by default does not remove non-empty directories, an install
that needs to remove existing non-empty directories may also need
the options -force-remove and -remove-recursive.
-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 stan-
dard, 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 com-
pressed archive that is located inside a plain file as star will
auto detect compression and choose the right decompression option to
extract.
-keep-nonempty-dirs
Do not complain about trying to remove nonempty directories in case
that -remove-recursive has not been specified.
-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. The dumplevel may be in the range
between 0..99.
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 referring 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 direc-
tory 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 tar-
dumps=name and -wtardumps options and the section INCREMENTAL BACK-
UPS for more information.
-link-data
In create mode, include the data for files even if these files are
hard links. This feature in create mode is currently only available
for the exustar archive format and only in case -sparse has not been
specified.
In extract mode, allow star to deal with data in hard linked files
even if the standard would not allow this for the used archive for-
mat.
-link-dirs
When in create mode, try to find hard linked directories. Using
-link-dirs will force star to keep track of all directories 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 directo-
ries. 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 recom-
mended 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 directories
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/diff command from filename.
The file filename must contain a list of path names, each on a sepa-
rate line. This option implies the -D option. To force star to
descend directories, use the -dodesc option in this case. See also
the -X option.
Note that if list=- has been specified, it is no longer possible to
use the -find -exec primary.
-lowmem
Try to run with reduced memory requirements. This causes star to
default to 1 MB of FIFO memory. Instead of allocating memory 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.
-lzip run the input or output through a lzip pipe - see option -z below.
-lzo run the input or output through a lzop pipe - see option -z below.
-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 multiplied 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 implementa-
tions that are not standard compliant to abort. Star also tries to
make all non POSIX.1-2001 compliant tar implementations 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 vio-
late POSIX but some tar implementations insist in reading such non-
standard 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 log-
ical 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 several logically indepen-
dent tasks. This is true for e.g. incremental dump/restore opera-
tions where inode numbers need to be traced for the whole task.
When tsize=# has been specified, but star is not in multi volume
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 compression); it does not work if the EOT condi-
tion 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-vol-
ume-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 vol-
ume 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. Currently
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 operating sys-
tems with slow file I/O (such as Linux), but includes the risk that
star may not be able to detect extraction problems 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 permissions.
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 pattern=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 pat-
tern 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 -signed-checksum option too. If you want directories not to be
archived in order to be compatible to very old historic tar ar-
chives, 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 cur-
rent 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. Normally,
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. With-
out this option, they are created using the permissions in the ar-
chive 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) implementations. 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. If you only like to extract the directory itself,
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 Pack-
age 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 permis-
sion, 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 pat-
tern 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 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-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 expressions 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 its own
meaning). The following characters are defined:
a Do not preserve file access times. This option is currently
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 currently
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 contains
inode numbers.
-print-artype
Check the type of the archive, print the archive and compression
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 over-
written from tarfile if either newer versions are present in the ar-
chive or if the -U flag is used. This allows to overwrite 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 recursively 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 BACK-
UPS 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 according 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 substi-
tute option has been specified, star will loop over all substitute
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 System V shared memory, you may
have to raise the system's internal limit for shared memory
resources to get enough shared memory 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 con-
taining chars with the most significant bit set may trigger this
problem because all other fields only contain 7 bit ASCII charac-
ters, 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 efficiently. 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 alloca-
tion 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 symlink
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 environment 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 sec-
tion 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 (verbose
create) to get only a list of the pathnames of the files in the ar-
chive. 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. The
value refers to the archive size without compression. 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 speci-
fier ends with a valid multiplication character (e.g '.' for bytes
or 'M' for MB) the specified size is used as specified and not mul-
tiplied 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 -multivol 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 permissions
for intermediate directories that are created by star in extract
mode. See also -p option.
-uncond-rename
When in interactive restore mode or when the -s option was speci-
fied, unconditionally ask for a new name or apply a substitution.
This happens even when the current path name would be skipped other-
wise because the file in the archive is not newer than the file with
the original name on disk.
-v Increment verbose level by one. This normally results in more out-
put during operation. See also in the description for the -t flag.
Normally, star does its work silently. If the verbose level is 2 or
more and star is in create or update mode, star will produce a list-
ing 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 pattern=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 modifi-
cation 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 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 settings. 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 tardumps=name and -C
option or INCREMENTAL BACKUPS section for more information.
-X filename
Use the file filename as a file containing a list of path names to
be excluded from the store/create/list/diff operation. The file
filename must contain a list of path names, each on a separate line.
Be careful with white space and note that path names in the list may
not contain new lines. Multiple -X options may be used. Each argu-
ment must refer to a file containing path names. The -X option has
precedence before other options that select files to be included in
the operation. See also list= option.
-xattr
-xattr-linux
Store and extract extended file attributes as found on Linux sys-
tems. This option only makes sense when creating or extracting
exustar archives as it is based on POSIX.1-2001 extended tar head-
ers.
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.
-xcopy An alias for -copy -sparse -acl
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 ar-
chive are not newer. This is useful when for some reason, 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 direc-
tory permission and time stamp setting, cpio users often create ar-
chives 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 cre-
ated 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 sys-
tems. This option only makes sense when creating or extracting
exustar archives as it is based on POSIX.1-2001 extended tar head-
ers. See NOTES section for problems with -xfflags on Linux systems.
-xmeta Extract meta files as if they were files. Meta files in archives
are plain files that do not contain any content data in the archive.
They may be created by using the -meta option in star's create mode.
Existing files are not overwritten. If a file is missing, a zero
sized file is created. If the option -meta is used together with
the option -force-hole, missing plain files are created as sparse
empty files of the original size.
-xz run the input or output through a xz pipe - see option -z below.
-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 reblocking 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 decompression option to extract. The environ-
ment variable STAR_COMPRESS_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 semantics.
To be more verbose:
· The filesystem needs to uniquely identify files by the two numbers
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 sta-
tus change time. Both time stamps need to be dealt with as docu-
mented by the 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 the inode num-
bers of all files while in incremental restore mode.
Detecting renamed files only works if star, while in backup mode, 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 direc-
tory 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 directory 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 .
Do not forget the dot at the end of the command line that specifies the
directory to start the operation.
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 command
then creates a level 0 backup from the file system using the time the snap-
shot was created and the original mount point of the file system for
/etc/tardumps and the archive header.
Note that if the backup is done on a live file system, it may be unreli-
able. 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 control 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 intervals. 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 10 dumps made between Monday and Friday accumulate all changes
made within the week. If you don't like this, use the following 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 (just before 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 10 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 incremental 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 filesystem
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 snap-
shots, copies should be made from a read-only mount of a snapshot. Be care-
ful 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 handles 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 cur-
rent operation. This is useful to watch the progress of the cur-
rent 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 compli-
ant 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 directory
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 com-
mand 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@remote-
host:/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 differ-
ences 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 permission
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 tempo-
rary files from ./star-tmpdir. The files in this directory 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/std-
out 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) program
and disallows star to directly access the network socket to the
remote server. This makes it impossible to set up performance
parameters and slows down the connection compared to a root initi-
ated 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=
archive1=
archive2=
archive3=
archive4=
archive5=
archive6=
archive7=
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 specified. 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 fol-
lowed by a TAB and one or more spaces, followed by the decimal 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 repre-
sentation 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 representation
is for informational use by humans only and not evaluated 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 operation.
./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 running 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), fss-
nap(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 bool-
ean 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 docu-
mented 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 characters ( rxtuc vxf-
blmo ) 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 prefix
field (155 chars) produce the pathname of the file. When recreating
the original filename, name and prefix are concatenated, 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 compliant way of storing file-
names, if the POSIX method would allow this. When the archive format is
xustar, exustar or pax very long filenames are stored using extended head-
ers from the POSIX.1-2001 standard.
Some buggy tar implementations will generate incorrect filenames during 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 com-
pliant 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 implementa-
tions 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 com-
pliant 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 feature
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 charac-
ter 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 however 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 encoun-
ters 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 fore-
ground 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 implementations
will not accept star and xstar type tar archives.
Sun's Solaris 2.x tar implementation violates the Posix standard. Tar ar-
chives 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 ar-
chives that violate the standard in a way that prevents other tar implemen-
tations to read these archives. Star knows about that and is able to han-
dle 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 compression 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 ar-
chive 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 possi-
ble 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 cre-
ate 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 envi-
ronment 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 for-
mat. 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 headers 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 compati-
ble 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 fol-
lows 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 similar to gnu-
tar'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 extensions were
added and star was renamed to star (Standard tar).
AUTHOR
Joerg Schilling
Seestr. 110
D-13353 Berlin
Germany
Mail bugs and suggestions to:
schilling@fokus.fraunhofer.de or js@cs.tu-berlin.de or
joerg@schily.isdn.cs.tu-berlin.de
Joerg Schilling 13/11/08 STAR(1)