Schily's USER COMMANDS STAR(1)
NAME
star - unique standard tape archiver
SYNOPSIS
star command [options] [-find] file1 ... filen [find_expr]
ustar command [options] [-find] file1 ... filen [find_expr]
star command list=name [options] -find [find_expr]
tar command [options] file1 ... filen
star -copy [options] [-find] file1 ... [f_expr] directory
star -copy [options] -C from_directory . to_directory
star cli=name ...
DESCRIPTION
Star is a very fast tar(1) like tape archiver with improved
functionality. It supports unlimited path name lengths (up
to 8 GB) in all cases that use suitable archive types.
Star archives and extracts multiple files to and from a sin-
gle file called a tarfile. A tarfile is usually a magnetic
tape, but it can be any file. In all cases, appearance of a
directory name refers to the files and (recursively) sub-
directories 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.
If the first argument is in the form cli=name, the command
line interface is selected to match name. See section
CLI SELECTION below.
FEATURES
Star includes the first free implementation of POSIX.1-2001
extended tar headers. The POSIX.1-2001 extended tar headers
define a new standard way for going beyond the limitations
of the historic tar format. They allow (among others) to
archive all UNIX time stamps in sub-second resolution, files
of arbitrary size and filenames without length limitation
using UNICODE UTF-8 coding for best exchange compatibility.
Star by default uses a fifo to optimize data flow from/to
tape. This results in a normally streaming tape during the
whole backup. See -fifo and fs= option to get information
on how to find the best fifo size.
Star includes a pattern matcher to control the list of files
to be processed. This gives a convenient interface for
archiving and restoring complex lists of files. In
Joerg Schilling Last change: 2020/09/04 1
Schily's USER COMMANDS STAR(1)
conjunction with the -w flag it is easy to merge a tar
archive into an existing file tree. See also -U option. In
create mode use the pat= option to specify either select or
exclude patterns (depending on the -V flag). In extract or
list mode all file type arguments are interpreted as select
patterns while the patterns specified with the pat= option
may be used as select or exclude patterns (depending on the
-V flag). Have a look at the description of the -C option
to learn how to fetch files from a list of directories (in
create mode) or to distribute files to a list of directories
(in extract mode). A substitute option allows ed(1) like
pattern substitution in file names.
Star includes support for incremental backup and restore
similar to the BSD commands dump(1) and restore(1) that are
known as ufsdump(1) and ufsrestore(1) on Solaris.
Star includes an enhanced function that is similar to the
find(1) command (see sfind(1)). This function is imple-
mented in libfind. It allows to use find expressions, even
in extract or list mode, directly on the content on an
archive. The extensions to find(1) allow to modify the file
metadata.
Star includes a sophisticated diff command that is able to
compare file content and meta data. Several diff options
allow user tailorable functionality. Star won't show you
differences you are not interested in. Check the diffopts=
option for more details.
Star has no limitation on filename length. Pathnames and
linknames up to PATH_MAX (typically 1024 bytes) may be
archived by most tar implementrations. Star allows to
archive path names up to 8 GB on modern platforms.
Star deals with all 3 times, available for files on UNIX
systems if the archive format is either chosen from the star
specific formats or is a format that uses POSIX.1-2001
extended headers. This is either done in second resolution
by using a star specific POSIX.1-1988 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 - if
run as root -, star is able to do backups without changing
any of the 3 the times.
If used with the H=ustar option, or if called as ustar or
tar while the H=headertype option is not used, star is 100%
POSIX compliant.
Star's default format (if called as star) is xstar and is as
posix compliant as possible. Enhancements to the standard
Joerg Schilling Last change: 2020/09/04 2
Schily's USER COMMANDS STAR(1)
that prevent correct extraction of single files when using a
different tar implementation that is only POSIX.1-1988 com-
pliant may occur, but they only affect single files with a
pathname that is longer than 100+130 chars or when archiving
sparse files with the -sparse option in effect. All other
files will extract correctly. See the description for the
H=headertype option below for more information on archive
formats and possible archive interchange problems.
Star makes it easy to repair corrupted filesystems. After a
fsck -y has been run on the filesystem, star is able to
restore only the missing files automatically. Use then star
-diff to check for differences (see EXAMPLES for more infor-
mation).
Star automatically recognizes the type of the archive. Star
therefore is able to handle features and properties of dif-
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 stan-
dard.
Star automatically recognizes and handles byte swapped
archives. There is no option to manually control byte swap-
ping.
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.
CLI SELECTION
If the first argument is in the form cli=name, the command
line interface is selected to match one of the supported CLI
variants. The following interfaces are supported:
star The star interface selects the command line
interface described in this manual page.
suntar The suntar interface selects the command line
interface of the classical UNIX tar command
as described in suntar(1).
tar The classical tar interface selects the com-
mand line interface of the classical UNIX tar
command. This is currently an alias to suntar
and implements extensions introduced by the
tar command found on Solaris.
Joerg Schilling Last change: 2020/09/04 3
Schily's USER COMMANDS STAR(1)
gnutar The gnutar interface selects the command line
interface of the GNU tar command as described
in gnutar(1). Star however does not imple-
ment the deviations from the standard
behavior, that are caused by the GNU option
parser that is used by the original gtar(1)
command.
pax The pax interface selects the command line
interface of the POSIX pax command as
described in spax(1).
cpio The cpio interface selects the command line
interface of the classical UNIX cpio command
as described in scpio(1).
COMMAND
In native mode, star is compatible to the command line syn-
tax of a typical POSIX command and for this reason expects
commands and options to start with a single dash (-). In
this case, commands and options may be specified separately,
all boolean or increment type options may be specified
either separately or combined.
For compatibility with GNU programs, long options may alter-
natively start with a double dash.
In compatibility mode to POSIX tar, star expects commands
and options to appear as one single string that does not
start with a dash. In POSIX tar compatibility mode, addi-
tional 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.
The Option -c may be used together with -diff and -t.
In this case, the whole command line has to be similar
to the command line for the -copy mode.
-copy
Copy named files to the target directory which is the
last file type argument. The target directory must
exist. The shorthand -cx instead of -copy is not
allowed because this could be a result of a typo.
If the option -diff has been specified in addition,
star performs a one pass directory tree compare instead
of copying files. The shorthand -c -diff instead of
Joerg Schilling Last change: 2020/09/04 4
Schily's USER COMMANDS STAR(1)
-copy -diff is also allowed.
On operating systems with slow file I/O (such as Linux
with any filesystem or platforms with Copy on Write
filesystems like ZFS), it may help to use -no-fsync in
addition (see also ENVIRONMENT and FILES), 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 copy-
ing files. This makes sense as the listing from star
may be better readable than the output from ls -lR.
The shorthand -c -t or -ct instead of -copy -t is also
allowed.
The job is by default done in the best archive mode.
This implies that it defaults to H=exustar -dump. When
in -copy mode, star forks into two processes and data
exchange is done via the shared memory from the FIFO.
This gives the best possible performance. Without
FIFO, the -copy mode will not work.
The list= option, patterns and substitutions apply only
to the create side of the copy command.
-diff
Compare the content and the attributes of the files
from the archive in tarfile to the filesystem. This
may also be used to compare two file trees in the
filesystem. If you use a set of diffopts that fits
your needs, it will give - in many cases - a more read-
able 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 star is read-
ing a tar archive that has been created in -dump mode.
-n No extraction. Show what star would do, in case the -x
command had been specified.
-r Replace files in a tarfile. The named files are written
to the end of tarfile. This implies that later, the
appropriate files will be found more than once on the
tarfile.
-t Table of contents. List the contents of the tarfile.
Joerg Schilling Last change: 2020/09/04 5
Schily's USER COMMANDS STAR(1)
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/epax
format. The option -a or -atime lists the access time
instead of the modification time, the option -ctime
lists the file creation time instead of the 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 extracts no file which is older than the
corresponding file on disk.
On operating systems with slow file I/O (such as Linux
with any filesystem or platforms with Copy on Write
filesystems like ZFS), it may help to use -no-fsync in
addition (see also ENVIRONMENT and FILES), but then
star is unable to detect all error conditions; so use
with care.
Except for the shorthands documented above, exactly one of
the commands above must be specified.
If one or more patterns or substitution commands have been
specified, they apply to any of the command listed above.
In copy mode, all patterns and substitute commands apply to
the create side.
OPTIONS
-help
Print a summary of the most important options for
star(1).
-xhelp
Print a summary of the less important options for
star(1).
-/ Don't strip leading slashes from file names when
extracting an archive. Tar archives containing abso-
lute pathnames are usually a bad idea. With other tar
Joerg Schilling Last change: 2020/09/04 6
Schily's USER COMMANDS STAR(1)
implementations, they may possibly never be extracted
without clobbering existing files. Star for that rea-
son, 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.
-7z run the input or output through a p7zip pipe - see
option -z below.
Note that the p7zip program currently does not operate
on a pipe but on a /tmp file copy and thus limits the
maximum archive size.
-0
-1
-2
-3
-4
-5
-6
-7 Select an archive entry from /etc/default/star. The
format for the archive entries is the same as the for-
mat in /etc/default/tar in Solaris.
-acl Handle Access Control List (ACL) information in create
and extract mode. If -acl has been specified, star is
in create mode and the header type is exustar, star
will add ACL information to the archive using
POSIX.1-2001 extended headers. If -acl has been speci-
fied and star is in extract mode, star will try to
Joerg Schilling Last change: 2020/09/04 7
Schily's USER COMMANDS STAR(1)
restore ACL information. If there is no ACL information
for one or all files in the archive, star will clear
the ACL information for the specific file. Note that
if -acl has not been specified, star will not handle
ACL information at all and files may inherit ACL infor-
mation from the parent directories. If the -acl option
has been specified, star assumes that the -p option has
been specified too.
Star currently supports ACLs from the withdrawn
POSIX.1e draft and NFSv4 ACLs. To check which ACL fla-
vors are supported on the current platform, call star
-version. Whether ACLs from the withdrawn POSIX.1e
draft can be converted into NFSv4 ACLs depends on the
local ACL support library.
artype=headertype
Generate a tape archive in headertype format. If this
option is used in extract/list mode this forces star to
interpret the headers to be of type headertype. As star
even in case of a user selected extract archive format
does format checking, it may be that you will not be
able to unpack a specific archive with all possible
forced archive formats. Selecting the old tar format
for extraction will always work though. Valid parame-
ter for headertype are:
help Print a help message about possible header
types.
v7tar Old UNIX V7 tar format. This archive format
may only store plain files. Pathnames or
linknames longer than 99 chars may not be
archived.
If the v7tar format has been selected, star
will not use enhancements to the historic
UNIX V7 tar format. File size is limited to
2 GB - 2 bytes, uid/gid is limited to 262143.
Sparse files will be filled up with zeroes.
tar Old BSD UNIX tar format. This archive format
may only store plain files, directories and
symbolic links. Pathnames or linknames
longer than 99 chars may not be archived.
See also the -d option as a note to some even
older tar implementations.
If the tar format has been selected, star
will not use enhancements to the historic tar
format. File size is limited to 2 GB - 2
bytes, uid/gid is limited to 262143. Sparse
Joerg Schilling Last change: 2020/09/04 8
Schily's USER COMMANDS STAR(1)
files will be filled up with zeroes.
star Old star standard format. This is an
upward/downward compatible enhancement of the
old (pre Posix) UNIX tar format. It has been
introduced in 1985 and therefore is not Posix
compliant. The star format allows to archive
special files (even sockets) and records
access time and creation time besides the
modification time. Newer versions of the old
star format allow very long filenames
(100+155 chars and above), linknames > 100
chars and sparse files (if -sparse is used).
This format is able to copy the device nodes
on HP-UX that have 24 bits in the minor dev-
ice number, which is more then the 21 bits
that are possible with the POSIX-1003.1-1988
archive format.
The nonstandard extensions are located in the
space between the link name and the POSIX
file name prefix. As the star format does
not use a POSIX magic string, the extensions
do not interfere with the POSIX tar formats.
The last 4 bytes of the tar header in the
star archive format contain a 'tar\0' signa-
ture.
This archive format supports very long path
names.
gnutar This is a commonly used, but unfortunately
not Posix compliant (although designed after
1987) enhancement to the old tar format. The
gnutar format has been defined between 1989
and 1994. Do not use the gnutar archive for-
mat 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.
GNU tar is not able to extract files with
with long path names, but under some condi-
tions creates archives with long path names.
We therefore do not limit the creation of
gnutar archives with long path names.
Using the gnutar archive format causes a high
risk that the resulting archive may only be
Joerg Schilling Last change: 2020/09/04 9
Schily's USER COMMANDS STAR(1)
read by gnutar or by star. The implementa-
tion of the gnutar archive format within star
is not complete, but sufficient for most gnu-
tar archives. See NOTES for more informa-
tion.
This archive format supports very long path
names.
ustar IEEE/Posix1003/IEC-9945-1-1988 Standard Data
Interchange format. With this option in
effect, star will generate 100% POSIX.1-1988
compliant tar archives. Files with pathnames
longer than 100+155 chars or linknames longer
than 100 chars may not be archived. If star
is called as ustar the default archive format
is ustar.
If the ustar format has been selected, star
will not use enhancements to the POSIX.1-1988
tar format, the archive will be strictly con-
forming. File size is limited to 8 GB,
uid/gid/major/minor is limited to 2097151.
Sparse files will be filled up with zeroes.
pax The IEEE/Posix1003/IEC-9945-1-1988 successor
is the POSIX-1003.1-2001 Standard Data Inter-
change 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 con-
forming. File size is unlimited,
uid/gid/uname/gidname is unlimited,
major/minor is limited to 2097151. Sparse
files will be filled up with zeroes.
This archive format supports very long path
names.
epax A format similar to the pax format but with
forced POSIX.1-2001 extended headers. This
enforces stimestamps with nanosecond resolu-
tion in the archive.
This archive format supports very long path
names.
xstar The extended standard tar format has been
introduced in 1994. Star uses the xstar for-
mat as default archive format. This is an
Joerg Schilling Last change: 2020/09/04 10
Schily's USER COMMANDS STAR(1)
upward/downward compatible enhancement of the
IEEE/Posix1003/IEC-9945-1 Standard Data
Interchange format. It allows among others
very long filenames (100+130 chars and above)
and records access time and creation time.
Sparse files will be archived correctly (if
-sparse is used).
The access time and creation time are stored
at the end of the POSIX file name prefix
(this limits the prefix to 130 chars). These
extensions do not interfere with the POSIX
standard as the fields for mtime and ctime
field are always separated from the POSIX
file name prefix by a null byte. The last 4
bytes of the tar header contain a 'tar\0'
signature.
The xstar format is the default format when
star is neither called as tar nor called as
ustar.
This archive format supports very long path
names.
xustar A new format introduced 1998, that omits the
'tar\0' signature at the end of the tar
header. It is otherwise identical to the
xstar format. As some tar implementations do
not follow the POSIX rules and compute the
checksum for less than 512 bytes of the tar
header, this format may help to avoid prob-
lems with these broken tar implementations.
The main other difference to the xstar format
is that the xustar format uses POSIX.1-2001
extended headers to overcome limitations of
the historic tar format while the xstar for-
mat uses proprietary extensions. The xustar
format is the default format when star is
called as tar.
File size is unlimited, uid/gid/uname/gidname
is unlimited, major/minor is unlimited.
Sparse files will be archived correctly (if
-sparse is used).
This archive format supports very long path
names.
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
Joerg Schilling Last change: 2020/09/04 11
Schily's USER COMMANDS STAR(1)
option, star records Access Control Lists
(ACLs) in POSIX.1-2001 extended headers.
The exustar format allows to archive all file
types but it does not archive more than the
POSIX.1-1988 set by default. If the -dump
option is used or if star is otherwise on
dump mode, star archives all file types and
in addition archives more meta data then
usual.
File size is unlimited, uid/gid/uname/gidname
is unlimited, major/minor is unlimited.
Sparse files will be archived correctly (if
-sparse is used).
This archive format supports very long path
names.
suntar The extended header format found on Solaris
7/8/9. This format is similar to the pax for-
mat but does not handle atime and ctime and
in addition uses 'X' as the typeflag for the
extended headers instead of the standard 'x'.
File size is unlimited, uid/gid/uname/gidname
is unlimited, major/minor is unlimited.
Sparse files will be filled up with zeroes.
bin The cpio UNIX V7 binary format. This is a
format with big interoperability problems.
Try to avoid this format. It is only present
to make the scpio command SVr4 compliant.
cpio The POSIX.1-1988 cpio format. This format
uses octal ascii headers. A similar format is
created by calling cpio -o -c on pre SYSVr4
systems and by calling cpio -o -Hodc on
SYSVr4 systems. The POSIX.1-1988 cpio format
allows a file name length up to 262142 char-
acters and allows to archive nearly any file
type. File size is limited to 8 GB,
uid/gid/st_dev is limited to 262143. The way
major and minor device numbers are stored
inside the st_dev field is implementation
dependent.
Even though this archive format is covered by
the POSIX.1-1988 standard, it has a lower
portability than the ustar format. Try to
avoid the cpio archive format.
Joerg Schilling Last change: 2020/09/04 12
Schily's USER COMMANDS STAR(1)
odc This archive format is similar to the The
POSIX.1-1988 cpio format but the file name
length is limited to 255 characters and the
socket file type is not allowed. This
archive format has been introduced to allow
non POSIX cpio implementations such as the
cpio program on SYSV to accept the archive.
Use this format whenever you are not sure if
the target system offers a fully POSIX com-
pliant cpio program.
Even though this archive format is covered by
the POSIX.1-1988 standard, it has a lower
portability than the ustar format. Try to
avoid the odc archive format.
asc Tell star to create a cpio archive in the
ascii format that is created with cpio -o -c
on SYSVr4 systems. It uses extended (32 bit)
numbers for uid's, gid's and device numbers
but limits the file size to 4 GB - 2 bytes
although the format has been specified after
the POSIX.1-1988 cpio format. Try to avoid
the asc archive format because of its limited
portability.
crc This format is similar to the asc cpio format
but in addition uses a simple byte based 32-
bit checksum. Hence the archive type name
CRC as used by AT&T is misleading. Try to
avoid the crc archive format because of its
limited portability.
All tar archive formats may be interchanged if the
archive contains no files that may not be archived by
using the old tar format. Archives in the xstar format
may be extracted by any 100% POSIX compliant tar imple-
mentation 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:
Joerg Schilling Last change: 2020/09/04 13
Schily's USER COMMANDS STAR(1)
remove 'filename' ? Y(es)/N(o) :
-atime, -a
Reset access time of files after storing them to tar-
file. On Solaris 2.x, (if invoked by root) star uses
the _FIOSATIME ioctl to do this. This enables star not
to trash the ctime while resetting the atime of the
files. If the -atime option is used in conjunction
with the list command, star lists access time instead
of modification time. (This works only in conjunction
with the star, xstar, xustar, exustar, and with the
pax/epax 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.
b=# Set the block size for tape operations. See option
blocks=#.
-block-number
Print the archive block number (archive offset / 512)
at the beginning of each line when in verbose mode.
This allows to write backup scripts that archive the
offsets for files and that use
mt fsr blockno
to skip to the tape block number of interest in a fast
way if a single file needs to be restored.
Since the numbers printed by the -block-number option
are based on a block size of 512 bytes and the tape
block size is usually larger, the tape block number for
the mt fsr command needs to be computed to honor the
tape blocking factor.
blocks=#, b=#
Set the blocking factor of the tarfile to # times
512 bytes (unless a different multiplication factor has
been specified - see bs= option for possible multipli-
cation 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
Joerg Schilling Last change: 2020/09/04 14
Schily's USER COMMANDS STAR(1)
use a blocking factor of 20 i.e. 10 kBytes. Increasing
the blocksize will speed up the backup. For portabil-
ity with very old tar implementations (pre BSD 4.2 or
pre AT&T SVR4), blocksize should not be more than
10 kBytes. For POSIX.1-1988 compatibility, blocksize
should be no more than 10 kBytes. For POSIX.1-2001
compatibility, blocksize should be no more than
32 kBytes. Most systems also have a hardware limita-
tion for the blocksize, 32 kBytes and 63 kBytes are
common limits on many systems. The upper limit in any
case is the size of the buffer RAM in the tape drive.
Make a test if you want to make sure that the target
system will handle the intended blocksize. If you use
star for data exchange via tape, it is a good idea to
use a blocksize of 10 kBytes unless you are sure that
the reading system will handle a larger blocksize. If
you use star for backup purposes with recent hardware
(e.g. DLT tape drives), a blocksize of 256 kBytes
results in sufficient speed and seems to be a good
choice. Star allows block sizes up to 2 GByte if the
system does not impose a smaller limit. If you want to
determine the blocking factor when reading an unknown
tar archive on tape, specify a blocking factor that is
higher than the supposed blocking factor of the tape.
Star then will determine the blocking factor by reading
the first record of the tape and print a message:
star: Blocksize = # records.
Where # is the blocking factor in multiples of 512
bytes. The blocks= option and the bs= option are
equivalent methods to specify the tape block size. The
blocks= option is preferred by people who like to use
an option that behaves similar to the interface of the
historic tar(1) implementations.
The best method to set the blocksize is to use the bs=#
option.
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 mul-
tiplied 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 separated by `x' or `*',
multiplication of the two numbers is performed. Thus
bs=7x8k will specify a blocksize of 56 kBytes. Block-
size must be a multiple of 512 bytes. See also the
description of the blocks= option for more details on
blocksizes. The option bs= is preferred by people who
Joerg Schilling Last change: 2020/09/04 15
Schily's USER COMMANDS STAR(1)
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 direc-
tory until a new C= is seen. With BSD tar, the C=
option is only related to the next file type argument.
-bz run the input or output through a bzip2 pipe - see
option -z -Z and -j below. As the -bz the -j the -Z
and the -z option are non standard, it makes sense to
omit the -bz the -j the -Z and the -z options inside
shell scripts if you are going to extract a compressed
archive that is located inside a plain file as star
will auto detect compression and choose the right
decompression option to extract.
C=dir
-C dir
Perform a chdir(2) operation to dir before storing or
extracting the next files. In all cases, star will
perform the chdir(2) operation relative to the current
working directory of the shell.
+ In list mode (with the -t flag), star ignores all
-C options.
+ In create mode (with the -c, -r and -u flag), star
walks through all -C options and file type argu-
ments. While a BSD derived tar(1) implementation
goes back to the current working directory after
storing one file argument that immediately follows
the -C option, star changes the directory only if
a new -C option follows. To emulate the behavior
of a BSD derived tar(1), add a -C . option after
the file argument.
+ In extract mode (with the -x, -n and -diff flag),
star builds a pattern list together with
corresponding directories from previous C=dir
options and performs a chdir(2) to the correspond-
ing directory of a matching pattern. All pat=
options that do not follow a C=dir option are
interpreted as if they were preceded by a -C .
option. See EXAMPLES for more information.
compress-program=name
Set a named compress program. The program must
compress in a pipe when called without parameters and
decompress when run with the -d option in a pipe. This
Joerg Schilling Last change: 2020/09/04 16
Schily's USER COMMANDS STAR(1)
option is otherwise similar to the -z the -j the -Z and
the -bz option.
-copydlinks
Try to recursively copy the content of linked direc-
tories instead of creating the link. This is an experi-
mental feature that may help to unpack archives on DOS.
-copyhardlinks
This option allows to copy hardlinked targets rather
than creating the link. It helps to extract tar files
on systems that do not implement hardlinks (e.g. BeOS).
-copylinks
This option allows to copy both, hard- and symlinked
targets rather than creating a link. It helps to
extract tar files on systems that do not implement
links (e.g. OS/2). To extract and copy all symlinks
correctly, you may need to call star twice as star can-
not 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 point-
ing to them.
-cpio-statistics
Instead of the star flavor of the statistics, print
statistics in cpio flavor.
-ctime
If used with the list command, this lists ctime rather
than mtime if the archive format is star, xstar, xus-
tar, exustar, or pax/epax.
If star is run as root and if -ctime is used with the
extract command and the same archive formats, this
causes star to try to restore even the ctime of a file
by generating time storms. You should not do this when
in multi user mode because this may confuse programs
like cron and the news system. Although star tries to
eliminate the accumulative effects of the time storm,
there is a tendency for the system clock to slow down a
bit. The clock typically lags about one millisecond
per extracted file. Use with care and check the system
clock after using this feature.
Joerg Schilling Last change: 2020/09/04 17
Schily's USER COMMANDS STAR(1)
If used with the create command this changes the
behavior of the newer= option. Star, in this case com-
pares the ctime of all files to the mtime of the stamp
file rather then comparing the mtimes of both files.
-cumulative
A shorthand for -dump-cumulative. See -dump-cumulative
for more information.
-D Do not descend directories when in create mode. Nor-
mally, star descends the whole tree if it encounters a
directory in in its file parameters. The option -D is
in effect by default if the list=file option is used.
If you like star to descend directories found in the
list file, use the -dodesc option (see below).
-d Do not store/create directories. Old versions of tar
such as published with the seventh edition of UNIX are
not able to deal with directories in tar archives. If a
tar archive is generated without directories this
avoids problems with tar implementations found on
SYSVr3 and earlier. If used during extract, no inter-
mediate missing directories are created.
-data-change-warn
If the size of a file changes while the file is being
archived, treat this condition as a warning only that
does not cause a non zero exit code. A warning message
is still written if the condition is not otherwise
ignored by another rule from an errctl= option. The
-data-change-warn option works as if the last error
control option was
errctl="WARN|GROW|SHRINK *"
The -e option or an ABORT entry in a condition set up
by errctl= has a higher precedence than the
-data-change-warn option. This option is ignored in
extract or list mode.
-debug
Print debug messages. Among other things, this gives
debug messages for header type recognition, tar type
properties, EOF recognition, opening of remote archives
and fifo internals.
diffopts=optlst
Comma separated list of diffopts. Valid members in
optlst are:
help Print a summary of possible members of the
diffopts list.
Joerg Schilling Last change: 2020/09/04 18
Schily's USER COMMANDS STAR(1)
! Invert the meaning of the following string.
No comma is needed after the exclamation
mark.
not Invert the meaning of all members in the dif-
fopts list i.e. exclude all present options
from an initially complete set compare list.
When using csh(1) you might have problems to
use ! due to its strange parser. This is why
the not alias exists.
perm Compare file permissions. With this option in
effect, star compares the low order 12 bits
of the st_mode field.
mode Same as perm.
symperm Compare permissions even in case the target
file on the local filesystem is a symbolic
link. By default, star will not compare the
permission of symbolic links as most systems
cannot set the permission of symbolic links.
Star compares symperm only if perm is com-
pared also.
type Compare file type. Note that star cannot com-
pare the file type in case of a hard link.
nlink Compare link count on hardlinks for all types
of files. This only works if the archive is
in exustar format and contains star's dump
extensions.
dnlink Compare link count on hardlinks for direc-
tories. If comparing dnlink is excluded but
nlink is not excluded, this allows to deal
with filesystems that differ in their direc-
tory implementation. The link count of
directories in POSIX is equal to the number
of manually created additional hard links + 1
(as with other file types), while on histori-
cal UNIX filesystems it is equal to the
number of sub-directories + 2 + number of
manually created additional hard links. This
only works if the archive is in exustar for-
mat 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.
Joerg Schilling Last change: 2020/09/04 19
Schily's USER COMMANDS STAR(1)
The user name is mapped via the file
/etc/passwd.
gname Compare ASCII version of group id of file.
The group name is mapped via the file
/etc/group.
id Shorthand for: uid,gid,uname,gname. Compare
all user/group related info of file. Note
that this will always find differences if the
source and target system use different user
or group mappings.
size Compare file size. Note that star cannot
compare the file size in case of a hard link.
data Compare content of file. If star already
found that the size of the files differ, it
will not compare the content anymore. If the
size of the files differ, star will always
report different data.
cont Same as data.
rdev Compare major/minor numbers for device nodes.
hardlink Compare target of hardlinks.
symlink Compare target of symlinks. This evaluates
the paths returned by the readlink(2) call.
Two symlinks are considered equal, it they
either have a characterwise identical link-
name, or if they either both use an absolute
path name or both use a relative path name
and the following is true: Both symlinks
point to the same file that must exist or
both pathnames look similar enough.
sympath Compare the target pathnames of symlinks.
This characterwise compares the strings
returned from the readlink(2) call.
sparse Compare if either both files are sparse or
not. If only one of both files is sparse,
then a difference is flagged. This only
works with if the archive format is star,
xstar, xustar, exustar, or gnutar.
atime Compare access time of file. This only works
with if the archive format is star, xstar,
xustar, exustar, or pax/epax.
Joerg Schilling Last change: 2020/09/04 20
Schily's USER COMMANDS STAR(1)
mtime Compare modification time of file.
ctime This only works with if the archive format is
star, xstar, xustar, exustar, or pax/epax.
lmtime Compare the modification time even in case
the target file on the local filesystem is a
symbolic link. By default, star will not
compare the modification time of symbolic
links as most systems cannot set the modifi-
cation time of symbolic links. Star compares
lmtime only if mtime is compared also.
times Shorthand for: atime,mtime,ctime.
nsecs Check nanoseconds in all selected timestamps
as well.
Note that the time resolution of various
filesystem differs. While modern filesystems
like ZFS and filesystems that introduced a
sub-second resolution recently, tend to sup-
port a nanosecond granularity, filesystems
like UFS that support a sub-second resolution
since the early 1990s tend to support only a
microsecond granularity. Since even in in
2018, the POSIX.1-2008 feature
pathconf(_PC_TIMESTAMP_RESOLUTION) has not
yet been implemented on any platform, you may
need to disable to compare nanoseconds in
some cases.
Star currently first tries to compare the
timestamps based on a nanosecond resolution
and if that fails and one timestamp seems to
have a microsecond resolution, the comparison
is repeated with microsecond resolution only.
dir Compare the content of directories. This
only works if the archive is in exustar for-
mat and contains star's dump extensions.
Together with increased verbose level (-vv)
this will print a list of files that are only
in the archive and a list of files that are
only on the current filesystem.
xtimes Shorthand for: atime,mtime,ctime,lmtime.
acl Compare access control lists. This only
works if the archive is in exustar format and
has been created with star's -acl option.
You need to specify the -acl option in
Joerg Schilling Last change: 2020/09/04 21
Schily's USER COMMANDS STAR(1)
addition when running the diff.
xattr Compare extended file attributes. This only
works if the archive is in exustar format and
has been created with star's -xattr option.
You need to specify the -xattr option in
addition when running the diff.
fflags Compare extended file flags. This only works
if the archive is in exustar format and has
been created with star's -xfflags option.
You need to specify the -xfflags option in
addition when running the diff.
If optlst starts with a ! the meaning of all members in
optlst is inverted as with the not optlist member. In
this case, star starts with a complete list that
includes atime and lmtime. Reasonable diff options to
use when comparing against a copy of a directory tree
are diffopts=!atime,ctime,lmtime.
If diffopts are not specified, star compares everything
but the access time of the files and the modification
time of symbolic links.
dir-group=group
If star extracts archives as root, this option allows
to control the group id of intermediate directories
created by star.
dir-owner=user
If star extracts archives as root, this option allows
to control the owner of intermediate directories
created by
-dirmode
If in create mode (i.e. when storing files to archive),
star stores directories past the corresponding files.
This guarantees that even old tar implementations
without a directory cache will be able to restore the
correct times of directories. The option -dirmode
should only be used if the archive needs to be
extracted by an old tar implementation. If star is used
to extract an archive that has been created with -dir-
mode the directories will not get an old time stamp
unless the option -U is used while extracting the
archive.
-do-fsync
Tell star to call fsync(2) for every file when in
extract mode. This enables star to check whether a
file could be successfully extracted. See -no-fsync
Joerg Schilling Last change: 2020/09/04 22
Schily's USER COMMANDS STAR(1)
for more information.
-dodesc
Force star to descend directories found in a list=file.
See also the -D option above. The -dodesc option only
works in create mode.
-dump
Allows to create archives with the same number of
attributes as an archive that has been created with the
level= option but without the restrictions that apply
to a true dump.
The resultant archive may be seen as a level-less dump
which includes similar attributes as a level 0 dump but
may span more than a single file system and does not
need to use a -C option. It has been originally intro-
duced 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 information on true incremental dumps.
-dump+
Works similar to -dump but creates more global archive
header meta data, e.g. the SCHILY.volhdr.hostname tag.
This helps to understand where a tar archive has been
created.
-dump-cumulative
instructs star to perform incremental dumps relatively
to the last incremental dump of the same level. Incre-
mental dumps with a level higher than 0 are normally
done relatively to the content of a previous dump with
lower level. If incremental dumps and restores are
going to be used to synchronize filesystem content,
every successive incremental dump will increase in size
if -dump-cumulative is not used. See section SYNCHRON-
IZING FILESYSTEMS for more information.
dumpdate=name
Tells star to use the mtime of the time stamp file name
instead of using the start time of star. This is
needed when star is run on file system snapshots. If
star would use the the it's own 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.
Joerg Schilling Last change: 2020/09/04 23
Schily's USER COMMANDS STAR(1)
A solution is to create the time stamp file, then to
create the snapshot and later use the option
dumpdate=name.
-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 unex-
pected error occurs. The -e option works as if the
last error control option was
errctl="ABORT|ALL|DIFF *"
This allows to use the errctl= option together with the
-e option and thus to ignore some error conditions
while aborting on all other conditions.
errctl= name
errctl= error control spec
Add the content from file name to the error control
definitions or add error control spec to the error con-
trol definitions. More than one error control file and
more than one error control spec as well as a mixture
of both forms is possible.
The reason for using error control is to make star
quiet about error conditions that are known to be
irrelevant on the quality of the archive or restore run
or to tell star to abort on certain error conditions
instead of trying to continue with the archive.
A typical reason to use error control is to suppress
warnings about growing log files while doing a backup
on a live file system. Another typical reason to use
error control is to tell star to abort if e.g. a file
could not be archived instead of continuing to archive
other files from a list.
The error control file contains a set of lines, each
starting with a list of error conditions to be ignored
followed by white space followed by a file name pattern
Joerg Schilling Last change: 2020/09/04 24
Schily's USER COMMANDS STAR(1)
(see match(1) or patmatch(3) for more information).
The error control spec uses the same syntax as a single
line from the error control file. If the file name
pattern needs to start with white space, use a
backslash to escape the start of the file name. It is
not possible to have new line characters in the file
name pattern. Whenever an error situation is encoun-
tered, star checks the lines in the error control file
starting from the top. If the current error condition
is listed on a line in the error control file, then
star checks whether the pattern on the rest of the line
matches the current file name. If this is the case,
star uses the current error control specification to
control the current error condition.
The list of error conditions to be handled may use one
or more (in this case separated by a '|' character)
identifiers from the list below:
ABORT If this meta condition is included in an
error 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 leat
another error condition or a list of error
conditions (separated by a '|' character).
WARN If this meta condition is included in an
error condition, star prints the warning
about the error condition but the error
condition does not affect the exit code of
star and the error statistics (which is
printed to the end) does not include the
related errors. This error condition flag
may only be used together with at another
error condition or a list of error condi-
tions (separated by a '|' character). The
WARN meta condition has a lower precedence
than ABORT.
DIFF Suppress output in case that star -diff did
encounter any differences.
ALL This is a shortcut for all error conditions
below.
STAT Suppress warnings that star could not
stat(2) a file.
GETACL Suppress warnings about files on which star
had problems to retrieve the ACL
Joerg Schilling Last change: 2020/09/04 25
Schily's USER COMMANDS STAR(1)
information.
OPEN Suppress warnings about files that could
not be opened.
READ Suppress warnings about read errors on
files.
WRITE Suppress warnings about write errors on
files.
READLINK Suppress warnings about 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 attri-
bute information.
CHDIR Suppress warnings about chdir(2) errors.
ICONV Suppress warnings about iconv(3) errors.
These error happen, when text is converted
from or to POSIX.1-2001 extended tar
headers.
ID Suppress warnings about uid/gid range
errors. These errors happen when the
archive format does not support the actual
value.
SETTIME Suppress warnings about files on that star
Joerg Schilling Last change: 2020/09/04 26
Schily's USER COMMANDS STAR(1)
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 target
names that start with '/' or have a '/../'
sequence inside when -no-secure-links has
not 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 about 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 condi-
tions, you may not be able to see real problems anymore.
Joerg Schilling Last change: 2020/09/04 27
Schily's USER COMMANDS STAR(1)
-exclude-from name
Exclude from named file, this is an alias for the -X
option. See -X option for more information.
-F,-FF ...
Fast and simple exclude option for create mode. With
one -F 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 end-
ing with .o. OBJ/. With three -F arguments, star
ignores all sub trees starting from a directory that
includes a file .mirror or .exclude and all object
files and files called core errs a.out all files ending
with .o. With four -F arguments, star ignores all sub
trees starting from a directory that includes a file
.mirror or .exclude the latter files are excluded too
as well as and all object files and files called core
errs a.out all files ending with .o. With five -F
arguments, star in addition again excludes all direc-
tories called SCCS and RCS.
f=tarfilename
Use tarfilename as the name for the tar archive. See
option file=tarfilename.
-fifo
Use a fifo to optimize data flow from/to tarfile. This
option is in effect by default (it may be changed at
compile time). The default fifo size is 8 MBytes on
all platforms except Linux versions that do not support
mmap() (4 MB because kernels before 2.4 did not handle
big shared memory areas) and Sun/mc68000 (1 MB). This
will star make even work on a tiny machine like a Sun
3/50. The fifo size may be modified with the fs=
option. A rule of thumb for the fifo size is to use
more than the buffer size of the tape drive and less
then half of the real memory of the machine. A good
choice would be to use a fifo size between 8 and 256
MB. This may increase backup speed up to 5% compared
to the speed achieved with the default fifo size. Note
that with a DLT drive from y2000 that gives 12MB/s
transfer rate, a fifo of 256 MB size will keep the tape
at least streaming in units of 20 seconds.
Future LTO tape drives are expected to implement
transfer rates of aprox. 3GB/s and need a much larger
fifo size to keep the tape streaming.
All options that start with the -f sequence are sensi-
tive to typo problems, see BUGS section for more infor-
mation.
Joerg Schilling Last change: 2020/09/04 28
Schily's USER COMMANDS STAR(1)
-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. Speci-
fying 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 tar-
file is a remote archive, only the connection to this
archive will be created with root privileges. After
this connection has been established as root, star
switches back to the id of the caller. If any of the
other archives in the list is located on a different
host, star will not be able to open this archive later
on, unless run by root.
Star normally uses stdin/stdout for the tar archive
because the most common way to use star is in conjunc-
tion with pipes. If star is installed suid root or if
it has been called by root, tarfilename may be in
remote syntax: user@host:filename as in rcp(1) even if
invoked by non root users. See SUID NOTES for more
information.
To make a file local although it includes a colon (:),
the filename must start with: '/', './' or '../'
Note that if star talks to an old rmt remote tape
server that does not support symbolic open modes, it
does not open a remote tape with the O_CREAT open flag
because this would be extremely dangerous. If the rmt
server on the other side is the rmt server that comes
with star or the GNU rmt server, star may use the sym-
bolic mode for the open flags. Only the symbolic open
modes allow to send all possible open modes in a port-
able way to remote tape servers.
It is recommended to use the rmt server that comes with
star. It is the only rmt server that gives platform
independent compatibility with BSD, Sun and GNU rmt
clients and it includes security features that may be
set up in /etc/default/rmt. All options that start
with the -f sequence are sensitive to typo problems,
see BUGS section for more information.
Joerg Schilling Last change: 2020/09/04 29
Schily's USER COMMANDS STAR(1)
See -rsh option on how to set up a different protocol
for the connection to the remote tape server.
See ENVIRONMENT section for information on how to use
ssh(1) to create a remote tape server connection.
Note that if file=- has been specified, it is no longer
possible to use the -find -exec primary.
-find
This option acts a separator. If it is used, all star
options must be to the left of the -find option. To the
right of the -find option, star accepts the find com-
mand line syntax only.
The find expression acts as a filter between the source
of file names and the consumer, which may either be the
archiving engine or list/extract engine. If the find
expression evaluated as TRUE, then the related file is
selected for processing, otherwise it is omited.
In order to make the evaluation of the find expression
more convenient, star implements additional find pri-
maries that have side effects on the file meta data.
Star implements the following additional find pri-
maries:
-chatime timespec
The primary always evaluates as true; it modifies
the time of last access of a file in struct stat.
See sfind(1) for a description of timespec.
-chctime timespec
The primary always evaluates as true; it modifies
the time of last status change of a file in struct
stat. See sfind(1) for a description of timespec.
-chmtime timespec
The primary always evaluates as true; it modifies
the time of last modification of a file in struct
stat. See sfind(1) for a description of timespec.
-chgrp gname
The primary always evaluates as true; it sets the
group of the file to gname.
-chmod mode
The primary always evaluates as true; it sets the
permissions of the file to mode. Octal and sym-
bolic permissions are accepted for mode as with
chmod(1).
Joerg Schilling Last change: 2020/09/04 30
Schily's USER COMMANDS STAR(1)
-chown uname
The primary always evaluates as true; it sets the
owner of the file to uname.
-false
The primary always evaluates as false; it allows
to make the result of the full expression dif-
ferent from the result of a part of the expres-
sion.
-true
The primary always evaluates as true; it allows to
make the result of the full expression different
from the result of a part of the expression.
The command line:
star -c f=o.tar -find . ( -type d -ls -o false ) -o !
-type d
lists all directories and archives all non-directories
to the archive o.tar.
The command line:
star -c f=o.tar -find . ( -type d -chown root -o true )
archives all directories so they appear to be owned by
root in the archive, all non-directories are archived
as they are in the file system.
Note that the -ls, -exec and the -ok primary cannot be
used if stdin or stdout has been redirected by the
list=- of by the file=- options.
-force_hole
obsoleted by -force-hole
-force-hole
Try to extract all files with holes. This even works
with files that are created without the -sparse option.
Star, in this case examines the content of the files in
the archive and replaces writes to parts containing
binary zeroes with seeks.
If used together with the -sparse option in create
mode, star assumes all files to be sparse and archives
files with blocks of nulls as sparse files.
This option should be used with extreme care because
you sometimes get in trouble when files get unattended
holes. All options that start with the -f sequence are
Joerg Schilling Last change: 2020/09/04 31
Schily's USER COMMANDS STAR(1)
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 sensi-
tive to typo problems, see BUGS section for more infor-
mation.
-force-restore
Force an incremental restore even if there is a dump
level mismatch or a reference date mismatch. See
-wtardumps, level= and sections INCREMENTAL BACKUPS and
INCREMENTAL RESTORES for more information.
-freeze
run the input or output through a freeze pipe - see
option -z below.
fs=# Set fifo size to #. See bs= for the possible syntax.
The default size of the fifo is 1 Mbyte on Sun mc68000
systems, 4 Mbytes on non mmap() aware Linux systems and
8 Mbytes on all other systems. See -fifo option for
hints on using the right fifo size.
fs-name=mount_point
Use mount_point when recording information in
/etc/tardumps and when comparing against information in
/etc/tardumps for incremental backups. This makes
sense when backups are made using file system snapshots
and allows /etc/tardumps and the archive to contain the
real name of the file system instead of the 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
Joerg Schilling Last change: 2020/09/04 32
Schily's USER COMMANDS STAR(1)
Follow symbolic links as if they were files. Normally
star will not follow symbolic links but stores their
values in tarfile. See also the -L option.
-hardlinks
In extract mode, this option tells star to try to
create a hardlink whenever a symlink is encountered in
the archive. In create mode, this option tells star to
try to archive a hardlink whenever a symlink is encoun-
tered in the file system.
-hpdev
Allow 24 bits for the minor device number using 8 octal
digits. Note that although it allows to create tar
archives that can be read with HP-UX tar, this creates
tar archives which violate POSIX.1-1988. This option
is only needed if you like to use a POSIX.1-1988 based
archive format that does not include extensions. If
you use the xstar format, star will use a base 256
extension that allows bigger major/minor numbers by
default, if you use the xustar or the exustar format
there is no limitation at all as these formats use
POSIX.1-2001 extended headers to archive the
major/minor numbers by default.
-i Ignore checksum errors on tar headers. If this option
is specified, star will not exit if a header with a bad
checksum is found but search for the next valid header.
-install
Carefully replace existing files when extracting files.
This is done similar to install(1) by first extracting
the files into a temporary name and renaming the file
to the final name after the extraction of that file was
successful.
As star by default does not remove non-empty direc-
tories, an install that needs to remove existing non-
empty directories may also need the options
-force-remove and -remove-recursive.
iskip=#
Set the initial skip size to #. See bs= for the possi-
ble syntax.
The skip size is the number of bytes to ignore from the
first tape record. This option is typically used if a
tar archive on a tape is not read from the beginning
and the tape has been forwarded before the tape is
read. iskip= then specifies the offset of the first
archive header within the current tape record. It does
not work on compressed archives.
Joerg Schilling Last change: 2020/09/04 33
Schily's USER COMMANDS STAR(1)
-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-nonempty-dirs
Do not complain about trying to remove nonempty direc-
tories in case that -remove-recursive has not been
specified.
-keep_old_files
obsoleted by -keep-old-files
-keep-old-files, -k
Keep existing files rather than restoring them from
tarfile. This saves files from being clobbered even if
tarfile contains a more recent version of the
corresponding file.
See SECURITY NOTES for more information.
-L, -h
Follow symbolic links as if they were files. Normally
star will not follow symbolic links but stores their
values in tarfile. See also the -h option.
-l Do not print a warning message if not all links to hard
linked files could be dumped. This option is evaluated
in the opposite way to historic tar(1) implementations
and to POSIX.1. POSIX.1 requests that by default no
warning messages will be printed and -l will enable
warning messages when not all links could be archived.
level=dumplevel
Set level for incremental dumps. This option is used
to switch star into true incremental dump mode. The
dumplevel may be in the range between 0..99.
In true incremental dump mode, a -C option which is
followed by the name a mount point and a dot ('.') as
starting directory name is required. Only a single file
system may be handled at a time. If the directory fol-
lowing the -C option is not referring to a root direc-
tory 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.
Joerg Schilling Last change: 2020/09/04 34
Schily's USER COMMANDS STAR(1)
By default, the tardumps database is not written. See
also the tardumps=name and -wtardumps options and the
section INCREMENTAL BACKUPS for more information.
-link-data
In create mode, include the data for files even if
these files are hard links. This feature in create mode
is currently only available for the exustar archive
format and only in case -sparse has not been specified.
In extract mode, allow star to deal with data in hard
linked files even if the standard would not allow this
for the used archive format.
-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 implementations create buggy archives
with respect to hard links. If star would look for
hard linked directories in all cases, it would detect
many pseudo hard links to directories. Use -link-dirs
with care if you extract cpio archives.
Note that not all filesystem allow to create hard links
to directories. Also note that even though a non-root
user is able detect and archive hard linked direc-
tories, all known operating systems require the extrac-
tion to be done as root in order to be able to create
or remove hard links to directories. For this reason
its only recommended to use this option when doing
accurate backups and when hard links to directories are
expected.
When the option -link-dirs is not used and hard links
to directories are present, the appendant sub-tree will
appear more than once on the archive and star will
print Linkcount below zero warnings for non directory
hard links inside the sub-tree.
list=filename
Read filenames for store/create/list/diff command from
filename. The file filename must contain a list of path
names, each on a separate line. This option implies
the -D option. To force star to descend directories,
use the -dodesc option in this case. See also the -X
Joerg Schilling Last change: 2020/09/04 35
Schily's USER COMMANDS STAR(1)
option.
If used together with -find, no path list is accepted
after the option -find.
See also the option pkglist= for a way to specify
filename, permission, owner and group.
Note that if list=- has been specified, it is no longer
possible to use the -find -exec primary.
-lowmem
Try to run with reduced memory requirements. This
causes star to default to 1 MB of FIFO memory. Instead
of allocating memory to hold the directory content and
reading the directory at once, star reads the directory
name by name. This may cause star to close the direc-
tory if it rans out of file descriptors because of dee-
ply nested directories. If a directory then does not
support telldir(3)/seekdir(3), star will fail.
-lzip
run the input or output through a lzip pipe - see
option -z below.
-lzma
run the input or output through a lzma pipe - see
option -z below.
-lzo run the input or output through a lzop pipe - see
option -z below.
-M, -xdev
Do not descend mount points. This is useful when doing
backups of complete file systems. See NOTES for more
information.
When using -find, this may not always work as expected,
e.g. when the /proc filesyestem is involved. Use -xdev
past -find for this reason.
-m Do not restore access and modification time. (Access
time is only available if star is reading star, xstar,
xustar, exustar, or pax/epax archives). If star
extracts other archive types, the -m flag only refers
to the modification time.
-match-tree
If in create mode a pattern does not match a directory,
and -match-tree has been specified, the whole directory
tree is excluded from the archive and from further
Joerg Schilling Last change: 2020/09/04 36
Schily's USER COMMANDS STAR(1)
directory scans. By default, star excludes the direc-
tory but still recursively scans the content of this
directory as complex patterns could allow files inside
the directory tree to match. Using -match-tree allows
to efficiently exclude whole trees from scanning. This
helps to avoid scannings directory trees that are on
remote file systems or contain excessive bad blocks.
maxsize=#
Do not store files in tarfile if they are bigger than
#. See bs= for the possible syntax. By default, the
number is multiplied by 1024, so the value counts in
units of kBytes. If the size specifier ends with a
valid multiplication character (e.g '.' for bytes or
'M' for MB) the specified size is used as specified and
not multiplied by 1024. See bs= option for all possi-
ble multipliers.
-meta
In create mode, -meta causes star to archive all meta
data of the file (e.g. uid, permissions, ...) but not
the file content. In extract mode, it causes star to
restore all meta data but not the file content. In
addition, in extract mode no plain file, special file
or directory will be created. Meta files are needed to
support incremental backups.
Warning: Do not try to extract star archives containing
meta files using other tar implementations if they are
not aware of the meta file extensions of star. Star
tries to force all tar implementations that are not
standard compliant to abort. Star also tries to make
all non POSIX.1-2001 compliant tar 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 back-
ups, I am looking for people and companies who like to
support me to be able to add the meta file concept to
the POSIX.1-2005 standard.
-modebits
This options allows you to create tar archives that
include more than 12 bits from st_mode. Note this
create tar archives that violate POSIX but some tar
implementations insist in reading such nonstandard
archives.
Joerg Schilling Last change: 2020/09/04 37
Schily's USER COMMANDS STAR(1)
mtskip=#
Set the initial archive skip amount to #. See bs= for
the possible syntax.
The archive skip size is the number of 512 byte blocks
to ignore before starting to read the archive. Typi-
cally, the value printed by the -block-number option is
used as the parameter.
This option is used if a tar archive on a tape is not
read from the beginning in order to fast forward to a
specific file. Check the -one-file option for a way to
extract only one file from the archive.
If the archive is a plain file, this option results in
a lseek() call to the input file. If the archive is a
magnetic tape, this option results in a mtioctl(MTFSR)
call for the part of the blocks that can be represented
by the tape block size followed by a skip of the
remainder of the blocks. Since star learns about the
tape block size from the first read() call, this option
does not work correctly if the tape block size used by
star does not match the tape block size on the medium.
See the blocks=# option above for information on the
tape block size.
If mtskip=# has been specified, a iskip=# option is
ignored and the value is rather computed from the
mtskip=# parameter. mtskip=# does not work on
compressed archives.
-multivol
Switch to multi volume mode. In multi volume mode,
there will be no logical EOF marker written to the end
of a single tape. If -multivol is used in read mode, a
hard EOF on input (if not preceded by a logical EOF)
triggers a medium change operation.
Specifying -multivol tells star to split files across
volumes if needed. This way, a virtual archive is
created that spans more than one medium. Multi volume
mode is needed whenever it is not possible to split the
archiving or extracting into several logically indepen-
dent 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
Joerg Schilling Last change: 2020/09/04 38
Schily's USER COMMANDS STAR(1)
together with tsize=# then a media change is initiated
exactly after an amount of tsize data has been written.
When -multivol has been specified in create mode and
tsize=# has not been specified, then the medium change
is triggered by a EOT condition from writing the
medium. This allows to use media where the size cannot
be known in advance (e.g. tapes with build in compres-
sion); it does not work if the EOT condition is not
returned in sync with the related write operation. For
this reason, it is expected that data buffering inside
a device driver cannot be used.
Depending on the selected archive format, star writes a
volume header at the beginning of a new medium. This
medium header allows to verify the correct volume after
a change during read back. It is recommended to use
the exustar format for best results. In create mode,
-multivol is only supported for archives types that
allow to write reliable multi volume header informa-
tion.
See tsize=# option for more information.
Note that -multivol is an interactive option that
prevents star from being used in non-interactive
environments. If you like to use it in a non-
interactive environment, you need to specify
new-volume-script=script in addition in order to auto-
mate the media change procedure.
newer=filename
Do not store files to tarfile if their modification
time is not newer than the modification time of
filename. See -ctime option for changing this behavior.
-newest
In conjunction with the list command this lists you
only the newest file in tarfile.
-newest_file
obsoleted by -newest-file
-newest-file
In conjunction with the list command this lists you
only the newest regular file in tarfile.
new-volume-script=script
Call script at end of each tape (even the last one) if
in multi volume mode or if the tsize= option has been
specified. If this option is not in effect, star will
ask the user to confirm the volume change. The script
is called with two parameters. The first parameter is
Joerg Schilling Last change: 2020/09/04 39
Schily's USER COMMANDS STAR(1)
the next volume number and the second parameter is the
next archive file name.
-nodump
If this option is set, star will not dump files that
have the nodump flag set. Note that this currently only
works on BSD-4.4 derivates and on Linux. On Linux,
using this option will cause a performance degradation
(the system time increases by 10%) because of the
unlucky kernel interface that requires a separate open
and ioctl.
-no-dirslash
Do not add a slash to the end of directory names if
writing to an archive. Historic tar archive formats
did only allow to specify plain files and hard links.
Around 1980, BSD added a feature to specify a directory
on tape by adding a slash to the end of the name.
POSIX.1-1988 defined the first official tar archive
format that had a clean method to specify the type of a
directory. As old tar formats need the slash to recog-
nize a directory, -no-dirslash may not be used if
archives should be compatible with the old tar format.
-no_fifo
obsoleted by -no-fifo
-no-fifo
Don't use a fifo to optimize data flow from/to tarfile.
Currently the -fifo option is used as default. (This
may be changed at compile time.)
-no-fsync
Do not call fsync(2) for each file that has been
extracted from the archive. Using -no-fsync may speed
up extraction on operating systems with slow file I/O
(such as Linux with any filesystem or platforms with
Copy on Write filesystems like ZFS), but includes the
risk that star may not be able to detect extraction
problems that occur after the call to close(2). A typ-
ical 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.
See also -do-fsync and STAR_FSYNC in ENVIRONMENT and
/etc/default/star for ways to configure the default
behavior.
-nochown, -o
Do not restore owner and group of files. This may be
used if super user privileges are needed to overwrite
Joerg Schilling Last change: 2020/09/04 40
Schily's USER COMMANDS STAR(1)
existing files but the local ownership of the existing
files should not change.
-no-p
Do not restore files and directories to their original
permissions. This option is needed only if star is
called by the super user and the permissions should not
be restored from the archive. See also the -p option.
The -p options has a higher precedence than the -no-p
option.
-no_statistics
obsoleted by -no-statistics
-no-statistics
Do not print statistic messages at the end of a star
run.
-no-secure-links
Extract hard links or symbolic links even if the target
of the link starts with a slash (/) or if /../ is con-
tained in the link target. See the description of the
option -secure-links below and STAR_SECURE_LINKS in
ENVIRONMENT and /etc/default/star for ways to configure
the default behavior.
-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 speci-
fied by the pattern or file operands.
-nowarn
Do not print warning messages. This sometimes is use-
ful to make the output more readable (e.g. when hun-
dreds of files that are going to be extracted are not
newer in the archive then on the filesystem).
-numeric
Use the numeric user/group fields in the listing rather
than the default. The default allows to list the ASCII
Joerg Schilling Last change: 2020/09/04 41
Schily's USER COMMANDS STAR(1)
version of user/group of the file and to extract the
owners of the files based on numeric values rather than
the names. In create mode, no user/groups names are
put on the archive. The -numeric option also applies
when ACLs are going to be archived or extracted.
-O Be compatible to old versions of tar. If star is
invoked with this option, star generates archives which
are fully compatible with old UNIX tar archives. If in
extract mode, star ignores any additional info in the
headers. This implies neither that archives generated
with this option are binary equal with archives gen-
erated by old tar versions nor that star is trying to
comprehend all bugs that are found in old tar versions.
The bug in old tar versions that cause a reversal of a
space and a NULL byte in the checksum field is not
repeated. If you want to have signed checksums you have
to specify the -signed-checksum option too. If you want
directories not to be archived in order to be compati-
ble to very old historic tar archives, you need to
specify the -d option too.
This option is superseeded by the H=headertype option.
-o, -nochown
Do not restore owner and group of files. This may be
used if super user privileges are needed to overwrite
existing files but the local ownership of the existing
files should not change.
-one-file
Exit star after one file has been extracted as a result
from a match with a pattern or with a command line
argument. This option is intended for users that need
to restore single files from larger tape archives and
do not like to wait until the end of the tape is
reached. To let star exit after the first file, call
-one-file together with pat=*. This is e.g. useful
together with the option mtskip=#.
-onull, -nullout
Do not actually write to the archive but compute and
add the sizes. This is useful when trying to figure
out if a tape may hold the current backup. Please only
use the -onull option as it is a similar option as used
by the sdd(1) command.
-P Allow star to write a partial record as the last
record. Normally, star writes each record with the same
size. This option is useful on unblocked tapes i.e.
cartridge tapes like QIC tapes as well as with archives
that are located in files. If you use this option on
Joerg Schilling Last change: 2020/09/04 42
Schily's USER COMMANDS STAR(1)
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 permis-
sions. Without this option, they are created using the
permissions in the archive and the present umask(2).
If star is called by the super user, star behaves as if
it has been called with the -p option. See also -no-p
option. If the archive contains Access Control Lists
(ACLs) in POSIX.1-2001 extended headers, star will
restore the access control lists from the archive for
files if the -acl option is specified. If the option
-acl has not been specified, ACLs are not restored at
all.
-partial
Force an incremental restore even if the incremental
dump is only a partial dump. See -wtardumps, level= and
sections INCREMENTAL BACKUPS and INCREMENTAL RESTORES
for more information.
pattern=pattern, pat=pattern
Set matching pattern to pattern. A maximum of 100
pattern=pat options may be specified. As each pattern
is unlimited in length, this is no real limitation. If
more than one pattern is specified, a file matches if
any of the specified pattern matches. Patterns may be
used in create mode to select or exclude files from the
list of file type arguments or the files located in a
sub tree of a file type argument directory. By
default, star scans the whole directory tree underneath
a directory that is in the argument list. This may be
modified by using the -match-tree option. In extract
or list mode, all file type arguments are interpreted
to be select pattern and all option type patterns may
be either select or exclude patterns depending on the
presence or absence of the -not option. If you use
file type select patterns, they work exactly like the
method used by other (non pattern aware) tar(1) imple-
mentations. File type select patterns do not offer
pattern matching but allow to restore subtrees. To
extract a complete sub tree from the directory dir with
star using the pattern= option, use pattern= dir/\* if
you like to select a subtree by using the historic
method, use dir as file type argument. If you only
like to extract the directory itself, use dir/ as file
type argument. See manual page for match(1) for more
details of the pattern matcher. All patterns are
Joerg Schilling Last change: 2020/09/04 43
Schily's USER COMMANDS STAR(1)
selection patterns by default. To make them exclude
patterns, use the -not or the -V option.
pkglist=file
This is (for now) an internal interface for the Schily
Source Package System (sps). It only works in create
mode and behaves similar to the list= option, but it
allows to overwrite the permissions, the uid and gid
values from the content of the pkglist= file. Each
line from the pkglist= file contains a file name fol-
lowed by the permission, a user name and a group name.
The permission is an octal character string. Each
value that is not used to overwrite the original values
may be replaced by a '?'. The fields are separated by
spaces, so the pkglist= option does not allow files
that contain newline or space characters.
If used together with -find, the uid, gid and permis-
sion values from the pkglist=file have precedence over
changes on this meta data introduced by libfind.
See list= option for further information.
-pax-c, -notarg
Match all file or archive members except those speci-
fied by the pattern or file operands.
-pax-H
Follow symbolic links that have been encountered on the
command line. If the referenced file does not exist,
the file information and type will be for the link
itself. If the link is referencing a file type that
cannot be archived with the current archive format, the
file information and type will be for the link itself.
-pax-i
Do interactive renaming in a way that has been defined
for POSIX pax. Star will print the original filename
and prompt for a reply. If you type just RETURN, than
the file is skipped. If you type '.', then the origi-
nal file name is retained. If you type anything else,
then this is taken as the new file name.
Note that -pax-i is an interactive option that prevents
star from being used in non-interactive environments.
-pax-L
Follow symbolic links. If the referenced file does not
exist, the file information and type will be for the
link itself. If the link is referencing a file type
that cannot be archived with the current archive for-
mat, the file information and type will be for the link
Joerg Schilling Last change: 2020/09/04 44
Schily's USER COMMANDS STAR(1)
itself.
-pax-ls
Switch listing format to the format defined for POSIX
pax and ls.
-pax-match
Allow file type arguments to be recognised as regular
expressions in a way that has been defined for POSIX
pax.
-pax-n
Allow each pattern to match only once. If a pattern
matches a directory, then the whole sub tree matches
the pattern.
-pax-o string
Set a pax like option control pattern.
The only argument that is currently supported is binary
to create a hdrcharset=BINARY header.
-pax-p string
PAX style privileges string. Several characters (each
has its own meaning). The following characters are
defined:
a Do not preserve file access times. This option is
currently ignored.
e Preserve the user ID, group ID, file mode bits.
This is equivalent to calling star -p -acl
-xfflags.
m Do not preserve file modification times. This is
currently equivalent to calling star -m.
o Preserve the user ID and group ID. This is the
default for star if called as root.
p Preserve the file mode bits. This is equivalent
to calling star -p.
-pax-s replstr
Modify file or archive member names named by a pattern
according to the substitution expression replstr. The
format of replstr is:
-pax-s /old/new/[gp]
The old pattern may use regular expressions and the new
Joerg Schilling Last change: 2020/09/04 45
Schily's USER COMMANDS STAR(1)
string may contain the special character '&'. The char-
acter '&' is substituted by the string that matches the
old pattern. The new string may also contain the spe-
cial strings '\1' .. '\9' that refer to parts of the
old string selected by '\(...\)' groups. 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 sub-
stitution 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.
The up to 100 substitute options are processed together
with the -s replstr options in the order they appear on
the command line.
If the name substitutes to the empty string, the file
is skipped.
If the target platform for star does not support regex
functions, there is a silent fallback to the -s replstr
option and the '\1' .. '\9' substitutions are not pos-
sible.
-prinodes
Print inode numbers in verbose list mode if the archive
contains inode numbers.
-print-artype
Check the type of the archive, print the archive and
compression type on a single line and exit.
-qic24
Set tape volume size to 61440 kBytes. See tsize=#
option for more information.
-qic120
Set tape volume size to 128000 kBytes. See tsize=#
option for more information.
-qic150
Set tape volume size to 153600 kBytes. See tsize=#
option for more information.
-qic250
Set tape volume size to 256000 kBytes. See tsize=#
option for more information.
-qic525
Set tape volume size to 512500 kBytes. See tsize=#
option for more information.
Joerg Schilling Last change: 2020/09/04 46
Schily's USER COMMANDS STAR(1)
-read0
Read null terminated file names from the file specified
with the list= option.
-refresh_old_files
obsoleted by -refresh-old-files
-refresh-old-files
-refresh
Do not create new files. Only already existing files
may be overwritten from tarfile if either newer ver-
sions are present in the archive or if the -U flag is
used. This allows to overwrite files by more recent
files from an archive that contains more files than the
target directory should contain. The option
-refresh-old-files is the same as the -refresh option.
-remove_first
obsoleted by -remove-first
-remove-first
Remove files before extraction. If this option is in
effect, star will remove files before extracting a file
from the archive. This is needed if you want to change
the file type or if you need to break a hard link. If
you do not use either -ask-remove or -force-remove
together with -remove-first, this option is useless and
no files will be removed.
-remove_recursive
obsoleted by -remove-recursive
-remove-recursive
Remove files recursive. If removing of a file is per-
mitted, star will only remove files, specials and empty
directories. If this option is in effect, star will be
allowed to recursively removes non empty directories
too.
-restore
switches star into true incremental restore mode. A
file named star-symtable and a directory named star-
tmpdir is created in the root directory of the file
system where the extraction takes place. If -restore
has been specified, star behaves as if -xdot has been
specified too. See also level= option and section
INCREMENTAL BACKUPS for more information.
Note: Do not use the -restore option if you only like
to restore a single file or a list of selected files.
Joerg Schilling Last change: 2020/09/04 47
Schily's USER COMMANDS STAR(1)
rmt=path
Specify the path to the program at the remote tape
server for the RMT protocol.
star by default calls the UNIX default path /etc/rmt.
Since most rmt implementations cause problems in case
that server and client are on a different OS, it is
recommended to tell star to call the rmt program that
comes with star (/opt/schily/sbin/rmt).
rsh=path
Specify the program to log into the remote tape server
for the RMT protocol. If the argument is the empty
string, connections are made via rcmd(3). The default
method to log into the remote server is configurable at
compile time. The current default is set up to use ssh.
-S Do not store/create special files. A special files is
any file except plain files, symbolic links and direc-
tories. You need to be super user to extract special
files.
-s replstr
Modify file or archive member names named by a pattern
according to the substitution expression replstr. The
format of replstr is:
-s /old/new/[gp]
The old pattern may use regular expressions and the new
string may contain the special character '&'. The char-
acter '&' is substituted by the string that matches the
old pattern. The optional trailing 'g' means global
substitution. If 'g' is not used, a substitution pat-
tern 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.
The up to 100 substitute options are processed together
with the -pax-s replstr options in the order they
appear on the command line.
If the name substitutes to the empty string, the file
is skipped.
-secure-links
Do not extract hard links or symbolic links if the tar-
get of the link starts with a slash (/) or if /../ is
Joerg Schilling Last change: 2020/09/04 48
Schily's USER COMMANDS STAR(1)
contained in the link target. Tar archives containing
such links could be used to compromise the system. If
they are unpacked together with a lot of other files,
this may not even be noticed.
Links that do not point outside the tree that starts
with the current working directory are not seen as a
security risk. This makes star easy to use. It is
always safe to unpack an unknown archive in an empty
directory.
Many system installations contain plenty of symbolic
links with absolute path name or with /../ inside. The
usability of a tar archiver for system backups and in
copy mode would be limited if -secure-links checking
would be done by default for backups or when in copy
mode, star thus makes link checking optional when in
-restore or in -copy mode. When neither -restore nor
-copy have been specified, link checking is the
default, since this is the usual way when archives from
unknown sources are going to be unpacked.
To turn off this default for the usual case, the option
-no-secure-links may be used and in -restore or -copy
mode, -secure-links may be specified to turn it on.
If you unpacked a tar archive while -secure-links is
effective 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. To speed this up, it helps to use:
star -xvpw -find -type l
See section SECURITY NOTES for more information and
STAR_SECURE_LINKS in ENVIRONMENT and /etc/default/star
for ways to configure the default behavior.
-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 com-
piled to have both code for mapped pages and for System
V shared memory, star will use shared memory instead of
the default. If the -help menu doesn't show the -shm
flag you have no choice. When using System V shared
memory, you may have to raise the system's internal
limit for shared memory resources to get enough shared
memory for star.
-signed_checksum
Joerg Schilling Last change: 2020/09/04 49
Schily's USER COMMANDS STAR(1)
obsoleted by -signed-checksum
-signed-checksum
Use signed chars to calculate checksums. This violates
the tar specs but old versions of tar derived from the
seventh edition of UNIX are implemented in this way.
Note: Only filenames and linknames containing chars
with the most significant bit set may trigger this
problem because all other fields only contain 7 bit
ASCII characters, octal digits or binary zeroes.
-silent
Suppress informational messages like foobar is sparse.
-sparse
Handle files with holes effectively on store/create.
Note that sparse files may not be archived this way if
the archive format is tar, ustar, suntar, pax, or any
cpio variant. On Solaris-2.3 ... Solaris-2.5.1 there
is a special ioctl() called _FIOAI that allows root to
get the allocation info more efficiently. On Solaris
11 there is an enhanced lseek(2) call with additional
whence values SEEK_HOLE and SEEK_DATA that allow to
find holes in an efficient way. Other operating sys-
tems lack support to get the real allocation list and
force star to scan the files to look for blocks that
only contain null characters. This may star cause to
assume more holes to be present than the number that
the file really contains.
-symlinks
This option tells star in extract mode to try to create
a symlink whenever a hardlink is encountered in the
archive.
-T If the option file= or f= is omitted and the -T option
is present, star will use the device indicated by the
TAPE environment variable, if set.
tardumps=name
Set the file name for tar dump dates database to name.
The default name is /etc/tardumps. Use in combination
with the level= option to create true incremental
dumps. See also -wtardumps option and section INCRE-
MENTAL BACKUPS for more information.
-time
Print timing info. See DIAGNOSTICS for more informa-
tion.
-to_stdout
obsoleted by -to-stdout
Joerg Schilling Last change: 2020/09/04 50
Schily's USER COMMANDS STAR(1)
-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 generate a name list. If used together with
the -diff option, star will only print the names of the
files that differ. A second run of star may then be
used to restore all files that had differences to the
archive. Use the list= option to specify the namelist
in this case.
tsize=#
Set tape volume size to # to enable multi volume tape
support. The value refers to the archive size without
compression. See bs= for the possible syntax. By
default, the number is multiplied by 512, so the value
counts in units of 512 byte blocks. If the size
specifier ends with a valid multiplication character
(e.g '.' for bytes or 'M' for MB) the specified size is
used as specified and not multiplied by 512. With this
option in effect, star is able to archive filesystems
that are bigger then the tape size. If the option
tsize=# without -multivol then no file will be split
across volumes and each volume may in theory be read
back separately. Files that do not fit on a single
tape may not be stored in this mode. If -multivol has
been specified in addition, star will split files when
the maximum allowed tape size has been reached. If the
tape volume size is not a multiple of the tape block
size, the tape volume size is silently rounded down to
a value that is a multiple of the tape block size.
See -multivol option for more information.
-U Restore files unconditionally. By default, an older
file from the archive will not replace a corresponding
newer file on disk.
umask=mask
Set star's umask to mask. This allows to control the
permissions for intermediate directories that are
created by star in extract mode. See also -p option.
-uncond-rename
When in interactive restore mode or when the -s option
was specified, unconditionally ask for a new name or
apply a substitution. This happens even when the
Joerg Schilling Last change: 2020/09/04 51
Schily's USER COMMANDS STAR(1)
current path name would be skipped otherwise because
the file in the archive is not newer than the file with
the original name on disk.
-v Increment verbose level by one. This normally results
in more output during operation. See also in the
description for the -t flag. Normally, star does its
work silently. If the verbose level is 2 or more and
star is in create or update mode, star will produce a
listing to the format of the ls -l output.
-V, -not
Invert the meaning of the pattern list. i.e. use those
files which do not match any of the pattern. Note that
this option only applies to patterns that have been
specified via the pattern=pattern or pat=pattern
option. Patterns specified as file type arguments will
not be affected.
-version
Print version information and exit.
VOLHDR=name
Use name to generate a volume header.
-w Do interactive creation, extraction or renaming. For
every file that matches the list of patterns and that
has a more recent modification time in the tar archive
(if in extract mode and the -U option is not specified)
star prints its name and asks:
get/put ? Y(es)/N(o)/C(hange name) :
You may answer either `N' for No or <Return> to skip
this file. If you answer `Y' the file is extracted or
archived on tape with its original name. If you answer
`C', you are prompted for a new name. This name is used
for the filename on disk if star is in extract mode or
for the archive name if star is in create mode.
See SECURITY NOTES for more information.
Note that -w is an interactive option that prevents
star from being used in non-interactive environments.
-wready
This option tells Star to wait up to two minutes for
the drive to become ready. It has been added as a hack
for a bug in the SunOS/Solaris st device driver. This
driver has problems to sense the loading time with Exa-
byte drives with factory settings. It also makes sense
to use -wready if multiple remote backups are made. In
Joerg Schilling Last change: 2020/09/04 52
Schily's USER COMMANDS STAR(1)
this case, the remote connection is closed while the
remote tape server is still writing a file mark. If
another remote backup is initiated before the old
remote server did finish to write the file mark, it
would be impossible to open the tape driver unless
-wready is specified to tell star to wait for the drive
to become ready again.
-wtardumps
Tell star to update the file that contains the tar dump
dates data base if in dump mode. If the dump is not a
full dump, the tar dump dates data base file is not
written. See also tardumps=name and -C option or
INCREMENTAL BACKUPS section for more information.
-X filename
Use the file filename as a file containing a list of
path names to be excluded from the
store/create/list/diff operation. The file filename
must contain a list of path names, each on a separate
line. Be careful with white space and note that path
names in the list may not contain new lines. Multiple
-X options may be used. Each argument must refer to a
file containing path names. The -X option has pre-
cedence before other options that select files to be
included in the operation. See also list= option.
-xattr
Reserved for NFSv4 extended attributes.
-xattr-linux
Store and extract extended file attributes as found on
Linux systems. This option only makes sense when
creating or extracting exustar archives as it is based
on POSIX.1-2001 extended tar headers.
The method used in the current implementation could be
used to store and extract extended file attributes from
BSD too. Note that the current implementation is not
generic enough to cover more general extended file
attribute implementations as found on Solaris. If star
starts to implement a method that covers extended file
attributes on Solaris, the new method will be used then
-xattr has been specified and -xattr-linux will refer
to the old method. The method used with -xattr-linux
may go away in the future.
-xcopy
An alias for -copy -sparse -acl
xdebug=#, xd=#
Set extended debug level to #.
Joerg Schilling Last change: 2020/09/04 53
Schily's USER COMMANDS STAR(1)
-xdev, -M
Do not descend mount points. This is useful when doing
backups of complete file systems. See NOTES for more
information.
When using -find, this may not always work as expected,
e.g. when the /proc filesyestem is involved. Use -xdev
past -find for this reason.
-xdir
Extract directories even if the corresponding direc-
tories on the archive are not newer. This is useful
when for some reason, the directories are recorded
after their content (see -dirmode option), or when the
permissions of some directories must be set in any
case. As the classical UNIX cpio program does not
implement delayed directory permission and time stamp
setting, cpio users often create archives in reverse
order (directories past their content). For this rea-
son, it makes sense to use -xdir while extracting cpio
archives.
-xdot
Unconditionally extract the first directory in the
archive if the name of this directory is either '.' or
'./'. This helps to extract archives in an expected
way if the target directory is a newly created empty
directory. As this directory is newer than the top
level directory in the archive, star would usually skip
this directory during extraction. The effect of this
directory is as if -xdir has been specified but is
switched off after the first directory has been found.
-xfflags
Store and extract extended file flags as found on BSD
and Linux systems. This option only makes sense when
creating or extracting exustar archives as it is based
on POSIX.1-2001 extended tar headers. See NOTES sec-
tion for problems with -xfflags on Linux systems.
-xmeta
Extract meta files as if they were files. Meta files
in archives are plain files that do not contain any
content data in the archive. They may be created by
using the -meta option in star's create mode. Existing
files are not overwritten. If a file is missing, a zero
sized file is created. If the option -meta is used
together with the option -force-hole, missing plain
files are created as sparse empty files of the original
size.
-xz run the input or output through a xz pipe - see option
Joerg Schilling Last change: 2020/09/04 54
Schily's USER COMMANDS STAR(1)
-z below.
-Z run the input or output through a compress pipe - see
option -z below.
-z run the input or output through a gzip pipe. This is
currently a quick and dirty hack, that mainly will
cover the most common usage to compress the tar output
if it is a file. No reblocking will be done, so this
option will currently only make sense on plain files.
As the -bz the -j the -Z and the -z option are non
standard, it makes sense to omit the -bz the -j the -Z
and the -z options inside shell scripts if you are
going to extract a compressed archive that is located
inside a plain file as star will auto detect compres-
sion and choose the right decompression option to
extract. The environment variable STAR_COMPRESS_FLAG
may be used to specify one option for gzip. If you
want to write write compressed archives to tape, you
should use
star -c . | gzip | sdd ibs=4k obs=32k -fill
of=/dev/rmt/1bn
or
star -c . | gzip | sdd ibs=4k obs=32k -fill ovsize=60m
of=/dev/rmt/1bn
if the tape can hold 60 MB.
-zstd
run the input or output through a zstd pipe - see
option -z above.
INCREMENTAL BACKUPS
Star is able to back up file system in full and incremental
mode. To allow incremental backups, the file system must
implement POSIX semantics.
To be more verbose:
+ The filesystem needs to uniquely identify files by the
two numbers st_dev (The filesystem ID or device ID of
the device containing the file) and st_ino (The file
serial number). If a file is renamed, these numbers
need to be retained. Both numbers need to be a cardi-
nal 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 the POSIX
standard. Both numbers need to be a cardinal scalar
that is expressible in a decimal number or as a decimal
number that counts in seconds plus another number that
Joerg Schilling Last change: 2020/09/04 55
Schily's USER COMMANDS STAR(1)
counts in fractions of a second.
+ 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 the
inode numbers of all files while in incremental restore
mode.
Detecting renamed files only works if star, while in backup
mode, scans the whole file system tree for each full and
incremental backup. This will work in case no files are
excluded and the dump starts at the root directory of a file
system. In case that no files are renamed from excluded
parts to included parts, partial backups may be taken also.
Partial backups only make sense if a complete directory sub
tree is excluded (e.g. by using the pat= option) or if a
partial backup starts at a sub directory that is not the
root directory of the file system.
In case of a partial backup, it is important that no file or
directory will ever be moved outside the scope and later
move into the scope again. Moving files or directories out-
side the scope of a partial backup is detected as deletion
and moving the files back into the scope does not make them
appear in an incremental backup since the time stamps of
files from inside renamed directories did not change.
Note that a backup must not include files that are mounted
from another filesystem and a restore cannot be done with
more than one filesystem as target.
Files in the backup tree that are hidden under a mount point
cannot be part of the backup as long as the backup is not
done from a snapshot.
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:
Joerg Schilling Last change: 2020/09/04 56
Schily's USER COMMANDS STAR(1)
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
f=archive-name -C /filestem-mount-point .
Do not forget the dot at the end of the command line that
specifies the directory to start the operation.
Backups from live filesystems should be avoided. On operat-
ing 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 set-
ting up a snapshot and starting an incremental backup may be
missing from all backups unless the dumpdate=name option is
used.
If the system that is going to be backed up is not acting as
a file server, it makes sense to shut down all services that
may result in inconsistent file states before setting up the
filesystem snapshot. After the filesystem snapshot has been
set up, the services may be restarted.
If the the system that is going to be backed up is acting as
a file server, it may be that services on remote clients
cause inconsistent file states unless all such services that
remotely access files are shut down before the snapshot is
set up.
Star includes options that help to deal with file system
snapshots. The following example backs up a file system on
Solaris using a file system snapshot from UFS:
echo > /tmp/snapstamp
mount -r `fssnap -F ufs -o \
backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs` /mnt
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
f=archive-name dumpdate=/tmp/snapstamp \
fs-name=/export/nfs -C /mnt .
First a file with a current time stamp is created, then a
snapshot for /export/nfs is created and mounted on /mnt.
The following star command then creates a level 0 backup
from the file system using the time the snapshot was created
and the original mount point of the file system for
/etc/tardumps and the archive header.
Note that if the backup is done on a live file system, it
may be unreliable. A typical problem problem in this context
is caused by growing log files. As growing files are not a
real problem with backups, the best way of dealing with
growing files is to set up a star error control file (see
errctl= option) and to tell star to ignore growing files.
Joerg Schilling Last change: 2020/09/04 57
Schily's USER COMMANDS STAR(1)
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 incre-
mental dumps with shorter intervals. The next table shows a
dump level list that may be used if monthly full dumps take
place:
Sun Mon Tue Wed Thu Fri
Week 1: 0 10 10 10 10 5
Week 2: 10 10 10 10 10 5
Week 3: 10 10 10 10 10 5
Week 4: 10 10 10 10 10 5
The level 10 dumps made between Monday and Friday accumulate
all changes made within the week, but you only need to
restore the latest level 10 dump in order to get all changes
back. If you don't like the size of the accumulated
changes, use the following backup schedule:
Sun Mon Tue Wed Thu Fri
Week 1: 0 20 30 40 50 5
Week 2: 10 20 30 40 50 5
Week 3: 10 20 30 40 50 5
Week 4: 10 20 30 40 50 5
Note that in this case, 7 dumps need to be restored if the a
crash happens at the worst case date (just before the Friday
dump in week 2 or later).
INCREMENTAL RESTORES
Incremental restores should be made to an empty file system
(except for the lost+found directory). Star is currently
unable to perform incremental restores to a file system that
contains active mount points.
Incremental restores should be run as root user. Star sup-
ports private incremental dumps and restores run as an
unprivileged user, but this mode has been tested less fre-
quently.
The incremental restore procedure starts with restoring the
last full (level 0) dump. Then the latest incremental dump
of each dump level (with ascending order of dump levels)
need to be restored.
Let us assume the first example from the section BACKUP
SCHEDULES for the backup schedule. If a disk crash happens
before the Thursday dump of week 3 has been made, the
Joerg Schilling Last change: 2020/09/04 58
Schily's USER COMMANDS STAR(1)
following restore procedure needs to be applied:
level 0
starting with an empty disk, the full (level 0) dump
from week 1 is restored.
level 5
after the level 0 restore has been finished, the level
5 dump from Friday in week 2 is restored.
level 10
after the level 5 restore has been finished, the level
10 dump from Wednesday in week 3 is restored.
The disk now contains the same files as it did when the
level 10 dump has been made on Wednesday of week 3.
To extract a level 0 dump call:
cd /extract-filestem-mount-point
star -xpU -restore f=archive-name
This creates the directory star-tmpdir and the database
star-symtable in the root directory of the new file system.
Subsequent restores with higher level backups depend on
these files.
To extract a level 1 (or higher) dump call:
cd /extract-filestem-mount-point
star -xpU -restore f=archive-name
In order to restore a partial dump, the -partial option
needs to be specified. This is to make sure that the user
understands that renames to a path outside the scope of the
partial dump may result in inconsistencies during a restore.
In case there is a dump level mismatch or a reference date
mismatch, it is possible to give a restore a chance by
specifying the -force-restore option.
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
Joerg Schilling Last change: 2020/09/04 59
Schily's USER COMMANDS STAR(1)
filesystem needs to be performed first.
To create an initial copy of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
-C /filestem-mount-point . | \
star -xpU -restore -C /extract-target-dir
In order to perform subsequent synchronization of the target
filesystem with the content of the source filesystem, a
modified incremental dump/restore procedure may be used.
To copy incremental content of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
-cumulative -C /filestem-mount-point . | \
star -xpU -restore -C /extract-target-dir
Note that like with backups in general, copies from a live
filesystem should be avoided. On operating systems that
support file system snapshots, copies should be made from a
read-only mount of a snapshot. Be careful that all files
that have been created between setting up a snapshot and
starting an incremental copy may be missing from all copies
unless the dumpdate=name option is used.
See section INCREMENTAL BACKUPS to learn how to modify the
command line in case file system snapshots are used.
SIGNALS
If star handles a signal, it first prints the statistics.
Star handles the following signals:
SIGINT usually generated by ^C from the controlling tty.
Upon receipt of a SIGINT, star prints statistics
and exits. If in create mode i.e. storing files to
archive, star finishes with the current file to
ensure that no partial file is written to the
archive, write an eof record and then exits.
SIGHUP not to be generated from a tty. The actions are
the same as upon receipt of a SIGINT.
SIGQUIT
SIGINFO 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 opera-
tion.
EXIT STATUS
The following exit values are returned. Note that the nega-
tive values are only available to modern shells and programs
Joerg Schilling Last change: 2020/09/04 60
Schily's USER COMMANDS STAR(1)
that use waitid(2) on a POSIX OS and thus can retrieve the
full 32 bits of the star exit code. The positive number
variants are what you get when only the low 8 bits from the
exit code are available.
0 All files were processed successfully.
-64 / 192
An exit code has been used that does not fit into an
8-bit unsigned number and the environment COMERR_EXCODE
has not been set. The value -64 / 192 in this case
marks a clash.
-4 / 252
Star has been interrupted in create mode and the end of
star has been delayed until the current file has been
archived completely. This error is only used in case
that no other error occured and the tar archive only
has become shorter than expected.
-3 / 253
Star has been called with the option -e, or the errctl=
option has been used to mark the current error fatal.
-2 / 254
One or more files could not be processed successfully.
-1 / 255
Command line parsing error.
>0 Other positive exit codes: The errno of the call that
caused the fatal error.
EXAMPLES
To get a listing in a way similar to ls -l one might use:
example% star -tv f=/dev/rmt/1bn
The same command as listed above in a POSIX tar command line
syntax compliant way is:
example% star tvf /dev/rmt/1mbn
To copy the directory tree in /home/someuser to the 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:
Joerg Schilling Last change: 2020/09/04 61
Schily's USER COMMANDS STAR(1)
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 direc-
tory tree is to use the -copy option.
example% star -copy -p -xdot -C /home/someuser . /home/fs
To copy a file tree including the Access Control List
entries for all files and to correctly copy sparse (holey)
files use:
example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
To compare the content of a tape to the filesystem one might
use:
example% star -diff -v f=/dev/rmt/1bn
To compare two directory trees one might use:
example% star -c . | star -C todir -diff -v diffopts=!times
or better by using a method similar to the -copy method
above:
example% star -c -diff -v diffopts=!times -C fromdir . todir
To compare all properties of two file trees, use:
example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
To extract a backup of the /usr tree without all files
residing below /usr/openwin one might use:
example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
To extract all .c files to src, all .o files to obj and all
other files to /tmp one might use:
example% star -xp -C src '*.c' -C obj '*.o' -C /tmp '*' f=/dev/rmt/1bn
To extract files from a zipped tar archive that is located
on a read only filesystem e.g. a CD while having the shell's
working directory on the CD one might use:
Joerg Schilling Last change: 2020/09/04 62
Schily's USER COMMANDS STAR(1)
example% star -zxp -C /tmp f=star-1.1.tar.gz
to extract the files from the tar archive to the /tmp direc-
tory.
To backup a list of files generated by the find(1) command:
example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
Note that this does not work if the file names from output
of the find command include new line characters.
To extract a tarfile that contains a tarfile one might use:
example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
Pat, in this case should match the tarfile in the tarfile on
tape that should be extracted.
To make a backup of the root filesystem to a tape drive con-
nected to a remote machine, one might use:
example# cd /
example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
You need a line in /etc/passwd like the following to enable
this:
tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
And a .rhosts file in /etc/tapehome to allow remote connec-
tions 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 faster rcmd(3) connection for a backup to a remote
tape server, one might use:
example# env RSH='' star -cM fs=128m bs=63k
f=tape@remotehost:/dev/rmt/1bn .
Note that this requires root privileges.
To repair a corrupted filesystem for which no recent backup
exists, do the following:
example# fsck -y /filesys
example# mount /filesys
example# cd /filesys
Joerg Schilling Last change: 2020/09/04 63
Schily's USER COMMANDS STAR(1)
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 con-
taining 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
corrupted files, use:
example# star -diff -tpath diffopts=type,perm
f=/dev/rmt/1bn
If you like to archive all directories only that are part of
the directory tree under ".", use:
example# star -c f=archive-name -find . -type d
If you like to archive all files as owner root and group
root and make all files world readable in the archive, use:
example# star -c f=archive-name -find . -chown root
-chgrp root -chmod o+r
If you like to archive all files with a mtime of now, use:
example# star -c f=archive-name -find . -chmtime now
If you like to list all files in an archive in a way like
sfind(1), instead of the way used by star, use:
example# star -t f=archive-name -find . -ls -false
If you like to split the content of an archived tree into
tar chunks of 1 GB, you could call:
example# star -c f=/tmp/v.tar tsize=1G \
new-volume-script='sh -c "mv /tmp/v.tar /tmp/v$(($1-1)).tar" nv' .
ENVIRONMENT
COMERR_EXCODE
If this environment is present, exit codes are not
Joerg Schilling Last change: 2020/09/04 64
Schily's USER COMMANDS STAR(1)
mapped to avoid possible clashes with calling programs
that use the outdated waitpid(2) instead of the
waitid(2) call to wait for the exit status from star.
While waitid(2) returns the full 32 bit exit code,
waitpid(2) masks the exit code with 0377. Without the
environment COMERR_EXCODE, exit codes outside the range
-63 .. 191 are mapped to -64 (192) to mark a clash.
If the environment COMERR_EXCODE is set and the value
starts with the character '0', an exitcode code > 0
that leads to exitcode & 0377 == 0, is mapped to -64 to
avoid confusion with shells that use waitid(2) but
interpret these exit codes as zero with respect to con-
ditional execution in order to implement compatibility
to historical shells.
With a shell that supports the full exitcode on and a
POSIX compliant operating system, it is recommended to
set the environment COMERR_EXCODE.
STAR_COMPRESS_FLAG
If you like star to always create compressed files that
use maximum compression, you may set the environment
variable STAR_COMPRESS_FLAG to -9.
STAR_DEBUG
If this environment variable is present, star will not
remove temporary files from ./star-tmpdir. The files
in this 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.
STAR_FSYNC
If set to `N', the default behavior of star is as if
the -no-fsync option has always been specified.
This grants that star is always faster than other
archivers, but makes it impossible for star to check
whether the extracion of a file to the filesystem was
successful.
If set to any other value, the default behavior of star
is as if the -do-fsync option has always been speci-
fied.
The environment STAR_FSYNC has precedence over
/etc/default/star but may still be overwritten by
Joerg Schilling Last change: 2020/09/04 65
Schily's USER COMMANDS STAR(1)
command line options.
STAR_NOHINT
If this environment is seen, some informative messages
are not printed. this currently applies to messages
related to STAR_FSYNC and STAR_SECURE_LINKS.
STAR_SECURE_LINKS
If set to `N', the default behavior of star is as if
the -no-secure-links option has always been specified.
This disables checks for potentially insecure links by
default.
If you like to make this the default, keep in mind that
you need to specify -secure-links in case you like to
unpack an archive from unknown sources.
The environment STAR_SECURE_LINKS has precedence over
/etc/default/star but may still be overwritten by com-
mand line options.
STAR_WORKAROUNDS
If this environment variable is present, implement wor-
karounds for named problems. The environment variable
is expected to contain a comma separated list of bug
names:
ssh-tcpip
implement a workaround for a bug caused by ssh or
TCP-IP seen on Linux in 2003. The bug caused the
verbose output from star on stderr to be lost when
calling something like:
ssh host 'star -c ...'
The workaround is activated when stderr is not
connected to a terminal and works by waiting for
0.1 seconds for the output to appear.
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 connec-
tion will not be created via the default method, but
rather uses the program specified by RSH. Use e.g.
RSH=/path/to/ssh to create a secure shell connection
using a specific ssh version.
If the RSH environment is not present, the compiled in
Joerg Schilling Last change: 2020/09/04 66
Schily's USER COMMANDS STAR(1)
default is used. This currently is ssh.
If the RSH environment is empty, then rcmd(3) is used.
Former versions of star by default did use rcmd(3) to
create a remote connection. Using a different method
forces star to create a pipe to the rsh(1) or ssh (1)
program and disallows star to directly access the net-
work socket to the remote server. This makes it impos-
sible to work at maximum performance and slows down the
connection compared to a root initiated rcmd(3) connec-
tion.
See rsh= option for more information.
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.
See rmt= option for more information.
FILES
/etc/default/star
Default values can be set for the following options in
/etc/default/star. For example: CDR_FIFOSIZE=64m
STAR_FIFOSIZE
Sets the default size of the FIFO (see also fs=#
option).
STAR_FIFOSIZE_MAX
Sets the maximum size of the FIFO (see also fs=#
option). Setting STAR_FIFOSIZE_MAX in
/etc/default/star allows to overwrite global
values from backup scripts for machines with less
memory.
STAR_FSYNC
If set to `N', the default behavior of star is as
if the -no-fsync option has always been specified.
This grants that star is always faster than other
archivers, but makes it impossible for star to
check whether the extracion of a file to the
filesystem was successful.
This setting is overwritten by the STAR_FSYNC
Joerg Schilling Last change: 2020/09/04 67
Schily's USER COMMANDS STAR(1)
environment, if present.
If you like to make the default fast, keep in mind
that you need to specify -do-fsync for cases where
star needs to be able to know whether the extrac-
tion was successful.
STAR_SECURE_LINKS
If set to `N', the default behavior of star is as
if the -no-secure-links option has always been
specified.
This disables checks for potentially insecure
links by default.
This setting is overwritten by the
STAR_SECURE_LINKS environment, if present.
If you like to make this the default, keep in mind
that you need to specify -secure-links in case you
like to unpack an archive from unknown sources.
archive0=
archive1=
archive2=
archive3=
archive4=
archive5=
archive6=
archive7=
Archive entries for the -[0..7] option.
A correct archive?= line has 3..4 space separated
entries. The first is the device entry (e.g.
archive0=/dev/tape). The second is the blocking
factor in 512 byte units. The third is the max-
imum media size in 1024 byte units. If this entry
contains a 0, then the media size is unlimited.
The fourth entry is optional. If it contains a 'n'
or a 'N', then the archive device is not a tape.
Examples:
archive0=/dev/tape 512 0 y
archive1=/dev/fd0 1 1440 n
Joerg Schilling Last change: 2020/09/04 68
Schily's USER COMMANDS STAR(1)
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
include the whole filesystem).
The dump time itself includes the decimal representa-
tion of the UTC seconds since Jan 01 1970, a space and
the textual local time representation of the dump time.
The numerical decimal dump time representation may be
followed by a dot and a sub second value. The textual
local time representation is for informational use by
humans only and not evaluated by star.
./star-symtable
Contains a database that is needed in incremental
restore mode.
./star-symdump
Contains an intermediate dump of restore database after
a fatal error condition was met during an incremental
restore operation.
./star-tmpdir
Is the temporary directory that is used as intermediate
file storage by star if in incremental restore mode.
./star-lock
Is a lock file created by star when doing an incremen-
tal restore. If this file is present, it prevents star
from running another incremental restore operation.
Joerg Schilling Last change: 2020/09/04 69
Schily's USER COMMANDS STAR(1)
This helps to avoid more than one restore operation at
a time (e.g. from a cron script).
/dev/tty
Is used for the interactive user interface.
SEE ALSO
spax(1), suntar(1), scpio(1), tar(1), cpio(1), pax(1),
rcp(1), mt(1), rmt(1), match(1), dd(1), sdd(1), rsh(1),
ssh(1), star_sym(1), tartest(1), star(4), rcmd(3),
fssnap(1m), waitid(2), waitpid(2)
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 pro-
cessing, star will display a delayed error summary before
exiting.
NOTES
The command line syntax for the tar command (as defined in
SUSv2 - UNIX-98) deviates from the command line syntax
defined for all other commands. While the POSIX command line
syntax requests all options to start with a dash (-) and
allows to either write options separately or combined (in
case of boolean flags), the tar command line syntax requires
all options to be combined into a single string that does
not start with a dash. Star by default assumes a command
line syntax like a typical POSIX command and includes a com-
patibility mode that allows to specify a command line syntax
as documented for the UNIX-98 tar command. If you believe
that you found a bug in the way star parses the command
line, please first check your command line for correctness
before you make a bug report for star.
If you like to write portable shell scripts that call tar,
use the UNIX-98 tar command line syntax (i.e. a single
option string and no dash), choose the commands and options
from the following set of 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 gnu-
tar, do not include the -o option as gnutar implements this
option in a way that violates UNIX-98.
Joerg Schilling Last change: 2020/09/04 70
Schily's USER COMMANDS STAR(1)
Star strips leading ./ sequences from pathnames. This lets
star in many cases store longer pathnames than other imple-
mentations.
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 pathname does not fit in the space
provided or may not be split at a slash character so
that the parts will fit into 100 + 155 chars, the file
may not be archived. Linknames longer than 100 chars
may not be archived too.
The star, xstar, xustar, exustar, pax, and gnutar archive
formats don't have these limitations. While gnutar uses a
method that makes it impossible for other tar implementa-
tions (except star) to restore filenames that are longer
than 100 chars, the xstar, xustar, exustar and pax/epax
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, exus-
tar or pax/epax very long filenames are stored using
extended 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 com-
pliant as possible. Inserting this tar signature is a minor
deviation from the standard that has the last 12 bytes of
each header reserved for future use. On the other side, tar
implementations such as some pax implementations that only
compute checksums on the first 500 bytes of the header are
violating the standard that requests the checksum to be com-
puted on all 512 bytes of the tar header. All tar implemen-
tations 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
Joerg Schilling Last change: 2020/09/04 71
Schily's USER COMMANDS STAR(1)
extended headers which are extensible to include any feature
without future limitation. The only known tar implementa-
tion 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/epax
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 read-
ing the archive if it encounters a logical EOF record in the
archive. If the fifo is used, star may read until the fifo
is full or until the real EOF mark on tape is reached. How
much data star actually reads depends on the star foreground
process sends a fifo shutdown signal to the background fifo
read process.
Gnu tar often creates tar archives with incorrect logical
EOF marks. The standard requires two blocks that are com-
pletely zeroed, whereas gnutar often only adds one of them.
Old versions of tar found on SYSVr3 and earlier cannot read
tar archives with a blocksize greater than 10 kBytes.
The method of storing sparse files currently used with the
star and xstar format is not guaranteed to be used in later
versions of star. If the author decides to change this
method, later versions of star may not be able to restore
sparse files from tar archives made by the current version
of star.
Some tar implementations violate the standard in using only
the first 500 Bytes of the header for checksum computation.
These tar implementations will not accept star and xstar
type tar archives.
Sun's Solaris 2.x tar implementation violates the Posix
standard. Tar archives generated by star cause Sun's tar to
print tar: impossible file type messages. You may ignore
these messages.
Joerg Schilling Last change: 2020/09/04 72
Schily's USER COMMANDS STAR(1)
Gnutar's dumpdirs are non standard and are currently not
implemented.
If gnutar archives sparse files with more than four holes,
it produces archives that violate the standard in a way that
prevents other tar implementations to read these archives.
Star knows about that and is able to handle these gnutar
archives.
The filetype N (LF_NAMES) from gnutar (an obsolete method of
storing long names) will never be implemented.
Note that on operating systems (like DOS) that do not imple-
ment real pipes, star implements compression via a temporary
file. Using compression thus is limited by the maximum file
size and the available disk space.
The extended file flags implementation (see -xfflags option)
on Linux is buggy by design. In order to retrieve the
needed information, every file needs to be opened. If the
/dev directory is included in create mode, every possible
driver will be loaded which may hang the system for a long
time. In the worst case, unwanted side effects from opening
devices (such as causing tape drives to rewind the media)
may be caused.
SECURITY NOTES
If you unpack a tar archive in a non empty directory, any
file in that directory may be overwritten unless you specify
the -k option. If the archive contains symbolic links or
hard links, star may even overwrite files outside the
current directory. If the directory where the archive is
been unpacked is not empty and contains contains symbolic
links or hard links to directories outside that directory,
star may also overwrite files outside the current directory.
As many other commands, star usually has all possible per-
missions 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 neither specify the -/ nor
-.. or -no-secure-links options. 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
Joerg Schilling Last change: 2020/09/04 73
Schily's USER COMMANDS STAR(1)
for the first run.
See the ENVIRONMENT section and /etc/default/star for ways
to configure the default behavior.
SUID NOTES
If star is installed suid root, star is able to make connec-
tions to remote archives for non root users. This is done by
using the rcmd(3) interface to get a connection to a rmt(1)
server.
Star resets its effective uid back to the real user id
immediately after setting up the remote connection to the
rmt server and before opening any other file.
If star has not been installed suid root and not called by
root, it will try to create the remote connection via rsh(1)
or ssh(1) (in case the environment RSH has been set to ssh).
Note that in this case, the throughput to the remote tape
server will be much lower than with a connection that has
been initiated via rcmd(3).
LIMITATIONS
If star is running on a large file aware platform, star is
able to handle files up to 8 GB in a mode that is compliant
to the POSIX.1-1988 ustar format. With a nonstandard star
specific extension, up to 95 bits may be used to code the
filesize. This will handle files up to 200,000,000 TB.
With the new POSIX.1-2001 extended headers used by the xus-
tar, exustar and pax/epax format, any filesize may be
archived.
BUGS
The fact that the -f option has to be implemented in a way
that is compatible with old tar implementations gives
several problems. The options -fifostats, -force-hole,
-force-remove and -fifo interfere with the -f option and the
fact that they exist prevents users from using filenames
like e.g. ifo using the traditional way where the filename
directly follows the string -f without any space between the
option name and the file name. However, there is no problem
to use a file named ifo by by calling -f ifo, f=ifo, -f=ifo
or -f= ifo. Be careful not to make typos with the above
options. The result could be that a file is created as a
result of the mistyped option.
There is currently no way to set the fifo lowwater and high-
water marks.
If you ever discover a hang in the fifo of star, get the
process ids for both star processes, send both a RTMAX sig-
nal using kill(1) and report the disgnostic output.
Joerg Schilling Last change: 2020/09/04 74
Schily's USER COMMANDS STAR(1)
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 direc-
tory 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 implementa-
tion of ssh(1).
If you use star to create a remote connection via an unfixed
rsh(1) or ssh(1), be prepared that terminal generated sig-
nals may interrupt the remote connection.
HISTORY
A tar command appeared in Seventh Edition Unix, which was
released in January, 1979. It replaced the tp program from
Fourth Edition Unix which replaced the tap program from
First Edition Unix.
Star was first created in 1982 to extract tapes on a UNIX
clone (UNOS) that had no tar command. In 1985 the first
fully functional version has been released as mtar.
When the old star format extensions have been introduced in
1985, it was renamed to star (Schily tar). In 1994, Posix
1003.1-1988 extensions were added and star was renamed to
star (Standard tar).
AUTHOR
Joerg Schilling
D-13353 Berlin
Joerg Schilling Last change: 2020/09/04 75
Schily's USER COMMANDS STAR(1)
Germany
Mail bugs and suggestions to:
joerg@schily.net
SOURCE DOWNLOAD
The source code for star is in the star project at Sour-
ceforge at:
http://sourceforge.net/projects/s-tar/
The download directory is:
http://sourceforge.net/projects/s-tar/files/
The preferred frequent development snapshots of the star
source are also included in the schilytools project and may
be retrieved from the schilytools project at Sourceforge at:
http://sourceforge.net/projects/schilytools/
The download directory is:
http://sourceforge.net/projects/schilytools/files/
Check for the schily-*.tar.bz2 archives and please use the
latter download in favor of old so called stable star
releases in separate tarballs.
Joerg Schilling Last change: 2020/09/04 76
Man(1) output converted with
man2html
Schily's Home
