|
|
| |
STAR(1) |
Schily´s USER COMMANDS |
STAR(1) |
star - unique standard tape archiver
star command [options] [-find] file1 ...
filen [find_expr]
ustar command [options] [-find] file1 ...
filen [find_expr]
star command list=name [options]
-find [find_expr]
star -copy [options] [-find]
file1 ... [f_expr] directory
star -copy [options] -C
from_directory . to_directory
star cli=name ...
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
single file called a tarfile. A tarfile is usually a magnetic
tape, but it can be any file. In all cases, appearance of a directory name
refers to the files and (recursively) subdirectories of that directory.
Star's actions are controlled by the mandatory command
flags from the list below. The way star acts may be modified by
additional options.
Note that unpacking tar archives may be a security risk because
star may overwrite existing files. See SECURITY NOTES for more
information.
If the first argument is in the form cli=name, the
command line interface is selected to match name. See section
CLI SELECTION below.
Star includes the first free implementation of POSIX.1-2001
extended tar headers. The POSIX.1-2001 extended tar
headers define a new standard way for going beyond the limitations of the
historic tar format. They allow (among others) to archive all UNIX time
stamps in sub-second resolution, files of arbitrary size and filenames without
length limitation using UNICODE UTF-8 coding for best exchange
compatibility.
Star by default uses a fifo to optimize data flow from/to
tape. This results in a normally streaming tape during the whole backup. See
-fifo and fs= option to get information on how to find the
best fifo size.
Star includes a pattern matcher to control the list of
files to be processed. This gives a convenient interface for archiving and
restoring complex lists of files. In conjunction with the -w flag it
is easy to merge a tar archive into an existing file tree. See also
-U option. In create mode use the pat= option to specify
either select or exclude patterns (depending on the -V flag). In
extract or list mode all file type arguments are 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 implemented
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 that prevent correct extraction of single files when using a
different tar implementation that is only POSIX.1-1988 compliant may
occur, but they only affect single files with a pathname that is longer than
100+130 chars or when archiving sparse files with the -sparse option
in effect. All other files will extract correctly. See the description for
the H=headertype option below for more information on archive
formats and possible archive interchange problems.
Star makes it easy to repair corrupted filesystems. After a
fsck -y has been run on the filesystem, star is able to restore only
the missing files automatically. Use then star -diff to check for
differences (see EXAMPLES for more information).
Star automatically recognizes the type of the archive.
Star therefore is able to handle features and properties of different
archive types in their native mode, if it knows about the peculiarities of
the archive type. See the H=headertype option for more details. To be
able to do this, star adds hidden fingerprints to the archive header
that allows to recognise all star specific archive formats. The GNU tar
format is recognised by the way it deviates from the standard.
Star automatically recognizes and handles byte swapped
archives. There is no option to manually control byte swapping.
Star automatically recognizes and handles compressed
archives inside plain files.
Star is able to archive and restore Access Control
Lists for files using POSIX.1-2001 extended headers.
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 command 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.
- gnutar
- The gnutar interface selects the command line interface of the
GNU tar command as described in gnutar(1). Star
however does not implement 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).
In native mode, star is compatible to the command line syntax of a
typical POSIX command and for this reason expects commands and
options to start with a single dash (-). In this case, commands and
options may be specified separately, all boolean or increment type options may
be specified either separately or combined.
For compatibility with GNU programs, long options may
alternatively start with a double dash.
In compatibility mode to POSIX tar, star expects
commands and options to appear as one single string that does not start with
a dash. In POSIX tar compatibility mode, additional non POSIX options
may be specified but must appear after the POSIX options and their
args and need to start with a dash.
- -c
- Create a new tarfile and write named files into it. Writing starts
at the beginning of tarfile. See -v option for information on how
to increase verbosity while the archive is written.
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 -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 copying files. This makes sense
as the listing from star may be better readable than the output
from ls -lR. The shorthand -c -t or -ct instead of
-copy -t is also allowed.
The job is by default done in the best archive mode. This
implies that it defaults to H=exustar -dump. When in -copy
mode, star forks into two processes and data exchange is done via
the shared memory from the FIFO. This gives the best possible
performance. Without FIFO, the -copy mode will not work.
The list= option, patterns and substitutions apply only
to the create side of the copy command.
- -diff
- Compare the content and the attributes of the files from the archive in
tarfile to the filesystem. This may also be used to compare two
file trees in the filesystem. If you use a set of diffopts that
fits your needs, it will give - in many cases - a more readable output
than diff -r. If you use star's dump 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 reading a tar archive that has been
created in -dump mode.
- -n
- No extraction. Show what star would do, in case the -x
command had been specified.
- -r
- Replace files in a tarfile. The named files are written to the end
of tarfile. This implies that later, the appropriate files will be
found more than once on the tarfile.
- -t
- Table of contents. List the contents of the tarfile. If the -v flag
is used, the listing is similar to the format of ls -l output. With this
option, the flags -a, -atime and -ctime have a
different meaning if the archive is in star, xstar,
xustar, exustar, or pax/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 modification time. The option -tpath may be used in
addition to modify the output so it may be used in shell scripts.
- -u
- Update a tarfile. The named files are written to the end of
tarfile if they are not already there or if the files are newer
than the files of the same name found in the archive. The -r and -u
command only work if the tar archives is a regular file or if the
tar archive is an unblocked tape that may backspace.
- -x
- Extract the named files from the tarfile. If no filename 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.
- -help
- Print a summary of the most important options for star(1).
- -xhelp
- Print a summary of the less important options for star(1).
- -/
- Don't strip leading slashes from file names when extracting an archive.
Tar archives containing absolute pathnames are usually a bad idea. With
other tar implementations, they may possibly never be extracted
without clobbering existing files. Star for that reason, by default
strips leading slashes from filenames when in extract mode. As it may be
impossible to create an archive where leading slashes have been stripped
while retaining correct path names, star does not strip leading
slashes in create mode.
See SECURITY NOTES for more information.
- -..
- Don't skip files that contain /../ in the name. Tar archives containing
names with /../ could be used to compromise the system. If they are
unpacked together with a lot of other files, this would in most cases not
even be noticed. For this reason, star by default does not extract
files that contain /../ in the name if star is not in interactive
mode (see -w option).
See SECURITY NOTES for more information.
- -7z
- run the input or output through a p7zip pipe - see option -z
below.
Note that the p7zip program currently does not operate
on a pipe but on a /tmp file copy and thus limits the maximum archive
size.
- -0
- -1
- -2
- -3
- -4
- -5
- -6
- -7
- Select an archive entry from /etc/default/star. The format for the
archive entries is the same as the format in /etc/default/tar in
Solaris.
- -acl
- Handle Access Control List (ACL) information in create and extract
mode. If -acl has been specified, star is in create mode and
the header type is exustar, star will add ACL information to
the archive using POSIX.1-2001 extended headers. If -acl has been
specified and star is in extract mode, star will try to
restore ACL information. If there is no ACL information for one or all
files in the archive, star will clear the ACL information for the
specific file. Note that if -acl has not been specified,
star will not handle ACL information at all and files may inherit
ACL information from the parent directories. If the -acl option has
been specified, star assumes that the -p option has been
specified too.
Star currently supports ACLs from the withdrawn
POSIX.1e draft and NFSv4 ACLs. To check which ACL flavors 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 parameter for headertype are:
- help
- Print a help message about possible header types.
- v7tar
- Old UNIX V7 tar format. This archive format may only store plain
files. Pathnames or linknames longer than 99 chars may not be archived.
If the v7tar format has been selected, star will
not use enhancements to the historic UNIX V7 tar format. File size is
limited to 2 GB - 2 bytes, uid/gid is limited to 262143. Sparse files
will be filled up with zeroes.
- tar
- Old BSD UNIX tar format. This archive format may only store plain
files, directories and symbolic links. Pathnames or linknames longer than
99 chars may not be archived. See also the -d option as a note to
some even older tar implementations.
If the tar format has been selected, star will
not use enhancements to the historic tar format. File size is limited to
2 GB - 2 bytes, uid/gid is limited to 262143. Sparse files will be
filled up with zeroes.
- star
- Old star standard format. This is an upward/downward compatible
enhancement of the old (pre Posix) UNIX tar format. It has
been introduced in 1985 and therefore is not Posix compliant. The
star format allows to archive special files (even sockets) and
records access time and creation time besides the modification time. Newer
versions of the old star format allow very long filenames
(100+155 chars and above), linknames > 100 chars and sparse
files (if -sparse is used). This format is able to copy the device
nodes on HP-UX that have 24 bits in the minor device number, which is more
then the 21 bits that are possible with the POSIX-1003.1-1988 archive
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' signature.
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 format unless you want to create an archive for
a target system that is known to have only the gnutar program available.
The gnutar archive format violates basic rules for any (even the
historic) tar archive format, in special when sparse files are archived
using the -sparse option.
GNU tar is not able to extract files with with long
path names, but under some conditions 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 read by gnutar or by star. The
implementation of the gnutar archive format within star is not
complete, but sufficient for most gnutar archives. See NOTES for more
information.
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 conforming. File size is limited to 8 GB, uid/gid/major/minor
is limited to 2097151. Sparse files will be filled up with zeroes.
- pax
- The IEEE/Posix1003/IEC-9945-1-1988 successor is the POSIX-1003.1-2001
Standard Data Interchange format. It is called the pax archive
format.
If the pax format has been selected, star will
not use enhancements to the POSIX.1-2001 tar format, the archive will be
strictly conforming. File size is unlimited, uid/gid/uname/gidname is
unlimited, major/minor is limited to 2097151. Sparse files will be
filled up with zeroes.
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 resolution 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 format as default archive format. This
is an upward/downward compatible enhancement of the
IEEE/Posix1003/IEC-9945-1 Standard Data Interchange format. It allows
among others very long filenames (100+130 chars and above) and
records access time and creation time. Sparse files will be archived
correctly (if -sparse is used).
The access time and creation time are stored at the end of the
POSIX file name prefix (this 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 problems with these
broken tar implementations. The main other difference to the
xstar format is that the xustar format uses POSIX.1-2001
extended headers to overcome limitations of the historic tar format
while the xstar format uses proprietary extensions. The
xustar format is the default format when star is called as
tar.
File size is unlimited, uid/gid/uname/gidname is unlimited,
major/minor is unlimited. Sparse files will be archived correctly (if
-sparse is used).
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
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 format but does not handle atime and ctime
and in addition uses 'X' as the typeflag for the extended headers instead
of the standard 'x'.
File size is unlimited, uid/gid/uname/gidname is unlimited,
major/minor is unlimited. Sparse files will be filled up with
zeroes.
- bin
- The cpio UNIX V7 binary format. This is a format with big interoperability
problems. Try to avoid this format. It is only present to make the
scpio command SVr4 compliant.
- cpio
- The POSIX.1-1988 cpio format. This format uses octal ascii headers.
A similar format is created by calling cpio -o -c on pre SYSVr4
systems and by calling cpio -o -Hodc on SYSVr4 systems. The
POSIX.1-1988 cpio format allows a file name length up to 262142
characters and allows to archive nearly any file type. File size is
limited to 8 GB, uid/gid/st_dev is limited to 262143. The way major and
minor device numbers are stored inside the st_dev field is implementation
dependent.
Even though this archive format is covered by the POSIX.1-1988
standard, it has a lower portability than the ustar format. Try
to avoid the cpio archive format.
- odc
- This archive format is similar to the The POSIX.1-1988 cpio format
but the file name length is limited to 255 characters and the socket file
type is not allowed. This archive format has been introduced to allow non
POSIX cpio implementations such as the cpio program on SYSV to accept the
archive. Use this format whenever you are not sure if the target system
offers a fully POSIX compliant cpio program.
Even though this archive format is covered by the POSIX.1-1988
standard, it has a lower portability than the ustar format. Try
to avoid the odc archive format.
- asc
- Tell star to create a cpio archive in the ascii 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 implementation if they contain no files with
pathnames > 100+130 chars and if they contain no sparse
files that have been archived by using the -sparse option.
- -ask_remove
- obsoleted by -ask-remove
- -ask-remove
- Ask to remove non writable files on extraction. By default, star
will not overwrite files that are read only. If this option is in effect,
star will ask whether it should remove these files to allow the
extraction of a file in the following way:
- remove 'filename' ? Y(es)/N(o) :
- -atime, -a
- Reset access time of files after storing them to tarfile. On
Solaris 2.x, (if invoked by root) star uses the _FIOSATIME
ioctl to do this. This enables star not to trash the ctime
while resetting the atime of the files. If the -atime option
is used in conjunction with the list command, star lists access
time instead of modification time. (This works only in conjunction with
the star, xstar, xustar, exustar, and with the
pax/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 multiplication factors).
Changing the blocking factor only makes sense when the archive is located
on a real tape device or when the archive is accessed via the remote tape
protocol (see f= option below). The default is to use a blocking
factor of 20 i.e. 10 kBytes. Increasing the blocksize will speed up
the backup. For portability with very old tar implementations (pre
BSD 4.2 or pre AT&T SVR4), blocksize should not be more
than 10 kBytes. For POSIX.1-1988 compatibility, blocksize should be
no more than 10 kBytes. For POSIX.1-2001 compatibility, blocksize
should be no more than 32 kBytes. Most systems also have a hardware
limitation for the blocksize, 32 kBytes and 63 kBytes are
common limits on many systems. The upper limit in any case is the size of
the buffer RAM in the tape drive. Make a test if you want to make sure
that the target system will handle the intended blocksize. If you use
star for data exchange via tape, it is a good idea to use a
blocksize of 10 kBytes unless you are sure that the reading system
will handle a larger blocksize. If you use star for backup purposes
with recent hardware (e.g. DLT tape drives), a blocksize of
256 kBytes results in sufficient speed and seems to be a good
choice. Star allows block sizes up to 2 GByte if the system does
not impose a smaller limit. If you want to determine the blocking factor
when reading an unknown tar archive on tape, specify a 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 multiplied by 1, 2,
512, 1024, 1024*1024, 1024*1024*1024, 1024*1024*1024*1024 or
1024*1024*1024*1024*1024. If the size consists of numbers separated by `x'
or `*', multiplication of the two numbers is performed. Thus
bs=7x8k will specify a blocksize of 56 kBytes. Blocksize
must be a multiple of 512 bytes. See also the description of the
blocks= option for more details on blocksizes. The option
bs= is preferred by people who like to use an option that behaves
similar to the interface used by dd(1) and sdd(1).
- -bsdchdir
- Switch the behavior of the C= option to BSD style. The default
behavior of star is to stay in a working directory until a new
C= is seen. With BSD tar, the C= option is only related to
the next file type argument.
- -bz
- run the input or output through a bzip2 pipe - see option -z
-Z and -j below. As the -bz the -j the
-Z and the -z option are non 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 arguments.
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 corresponding directory of a matching pattern. All pat=
options that do not follow a C=dir option are interpreted as
if they were preceded by a -C . option. See EXAMPLES for
more information.
- compress-program=name
- Set a named compress program. The program must compress in a pipe when
called without parameters and decompress when run with the -d
option in a pipe. This option is otherwise similar to the -z the
-j the -Z and the -bz option.
- -copydlinks
- Try to recursively copy the content of linked directories instead of
creating the link. This is an experimental feature that may help to unpack
archives on DOS.
- -copyhardlinks
- This option allows to copy hardlinked targets rather than creating the
link. It helps to extract tar files on systems that do not
implement hardlinks (e.g. BeOS).
- -copylinks
- This option allows to copy both, hard- and symlinked targets rather than
creating a link. It helps to extract tar files on systems that do
not implement links (e.g. OS/2). To extract and copy all symlinks
correctly, you may need to call star twice as star cannot
copy files that appear in the archive later than a symlink pointing to
them.
- -copysymlinks
- This option allows to copy symlinked targets rather than creating a
symbolic link. It helps to extract tar files on systems that do not
implement links (e.g. OS/2). To extract and copy all symlinks correctly,
you may need to call star twice as star cannot copy files
that appear in the archive later than a symlink pointing to them.
- -cpio-statistics
- Instead of the star flavor of the statistics, print statistics in
cpio flavor.
- -ctime
- If used with the list command, this lists ctime rather than
mtime if the archive format is star, xstar,
xustar, exustar, or pax/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.
If used with the create command this changes the behavior of
the newer= option. Star, in this case compares the
ctime of all files to the mtime of the stamp file rather
then comparing the mtimes of both files.
- -cumulative
- A shorthand for -dump-cumulative. See -dump-cumulative for
more information.
- -D
- Do not descend directories when in create mode. Normally, star
descends the whole tree if it encounters a directory in in its file
parameters. The option -D is in effect by default if the
list=file option is used. If you like star to descend
directories found in the list file, use the -dodesc option (see
below).
- -d
- Do not store/create directories. Old versions of tar such as
published with the seventh edition of UNIX are not able to deal with
directories in tar archives. If a tar archive is generated
without directories this avoids problems with tar implementations
found on SYSVr3 and earlier. If used during extract, no intermediate
missing directories are created.
- -data-change-warn
- If the size of a file changes while the file is being archived, treat this
condition as a warning only that does not cause a non zero exit code. A
warning message is still written if the condition is not otherwise ignored
by another rule from an errctl= option. The
-data-change-warn option works as if the last error control option
was
errctl="WARN|GROW|SHRINK *"
The -e option or an ABORT entry in a condition
set up by errctl= has a higher precedence than the
-data-change-warn option. This option is ignored in extract or
list mode.
- -debug
- Print debug messages. Among other things, this gives debug messages for
header type recognition, tar type properties, EOF recognition,
opening of remote archives and fifo internals.
- diffopts=optlst
- Comma separated list of diffopts. Valid members in optlst are:
- help
- Print a summary of possible members of the diffopts list.
- !
- Invert the meaning of the following string. No comma is needed after the
exclamation mark.
- not
- Invert the meaning of all members in the diffopts list i.e. exclude all
present options from an initially 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
compared also.
- type
- Compare file type. Note that star cannot compare the file type in
case of a hard link.
- nlink
- Compare link count on hardlinks 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 directories. If comparing
dnlink is excluded but nlink is not excluded, this allows to
deal with filesystems that differ in their directory 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
historical 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 format and contains star's dump
extensions.
- uid
- Compare numerical user id of file.
- gid
- Compare numerical group id of file.
- uname
- Compare ASCII version of user id of file. The user name is mapped via the
file /etc/passwd.
- gname
- Compare ASCII version of group id of file. The group name is mapped via
the file /etc/group.
- id
- Shorthand for: uid,gid,uname,gname. Compare all user/group related
info of file. Note that this will always find differences if the source
and target system use different user or group mappings.
- size
- Compare file size. Note that star cannot compare the file size in
case of a hard link.
- data
- Compare content of file. If star already found that the size of the
files differ, it will not compare the content anymore. If the size of the
files differ, star will always report different data.
- cont
- Same as data.
- rdev
- Compare major/minor numbers for device nodes.
- hardlink
- Compare target of hardlinks.
- symlink
- Compare target of symlinks. This evaluates the paths returned by the
readlink(2) call.
Two symlinks are considered equal, it they either have a
characterwise identical link-name, or if they either both use an
absolute path name or both use a relative path name and the following is
true: Both symlinks point to the same file that must exist or both
pathnames look similar enough.
- sympath
- Compare the target pathnames of symlinks. This 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.
- 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
modification 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 support 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 format and contains star's dump extensions. Together
with increased verbose level (-vv) this will print a list of files
that are only in the archive and a list of files that are only on the
current filesystem.
- xtimes
- Shorthand for: atime,mtime,ctime,lmtime.
- acl
- Compare access control lists. This only works if the archive is in
exustar format and has been created with star's -acl
option. You need to specify the -acl option in addition when
running the diff.
- xattr
- Compare extended file attributes. This only works if the archive is in
exustar format and has been created with star's
-xattr option. You need to specify the -xattr option in
addition when running the diff.
- fflags
- Compare extended file flags. This only works if the archive is in
exustar format and has been created with star's
-xfflags option. You need to specify the -xfflags option in
addition when running the diff.
If optlst starts with a ! the meaning of all members in
optlst is inverted as with the not optlist member. In this
case, star starts with a complete list that includes atime and
lmtime. Reasonable diff options to use when comparing against a copy
of a directory tree are diffopts=!atime,ctime,lmtime.
If diffopts are not specified, star compares
everything but the access time of the files and the modification time of
symbolic links.
- dir-group=group
- If star extracts archives as root, this option allows to control
the group id of intermediate directories created by star.
- dir-owner=user
- If star extracts archives as root, this option allows to control
the owner of intermediate directories created by
- -dirmode
- If in create mode (i.e. when storing files to archive), star stores
directories past the corresponding files. This guarantees that even old
tar implementations without a directory cache will be able to
restore the correct times of directories. The option -dirmode
should only be used if the archive needs to be extracted by an old
tar implementation. If star is used to extract an archive
that has been created with -dirmode the directories will not get an
old time stamp unless the option -U is used while extracting the
archive.
- -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 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 introduced to make it easier to implement a
star version that supports true incremental dumps, but it
is kept as it gives additional benefits. Star currently sets the
archive type to exustar and, in addition archives more inode meta
data inside POSIX.1-2001 extended headers. See also level= option
and the section INCREMENTAL BACKUPS for more 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. Incremental dumps with a level higher
than 0 are normally done relatively to the content of a previous dump with
lower level. If incremental dumps and restores are going to be used to
synchronize filesystem content, every successive incremental dump will
increase in size if -dump-cumulative is not used. See section
SYNCHRONIZING FILESYSTEMS for more information.
- dumpdate=name
- Tells star to use the mtime of the time stamp file
name instead of using the start time of star. This is needed
when star is run on file system snapshots. If star would use
the the 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.
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 unexpected error occurs.
The -e option works as if the last error control option was
errctl="ABORT|ALL|DIFF *"
This allows to use the errctl= option together with the
-e option and thus to ignore some error conditions while aborting
on all other conditions.
- errctl= name
- errctl= error control spec
- Add the content from file name to the error control definitions or
add error control spec to the error control definitions. More than
one error control file and more than one error control spec as well
as a mixture of both forms is possible.
The reason for using error control is to make star
quiet about error conditions that are known to be irrelevant on the
quality of the archive or restore run or to tell star to abort on
certain error conditions instead of trying to continue with the
archive.
A typical reason to use error control is to suppress warnings
about growing log files while doing a backup on a live file system.
Another typical reason to use error control is to tell star to
abort if e.g. a file could not be archived instead of continuing to
archive other files from a list.
The error control file contains a set of lines, each starting
with a list of error conditions to be ignored followed by white space
followed by a file name pattern (see match(1) or
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
encountered, star checks the lines in the error control file
starting from the top. If the current error condition is listed on a
line in the error control file, then star checks whether the
pattern on the rest of the line matches the current file name. If this
is the case, star uses the current error control specification to
control the current error condition.
The list of error conditions to be handled may use one or more
(in this case separated by a '|' character) identifiers from the list
below:
- ABORT
- If this meta condition is included in an error 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 conditions (separated by a '|' character). The
WARN meta condition has a lower precedence than ABORT.
- DIFF
- Suppress output in case that star -diff did encounter any
differences.
- ALL
- This is a shortcut for all error conditions below.
- STAT
- Suppress warnings that star could not stat(2) a file.
- GETACL
- Suppress warnings about files on which star had problems to
retrieve the ACL information.
- OPEN
- Suppress warnings about files that could not be opened.
- READ
- Suppress warnings 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 attribute 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 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 conditions, you may not be
able to see real problems anymore.
- -exclude-from name
- Exclude from named file, this is an alias for the -X option. See
-X option for more information.
- -F,-FF ...
- Fast and simple exclude option for create mode. With one -F
argument, star ignores all directories called SCCS and
RCS. With two -F arguments, star in addition ignores
all files called core errs a.out all files ending with .o.
OBJ/. With three -F arguments, star ignores all sub
trees starting from a directory that includes a file .mirror or
.exclude and all object files and files called core errs
a.out all files ending with .o. With four -F arguments,
star ignores all sub trees starting from a directory that includes
a file .mirror or .exclude the latter files are excluded too
as well as and all object files and files called core errs a.out
all files ending with .o. With five -F arguments,
star in addition again excludes all directories called SCCS
and RCS.
- 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
sensitive to typo problems, see BUGS section for more information.
- -fifostats
- Print fifo statistics at the end of a star run when the fifo has
been in effect. All options that start with the -f sequence are
sensitive to typo problems, see BUGS section for more information.
- file=tarfilename, f=tarfilename
- Use tarfilename as the name for the tar archive. Currently
up to 100 file= options are possible. Specifying more then one
file= option make sense in multi volume mode. In this case
star will use the next name in the list every time a media change
is needed. To make star behave consistent with the single file
case, star loops over the list of known archive files. Note that if
star is installed suid root and the first tarfile is a remote
archive, only the connection to this archive will be created with root
privileges. After this connection has been established as root,
star switches back to the id of the caller. If any of the other
archives in the list is located on a different host, star will not
be able to open this archive later on, unless run by root.
Star normally uses stdin/stdout for the
tar archive because the most common way to use star is in
conjunction with pipes. If star is installed suid root or if it
has been called by root, tarfilename may be in remote syntax:
user@host:filename as in rcp(1) even if invoked by non root
users. See SUID NOTES for more information.
To make a file local although it includes a colon (:), the
filename must start with: '/', './' or '../'
Note that if star talks to an old rmt remote
tape server that does not support symbolic open modes, it does not open
a remote tape with the O_CREAT open flag because this would be
extremely dangerous. If the rmt server on the other side is the
rmt server that comes with star or the GNU rmt
server, star may use the symbolic mode for the open flags. Only
the symbolic open modes allow to send all possible open modes in a
portable way to remote tape servers.
It is recommended to use the rmt server that comes with
star. It is the only rmt server that gives platform
independent compatibility with BSD, Sun and GNU rmt clients and
it includes security features that may be set up in /etc/default/rmt.
All options that start with the -f sequence are sensitive to typo
problems, see BUGS section for more information.
See -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 command line
syntax only.
The find expression acts as a filter between the source
of file names and the consumer, which may either be the archiving engine
or list/extract engine. If the find expression evaluated as TRUE,
then the related file is selected for processing, otherwise it is
omited.
In order to make the evaluation of the find expression
more convenient, star implements additional find primaries
that have side effects on the file meta data. Star implements the
following additional find primaries:
- -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 symbolic permissions are accepted for
mode as with chmod(1).
- -chown uname
- The primary always evaluates as true; it sets the owner of the file to
uname.
- -false
- The primary always evaluates as false; it allows to make the result of the
full expression different from the result of a part of the
expression.
- -true
- The primary always evaluates as true; it allows to make the result of the
full expression different from the result of a part of the
expression.
The command line:
star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type
d
lists all directories and archives all non-directories to the
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 sensitive to typo problems,
see BUGS section for more information.
- -force_remove
- obsoleted by -force-remove
- -force-remove
- Force to remove non writable files on extraction. By default, star
will not overwrite files that are read only. If this option is in effect,
star will silently remove these files to allow the extraction of a
file. All options that start with the -f sequence are sensitive to
typo problems, see BUGS section for more information.
- -force-restore
- Force an incremental restore even if 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
- Follow symbolic links as if they were files. Normally star will not
follow symbolic links but stores their values in tarfile. See also
the -L option.
- -hardlinks
- In extract mode, this option tells star to try to create a hardlink
whenever a symlink is encountered in the archive. In create mode, this
option tells star to try to archive a hardlink whenever a symlink
is encountered in the file system.
- -hpdev
- Allow 24 bits for the minor device number using 8 octal digits. Note that
although it allows to create tar archives that can be read with
HP-UX tar, this creates tar archives which violate POSIX.1-1988.
This option is only needed if you like to use a POSIX.1-1988 based archive
format that does not include extensions. If you use the xstar
format, star will use a base 256 extension that allows bigger
major/minor numbers by default, if you use the xustar or the
exustar format there is no limitation at all as these formats use
POSIX.1-2001 extended headers to archive the major/minor numbers by
default.
- -i
- Ignore checksum errors on tar headers. If this option is specified,
star will not exit if a header with a bad checksum is found but
search for the next valid header.
- -install
- Carefully replace existing files when extracting files. This is done
similar to install(1) by first extracting the files into a
temporary name and renaming the file to the final name after the
extraction of that file was successful.
As star by default does not remove non-empty
directories, an install that needs to remove existing non-empty
directories may also need the options -force-remove and
-remove-recursive.
- iskip=#
- Set the initial skip size to #. See bs= for the possible 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.
- -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 directories in case that
-remove-recursive has not been specified.
- -keep_old_files
- obsoleted by -keep-old-files
- -keep-old-files, -k
- Keep existing files rather than restoring them from tarfile. This
saves files from being clobbered even if tarfile contains a more
recent version of the corresponding file.
See SECURITY NOTES for more information.
- -L, -h
- Follow symbolic links as if they were files. Normally star will not
follow symbolic links but stores their values in tarfile. See also
the -h option.
- -l
- Do not print a warning message if not all links to hard linked files could
be dumped. This option is evaluated in the opposite way to historic
tar(1) implementations and to POSIX.1. POSIX.1 requests that by
default no warning messages will be printed and -l will enable
warning messages when not all links could be archived.
- level=dumplevel
- Set level for incremental dumps. This option is used to switch star
into true incremental dump mode. The dumplevel may be in the
range between 0..99.
In true incremental dump mode, a -C option which
is followed by the name a mount point and a dot ('.') as starting
directory name is required. Only a single file system may be handled at
a time. If the directory following the -C option is not referring
to a root directory of a file system, the dump is called a partial
dump. If the directory following the -C option is referring
to a root directory of a file system and no other restrictions apply
that exclude certain files from the dump, the dump is called a full
dump.
By default, the tardumps database is not written. See
also the tardumps=name and -wtardumps options and
the section INCREMENTAL BACKUPS for more information.
- -link-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 directories. Using
-link-dirs will force star to keep track of all directories
that will go into the archive and thus causes a lot more memory to be
allocated than in the default case.
If you like to extract a cpio archive that contains
hard linked directories, you also need to specify -link-dirs in
extract or diff mode. This is needed because many cpio
implementations create buggy archives with respect to hard links. If
star would look for hard linked directories in all cases, it
would detect many pseudo hard links to directories. Use
-link-dirs with care if you extract cpio archives.
Note that not all filesystem allow to create hard links to
directories. Also note that even though a non-root user is able detect
and archive hard linked directories, all known operating systems require
the extraction to be done as root in order to be able to create or
remove hard links to directories. For this reason its only recommended
to use this option when doing accurate backups and when hard links to
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 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 directory
if it rans out of file descriptors because of deeply nested directories.
If a directory then does not support telldir(3)/seekdir(3),
star will fail.
- -lzip
- run the input or output through a lzip pipe - see option -z
below.
- -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 directory scans. By default,
star excludes the directory but still recursively scans the content
of this directory as complex patterns could allow files inside the
directory tree to match. Using -match-tree allows to efficiently
exclude whole trees from scanning. This helps to avoid scannings directory
trees that are on remote file systems or contain excessive bad
blocks.
- maxsize=#
- Do not store files in tarfile if they are bigger than #. See
bs= for the possible syntax. By default, the number is multiplied
by 1024, so the value counts in units of kBytes. If the size specifier
ends with a valid multiplication character (e.g '.' for bytes or 'M' for
MB) the specified size is used as specified and not multiplied by 1024.
See bs= option for all possible multipliers.
- -meta
- In create mode, -meta causes star to archive all meta
data of the file (e.g. uid, permissions, ...) but not the file content. In
extract mode, it causes star to restore all meta data but
not the file content. In addition, in extract mode no plain file, special
file or directory will be created. Meta files are needed to support
incremental backups.
Warning: Do not try to extract star archives containing
meta files using other tar implementations if they are not aware
of the meta file extensions of star. Star tries to
force all tar implementations that are not standard compliant to abort.
Star also tries to make all non POSIX.1-2001 compliant tar
implementations unable to find a valid filename. However when other
POSIX.1-2001 aware tar implementations come up and don't know about
meta files, they will destroy files on disk.
The problems result from the only current fallback in the
POSIX standard that tells tar implementations to treat all unknown file
types as if they were plain files. As meta files are needed for
incremental backups, I am looking for people and companies who like to
support me to be able to add the meta file concept to the
POSIX.1-2005 standard.
- -modebits
- This options allows you to create tar archives that include more
than 12 bits from st_mode. Note this create tar archives that
violate POSIX but some tar implementations insist in reading such
nonstandard archives.
- 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. Typically, 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
independent tasks. This is true for e.g. incremental dump/restore
operations where inode numbers need to be traced for the whole task.
When tsize=# has been specified, but star
is not in multi volume mode, files cannot be split across volumes.
When -multivol has been specified in create mode
together with tsize=# then a media change is initiated
exactly after an amount of tsize data has been written. When
-multivol has been specified in create mode and
tsize=# has not been specified, then the medium change is
triggered by a EOT condition from writing the medium. This allows to use
media where the size cannot be known in advance (e.g. tapes with build
in compression); it does not work if the EOT condition is not returned
in sync with the related write operation. For this reason, it is
expected that data buffering inside a device driver cannot be used.
Depending on the selected archive format, star writes a
volume header at the beginning of a new medium. This medium header
allows to verify the correct volume after a change during read back. It
is recommended to use the exustar format for best results. In
create mode, -multivol is only supported for archives types that
allow to write reliable multi volume header information.
See tsize=# option for more information.
Note that -multivol is an interactive option that
prevents star from being used in non-interactive environments. If
you like to use it in a non-interactive environment, you need to specify
new-volume-script=script in addition in order to automate
the media change procedure.
- newer=filename
- Do not store files to tarfile if their modification time is not
newer than the modification time of filename. See -ctime
option for changing this behavior.
- -newest
- In conjunction with the list command this lists you only the newest file
in tarfile.
- -newest_file
- obsoleted by -newest-file
- -newest-file
- In conjunction with the list command this lists you only the newest
regular file in tarfile.
- new-volume-script=script
- Call script at end of each tape (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 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 recognize a
directory, -no-dirslash may not be used if archives should be
compatible with the old tar format.
- -no_fifo
- obsoleted by -no-fifo
- -no-fifo
- Don't use a fifo to optimize data flow from/to tarfile.
Currently the -fifo option is used as default. (This may be changed
at compile time.)
- -no-fsync
- Do not call fsync(2) for each file that has been extracted from the
archive. Using -no-fsync may speed up extraction on operating
systems with slow file I/O (such as Linux 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 typical cause for such problems is a NFS
file system that fills up before the buffer cache is synced or a write
error that occurs while the buffer cache is synced. There may be other
reasons. Use with extreme care.
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 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 contained 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 specified by the pattern or
file operands.
- -nowarn
- Do not print warning messages. This sometimes is useful to make the output
more readable (e.g. when hundreds of files that are going to be extracted
are not newer in the archive then on the filesystem).
- -numeric
- Use the numeric user/group fields in the listing rather than the default.
The default allows to list the ASCII version of user/group of the file and
to extract the owners of the files based on numeric values rather than the
names. In create mode, no user/groups names are put on the archive. The
-numeric option also applies when ACLs are going to be archived or
extracted.
- -O
- Be compatible to old versions of tar. If star is invoked
with this option, star generates archives which are fully
compatible with old UNIX tar archives. If in extract mode,
star ignores any additional info in the headers. This implies
neither that archives generated with this option are binary equal with
archives generated by old tar versions nor that star is
trying to comprehend all bugs that are found in old tar versions.
The bug in old tar versions that cause a reversal of a space and a
NULL byte in the checksum field is not repeated. If you want to have
signed checksums you have to specify the -signed-checksum option
too. If you want directories not to be archived in order to be compatible
to very old historic tar archives, you need to specify the -d
option too.
This option is superseeded by the H=headertype
option.
- -o, -nochown
- Do not restore owner and group of files. This may be used if super user
privileges are needed to 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 local files,
the size of the archive will be smaller. If you use this option on
cartridge tapes, is makes sure that later - in extract mode - star
will read up to the end of file marker on the tape and the next call to
star will read from the next archive on the same tape.
- -p
- Restore files and directories to their original permissions. Without this
option, they are created using the permissions in the archive and the
present umask(2). If star is called by the super user,
star behaves as if it has been called with the -p option.
See also -no-p option. If the archive contains Access Control Lists
(ACLs) in POSIX.1-2001 extended headers, star will restore the
access control lists from the archive for files if the -acl option is
specified. If the option -acl has not been specified, ACLs are not
restored at all.
- -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) implementations. File type select patterns do not
offer pattern matching but allow to restore subtrees. To extract a
complete sub tree from the directory dir with star using the
pattern= option, use pattern= dir/ if you like to
select a subtree by using the historic method, use dir as file type
argument. If you only like to extract the directory itself, use
dir/ as file type argument. See manual page for match(1) for
more details of the pattern matcher. All patterns are selection patterns
by default. To make them exclude patterns, use the -not or the
-V option.
- pkglist=file
- This is (for now) an internal interface for the Schily Source Package
System (sps). It only works in create mode and behaves similar to the
list= option, but it allows to overwrite the permissions,
the uid and gid values from the content of the
pkglist= file. Each line from the pkglist= file contains a
file name followed by the permission, a user name and a group name. The
permission is an octal character string. Each value that is not used to
overwrite the original values may be replaced by a '?'. The fields are
separated by spaces, so the pkglist= option does not allow files
that contain newline or space characters.
If used together with -find, the uid, gid
and permission 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 specified by the pattern or
file operands.
- -pax-H
- Follow symbolic links that have been encountered on the command line. If
the referenced file does not exist, the file information and type will be
for the link itself. If the link is referencing a file type that cannot be
archived with the current archive format, the file information and type
will be for the link itself.
- -pax-i
- Do interactive renaming in a way that has been defined for POSIX
pax. Star will print the original filename and prompt for a
reply. If you type just RETURN, than the file is skipped. If you
type '.', then the original file name is retained. If you type anything
else, then this is taken as the new file name.
Note that -pax-i is an interactive option that prevents
star from being used in non-interactive environments.
- -pax-L
- Follow symbolic links. If the referenced file does not exist, the file
information and type will be for the link itself. If the link is
referencing a file type that cannot be archived with the current archive
format, the file information and type will be for the link itself.
- -pax-ls
- Switch listing format to the format defined for POSIX pax and
ls.
- -pax-match
- Allow file type arguments to be recognised as regular expressions in a way
that has been defined for POSIX pax.
- -pax-n
- Allow each pattern to match only once. If a pattern matches a 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 string may contain the special character '&'. The
character '&' is substituted by the string that matches the
old pattern. The new string may also contain the special
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 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 -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
possible.
- -prinodes
- Print inode numbers in verbose list mode if the archive contains inode
numbers.
- -print-artype
- Check the type of the archive, print the archive and compression type on a
single line and exit.
- -qic24
- Set tape volume size to 61440 kBytes. See tsize=# option for
more information.
- -qic120
- Set tape volume size to 128000 kBytes. See tsize=# option
for more information.
- -qic150
- Set tape volume size to 153600 kBytes. See tsize=# option
for more information.
- -qic250
- Set tape volume size to 256000 kBytes. See tsize=# option
for more information.
- -qic525
- Set tape volume size to 512500 kBytes. See tsize=# option
for more information.
- -read0
- Read null terminated file names from the file specified with the
list= option.
- -refresh_old_files
- obsoleted by -refresh-old-files
- -refresh-old-files
- -refresh
- Do not create new files. Only already existing files may be overwritten
from tarfile if either newer versions are present in the archive or
if the -U flag is used. This allows to overwrite files by more
recent files from an archive that contains more files than the target
directory should contain. The option -refresh-old-files is the same
as the -refresh option.
- -remove_first
- obsoleted by -remove-first
- -remove-first
- Remove files before extraction. If this option is in effect, star
will remove files before extracting a file from the archive. This is
needed if you want to change the file type or if you need to break a hard
link. If you do not use either -ask-remove or -force-remove
together with -remove-first, this option is useless and no files
will be removed.
- -remove_recursive
- obsoleted by -remove-recursive
- -remove-recursive
- Remove files recursive. If removing of a file is permitted, star
will only remove files, specials and empty directories. If this option is
in effect, star will be allowed to recursively removes non empty
directories too.
- -restore
- switches star into true incremental restore mode. A file
named star-symtable and a directory named star-tmpdir is
created in the root directory of the file system where the extraction
takes place. If -restore has been specified, star behaves as if
-xdot has been specified too. See also level= option and
section INCREMENTAL BACKUPS for more information.
Note: Do not use the -restore option if you only like
to restore a single file or a list of selected files.
- 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 directories. You need to be super user to
extract special files.
- -s replstr
- Modify file or archive member names named by a pattern according to the
substitution expression replstr. The format of replstr is:
-s /old/new/[gp]
The old pattern may use regular expressions and the
new string may contain the special character '&'. The
character '&' is substituted by the string that matches the
old pattern. The optional trailing 'g' means global substitution.
If 'g' is not used, a substitution pattern is only used once on a name.
If the optional trailing 'p' is used, the substitution is printed to
standard error.
Up to 100 substitute options may be used. If more than one
substitute option has been specified, star will loop over all
substitute patterns until one matches. 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 target of the link
starts with a slash (/) or if /../ is 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 compiled to have both code for mapped pages and
for System V shared memory, star will use shared memory instead of
the default. If the -help menu doesn't show the -shm flag
you have no choice. When using System V shared memory, you may have to
raise the system's internal limit for shared memory resources to get
enough shared memory for star.
- -signed_checksum
- obsoleted by -signed-checksum
- -signed-checksum
- Use signed chars to calculate checksums. This violates the tar
specs but old versions of tar derived from the seventh edition of
UNIX are implemented in this way. Note: Only filenames and linknames
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 systems lack support to
get the real allocation list and force star to scan the files to
look for blocks that only contain null characters. This may star
cause to assume more holes to be present than the number that the file
really contains.
- -symlinks
- This option tells star in extract mode to try to create a symlink
whenever a hardlink is encountered in the archive.
- -T
- If the option file= or f= is omitted and the -T option is
present, star will use the device indicated by the
TAPE environment variable, if set.
- tardumps=name
- Set the file name for tar dump dates database to name. The default
name is /etc/tardumps. Use in combination with the level=
option to create true incremental dumps. See also -wtardumps
option and section INCREMENTAL BACKUPS for more information.
- -time
- Print timing info. See DIAGNOSTICS for more information.
- -to_stdout
- obsoleted by -to-stdout
- -to-stdout
- Extract files to stdout. This option may be used to extract
tarfiles containing tarfiles (see examples below).
- -tpath
- Use this option together with the -t option or with -cv
(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 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 Exabyte drives with factory settings. It also makes sense to use
-wready if multiple remote backups are made. In this case, the
remote connection is closed while the remote tape server is still writing
a file mark. If another remote backup is initiated before the old remote
server did finish to write the file mark, it would be impossible to open
the tape driver unless -wready is specified to tell star to
wait for the drive to become ready again.
- -wtardumps
- Tell star to update the file that contains the tar dump dates data
base if in dump mode. If the dump is not a full dump, the tar dump
dates data base file is not written. See also tardumps=name
and -C option or INCREMENTAL BACKUPS section for more
information.
- -X filename
- Use the file filename as a file containing a list of path names to
be excluded from the store/create/list/diff operation. The file
filename must contain a list of path names, each on a separate
line. Be careful with white space and note that path names in the list may
not contain new lines. Multiple -X options may be used. Each
argument must refer to a file containing path names. The -X option
has precedence before other options that select files to be included in
the operation. See also list= option.
- -xattr
- 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 #.
- -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 directories on the archive
are not newer. This is useful when for some reason, the directories are
recorded after their content (see -dirmode option), or when the
permissions of some directories must be set in any case. As the classical
UNIX cpio program does not implement delayed directory permission
and time stamp setting, cpio users often create archives in reverse
order (directories past their content). For this reason, it makes sense to
use -xdir while extracting cpio archives.
- -xdot
- Unconditionally extract the first directory in the archive if the name of
this directory is either '.' or './'. This helps to extract archives in an
expected way if the target directory is a newly created empty directory.
As this directory is newer than the top level directory in the archive,
star would usually skip this directory during extraction. The
effect of this directory is as if -xdir has been specified but is
switched off after the first directory has been found.
- -xfflags
- Store and extract extended file flags as found on BSD and Linux systems.
This option only makes sense when creating or extracting exustar
archives as it is based on POSIX.1-2001 extended tar headers. See NOTES
section for problems with -xfflags on Linux systems.
- -xmeta
- Extract meta files as if they were files. Meta files in
archives are plain files that do not contain any content data in the
archive. They may be created by using the -meta option in
star's create mode. Existing files are not overwritten. If a file
is missing, a zero sized file is created. If the option -meta is
used together with the option -force-hole, missing plain files are
created as sparse empty files of the original size.
- -xz
- run the input or output through a xz pipe - see option -z
below.
- -Z
- run the input or output through a compress pipe - see option
-z below.
- -z
- run the input or output through a gzip pipe. This is currently a
quick and dirty hack, that mainly will cover the most common usage to
compress the tar output if it is a file. No reblocking will be
done, so this option will currently only make sense on plain files. As the
-bz the -j the -Z and the -z option are non
standard, it makes sense to omit the -bz the -j the
-Z and the -z options inside shell scripts if you are going
to extract a compressed archive that is located inside a plain file as
star will auto detect compression and choose the right
decompression option to extract. The 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.
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 cardinal
scalar that is expressible in a decimal number.
- •
- The filesystem needs to implement at least two time stamps,
st_mtime the file's last modification time and st_ctime the
file's last status change time. Both time stamps need to be dealt with as
documented by 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 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
comparing the time stamps of all files against the time of the last backup.
Note that this method only works correctly if the level 0 backup and all
higher level incrementals include the whole file system. As star
archives all inode meta data, star is able to detect renamed files by
comparing the inode 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 outside 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:
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
f=archive-name -C
/filestem-mount-point .
Do not forget the dot at the end of the command line that
specifies the directory to start the operation.
Backups from live filesystems should be avoided. On operating
systems that support file system snapshots, backups should be made
from a read-only mount of a snapshot. Be careful that all files that have
been created between setting up a snapshot and starting an incremental
backup may be missing from all backups unless the
dumpdate=name option is used.
If the system that is going to be backed up is not acting as a
file server, it makes sense to shut down all services that may result in
inconsistent file states before setting up the filesystem snapshot. After
the filesystem snapshot has been set up, the services may be restarted.
If the the system that is going to be backed up is acting as a
file server, it may be that services on remote clients cause inconsistent
file states unless all such services that remotely access files are shut
down before the snapshot is set up.
Star includes options that help to deal with file system
snapshots. The following example backs up a file system on Solaris using
a file system snapshot 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.
Full (level 0) dumps should be made on a regular base (e.g. once a month). As a
full dump may take a long time and takes a lot of tape, it is wise to make
higher level incremental dumps with shorter intervals. The next table shows a
dump level list that may be used if monthly full dumps take place:
Sun Mon Tue Wed Thu Fri
Week 1: 0 10 10 10 10 5
Week 2: 10 10 10 10 10 5
Week 3: 10 10 10 10 10 5
Week 4: 10 10 10 10 10 5
The level 10 dumps made between Monday and Friday accumulate all
changes made within the week, 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 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 supports private incremental dumps and restores run as an
unprivileged user, but this mode has been tested less frequently.
The incremental restore procedure starts with restoring the last
full (level 0) dump. Then the latest incremental dump of each dump level
(with ascending order of dump levels) need to be restored.
Let us assume the first example from the section BACKUP
SCHEDULES for the backup schedule. If a disk crash happens before the
Thursday dump of week 3 has been made, the following restore procedure needs
to be applied:
- level 0
- starting with an empty disk, the full (level 0) dump from week 1 is
restored.
- level 5
- after the level 0 restore has been finished, the level 5 dump from Friday
in week 2 is restored.
- level 10
- after the level 5 restore has been finished, the level 10 dump from
Wednesday in week 3 is restored.
The disk now contains the same files as it did when the level 10
dump has been made on Wednesday of week 3.
To extract a level 0 dump call:
cd /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.
Star may be used to synchronize filesystem content. To do this, an
initial copy of the current content of the source filesystem needs to be
performed first.
To create an initial copy of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
-C /filestem-mount-point . | \
star -xpU -restore -C
/extract-target-dir
In order to perform subsequent synchronization of the target
filesystem with the content of the source filesystem, a modified incremental
dump/restore procedure may be used.
To copy incremental content of a filesystem call:
star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
-cumulative -C /filestem-mount-point
. | \
star -xpU -restore -C
/extract-target-dir
Note that like with backups in general, copies from a live
filesystem should be avoided. On operating systems that support file
system 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.
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
operation.
The following exit values are returned. Note that the negative values are only
available to modern shells and programs 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.
To get a listing in a way similar to ls -l one might use:
- example% star -tv f=/dev/rmt/1bn
The same command as listed above in a POSIX tar command
line syntax compliant way is:
- example% star tvf /dev/rmt/1mbn
To copy the directory tree in /home/someuser to the
directory /home/fs use:
-
example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
or by using the change directory option of star:
-
example% star -c -C /home/someuser . | star -xp -C /home/fs
Note that both examples above are not the optimum way to copy a
directory tree. A more efficient way to copy a directory tree is to use the
-copy option.
-
example% star -copy -p -xdot -C /home/someuser . /home/fs
To copy a file tree including the Access Control List
entries for all files and to correctly copy sparse (holey) files use:
-
example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
To compare the content of a tape to the filesystem one might
use:
- example% star -diff -v f=/dev/rmt/1bn
To compare two directory trees one might use:
-
example% star -c . | star -C todir -diff -v diffopts=!times
or better by using a method similar to the -copy method
above:
-
example% star -c -diff -v diffopts=!times -C fromdir . todir
To compare all properties of two file trees, use:
-
example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
To extract a backup of the /usr tree without all files residing
below /usr/openwin one might use:
- example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
To extract all .c files to src, all .o files
to obj and all other files to /tmp one might use:
-
example% star -xp -C src '*.c' -C obj '*.o' -C /tmp '*' f=/dev/rmt/1bn
To extract files from a zipped tar archive that is located
on a read only filesystem e.g. a CD while having the shell's working
directory on the CD one might use:
- example% star -zxp -C /tmp f=star-1.1.tar.gz
to extract the files from the tar archive to the /tmp
directory.
To backup a list of files generated by the find(1)
command:
-
example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
Note that this does not work if the file names from output of the
find command include new line characters.
To extract a tarfile that contains a tarfile one
might use:
-
example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
Pat, in this case should match the tarfile in the
tarfile on tape that should be extracted.
To make a backup of the root filesystem to a tape drive connected
to a remote machine, one might use:
- example# cd /
example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
You need a line in /etc/passwd like the following to enable
this:
- tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
And a .rhosts file in /etc/tapehome to allow remote connections
from the appropriate hosts. Make sure that the file /etc/default/rmt exists
and allows remote access to the requested tape drive.
To use a 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
example# star -xpk f=/dev/rmt/1bn
example# mt -f /dev/rmt/1bn rewind
example# star -diff -v diffopts=!times f=/dev/rmt/1bn
Now check the differences and decide whether to restore additional
files. This may be done by generating a list containing the needed filenames
and using the list= option or by using the interactive mode (see -w
option).
If you want a list that only contains all filenames from files
with differences you may use:
- example# star -diff -tpath diffopts=!times f=/dev/rmt/1bn
If you are looking for files that changed the type or the access
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' .
- COMERR_EXCODE
- If this environment is present, exit codes are not 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 conditional 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 specified.
The environment STAR_FSYNC has precedence over
/etc/default/star but may still be overwritten by 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 command line
options.
- STAR_WORKAROUNDS
- If this environment variable is present, implement workarounds 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 connection 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
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 network
socket to the remote server. This makes it impossible to work at maximum
performance and slows down the connection compared to a root
initiated rcmd(3) connection.
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.
- /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
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 extraction 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
maximum media size in 1024 byte units. If this entry contains a 0, then
the media size is unlimited. The fourth entry is optional. If it
contains a 'n' or a 'N', then the archive device is not a tape.
Examples:
archive0=/dev/tape 512 0 y
archive1=/dev/fd0 1 1440 n
archive2=/dev/rmt/0mbn 512 0
If the default file does not need to be shared with the tar
program from Solaris, any number may be used like a generic size option
like bs=.
Example:
archive0=/dev/tape 256k 40G y
- /etc/tardumps
- The default name for the dump level archive. The default name is used
whenever the tardumps=name option has not been specified.
The file is written or updated when -wtardumps is used.
The file holds one or more lines, each specifying a dump level
entry. Each dump level entry starts with a mount point name 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 representation of
the UTC seconds since Jan 01 1970, a space and the textual local time
representation of the dump time.
The numerical decimal dump time representation may be followed
by a dot and a sub second value. The textual local time representation
is for informational use by humans only and not evaluated by
star.
- ./star-symtable
- Contains a database that is needed in incremental restore mode.
- ./star-symdump
- Contains an intermediate dump of restore database after a fatal error
condition was met during an incremental restore operation.
- ./star-tmpdir
- Is the temporary directory that is used as intermediate file storage by
star if in incremental restore mode.
- ./star-lock
- Is a lock file created by star when doing an incremental restore. If this
file is present, it prevents star from running another incremental
restore operation. This helps to avoid more than one restore operation at
a time (e.g. from a cron script).
- /dev/tty
- Is used for the interactive user interface.
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)
star: f records + p bytes (total of x bytes = d.nnk).
The number of full records, the number of bytes in partial records
and the total amount of data in KBytes.
star: Total time x.yyysec (z kBytes/sec)
The time used and the transfer speed from/to the archive.
If there have been non fatal errors during the archive processing,
star will display a delayed error summary before exiting.
The command line syntax for the tar command (as defined in SUSv2 - UNIX-98)
deviates from the command line syntax defined for all other commands. While
the POSIX command line syntax requests all options to start with a dash
(-) and allows to either write options separately or combined (in case of
boolean flags), the tar command line syntax requires all options to be
combined into a single string that does not start with a dash. Star by
default assumes a command line syntax like a typical POSIX command and
includes a compatibility mode that allows to specify a command line syntax as
documented for the UNIX-98 tar command. If you believe that you found a
bug in the way star parses the command line, please first check your
command line for correctness before you make a bug report for star.
If you like to write portable shell scripts that call tar, use the
UNIX-98 tar command line syntax (i.e. a single option string and no
dash), choose the commands and options from the following set of characters
( rxtuc vxfblmo ) and check the shell script with both, your local
tar and star for correct behavior. It you expect the script to call
gnutar, do not include the -o option as gnutar implements this option
in a way that violates UNIX-98.
Star strips leading ./ sequences from pathnames. This lets
star in many cases store longer pathnames than other
implementations.
The POSIX.1-1988 method (ustar format) of storing files with
pathnames that are longer than 100 chars has some limitations:
- The name field (100 chars) an inserted slash (`/') and the prefix field
(155 chars) produce the pathname of the file. When recreating the original
filename, name and prefix are concatenated, using a slash character in the
middle. If a pathname does not fit in the space provided or may not be
split at a slash character so that the parts will fit into 100 + 155
chars, the file may not be archived. Linknames longer than 100 chars may
not be archived too.
The star, xstar, xustar, exustar,
pax, and gnutar archive formats don't have these limitations.
While gnutar uses a method that makes it impossible for other tar
implementations (except star) to restore filenames that are longer
than 100 chars, the xstar, xustar, exustar and
pax/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, exustar 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 compliant as possible. Inserting
this tar signature is a minor deviation from the standard that has
the last 12 bytes of each header reserved for future use. On the other side,
tar implementations such as some pax implementations that only
compute checksums on the first 500 bytes of the header are violating the
standard that requests the checksum to be computed on all 512 bytes of the
tar header. All tar implementations that are 100% Posix compliant
will be able to extract xstar archives as long as no new standard is
defined that claims the last 12 bytes of the header for a different use. But
then the ustar version number should be changed from `00' to `01'.
Now, that the POSIX-2001 standard has been accepted, it is even predictable
that all extensions to the standard tar format will go into the
POSIX.1-2001 extended headers which are extensible to include any feature
without future limitation. The only known tar implementation that
also uses the last 12 bytes of the tar header is Sun's tar
which uses these 12 bytes for files that are split over several archives.
Such archives created by Sun's tar are not readable by the buggy pax
implementation too. The Sun extension is not incompatible to the star
signature because Sun expects an octal number at the beginning of the 12
byte field which is a null character in the star case.
Star uses these four bytes since 1985 without problems. If
you need a 100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive,
you may use the xustar, exustar or the pax/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 reading the
archive if it encounters a logical EOF record in the archive. If the fifo is
used, star may read until the fifo is full or until the real EOF mark
on tape is reached. How much data star actually reads depends on the time
when the star foreground process sends a fifo shutdown signal to
the background fifo read process.
Gnu tar often creates tar archives with incorrect logical
EOF marks. The standard requires two blocks that are completely zeroed,
whereas gnutar often only adds one of them.
Old versions of tar found on SYSVr3 and earlier cannot read
tar archives with a blocksize greater than 10 kBytes.
The method of storing sparse files currently used with the
star and xstar format is not guaranteed to be used in later
versions of star. If the author decides to change this method, later
versions of star may not be able to restore sparse files from
tar archives made by the current version of star.
Some tar implementations violate the standard in using only
the first 500 Bytes of the header for checksum computation. These tar
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.
Gnutar's dumpdirs are non standard and are currently not
implemented.
If gnutar archives sparse files with more than four holes, it
produces archives that violate the standard in a way that prevents other
tar implementations to read these archives. Star knows about
that and is able to handle these gnutar archives.
The filetype N (LF_NAMES) from gnutar (an obsolete method
of storing long names) will never be implemented.
Note that on operating systems (like DOS) that do not implement
real pipes, star implements compression via a temporary file. Using
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.
If you unpack a tar archive in a non empty directory, any file in that directory
may be overwritten unless you specify the -k option. If the archive
contains symbolic links or hard links, star may even overwrite files
outside the current directory. If the directory where the archive is been
unpacked is not empty and contains contains symbolic links or hard links to
directories outside that directory, star may also overwrite files
outside the current directory. As many other commands, star usually has
all possible permissions when run as root. Unpacking archives as root thus may
have fatal results to any file on your system. Be very careful when you try to
extract an archive that has not been created by you. It is possible to create
hand crafted tar archives that may overwrite critical files (like /etc/passwd)
on your system. In addition all tar archives that have been created with the
list= option and tar archives where the C= option was not
specified before all file type arguments may be critical.
A good advise is to extract all doubtful archives as non root in
an empty directory and to 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 for the first run.
See the ENVIRONMENT section and /etc/default/star
for ways to configure the default behavior.
If star is installed suid root, star is able to make connections
to remote archives for non root users. This is done by using the rcmd(3)
interface to get a connection to a rmt(1) server.
Star resets its effective uid back to the real user id
immediately after setting up the remote connection to the rmt server and
before opening any other file.
If star has not been installed suid root and not called by
root, it will try to create the remote connection via rsh(1) or
ssh(1) (in case the environment RSH has been set to
ssh). Note that in this case, the throughput to the remote tape
server will be much lower than with a connection that has been initiated via
rcmd(3).
If star is running on a large file aware platform, star is able to
handle files up to 8 GB in a mode that is compliant to the POSIX.1-1988
ustar format. With a nonstandard star specific extension, up to
95 bits may be used to code the filesize. This will handle files up to
200,000,000 TB. With the new POSIX.1-2001 extended headers used by the
xustar, exustar and pax/epax format, any filesize
may be archived.
The fact that the -f option has to be implemented in a way that is
compatible with old tar implementations gives several problems. The options
-fifostats, -force-hole, -force-remove and -fifo
interfere with the -f option and the fact that they exist prevents
users from using filenames like e.g. ifo using the traditional way
where the filename directly follows the string -f without any space
between the option name and the file name. However, there is no problem to use
a file named ifo by by calling -f ifo, f=ifo,
-f=ifo or -f= ifo. Be careful not to make typos with the above
options. The result could be that a file is created as a result of the
mistyped option.
There is currently no way to set the fifo lowwater and highwater
marks.
If you ever discover a hang in the fifo of star, get the
process ids for both star processes, send both a RTMAX signal using
kill(1) and report the disgnostic output.
There is currently no way to automatically delete files in the
target file tree if they are obsolete. Star should implement
something similar to gnutar's dumpdirs.
If not invoked by the super user star may not be able to
extract files if they reside in read only directories.
Star is not able to make a complete backup of a filesystem
if files are hidden by a mount that is in effect on a directory of this
filesystem. This may be avoided in case of the ufs filesystem if the backup
is made off a ufs snapshot (see the man page for fssnap(1m) It could
be avoided for any filesystem if the loopback filesystem had an option that
tells lofs not to traverse mountpoints.
For now (late 2002), we know that the following programs are
broken and do not implement signal handling correctly:
- rsh
- on SunOS-5.0...SunOS-5.9
- ssh
- from ssh.com
- ssh
- from openssh.org
Sun already did accept a bug report for
rsh(1)/ssh(1). Openssh.org accepted and fixed a bug for
their implementation of ssh(1).
If you use star to create a remote connection via an
unfixed rsh(1) or ssh(1), be prepared that terminal generated
signals may interrupt the remote connection.
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).
Joerg Schilling
D-13353 Berlin
Germany
Mail bugs and suggestions to:
joerg@schily.net
The source code for star is in the star project at Sourceforge 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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |