star(1)

NAME

star - unique standard tape archiver

SYNOPSIS

star  command [ options ] file1 ... filen
ustar command [ options ] file1 ... filen
tar   command [ options ] file1 ... filen
star  -copy   [ options ] file1 ... directory
star  -copy   [ options ] -C from_directory . to_directory

DESCRIPTION

Star is a very fast tar(1) like tape archiver with im
proved 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 di
rectory 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

fine 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 exist
ing file tree. See also -U option. In create mode use the pat=
option to specify either select or exclude patterns (depending on
the -V flag). In extract or list mode all file type arguments are
interpreted as select patterns while the patterns specified with
the pat= option may be used as select or exclude patterns (de
pending 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 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= op
tion for more details.
Star has no limitation on filename length. Pathnames and
linknames up to PATH_MAX (1023 bytes with old OS versions and
4095 bytes with POSIX.1-2001) may be archived. Later versions may
be able to deal with longer pathnames.
Star deals with all 3 times, available for files on UNIX
systems if the archive format is either chosen from the star spe
cific 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 chang
ing 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 correct
ly. See the description for the H=headertype option below for
more information on archive formats and possible archive inter
change 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

ferent 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 sepa
rately or combined. For compatibility with GNU programs, long
options may alternatively start with a double dash. In compati
bility 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 copy
ing 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 cas
es - a more readable output than diff -r. If you use star's dump
extensions for the tar archive, the -diff option allows to find
even if the directory in the file tree contains more files than
the archive. This way, it is possible to compare all properties
of two file trees in one run. See diffopts for more details.
Adding one or more -v options increases the verbosity. With -vv
and above, the directory content is compared also if in -dump
mode.
-n No extraction. Show what star would do, in case the
-x command had been specified.
-r Replace files in a tarfile. The named files are
written to the end of tarfile. This implies that later, the ap
propriate 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 op
tion -ctime lists the file creation time instead of the modifica
tion 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 ex
tracts 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 cre
ate 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 path
names 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 in
formation 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 in
formation 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 in
terpret the headers to be of type headertype. As star even in
case of a user selected extract archive format does format check
ing, 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 pa
rameter for headertype are:
help Print a help message about possible head
er 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 for
mat. File size is limited to 2 GB - 2 bytes, uid/gid is limited
to 262143. Sparse files will be filled up with zeroes.
tar Old BSD UNIX tar format. This archive
format may only store plain files, directories and symbolic
links. Pathnames or linknames longer than 99 chars may not be
archived. See also the -d option as a note to some even older
tar implementations.

If the tar format has been selected, star
will not use enhancements to the historic tar format. File size
is limited to 2 GB - 2 bytes, uid/gid is limited to 262143.
Sparse files will be filled up with zeroes.
star Old star standard format. This is an up
ward/downward compatible enhancement of the old (pre Posix) UNIX
tar format. It has been introduced in 1985 and therefore is not
Posix compliant. The star format allows to archive special files
(even sockets) and records access time and creation time besides
the modification time. Newer versions of the old star format al
low 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 pos
sible 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 exten
sions do not interfere with the POSIX tar formats. The last 4
bytes of the tar header contain a 'tar ' signature.
gnutar This is a commonly used, but unfortunate
ly not Posix compliant (although designed after 1987) enhancement
to the old tar format. The gnutar format has been defined be
tween 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 de
fault 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 suc
cessor is the POSIX-1003.1-2001 Standard Data Interchange format.
It is called the pax archive format.

If the pax format has been selected, star
will not use enhancements to the POSIX.1-2001 tar format, the
archive will be strictly conforming. File size is unlimited,
uid/gid/uname/gidname is unlimited, major/minor is limited to
2097151. Sparse files will be filled up with zeroes.
xstar The extended standard tar format has been
introduced in 1994. Star uses the xstar format as default
archive format. This is an upward/downward compatible enhance
ment of the IEEE/Posix1003/IEC-9945-1 Standard Data Interchange
format. It allows among others very long filenames (100+130
chars and above) and records access time and creation time.
Sparse files will be archived correctly (if -sparse is used).

The access time and creation time are
stored at the end of the POSIX file name prefix (this limits the
prefix to 130 chars). These extensions do not 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 ' 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 ' signature at the end of the tar header. It is other
wise identical to the xstar format. As some tar implementations
do not follow the POSIX rules and compute the checksum for less
than 512 bytes of the tar header, this format may help to avoid
problems with these broken tar implementations. The main other
difference to the xstar format is that the xustar format uses
POSIX.1-2001 extended headers to overcome limitations of the his
toric tar format while the xstar format uses proprietary exten
sions. The xustar format is the default format when star is
called as tar.

File size is unlimited, uid/gid/un
ame/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/un
ame/gidname is unlimited, major/minor is unlimited. Sparse files
will be archived correctly (if -sparse is used).
suntar The extended header format found on So
laris 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 type
flag for the extended headers instead of the standard 'x'.

File size is unlimited, uid/gid/un
ame/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 com
pliant.
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 lim
ited 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 cov
ered 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 imple
mentations 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 cov
ered 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 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

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 op
tion is used in conjunction with the list command, star lists ac
cess time instead of modification time. (This works only in con
junction with the star, xstar, xustar, exustar, and with the pax
format.) Another option to retain the access time for the the
files that are going to be archives is to readonly mount a UFS
snapshot and to archive files from the mount point of the UFS
snapshot.
-B Force star to perform multiple reads (if necessary)
to fill a block. This option exists so that star can work across
the Ethernet, since pipes and sockets return partial blocks even
when more data is coming. If star uses stdin as archive file,
star behaves as if it has been called with the -B option. For
this reason, the option -B in practice is rarely needed.
-block-number
Print the archive block number (archive offset /
512) at the beginning of each line when in verbose mode. This al
lows 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 implementations (pre BSD 4.2 or pre AT&T SVR4), blocksize
should not be more than 10 kBytes. For POSIX.1-1988 compatibili
ty, 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 up
per 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 sys
tem 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 re
cent hardware (e.g. DLT tape drives), a blocksize of 256 kBytes
results in sufficient speed and seems to be a good choice. Star
allows block sizes up to 2 GByte if the system does not impose a
smaller limit. If you want to determine the blocking factor when
reading an unknown tar archive on tape, specify a blocking factor
that is higher than the supposed blocking factor of the tape.

Star

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 simi
lar 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 per
formed. Thus bs=7x8k will specify a blocksize of 56 kBytes.
Blocksize must be a multiple of 512 bytes. See also the descrip
tion 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 re
lated to the next file type argument.
-bz run the input or output through a bzip2 pipe - see
option -z -Z and -j below. As the -bz the -j the -Z and the -z
option are non standard, it makes sense to omit the -bz the -j
the -Z and the -z options inside shell scripts if you are going
to extract a compressed archive that is located inside a plain
file as star will auto detect compression and choose the right
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 ig
nores all -C options.
· In create mode (with the -c, -r and -u
flag), star walks through all -C options and file type arguments.
While a BSD derived tar(1) implementation goes back to the cur
rent working directory after storing one file argument that imme
diately follows the -C option, star changes the directory only if
a new -C option follows. To emulate the behavior of a BSD de
rived 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 di
rectories from previous C=dir options and performs a chdir(2) to
the corresponding directory of a matching pattern. All pat= op
tions that do not follow a C=dir option are interpreted as if
they were preceded by a -C . option. See EXAMPLES for more in
formation.
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 di
rectories 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 sym
linked 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 be
cause 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 ex
tracted file. Use with care and check the system clock after us
ing this feature.
If used with the create command this changes the
behavior of the newer= option. Star, in this case compares the
ctime of all files to the mtime of the stamp file rather then
comparing the mtimes of both files.
-cumulative
A shorthand for -dump-cumulative. See
-dump-cumulative for more information.
-D Do not descend directories. Normally, star de
scends 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 directo
ries 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 ex
tract, no intermediate missing directories are created.
-data-change-warn
If the size of a file changes while the file is be
ing archived, treat this condition as a warning only that does
not cause a non zero exit code. A warning message is still writ
ten 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 prop
erties, EOF recognition, opening of remote archives and fifo in
ternals.
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 op
tion in effect, star compares the low order 12 bits of the
st_mode field.
mode Same as perm.
type Compare file type. Note that star cannot
compare the file type in case of a hard link.
nlink Compare link count on hardlinks. This
only works if the archive is in exustar format and contains
star's dump extensions.
uid Compare numerical user id of file.
gid Compare numerical group id of file.
uname Compare ASCII version of user id of file.
The user name is mapped via the file /etc/passwd.
gname Compare ASCII version of group id of
file. The group name is mapped via the file /etc/group.
id Shorthand for: uid,gid,uname,gname. Com
pare all user/group related info of file. Note that this will
always find differences if the source and target system use dif
ferent 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 al
ways 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 evalu
ates the value returned by the readlink(2) call.
sparse Compare if either both files are sparse
or not. If only one of both files is sparse, then a difference is
flagged. This only works with if the archive 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 for
mat is star, xstar, xustar, exustar, or pax.
lmtime Compare the modification time of symbolic
links. By default, star will not compare the modification time
of symbolic links as most systems cannot set the 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 filesys
tem.
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 cre
ated 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 mem
bers 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 every
thing 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 al
lows to control the group id of intermediate directories created
by star.
dir-owner=user
If star extracts archives as root, this option al
lows 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 di
rectory cache will be able to restore the correct times of direc
tories. 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 section INCREMENTAL BACKUPS for more infor
mation on true incremental dumps.
-dump-cumulative
instructs star to perform incremental dumps rela
tively to the last incremental dump of the same level. Incremen
tal dumps with a level higher than 0 are normally done relatively
to the content of a previous dump with lower level. If incremen
tal dumps and restores are going to be used to synchronize
filesystem content, every successive incremental dump will in
crease in size if -dump-cumulative is not used. See section

SYNCHRONIZING FILESYSTEMS

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 er
ror 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 defi
nitions. More than one error control file and more than one
error control spec as well as a mixture of both forms is possi
ble.
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 conditions instead of trying to continue
with the archive.
A typical reason to use error control is to sup
press warnings about growing log files while doing a backup on a
life file system. Another typical reason to use error control is
to tell star to abort if e.g. a file could not be archived in
stead 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 fol
lowed by white space followed by a file name pattern (see
star-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 pat
tern. Whenever an error situation is encountered, star checks
the lines in the error control file starting from the top. If
the current error condition is listed on a line in the error con
trol file, then star checks whether the pattern on the rest of
the line matches the current file name. If this is the case,
star uses the current error control specification to control the
current error condition.
The list of error conditions to be handled may use
one or more (in this case separated by a '|' character) identi
fiers from the list below:
ABORT If this meta condition is included in
an error condition, star aborts (exits) as soon as possible after
this error condition has been seen instead of making star quiet
about the condition. This error condition flag may only be used
together with at another error condition or a list of error con
ditions (separated by a '|' character).
WARN If this meta condition is included in
an error condition, star prints the warning about the error con
dition but the error condition does not affect the exit code of
star and the error statistics (which is printed to the end) does
not include the related errors. This error condition flag may
only be used together with at another error condition or a list
of error conditions (separated by a '|' character). The WARN
meta contition has a lower precedence than ABORT.
DIFF Suppress output in case that star -diff
did encounter any differences.
ALL This is a shortcut for all error condi
tions 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 completely. In
this case, star tries to match the link name against the pattern
in the error control file.
BADACL Suppress warnings access control list
conversion problems.
SETACL Suppress warnings about files on that
star could not set the ACL information during extraction.
SETXATTR Suppress warnings about files on that
star could not set the extended file attribute information during
extraction.
If a specific error condition is ignored, then the error
condition is not only handled in a silent way but also excluded
from the error statistics that are printed at the end of the star
run.
Be very careful when using error control as you may ignore
any error condition. If you ignore the wrong error conditions,
you may not be able to see real problems anymore.
-F,-FF ...
Fast and simple exclude option for create mode.
With one -F argument, star ignores all directories called SCCS
and RCS. With two -F arguments, star in addition ignores all
files called core errs a.out all files ending with .o. OBJ/.
With three -F arguments, star ignores all sub trees starting from
a directory that includes a file .mirror or .exclude and all ob
ject 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 ma
chine 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 mem
ory 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 sensi
tive 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 cre
ated with root privileges. After this connection has been estab
lished as root, star switches back to the id of the caller. If
any of the other archives in the list is located on a different
host, star will not be able to open this archive later on, unless
run by root.
Star normally uses stdin/stdout for the tar archive
because the most common way to use star is in conjunction with
pipes. If star is installed suid root or if it has been called
by root, tarfilename may be in remote syntax: user@host:filename
as in rcp(1) even if invoked by non root users. See SUID NOTES
for more information.
To make a file local although it includes a colon
(:), the filename must start with: '/', './' or '../'
Note that if star talks to an old rmt remote tape
server that does not support symbolic open modes, it does not
open a remote tape with the O_CREAT open flag because this would
be extremely dangerous. If the rmt server on the other side is
the rmt server that comes with star or the GNU rmt server, star
may use the symbolic mode for the open flags. Only the symbolic
open modes allow to send all possible open modes in a portable
way to remote tape servers.
It is recommended to use the rmt server that comes
with star. It is the only rmt server that gives platform inde
pendent compatibility with BSD, Sun and GNU rmt clients and it
includes security features that may be set up in /etc/de
fault/rmt. All options that start with the -f sequence are sen
sitive 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.
-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

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 incremen
tal dump is only a partial dump. See -wtardumps, level= and sec
tion INCREMENTAL BACKUPS for more information.
fs=# Set fifo size to #. See bs= for the possible syn
tax. The default size of the fifo is 1 Mbyte on Sun mc68000 sys
tems, 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 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. Nor
mally 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 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 op
tion 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. Nor
mally star will not follow symbolic links but stores their values
in tarfile. See also the -h option.
-l Do not print a warning message if not all links to
hard linked files could be dumped. This option is evaluated in
the opposite way to historic tar(1) implementations and to
POSIX.1. POSIX.1 requests that by default no warning messages
will be printed and -l will enable warning messages when not all
links could be archived.
level=dumplevel
Set level for incremental dumps. This option is
used to switch star into true incremental dump mode.
In true incremental dump mode, a -C option which is
followed by the name a mount point and a dot ('.') as starting
directory name is required. Only a single file system may be
handled at a time. If the directory following the -C option is
not 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

-link-dirs
When in create mode, try to find hard linked direc
tories. 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 implemen
tations 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 op
erating systems require the extraction to be done as root in or
der to be able to create or remove hard links to directories.
For this reason its only recommended to use this option when do
ing accurate backups and when hard links to directories are ex
pected.
When the option -link-dirs is not used and hard
links to directories are present, the appendant sub-tree will ap
pear more than once on the archive and star will print Linkcount
below zero warnings for non directory hard links inside the sub
tree.
list=filename
Read filenames for store/create/list command from
filename. The file filename must contain a list of filenames,
each on a separate line. This option implies the -D option. To
force star to descend directories, use the -dodesc option in this
case.
-lowmem
Try to run with reduced memory requirements. This
causes star to default to 1 MB of FIFO memory. Instead of allo
cating memory to hold the directory content and reading the di
rectory at once, star reads the directory name by name. This may
cause star to close the directory if it rans out of file descrip
tors 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 in
formation.
-m Do not restore access and modification time. (Ac
cess 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 direc
tory, 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 recur
sively 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 scan
ning. 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 con
taining 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 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 com
panies who like to support me to be able to add the meta file
concept to the POSIX.1-2005 standard.
-modebits
This options allows you to create tar archives that
include more than 12 bits from st_mode. Note this create tar
archives that violate POSIX but some tar implementations insist
in 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 sin
gle tape. If -multivol is used in read mode, a hard EOF on input
(if not preceded by a logical EOF) triggers a medium change oper
ation.
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 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 speci
fied, then the medium change is triggered by a EOT condition from
writing the medium. This allows to use media where the size can
not 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 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.
newer=filename
Do not store files to tarfile if their modification
time is not newer than the modification time of filename. See
-ctime option for changing this behavior.
-newest
In conjunction with the list command this lists you
only the newest file in tarfile.
-newest_file
obsoleted by -newest-file
-newest-file
In conjunction with the list command this lists you
only the newest regular file in tarfile.
new-volume-script=script
Call script at end of each tape if in multi volume
mode. If this option is not in effect, star will ask the user to
confirm the volume change. The script is called with two parame
ters. The first parameter is the next volume number and the sec
ond 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 in
creases 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 al
low 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 extrac
tion 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 overwrite existing
files but the local ownership of the existing files should not
change.
-no-p Do not restore files and directories to their orig
inal 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 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 cre
ate 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 op
tion.
-o, -nochown
Do not restore owner and group of files. This may
be used if super user privileges are needed to overwrite existing
files but the local ownership of the existing files should not
change.
-onull, -nullout
Do not actually write to the archive but compute
and add the sizes. This is useful when trying to figure out if a
tape may hold the current backup. Please only use the -onull op
tion 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 con
tains Access Control Lists (ACLs) in POSIX.1-2001 extended head
ers, 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 unlim
ited in length, this is no real limitation. If more than one
pattern is specified, a file matches if any of the specified pat
tern 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 de
fault, 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 argu
ments 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
patterns do not offer pattern matching but allow to restore sub
trees. 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 star-match(1) for
more details of the pattern matcher. All patterns are selection
patterns by default. To make them exclude patterns, use the -not
or the -V option.
pkglist=file
This is (for now) an internal interface for the
Schily Source Package System (sps). It only works in create mode
and behaves similar to the list= option, but it allows to over
write 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 charac
ters.
-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 de
fined 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 re
tained. If you type anything else, then this is taken as the new
file name.
-pax-L Follow symbolic links. If the referenced file does
not exist, the file information and type will be for the link it
self. 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 regu
lar expressions in a way that has been defined for POSIX pax.
-pax-n Allow each pattern to match only once. If a pat
tern 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 de
fined:
a Do not preserve file access times. This op
tion 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 equiv
alent 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 spec
ified with the list= option.
-refresh_old_files
obsoleted by -refresh-old-files
-refresh-old-files
-refresh
Do not create new files. Only already existing
files may be overwritten from tarfile if either newer versions
are present in the archive or if the -U flag is used. This al
lows 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 direc
tories. If this option is in effect, star will be allowed to re
cursively 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 ex
traction takes place. If -restore has been specified, star be
haves as if -xdot has been specified too. See also level= option
and section INCREMENTAL BACKUPS for more information.
-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 pat
tern according to the substitution expression replstr. The for
mat 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 compromise the system. If they are un
packed 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 lim
it 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 vio
lates the tar specs but old versions of tar derived from the sev
enth edition of UNIX are implemented in this way. Note: Only
filenames and linknames containing chars with the most signifi
cant bit set may trigger this problem because all other fields
only contain 7 bit ASCII characters, octal digits or binary ze
roes.
-silent
Suppress informational messages like foobar is
sparse.
-sparse
Handle files with holes effectively on store/cre
ate. 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 op
tion 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 al
so -wtardumps option and section INCREMENTAL BACKUPS for more in
formation.
-time Print timing info. See DIAGNOSTICS for more infor
mation.
-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 archive. This may be used in shell scripts to gen
erate 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 differ
ences 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 multiplica
tion 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 vol
ume 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 old
er 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.
-v Increment verbose level by one. This normally re
sults in more output during operation. See also in the descrip
tion 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 out
put.
-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.
-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 prob
lems 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 ex
tended 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 cov
ers 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 in
formation.
-xdir Extract directories even if the corresponding di
rectories 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 directo
ries 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 (di
rectories 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 creat
ing 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 ex
tract a compressed archive that is located inside a plain file as
star will auto detect compression and choose the right decompres
sion option to extract. The environment variable

STAR_COMPRESS_FLAG

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 incremen
tal mode. To allow incremental backups, the file system must im
plement 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 re
named, 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 com
paring the time stamps of all files against the time of the last
backup. Note that this method only works correctly if the level 0
backup and all higher level incrementals include the whole file
system. As star archives all inode meta data, star is able to
detect renamed files by comparing inode numbers.
Detecting renamed files only works if star scans the whole
file system tree for each full and incremental backup. This will
work in case no files are excluded and the dump starts at the
root directory of a file system. In case that no files are re
named from excluded parts to included parts, partial backups may
be taken also. Partial backups only make sense if a complete di
rectory 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 life filesystems should be avoided. On oper
ating 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 So
laris 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 orig
inal mount point of the file system for /etc/tardumps and the
archive header.
Note that if the backup is done on a life 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 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 9 dumps made between Monday and Friday accumu
late 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 (after the Friday dump in
week 2 or later).

INCREMENTAL RESTORES

Incremental restores should be made to an empty file sys
tem (except for the lost+found directory). Star is currently un
able to perform incremental restores to a file system that con
tains 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

the Thursday dump of week 3 has been made, the following restore
procedure needs to be applied:
level 0
starting with an empty disk, the full (level 0)
dump from week 1 is restored.
level 5
after the level 0 restore has been finished, the
level 5 dump from Friday in week 2 is restored.
level 10
after the level 5 restore has been finished, the
level 10 dump from Wednesday in week 3 is restored.
The disk now contains the same files as it did when the
level 9 dump has been made on Wednesday of week 3.
To extract a level 0 dump call:
cd /filestem-mount-point star -xpU -restore f=archive-name
This creates the directory star-tmpdir and the database
star-symtable in the root directory of the new file system. Sub
sequent 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 tar
get filesystem with the content of the source filesystem, a modi
fied 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 life
filesystem should be avoided. On operating systems that support
file system snapshots, copies should be made from a read-only
mount of a snapshot. Be careful that all files that have been
created between setting up a snapshot and starting an incremental
copy may be missing from all copies unless the dumpdate=name op
tion 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

SIGINT usually generated by ^C from the controlling
tty. Upon receipt of a SIGINT, star prints statistics and exits.
If in create mode i.e. storing files to archive, star finishes
with the current file to ensure that no partial file is written
to the archive, write an eof record and then exits.
SIGHUP not to be generated from a tty. The actions are
the same as upon receipt of a SIGINT.
SIGQUIT usually generated by ^ from the controlling tty.
Upon receipt of a SIGQUIT, star prints statistics and continues
with the current operation. This is useful to watch the progress
of the current operation.

EXIT STATUS

The following exit values are returned:

0 All files were processed successfully.

-3 / 253
Star has been called with the option -e, or the
errctl= option has been used to mark the current error fatal.
-2 / 254
One or more files could not be processed success
fully.
-1 / 255
Command line parsing error.
>0 Other positive exit codes: The errno of the call
that caused the fatal error.

EXAMPLES

To get a listing in a way similar to ls -l one might use:
example% star -tv f=/dev/rmt/1bn
The same command as listed above in a POSIX tar command
line syntax compliant way is:

example% star tvf /dev/rmt/1mbn
To copy the directory tree in /home/someuser to the direc
tory /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 en
tries 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 re
siding 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 di
rectory.
To backup a list of files generated by the find(1) com
mand:

example% find . find_options -print | star -c
list=- f=/dev/rmt/1bn
Note that this does not work if the file names from output
of the find command include new line characters.
To extract a tarfile that contains a tarfile one might
use:

example% star -x -to-stdout f=/dev/rmt/1bn pat=pat
| star -xp
Pat, in this case should match the tarfile in the tarfile
on tape that should be extracted.
To make a backup of the root filesystem to a tape drive
connected to a remote machine, one might use:

example# cd /
example# star -cM fs=128m bs=63k
f=tape@remotehost:/dev/rmt/1bn .
You need a line in /etc/passwd like the following to en
able this:

tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
And a .rhosts file in /etc/tapehome to allow remote con
nections from the appropriate hosts. Make sure that the file
/etc/default/rmt exists and allows remote access to the requested
tape drive.
To use a ssh(1) connection for a backup to a remote tape
server, one might use:

example# env RSH=/usr/bin/ssh star -cM fs=128m
bs=63k f=tape@remotehost:/dev/rmt/1bn .
To repair a corrupted filesystem for which no recent back
up 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 contain
ing the needed filenames and using the list= option or by using
the interactive mode (see -w option).
If you want a list that only contains all filenames from
files with differences you may use:

example# star -diff -tpath diffopts=!times
f=/dev/rmt/1bn
If you are looking for files that changed the type or the
access permission because this is a common case on still corrupt
ed files, use:

example# star -diff -tpath diffopts=type,perm
f=/dev/rmt/1bn

ENVIRONMENT

STAR_COMPRESS_FLAG
If you like star to always create compressed files
that use maximum compression, you may set the environment vari
able STAR_COMPRESS_FLAG to -9.
STAR_DEBUG
If this environment variable is present, star will
not remove temporary files from ./star-tmpdir. The files in this
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/stdout for the archive. If you like star to use the
file name from the TAPE environment instead, you need to specify
the -T option too.
RSH If the RSH environment is present, the remote con
nection will not be created via rcmd(3) but by calling the pro
gram 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 initiated rcmd(3) connection.
See BUGS section for more information.
RMT If the RMT environment is present, the remote tape
server will not be the program /etc/rmt but the program pointed
to by RMT. Note that the remote tape server program name will be
ignored if you log in using an account that has been created with
a remote tape server program as login shell.

FILES

/etc/default/star
Default values can be set for the following options
in /etc/default/star. For example: CDR_FIFOSIZE=64m
STAR_FIFOSIZE
Sets the default size of the FIFO (see also
fs=# option).
STAR_FIFOSIZE_MAX
Sets the maximum size of the FIFO (see also
fs=# option). Setting STAR_FIFOSIZE_MAX in /etc/default/star al
lows to overwrite global values from backup scripts for machines
with less memory.
archive0=
archive2=
archive3=
archive4=
archive5=
archive6=
archive7=
archive0=
Archive entries for the -[0..7] option.
A correct archive?= line has 3..4 space sep
arated 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 unlim
ited. 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 followed 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 in
clude the whole filesystem).
The dump time itself includes the decimal represen
tation of the UTC seconds since Jan 01 1970, a space and the tex
tual local time representation of the dump time.
The numerical decimal dump time representation may
be followed by a dot and a sub second value. The textual local
time 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 re
store operation.
./star-tmpdir
Is the temporary directory that is used as interme
diate file storage by star if in incremental restore mode.
./star-lock
Is a lock file created by star when doing an incre
mental 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-star(1), star-match(1), dd(1), sdd(1), rsh(1),
ssh(1), star(4/5), rcmd(3), fssnap(1m)

DIAGNOSTICS

star: f records + p bytes (total of x bytes = d.nnk).

The number of full records, the number of bytes in partial
records and the total amount of data in KBytes.
star: Total time x.yyysec (z kBytes/sec)
The time used and the transfer speed from/to the archive.
If there have been non fatal errors during the archive
processing, star will display a delayed error summary before ex
iting.

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 re
quests all options to start with a dash (-) and allows to either
write options separately or combined (in case of boolean flags),
the tar command line syntax requires all options to be combined
into a single string that does not start with a dash. Star by
default assumes a command line syntax like a typical POSIX com
mand and includes a compatibility mode that allows to specify a
command line syntax as documented for the UNIX-98 tar command.
If you believe that you found a bug in the way star parses the
command line, please first check your command line for correct
ness 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 vxfblmo ) and check the shell
script with both, your local tar and star for correct behavior.
It you expect the script to call gnutar, do not include the -o
option as gnutar implements this option in a way that violates
UNIX-98.
Star strips leading ./ sequences from pathnames. This lets
star in many cases store longer pathnames than other implementa
tions.
The POSIX.1-1988 method (ustar format) of storing files
with pathnames that are longer than 100 chars has some limita
tions:

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 path
name 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 filenames, if the
POSIX method would allow this. When the archive format is
xustar, exustar or pax very long filenames are stored using ex
tended headers 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 compliant as possi
ble. Inserting this tar signature is a minor deviation from the
standard that has the last 12 bytes of each header reserved for
future use. On the other side, tar implementations such as some
pax implementations that only compute checksums on the first 500
bytes of the header are violating the standard that requests the
checksum to be computed on all 512 bytes of the tar header. All
tar implementations that are 100% Posix compliant will be able to
extract xstar archives as long as no new standard is defined that
claims the last 12 bytes of the header for a different use. But
then the ustar version number should be changed from `00' to
`01'. Now, that the POSIX-2001 standard has been accepted, it is
even predictable that all extensions to the standard tar format
will go into the POSIX.1-2001 extended headers which are extensi
ble 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 character in the star case.
Star uses these four bytes since 1985 without problems.
If you need a 100% POSIX.1-1988 and 100% POSIX.1-2001 compliant
tar archive, you may use the xustar, exustar or the pax archive
format. The probability of falsely detecting other tar formats
as xustar or exustar format 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 encounters a logical EOF record in the archive.
If the fifo is used, star may read until the fifo is full or un
til the real EOF mark on tape is reached. How much data star
actually reads depends on the time when the star foreground pro
cess 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 ver
sions of star. If the author decides to change this method, lat
er 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 on
ly 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 archives generated by star cause Sun's tar to print
tar: impossible file type messages. You may ignore these mes
sages.
Gnutar's dumpdirs are non standard and are currently not
implemented.
If gnutar archives sparse files with more than four holes,
it produces archives that violate the standard in a way that pre
vents other tar implementations to read these archives. Star
knows about that and is able to handle these gnutar archives.
The filetype N (LF_NAMES) from gnutar (an obsolete method
of storing long names) will never be implemented.
Note that on operating systems (like DOS) that do not im
plement 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 op
tion) on Linux is buggy by design. In order to retrieve the
needed information, every file needs to be opened. If the /dev
directory is included in create mode, every possible driver will
be loaded which may hang the system for a long time. In the worst
case, unwanted side effects from opening devices (such as causing
tape drives to rewind the media) may be caused.

SECURITY NOTES

If you unpack a tar archive in a non empty directory, any
file in that directory may be overwritten unless you specify the
-k option. If the archive contains symbolic links or hard links,
star may even overwrite files outside the current directory. As
many other commands, star usually has all possible permissions
when run as root. Unpacking archives as root thus may have fatal
results to any file on your system. Be very careful when you try
to extract an archive that has not been created by you. It is
possible to create hand crafted tar archives that may overwrite
critical files (like /etc/passwd) on your system. In addition
all tar archives that have been created with the list= option and
tar archives where the C= option was not specified before all
file type arguments may be critical.
A good advise is to extract all doubtful archives as non
root in an empty directory and to specify the -secure-links op
tion. If you get a warning, you should unpack the archive a sec
ond 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 con
nections to remote archives for non root users. This is done by
using the rcmd(3) interface to get a connection to a rmt(1) serv
er.
Star resets its effective uid back to the real user id im
mediately after setting up the remote connection to the rmt serv
er and before opening any other file.
If star has not been installed suid root and not called by
root, it will try to create the remote connection via rsh(1) or
ssh(1) (in case the environment RSH has been set to ssh). Note
that in this case, the throughput to the remote tape server will
be much lower than with a connection that has been initiated via
rcmd(3).

LIMITATIONS

If star is running on a large file aware platform, star is
able to handle files up to 8 GB in a mode that is compliant to
the POSIX.1-1988 ustar format. With a nonstandard star specific
extension, up to 95 bits may be used to code the filesize. This
will handle files up to 200,000,000 TB. With the new
POSIX.1-2001 extended 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 compatible with old tar implementations gives several
problems. The options -fifostats, -force-hole, -force-remove and
-fifo interfere with the -f option and the fact that they exist
prevents users from using filenames like e.g. ifo using the tra
ditional way where the filename directly follows the string -f
without any space between the option name and the file name.
However, there is no problem to use a file named ifo by by call
ing -f ifo, f=ifo, -f=ifo or -f= ifo. Be careful not to make ty
pos 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 gnutar's dumpdirs.
If not invoked by the super user star may not be able to
extract files if they reside in read only directories.
Star is not able to make a complete backup of a filesystem
if files are hidden by a mount that is in effect on a directory
of this filesystem. This may be avoided in case of the ufs
filesystem if the backup is made off a ufs snapshot (see the man
page for fssnap(1m) It could be avoided for any filesystem if the
loopback filesystem had an option that tells lofs not to traverse
mountpoints.
For now (late 2002), we know that the following programs
are broken and do not implement signal handling correctly:
rsh on SunOS-5.0...SunOS-5.9
ssh from ssh.com
ssh from openssh.org
Sun already did accept a bug report for rsh(1)/ssh(1).
Openssh.org accepted and fixed a bug for their implementation of
ssh(1).
If you use star to create a remote connection via an un
fixed rsh(1) or ssh(1), be prepared that terminal generated sig
nals 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 function
al 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 05/09/03

STAR(1)

Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout