From Linux Man Pages
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 modi-
fied 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 UNICODE UTF-8 coding for best exchange compatibility.
Star by default uses a fifo to optimize data flow from/to tape. This results in a normally streaming tape during
the whole backup. See -fifo and fs= option to get information on how to find the best fifo size.
Star includes a pattern matcher to control the list of files to be processed. This gives a convenient interface
for archiving and restoring complex lists of files. In conjunction with the -w flag it is easy to merge a tar
archive into an existing file tree. See also -U option. In create mode use the pat= option to specify either
select or exclude patterns (depending on the -V flag). In extract or list mode all file type arguments are inter-
preted as select patterns while the patterns specified with the pat= option may be used as select or exclude pat-
terns (depending on the -V flag). Have a look at the description of the -C option to learn how to fetch files
from a list of directories (in create mode) or to distribute files to a list of directories (in extract mode). A
substitute option allows ed(1) like pattern 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 ver-
sions and 4095 bytes with POSIX.1-2001) may be archived. Later versions may be able to deal with longer path-
names.
Star deals with all 3 times, available for files on UNIX systems if the archive format is either chosen from the
star specific formats or is a format that uses POSIX.1-2001 extended headers. This is either done in second res-
olution 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 compliant as possible. Enhancements to the
standard that prevent correct extraction 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 compati-
bility 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 create side of the copy command.
-diff Compare the content and the attributes of the files from the archive in tarfile to the filesystem. This
may also be used to compare two file trees in the filesystem. If you use a set of diffopts that fits your
needs, it will give - in many cases - a more readable output than diff -r. If you use star's dump exten-
sions for the tar archive, the -diff option allows to find even if the directory in the file tree contains
more files than the archive. This way, it is possible to compare all properties of two file trees in one
run. See diffopts for more details. Adding one or more -v options increases the verbosity. With -vv and
above, the directory content is compared also if in -dump mode.
-n No extraction. Show what star would do, in case the -x command had been specified.
-r Replace files in a tarfile. The named files are written to the end of tarfile. This implies that later,
the appropriate files will be found more than once on the tarfile.
-t Table of contents. List the contents of the tarfile. If the -v flag is used, the listing is similar to
the format of ls -l output. With this option, the flags -a, -atime and -ctime have a different meaning if
the archive is in star, xstar, xustar, exustar, or pax format. The option -a or -atime lists the access
time instead of the modification time, the option -ctime lists the file creation time instead of the modi-
fication time. The option -tpath may be used in addition to modify the output so it may be used in shell
scripts.
-u Update a tarfile. The named files are written to the end of tarfile if they are not already there or if
the files are newer than the files of the same name found in the archive. The -r and -u command only work
if the tar archives is a regular file or if the tar archive is an unblocked tape that may backspace.
-x Extract the named files from the tarfile. If no filename 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 archive. 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 containing 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.
-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 information at all and files may inherit ACL information from the parent directories. If the
-acl option has been specified, star assumes that the -p option has been specified too.
artype=headertype
Generate a tape archive in headertype format. If this option is used in extract/list mode this forces
star to interpret the headers to be of type headertype. As star even in case of a user selected extract
archive format does format checking, it may be that you will not be able to unpack a specific archive with
all possible forced archive formats. Selecting the old tar format for extraction will always work though.
Valid parameter for headertype are:
help Print a help message about possible header types.
v7tar Old UNIX V7 tar format. This archive format may only store plain files. Pathnames or linknames
longer than 99 chars may not be archived.
If the v7tar format has been selected, star will not use enhancements to the historic UNIX V7
tar format. File size is limited to 2 GB - 2 bytes, uid/gid is limited to 262143. Sparse files
will be filled up with zeroes.
tar Old BSD UNIX tar format. This archive format may only store plain files, directories and sym-
bolic links. Pathnames or linknames longer than 99 chars may not be archived. See also the -d
option as a note to some even older tar implementations.
If the tar format has been selected, star will not use enhancements to the historic tar format.
File size is limited to 2 GB - 2 bytes, uid/gid is limited to 262143. Sparse files will be
filled up with zeroes.
star Old star standard format. This is an upward/downward compatible enhancement of the old (pre
Posix) UNIX tar format. It has been introduced in 1985 and therefore is not Posix compliant.
The star format allows to archive special files (even sockets) and records access time and 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 inter-
fere with the POSIX tar formats. The last 4 bytes of the tar header contain a 'tar\0' signa-
ture.
gnutar This is a commonly used, but unfortunately not Posix compliant (although designed after 1987)
enhancement to the old tar format. The gnutar format has been defined between 1989 and 1994.
Do not use the gnutar archive format unless you want to create an archive for a target system
that is known to have only the gnutar program available. The gnutar archive format violates
basic rules for any (even the historic) tar archive format, in special when sparse files are
archived using the -sparse option. Using the gnutar archive format causes a high risk that the
resulting archive may only be read by gnutar or by star. The implementation of the gnutar
archive format within star is not complete, but sufficient for most gnutar archives. See NOTES
for more information.
ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data 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 for-
mat, the archive will be strictly conforming. File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is limited to 2097151. Sparse files will be filled up with zeroes.
xstar The extended standard tar format has been introduced in 1994. Star uses the xstar format as
default archive format. This is an upward/downward 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 creation time. Sparse files
will be archived correctly (if -sparse is used).
The access time and creation time are stored at the end of the POSIX file name prefix (this lim-
its 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 neither called as tar nor called as ustar.
xustar A new format introduced 1998, that omits the 'tar\0' signature at the end of the tar header. It
is otherwise identical to the xstar format. As some tar implementations do not follow the POSIX
rules and compute the checksum for less than 512 bytes of the tar header, this format may help
to avoid problems with these broken tar implementations. The main other difference to the xstar
format is that the 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 unlimited, major/minor is unlimited. Sparse
files will be archived correctly (if -sparse is used).
exustar A format similar to the xustar format but with forced POSIX.1-2001 extended headers. If this
format is used together with the -acl option, star records Access Control Lists (ACLs) in
POSIX.1-2001 extended headers.
The exustar format allows to archive all file types but it does not archive more than the
POSIX.1-1988 set by default. If the -dump option is used or if star is otherwise on dump mode,
star archives all file types and in addition archives more meta data then usual.
File size is unlimited, uid/gid/uname/gidname is unlimited, major/minor is unlimited. Sparse
files will be archived correctly (if -sparse is used).
suntar The extended header format found on Solaris 7/8/9. This format is similar to the pax format but
does not handle atime and ctime and in addition uses 'X' as the typeflag for the extended head-
ers instead of the standard 'x'.
File size is unlimited, uid/gid/uname/gidname is unlimited, major/minor is unlimited. Sparse
files will be filled up with zeroes.
bin The cpio UNIX V7 binary format. This is a format with big interoperability problems. Try to
avoid this format. It is only present to make the scpio command SVr4 compliant.
cpio The POSIX.1-1988 cpio format. This format uses octal ascii headers. A similar format is created
by calling cpio -o -c on pre SYSVr4 systems and by calling cpio -o -Hodc on SYSVr4 systems. The
POSIX.1-1988 cpio format allows a file name length up to 262142 characters and allows to archive
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 depen-
dent.
Even though this archive format is covered by the POSIX.1-1988 standard, it has a lower porta-
bility than the ustar format. Try to avoid the cpio archive format.
odc This archive format is similar to the The POSIX.1-1988 cpio format but the file name length is
limited to 255 characters and the socket file type is not allowed. This archive format has been
introduced to allow non POSIX cpio implementations such as the cpio program on SYSV to accept
the archive. Use this format whenever you are not sure if the target system offers a fully POSIX
compliant cpio program.
Even though this archive format is covered by the POSIX.1-1988 standard, it has a lower porta-
bility 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 2 GB - 2 bytes although the format has been specified after the POSIX.1-1988 cpio
format. Try to avoid the asc archive format because of it's limited portability.
crc This format is similar to the asc cpio format but in addition uses a simple byte based checksum
called CRC. Try to avoid the crc archive format because of it's limited portability.
All tar archive formats may be interchanged if the archive contains no files that may not be archived by
using the old tar format. Archives in the xstar format may be extracted by any 100% POSIX compliant tar
implementation if they contain no files with pathnames > 100+130 chars and if they contain no sparse files
that have been archived by using the -sparse option.
-ask_remove
obsoleted by -ask-remove
-ask-remove
Ask to remove non writable files on extraction. By default, star will not overwrite files that are read
only. If this option is in effect, star will ask whether it should remove these files to allow the
extraction of a file in the following way:
remove 'filename ?' Y(es)/N(o) :
-atime, -a
Reset access time of files after storing them to tarfile. On Solaris 2.x, (if invoked by root) star uses
the _FIOSATIME ioctl to do this. This enables star not to trash the ctime while resetting the atime of the
files. If the -atime option is used in conjunction with the list command, star lists access time instead
of modification time. (This works only in 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 coming. If
star uses stdin as archive file, star behaves as if it has been called with the -B option. For this rea-
son, the option -B in practice is rarely needed.
-block-number
Print the archive block number (archive offset / 512) at the beginning of each line when in verbose mode.
This allows to write backup scripts that archive the offsets for files and that use
mt fsr blockno
to skip to the tape block number of interest in a fast way if a single file needs to be restored.
blocks=#, b=#
Set the blocking factor of the tarfile to # times 512 bytes (unless a different multiplication factor has
been specified - see bs= option for posible multiplication factors). Changing the blocking factor only
makes sense when the archive is located on a real tape device or when the archive is accessed via the
remote tape protocol (see f= option below). The default is to use a blocking factor of 20 i.e.
10 kBytes. Increasing the blocksize will speed up the backup. For portability with very old tar imple-
mentations (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 suffi-
cient speed and seems to be a good choice. Star allows block sizes up to 2 GByte if the system does not
impose a smaller limit. If you want to determine the blocking factor when reading an unknown tar archive
on tape, specify a blocking factor that is higher than the supposed blocking 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 multiplied by 1, 2, 512, 1024, 1024*1024,
1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024. If the size consists of numbers sepa-
rated by `x' or `*', multiplication of the two numbers is performed. Thus bs=7x8k will specify a block-
size 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 argu-
ment.
-bz run the input or output through a bzip2 pipe - see option -z -Z and -j below. As the -bz the -j the -Z
and the -z option are non standard, it makes sense to omit the -bz the -j the -Z and the -z options inside
shell scripts if you are going to extract a compressed archive that is located inside a plain file as star
will auto detect compression and choose the right 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 argu-
ments. While a BSD derived tar(1) implementation goes back to the current working directory after
storing one file argument that immediately follows the -C option, star changes the directory only
if a new -C option follows. To emulate the behavior of a BSD derived tar(1), add a -C . option
after the file argument.
� In extract mode (with the -x, -n and -diff flag), star builds a pattern list together with corre-
sponding directories from previous C=dir options and performs a chdir(2) to the corresponding
directory of a matching pattern. All pat= options that do not follow a C=dir option are inter-
preted 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 experi-
mental 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 symlinks
correctly, you may need to call star twice as star cannot copy files that appear in the archive later than
a symlink pointing to them.
-copysymlinks
This option allows to copy symlinked targets rather than 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 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.
-ctime If used with the list command, this lists ctime rather than mtime if the archive format is star, xstar,
xustar, exustar, or pax.
If star is run as root and if -ctime is used with the extract command and the same archive formats, this
causes star to try to restore even the ctime of a file by generating time storms. You should not do this
when in multi user mode because this may confuse programs like cron and the news system. Although star
tries to eliminate the accumulative effects of the time storm, there is a tendency for the system clock to
slow down a bit. The clock typically lags about one millisecond per extracted file. Use with care and
check the system clock after using this feature.
If used with the create command this changes the behavior of the newer= option. Star, in this case com-
pares the ctime of all files to the mtime of the stamp file rather then comparing the mtimes of both
files.
-cumulative
A shorthand for -dump-cumulative. See -dump-cumulative for more information.
-D Do not descend directories. Normally, star descends the whole tree if it encounters a directory in in its
file parameters. The option -D is in effect by default if the list=file option is used. If you like star
to descend directories found in the list file, use the -dodesc option (see below).
-d Do not store/create directories. Old versions of tar such as published with the seventh edition of UNIX
are not able to deal with directories in tar archives. If a tar archive is 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 oth-
erwise 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 complete set compare list. When using csh(1) you might have problems to use ! due to
its strange parser. This is why the not alias exists.
perm Compare file permissions. With this option in effect, star compares the low order 12 bits of the
st_mode field.
mode Same as perm.
type Compare file type. Note that star cannot compare the file type in case of a hard link.
nlink Compare link count on hardlinks. This only works if the archive is in exustar format and con-
tains 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 value returned by the readlink(2) call.
sparse Compare if either both files are sparse or not. If only one of both files is sparse, then a dif-
ference 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 of symbolic links. By default, star will not compare the modifi-
cation 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 archive and a list of files that are only on the current
filesystem.
xtimes Shorthand for: atime,mtime,ctime,lmtime.
acl Compare access control lists. This only works if the archive is in exustar format and has been
created with star's -acl option. You need to specify the -acl option in addition when running
the diff.
xattr Compare extended file attributes. This only works if the archive is in exustar format and has
been created with star's -xattr option. You need to specify the -xattr option in addition when
running the diff.
fflags Compare extended file flags. This only works if the archive is in exustar format and has been
created with star's -xfflags option. You need to specify the -xfflags option in addition when
running the diff.
If optlst starts with a ! the meaning of all members in optlst is inverted as with the not optlist member.
In this case, star starts with a complete list that includes atime and lmtime. Reasonable diff options to
use when comparing against a copy of a directory tree are diffopts=!atime,ctime,lmtime.
If diffopts are not specified, star compares everything but the access time of the files and the modifica-
tion 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.
-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 previous
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 archive or restore run or to tell star to abort on certain error condi-
tions instead of trying to continue with the archive.
A typical reason to use error control is to suppress warnings about growing log files while doing a backup
on a live file system. Another typical reason to use error control is to tell star to abort if e.g. a
file could not be archived instead of continuing to archive other files from a list.
The error control file contains a set of lines, each starting with a list of error conditions to be
ignored followed by white space followed by a file name pattern (see match(1) or patmatch(3) for more
information). The error control spec uses the same syntax as a single line from the error control file.
If the file name pattern needs to start with white space, use a backslash to escape the start of the file
name. It is not possible to have new line characters in the file name pattern. Whenever an error situa-
tion is encountered, star checks the lines in the error control file starting from the top. If the cur-
rent 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 condition, star aborts (exits) as soon as pos-
sible after this error condition has been seen instead of making star quiet about the condi-
tion. This error condition flag may only be used together with at another error condition or
a list of error conditions (separated by a '|' character).
WARN If this meta condition is included in an error condition, 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 con-
dition flag may only be used together with at another error condition or a list of error con-
ditions (separated by a '|' character). The WARN meta contition has a lower precedence than
ABORT.
DIFF Suppress output in case that star -diff did encounter any differences.
ALL This is a shortcut for all error conditions below.
STAT Suppress warnings that star could not stat(2) a file.
GETACL Suppress warnings about files on which star had problems to retrieve the ACL information.
OPEN Suppress warnings about files that could not be opened.
READ Suppress warnings read errors on files.
WRITE Suppress warnings write errors on files.
READLINK Suppress warnings readlink(2) errors on symbolic links.
GROW Suppress warnings about files that did grow while they have been archived.
SHRINK Suppress warnings about files that did shrink while they have been archived.
MISSLINK Suppress warnings about files for which star was unable to archive all hard links.
NAMETOOLONG Suppress warnings about files that could not be archived because the name of the file is too
long for the archive format.
FILETOOBIG Suppress warnings about files that could not be archived because the size of the file is too
big for the archive format.
SPECIALFILE Suppress warnings about files that could not be archived because the file type is not sup-
ported 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 extrac-
tion.
SETMODE Suppress warnings about files on that star could not set the access modes during extraction.
SECURITY Suppress warnings about files that have been skipped on extraction because they have been con-
sidered to be a security risk. This currently applies to all files that have a '/../'
sequence inside when -.. has not been specified.
LSECURITY Suppress warnings about links that have been skipped on extraction because they have been con-
sidered to be a security risk. This currently applies to all link names that start with '/'
or have a '/../' sequence inside when -secure-links has been specified. In this case, star
tries to match the link name against the pattern in the error control file.
SAMEFILE Suppress warnings about links that have been skipped on extraction because source and target
of the link are pointing to the same file. If star would not skip these files, it would end
up with removing the file completely. In this case, star tries to match the link name against
the pattern in the error control file.
BADACL Suppress warnings access control list conversion problems.
SETACL Suppress warnings about files on that star could not set the ACL information during extrac-
tion.
SETXATTR Suppress warnings about files on that star could not set the extended file attribute informa-
tion during extraction.
If a specific error condition is ignored, then the error condition is not only handled in a silent way but also
excluded from the error statistics that are printed at the end of the star run.
Be very careful when using error control as you may ignore any error condition. If you ignore the wrong error
conditions, you may not be able to see real problems anymore.
-F,-FF ...
Fast and simple exclude option for create mode. With one -F argument, star ignores all directories called
SCCS and RCS. With two -F arguments, star in addition ignores all files called core errs a.out all files
ending with .o. OBJ/. With three -F arguments, star ignores all sub trees starting from a directory that
includes a file .mirror or .exclude and all object files and files called core errs a.out all files ending
with .o. With four -F arguments, star ignores all sub trees starting from a directory that includes a
file .mirror or .exclude the latter files are excluded too as well as and all object files and files
called core errs a.out all files ending with .o. With five -F arguments, star in addition again excludes
all directories called SCCS and RCS.
-fifo Use a fifo to optimize data flow from/to tarfile. This option is in effect by default (it may be changed
at compile time). The default fifo size is 8 MBytes on all platforms except Linux versions that do not
support mmap() (4 MB because kernels before 2.4 did not handle big shared memory areas) and Sun/mc68000 (1
MB). This will star make even work on a tiny machine like a Sun 3/50. The fifo size may be modified with
the fs= option. A rule of dumb for the fifo size is to use more than the buffer size of the tape drive and
less then half of the real memory of the machine. A good choice would be to use a fifo size between 8 and
256 MB. This may increase backup speed up to 5% compared to the speed achieved with the default fifo
size. Note that with a DLT drive that gives 12MB/s 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 sensitive 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. Specify-
ing 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 privi-
leges. After this connection has been established as root, star switches back to the id of the caller.
If any of the other archives in the list is located on a different host, star will not be able to open
this archive later on, unless run by root.
Star normally uses stdin/stdout for the tar archive because the most common way to use star is in conjunc-
tion 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 plat-
form 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 create 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 convenient, star implements additional find
primaries that have side effects on the file meta data. Star implements the following additional find
primaries:
-chgrp gname
The primary always evaluates as true; it sets the group of the file to gname.
-chmod mode
The primary always evaluates as true; it sets the permissions of the file to mode. Octal and sym-
bolic 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 differ-
ent from the result of a part of the expression.
-true The primary always evaluates as true; it allows to make the result of the full expression different
from the result of a part of the expression.
The command line:
star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d
lists all directories and archives all non-directories to the archive o.tar.
The command line:
star -c f=o.tar -find . ( -type d -chown root -o true )
archives all directories so they appear to be owned by root in the archive, all non-directories are
archived as they are in the file system.
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. 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 extraction 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 backups. This makes sense when backups are made using file system snapshots
and allows /etc/tardumps and the archive to contain the real name of the file system instead of the tempo-
rary 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 symlink is
encountered in the file system.
-hpdev Allow 24 bits for the minor device number using 8 octal digits. Note that although it allows to create
tar archives that can be read with HP-UX tar, this creates tar archives which violate POSIX.1-1988. This
option is only needed if you like to use a POSIX.1-1988 based archive format that does not include exten-
sions. If you use the xstar format, star will use a base 256 extension that allows bigger major/minor
numbers by default, if you use the xustar or the exustar format there is no limitation at all as these
formats use POSIX.1-2001 extended headers to archive the major/minor numbers by default.
-i Ignore checksum errors on tar headers. If this option is specified, star will not exit if a header with a
bad checksum is found but search for the next valid header.
-j run the input or output through a bzip2 pipe - see option -z -Z and -bz below. As the -bz the -j the -Z
and the -z option are non standard, it makes sense to omit the -bz the -j the -Z and the -z options inside
shell scripts if you are going to extract a compressed archive that is located inside a plain file as star
will auto detect compression and choose the right decompression option to extract.
-keep_old_files
obsoleted by -keep-old-files
-keep-old-files, -k
Keep existing files rather than restoring them from tarfile. This saves files from being clobbered even
if tarfile contains a more recent version of the corresponding file.
See SECURITY NOTES for more information.
-L, -h Follow symbolic links as if they were files. Normally star will not follow symbolic links but stores
their values in tarfile. See also the -h option.
-l Do not print a warning message if not all links to hard linked files could be dumped. This option is eval-
uated in the opposite way to historic tar(1) implementations and to POSIX.1. POSIX.1 requests that by
default no warning messages will be printed and -l will enable warning messages when not all links could
be archived.
level=dumplevel
Set level for incremental dumps. This option is used to switch star into true incremental dump mode.
In true incremental dump mode, a -C option which is followed by the name a mount point and a dot ('.') as
starting directory name is required. Only a single file system may be handled at a time. If the direc-
tory 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 directory of a file system
and no other restrictions apply that exclude certain files from the dump, the dump is called a full dump.
By default, the tardumps database is not written. See also the tardumps=name and -wtardumps options and
the section INCREMENTAL BACKUPS for more information.
-link-dirs
When in create mode, try to find hard linked directories. Using -link-dirs will force star to keep track
of all 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 directories. Also note that even though a non-
root user is able detect and archive hard linked directories, all known operating systems require the
extraction to be done as root in order to be able to create or remove hard links to directories. For this
reason its only recommended to use this option when doing accurate backups and when hard links to directo-
ries 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 direc-
tory hard links inside the sub-tree.
list=filename
Read filenames for store/create/list command from filename. The file filename must contain a list of
filenames, each on a separate line. This option implies the -D option. To force star to descend directo-
ries, use the -dodesc option in this case.
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.
-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 implementations that are
not standard compliant to abort. Star also tries to make all non POSIX.1-2001 compliant tar implementa-
tions 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 back-
ups, 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 cre-
ate tar archives that violate POSIX but some tar implementations insist in reading such nonstandard
archives.
-multivol
Switch to multi volume mode. In multi volume mode, there will be no logical EOF marker written to the end
of a single tape. If -multivol is used in read mode, a hard EOF on input (if not preceded by a logical
EOF) triggers a medium change operation.
Specifying -multivol tells star to split files across volumes if needed. This way, a virtual archive is
created that spans more than one medium. Multi volume mode is needed whenever it is not possible to split
the archiving or extracting into several logically independent tasks. This is true for e.g. incremental
dump/restore operations where inode numbers need to be traced for the whole task.
When tsize=# has been specified, but star is not in multi volume mode, files cannot be split across vol-
umes.
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 condition is not returned in sync with the related write opera-
tion. 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 envi-
ronments. 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 file-
name. See -ctime option for changing this behavior.
-newest
In conjunction with the list command this lists you only the newest file in tarfile.
-newest_file
obsoleted by -newest-file
-newest-file
In conjunction with the list command this lists you only the newest regular file in tarfile.
new-volume-script=script
Call script at end of each tape if in multi volume mode. If this option is not in effect, star will ask
the user to confirm the volume change. The script is called with two parameters. The first parameter is
the next volume number and the second parameter is the next archive file name.
-nodump
If this option is set, star will not dump files that have the nodump flag set. Note that this currently
only works on BSD-4.4 derivates and on Linux. On Linux, using this option will cause a performance degra-
dation (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 systems 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 over-
write 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 pattern or file operands.
-nowarn
Do not print warning messages. This sometimes is useful to make the output more readable (e.g. when hun-
dreds of files that are going to be extracted are not newer in the archive then on the filesystem).
-numeric
Use the numeric user/group fields in the listing rather than the default. The default allows to list the
ASCII version of user/group of the file and to extract the owners of the files based on numeric values
rather than the names. In create mode, no user/groups names are put on the archive. The -numeric option
also applies when ACLs are going to be archived or extracted.
-O Be compatible to old versions of tar. If star is invoked with this option, star generates archives which
are fully compatible with old UNIX tar archives. If in extract mode, star ignores any additional info in
the headers. This implies neither that archives generated with this option are binary equal with archives
generated by old tar versions nor that star is trying to comprehend all bugs that are found in old tar
versions. The bug in old tar versions that cause a reversal of a space and a NULL byte in the checksum
field is not repeated. If you want to have signed checksums you have to specify the -singed-checksum
option too. If you want directories not to be archived in order to be compatible to very old historic tar
archives, you need to specify the -d option too.
This option is superseeded by the H=headertype option.
-o, -nochown
Do not restore owner and group of files. This may be used if super user privileges are needed to over-
write existing files but the local ownership of the existing files should not change.
-onull, -nullout
Do not actually write to the archive but compute and add the sizes. This is useful when trying to figure
out if a tape may hold the current backup. Please only use the -onull option as it is a similar option as
used by the sdd(1) command.
-P Allow star to write a partial record as the last record. 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. Without this option, they are created using
the permissions in the archive and the present umask(2). If star is called by the super user, star
behaves as if it has been called with the -p option. See also -no-p option. If the archive contains
Access Control Lists (ACLs) in POSIX.1-2001 extended headers, star will restore the access control lists
from the archive for files if the -acl option is specified. If the option -acl has not been specified,
ACLs are not restored at all.
pattern=pattern, pat=pattern
Set matching pattern to pattern. A maximum of 100 pattern=pat options may be specified. As each pattern
is unlimited in length, this is no real limitation. If more than one pattern is specified, a file matches
if any of the specified pattern matches. Patterns may be used in create mode to select or exclude files
from the list of file type arguments or the files located in a sub tree of a file type argument directory.
By default, star scans the whole directory tree underneath a directory that is in the argument list. This
may be modified by using the -match-tree option. In extract or list mode, all file type arguments are
interpreted to be select pattern and all option type patterns may be either select or exclude patterns
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 pat-
terns do not offer pattern matching but allow to restore subtrees. To extract a complete sub tree from
the directory dir with star using the pattern= option, use pattern= dir/\* if you like to select a subtree
by using the historic method, use dir/ as file type argument. See manual page for match(1) for more
details of the pattern matcher. All patterns are selection patterns by default. To make them exclude pat-
terns, use the -not or the -V option.
pkglist=file
This is (for now) an internal interface for the Schily Source Package System (sps). It only works in cre-
ate mode and behaves similar to the list= option, but it allows to overwrite the permissions, the uid and
gid values from the content of the pkglist= file. Each line from the pkglist= file contains a file name
followed by the permission, a user name and a group name. The permission is an octal character string.
Each value that is not used to overwrite the original values may be replaced by a '?'. The fields are
separated by spaces, so the pkglist= option does not allow files that contain newline or space characters.
-pax-c, -notarg
Match all file or archive members except those specified by the pattern or file operands.
-pax-H Follow symbolic links that have been encountered on the command line. If the referenced file does not
exist, the file 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 file-
name 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 environ-
ments.
-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 it's 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 nubers.
-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 overwritten from tarfile if either newer ver-
sions are present in the archive 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 BACKUPS for more information.
Note: Do not use the -restore option if you only like to restore a single file or a list of selected
files.
-S Do not store/create special files. A special files is any file except plain files, symbolic links and
directories. You need to be super user to extract special files.
-s replstr
Modify file or archive member names named by a pattern 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 substitute 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 compro-
mise 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 sys-
tem'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 containing
chars with the most significant bit set may trigger this problem because all other fields only contain 7
bit ASCII characters, octal digits or binary zeroes.
-silent
Suppress informational messages like foobar is sparse.
-sparse
Handle files with holes effectively on store/create. Note that sparse files may not be archived this way
if the archive format is tar, ustar, suntar, pax, or any cpio variant. On Solaris-2.3 ... Solaris-2.5.1
there is a special ioctl() called _FIOAI that allows root to get the allocation info more 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 allocation
list and force star to scan the files to look for blocks that only contain null characters. This may star
cause to assume more holes to be present than the number that the file really contains.
-symlinks
This option tells star in extract mode to try to create a 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 combi-
nation with the level= option to create true incremental dumps. See also -wtardumps option and section
INCREMENTAL BACKUPS for more information.
-time Print timing info. See DIAGNOSTICS for more information.
-to_stdout
obsoleted by -to-stdout
-to-stdout
Extract files to stdout. This option may be used to extract tarfiles containing tarfiles (see examples
below).
-tpath Use this option together with the -t option or with -cv (verbose create) to get only a list of the path-
names of the files in the archive. This may be used in shell scripts to generate a name list. If used
together with the -diff option, star will only print the names of the files that differ. A second run of
star may then be used to restore all files that had differences to the archive. Use the list= option to
specify the namelist in this case.
tsize=#
Set tape volume size to # to enable multi volume tape support. See bs= for the possible syntax. By
default, the number is multiplied by 512, so the value counts in units of 512 byte blocks. If the size
specifier ends with a valid multiplication character (e.g '.' for bytes or 'M' for MB) the specified size
is used as specified and not multiplied by 512. With this option in effect, star is able to archive
filesystems that are bigger then the tape size. If the option tsize=# without -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 correspond-
ing 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.
-v Increment verbose level by one. This normally results in more output during operation. See also in the
description for the -t flag. Normally, star does its work silently. If the verbose level is 2 or more
and star is in create or update mode, star will produce a listing to the format of the ls -l output.
-V, -not
Invert the meaning of the pattern list. i.e. use those files which do not match any of the pattern. Note
that this option only applies to patterns that have been specified via the 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 modification time in the tar archive (if in extract mode and the -U option is not
specified) star prints its name and asks:
get/put ? Y(es)/N(o)/C(hange name) :
You may answer either `N' for No or <Return> to skip this file. If you answer `Y' the file is extracted
or archived on tape with its original name. If you answer `C', you are prompted for a new name. This name
is used for the filename on disk if star is in extract mode or for the archive name if star is in create
mode.
See SECURITY NOTES for more information.
Note that -w is an interactive option that prevents star from being used in non-interactive environments.
-wready
This option tells Star to wait up to two minutes for the drive to become ready. It has been added as a
hack for a bug in the SunOS/Solaris st device driver. This driver has problems to sense the loading time
with Exabyte drives with factory 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.
-xattr
-xattr-linux
Store and extract extended file attributes as found on Linux systems. This option only makes sense when
creating or extracting exustar archives as it is based on POSIX.1-2001 extended tar headers.
The method used in the current implementation could be used to store and extract extended file attributes
from BSD too. Note that the current implementation is not generic enough to cover more general extended
file attribute implementations as found on Solaris. If star starts to implement a method that covers
extended file attributes on Solaris, the new method will be used then -xattr has been specified and
-xattr-linux will refer to the old method. The method used with -xattr-linux may go away in the future.
xdebug=#, xd=#
Set extended debug level to #.
-xdev, -M
Do not descend mount points. This is useful when doing backups of complete file systems. See NOTES for
more information.
-xdir Extract directories even if the corresponding directories on the archive are not newer. This is useful
when for some 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 directory permission and time stamp setting, cpio users often create archives in reverse
order (directories past their content). For this reason, it makes sense to use -xdir while extracting cpio
archives.
-xdot Unconditionally extract the first directory in the archive if the name of this directory is either '.' or
'./'. This helps to extract archives in an expected way if the target directory is a newly created empty
directory. As this directory is newer than the top level directory in the archive, star would usually skip
this directory during extraction. The effect of this directory is as if -xdir has been specified but is
switched off after the first directory has been found.
-xfflags
Store and extract extended file flags as found on BSD and Linux systems. This option only makes sense
when creating or extracting exustar archives as it is based on POSIX.1-2001 extended tar headers. See
NOTES section for problems with -xfflags on Linux systems.
-Z run the input or output through a compress pipe - see option -z below.
-z run the input or output through a gzip pipe. This is currently a quick and dirty hack, that mainly will
cover the most common usage to compress the tar output if it is a file. No 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 environment variable STAR_COM-
PRESS_FLAG may be used to specify one option for gzip. If you want to write write compressed archives to
tape, you should use
star -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
or
star -c . | gzip | sdd ibs=4k obs=32k -fill ovsize=60m of=/dev/rmt/1bn
if the tape can hold 60 MB.
INCREMENTAL BACKUPS
Star is able to back up file system in full and incremental mode. To allow incremental backups, the file system
must implement POSIX 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 status change time. Both time stamps need to be dealt with as documented by te
POSIX standard. Both numbers need to be a cardinal scalar that is expressible in a decimal number.
� The filesystem needs to allow to rename files and directories by either calling rename(2), or link(2) and
unlink(2).
� The filesystem needs to honor and preserve the case of file names.
The incremental backup method used by star depends on comparing the time stamps of all files against the time of
the last backup. Note that this method only works correctly if the level 0 backup and all higher level incremen-
tals include the whole file system. As star archives all inode meta data, star is able to detect renamed files
by comparing inode numbers.
Detecting renamed files only works if star scans the whole file system tree for each full and incremental backup.
This will work in case no files are excluded and the dump starts at the root directory of a file system. In case
that no files are renamed from excluded parts to included parts, partial backups may be taken also. Partial back-
ups 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 .
Backups from live filesystems should be avoided. On operating systems that support file system snapshots, back-
ups 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 ser-
vices 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 snapshot
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 unreliable. 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 ba