Manpages

NAME

star − unique standard tape archiver

SYNOPSIS

star  command [ options ] file1 ... filen
ustar command [ options ] file1 ... filen
tar   command [ options ] file1 ... filen
star  −copy   [ options ] file1 ... directory

DESCRIPTION

Star is a very fast tar(1) like tape archiver with improved functionality.

Star archives and extracts multiple files to and from a single file called a tarfile. A tarfile is usually a magnetic tape, but it can be any file. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory.

Star’s actions are controlled by the mandatory command flags from the list below. The way star acts may be modified by additional options.

Note that unpacking tar archives may be a security risk because star may overwrite existing files. See SECURITY NOTES for more information.

FEATURES

Star includes the first free implementation of POSIX.1−2001 extended tar headers. The 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 fetch files from a list of directories (in create mode) or to distribute files to a list of directories (in extract mode). A substitute option allows ed(1) like pattern substitution in file names.

Star includes a sophisticated diff command. Several diff options allow user tailorable functionality. Star won’t show you differences you are not interested in. Check the diffopts= option for more details.

Star has no limitation on filename length. Pathnames and linknames up to PATH_MAX (1023 bytes with old OS versions and 4095 bytes with POSIX.1−2001) may be archived. Later versions may be able to deal with longer pathnames.

Star deals with all 3 times, available for files on UNIX systems if the 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, star is able to do backups without changing any of the 3 the times.

If used with the H=ustar option, or if called as ustar or tar while the H=headertype option is not used, star is 100% POSIX compliant.

Star’s default format (if called as star) is xstar and is as posix compliant as possible. Enhancements to the standard that prevent correct extraction of single files when using a different tar implementation that is only POSIX.1−1988 compliant may occur, but they only affect single files with a pathname that is longer than 100+130 chars or when archiving sparse files with the −sparse option in effect. All other files will extract correctly. See the description for the H=headertype option below for more information on archive formats and possible archive interchange problems.

Star makes it easy to repair corrupted filesystems. After a fsck −y has been run on the filesystem, star is able to restore only the missing files automatically. Use then star −diff to check for differences (see EXAMPLES for more information).

Star automatically recognizes the type of the archive. Star therefore is able to handle features and properties of different archive types in their native mode, if it knows about the peculiarities of the archive type. See the H=headertype option for more details. To be able to do this, star adds hidden fingerprints to the archive header that allows to recognise all star specific archive formats. The GNU tar format is recognised by the way it deviates from the standard.

Star automatically recognizes and handles byte swapped archives. There is no option to manually control byte swapping.

Star automatically recognizes and handles compressed archives inside plain files.

Star is able to archive and restore Access Control Lists for files using POSIX.1−2001 extended headers.

COMMAND

In native mode, star is compatible to the command line syntax of a typical POSIX command and for this reason expects commands and options to start with a single dash (−). In this case, commands and options may be specified separately, all boolean or increment type options may be specified either separately or combined. For 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 compatibilitx 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.

If the option −diff has been specified in addition, star performs a one pass directory tree compare instead of copying files. The shorthand −c −diff instead of −copy −diff is also allowed.

On operating systems with slow file I/O (such as Linux), it may help to use −no−fsync in addition, but then star is unable to detect all error conditions; so use with care.

If the option −t has been specified in addition, the last file type argument is not a target directory and star is performing a one pass listing instead of copying files. This makes sense as the listing from star may be better readable than the output from ls −lR. The shorthand −c −t or −ct instead of −copy −t is also allowed.

The job is by default done in the best archive mode. This implies that it defaults to H=exustar −dump. When in −copy mode, star forks into two processes and data exchange is done via the shared memory from the FIFO. This gives the best possible performance. Without FIFO, the −copy mode will not work.

The list= option, patterns and substitutions apply only to the create side of the copy command.

On operating systems with slow file I/O (such as Linux), it may help to use −no−fsync in addition, but then star is unable to detect all error conditions; so use with care.

Except for the shorthands documented above, exactly one of the commands above must be specified.

If one or more patterns or substitution commands have been specified, they apply to any of the command listed above. In copy mode, all patterns and substitute commands apply to the create side.

OPTIONS

See SECURITY NOTES for more information.

See SECURITY NOTES for more information.

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:

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.

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.

The nonstandard extensions are located in the space between the link name and the POSIX file name prefix. As the star format does not use a POSIX magic string, the extensions do not interfere with the POSIX tar formats. The last 4 bytes of the tar header contain a ’tar\0’ signature.

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.

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.

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.

File size is unlimited, uid/gid/uname/gidname is unlimited, major/minor is unlimited. Sparse files will be archived correctly.

File size is unlimited, uid/gid/uname/gidname is unlimited, major/minor is unlimited. Sparse files will be archived correctly.

File size is unlimited, uid/gid/uname/gidname is unlimited, major/minor is unlimited. Sparse files will be filled up with zeroes.

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.

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.

All tar archive formats may be interchanged if the archive contains no files that may not be archived by using the old tar format. Archives in the xstar format may be extracted by any 100% POSIX compliant tar implementation if they contain no files with pathnames > 100+130 chars and if they contain no sparse files that have been archived by using the −sparse option.

−ask_remove

obsoleted by −ask−remove

−ask−remove

Ask to remove non writable files on extraction. By default, star will not overwrite files that are read only. If this option is in effect, star will ask whether it should remove these files to allow the extraction of a file in the following way:

remove ’filename’ ? Y(es)/N(o) :

−atime, −a

Reset access time of files after storing them to tarfile. On Solaris 2.x, (if invoked by root) star uses the _FIOSATIME ioctl to do this. This enables star not to trash the ctime while resetting the atime of the files. If the −atime option is used in conjunction with the list command, star lists access time instead of modification time. (This works only in conjunction with the star, xstar, xustar, exustar, and with the pax format.) Another option to retain the access time for the the files that are going to be archives is to readonly mount a UFS snapshot and to archive files from the mount point of the UFS snapshot.

−block−number

Print the archive block number (archive offset / 512) at the beginning of each line when in verbose mode. This allows to write backup scripts that archive the offsets for files and that use

mt fsr blockno

to skip to the tape block number of interest in a fast way if a single file needs to be restored.

blocks=#, b=#

Set the blocking factor of the tarfile to # times 512 bytes (unless a different multiplication factor has been specified - see bs= option for posible multiplication factors). Changing the blocking factor only makes sense when the archive is located on a real tape device or when the archive is accessed via the remote tape protocol (see f= option below). The default is to use a blocking factor of 20 i.e. 10 kBytes. Increasing the blocksize will speed up the backup. For portability with very old tar 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.

−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.

•

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.

−cumulative

A shorthand for −dump−cumulative. See −dump−cumulative for more information.

diffopts=optlst

Comma separated list of diffopts. Valid members in optlst are:

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.

−dirmode

If in create mode (i.e. when storing files to archive), star stores directories past the corresponding files. This guarantees that even old tar implementations without a directory cache will be able to restore the correct times of directories. The option −dirmode should only be used if the archive needs to be extracted by an old tar implementation. If star is used to extract an archive that has been created with −dirmode the directories will not get an old time stamp unless the option −U is used while extracting the archive.

−dodesc

Force star to descend directories found in a list=file. See also the −D option above.

The 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−cumulative

instructs star to perform incremental dumps relatively to the last incremental dump of the same level. Incremental dumps with a level higher than 0 are normally done relatively to the content of a previous dump with lower level. If incremental dumps and restores are going to be used to synchronize filesystem content, every successive incremental dump will increase in size if −dump−cumulative is not used. See section SYNCHRONIZING FILESYSTEMS for more information.

dumpdate=name

Tells star to use the mtime of the time stamp file name instead of using the start time of star. This is needed when star is run on file system snapshots. If star would use the the start time with snapshots, all files that have been modified between the setup of the snapshot and the start of star would be missing on the backup.

−dumpmeta

changes the behavior of star in incremental dump mode. If −dumpmeta is used and only the inode change time (st_ctime) of a file has been updated since the last incremental dump, star will archive only the meta data of the file (e.g. uid, permissions, ...) but not the file content. Using −dumpmeta will result in smaller incremental dumps, but files that have been created between two incrementals and set to an old date in st_mtime (e.g. as a result from a tar extract) will not be archived with full content. Using −dumpmeta thus may result in incomplete incremental dumps, use with extreme care.

errctl= name

Use the file name as error control file. The reason for using an error control file is to make star quiet about error conditions that are known to be irrelevant on the quality of the archive or restore run. A typical reason to use error control is to suppress warnings about growing log files while doing a backup on a life file system.

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 star-match(1) or patmatch(3) for more information). 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 ignores the current error condition.

The list of error conditions to be ignored may use one or more (in this case separated by a ’|’ character) identifiers from the list below:

If a specific error condition is ignored, then the error condition is not only handled in a silent way but also excluded from the error statistics that are printed at the end of the star run.

Be very careful when using error control as you may ignore any error condition. If you ignore the wrong error conditions, you may not be able to see real problems anymore.
−F,−FF ...

Fast and simple exclude option for create mode. With one −F argument, star ignores all directories called SCCS and RCS. With two −F arguments, star in addition ignores all files called core errs a.out all files ending with .o. OBJ/. With three −F arguments, star ignores all sub trees starting from a directory that includes a file .mirror or .exclude and all object files and files called core errs a.out all files ending with .o. With four −F arguments, star ignores all sub trees starting from a directory that includes a file .mirror or .exclude the latter files are excluded too as well as and all object files and files called core errs a.out all files ending with .o. With five −F arguments, star in addition again excludes all directories called SCCS and RCS.

−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 ENVIRONMENT section for information on how to use ssh(1) to create a remote tape server connection.

−force_hole

obsoleted by −force−hole

−force−hole

Try to extract all files with holes. This even works with files that are created without the −sparse option. Star, in this case examines the content of the files in the archive and replaces writes to parts containing binary zeroes with seeks. This option should be used with extreme care because you sometimes get in trouble when files get unattended holes. All options that start with the −f sequence are sensitive to typo problems, see BUGS section for more information.

−force_remove

obsoleted by −force−remove

−force−remove

Force to remove non writable files on extraction. By default, star will not overwrite files that are read only. If this option is in effect, star will silently remove these files to allow the extraction of a file. All options that start with the −f sequence are sensitive to typo problems, see BUGS section for more information.

−force-restore

Force an incremental restore even if the incremental dump is only a partial dump. See −wtardumps, level= and section INCREMENTAL BACKUPS for more information.

fs-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.

−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.

−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.

level=dumplevel

Set level for incremental dumps. This option is used to switch star into true incremental dump mode.

In true incremental dump mode, a −C option which is followed by the name a mount point and a dot (’.’) as starting directory name is required. Only a single file system may be handled at a time. If the directory followed by the −C option is not referring to a root directory of a file system, the dump is called a partial dump. If the directory followed by the −C option is referring to a root directory of a file system and no other restrictions apply that exclude certain files from the dump, the dump is called a full dump.

By default, the tardumps database is not written. See also the tardumps=name and −wtardumps options and the section INCREMENTAL BACKUPS for more information.

−link−dirs

When in create mode, try to find hard linked directories. Using −link−dirs will force star to keep track of all directories that will go into the archive and thus causes a lot more memory to be allocated than in the default case.

If you like to extract a cpio archive that contains hard linked directories, you also need to specify −link−dirs in extract or diff mode. This is needed because many cpio implementations create buggy archives with respect to hard links. If star would look for hard linked directories in all cases, it would detect many pseudo hard links to directories. Use −link−dirs with care if you extract cpio archives.

Note that not all filesystem allow to create hard links to directories. Also note that even though a non-root user is able detect and archive hard linked directories, all known operating systems require the extraction to be done as root in order to be able to create or remove hard links to directories. For this reason its only recommended to use this option when doing accurate backups and when hard links to 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 command from filename. The file filename must contain a list of filenames, each on a separate line. This option implies the −D option. To force star to descend directories, use the −dodesc option in this case.

−lowmem

Try to run with reduced memory requirements. This causes star to default to 1 MB of FIFO memory. Instead of allocating memory to hold the directory content and reading the directory at once, star reads the directory name by name. This may cause star to close the directory if it rans out of file descriptors because of deeply nested directories. If a directory then does not support telldir(3)/seekdir(3), star will fail.

−M, −xdev

Do not descend mount points. This is useful when doing backups of complete file systems. See NOTES for more information.

−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.

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.

−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.

newer=filename

Do not store files to tarfile if their modification time is not newer than the modification time of filename. See −ctime option for changing this behavior.

−newest

In conjunction with the list command this lists you only the newest file in tarfile.

−newest_file

obsoleted by −newest−file

−newest−file

In conjunction with the list command this lists you only the newest regular file in tarfile.

new−volume−script=script

Call script at end of each tape if in multi volume mode. If this option is not in effect, star will ask the user to confirm the volume change. The script is called with two parameters. The first parameter is the next volume number and the second parameter is the next archive file name.

−nodump

If this option is set, star will not dump files that have the nodump flag set. Note that this currently only works on BSD−4.4 derivates and on Linux. On Linux, using this option will cause a performance degradation (the system time increases by 10%) because of the unlucky kernel interface.

−no-dirslash

Do not add a slash to the end of directory names if writing to an archive. Historic tar archive formats did only allow to specify plain files and hard links. Around 1980, BSD added a feature to specify a directory on tape by adding a slash to the end of the name. POSIX.1-1988 defined the first official tar archive format that had a clean method to specify the type of a directory. As old tar formats need the slash to recognize a directory, −no-dirslash may not be used if archives should be compatible with the old tar format.

−no_fifo

obsoleted by −no−fifo

−no−fifo

Don’t use a fifo to optimize data flow from/to tarfile. Currently the −fifo option is used as default. (This may be changed at compile time.)

−no−fsync

Do not call fsync(2) for each file that has been extracted from the archive. Using −no−fsync may speed up extraction on operating systems with slow file I/O (such as Linux), but includes the risk that star may not be able to detect extraction problems that occur after the call to close(2). A typical cause for such problems is a NFS file system that fills up before the buffer cache is synced or a write error that occurs while the buffer cache is synced. There may be other reasons. Use with extreme care.

−nochown, −o

Do not restore owner and group of files. This may be used if super user privileges are needed to overwrite existing files but the local ownership of the existing files should not change.

−no_statistics

obsoleted by −no−statistics

−no−statistics

Do not print statistic messages at the end of a star run.

−no−xheader

Do not create or extract POSIX.1-2001 extended headers. This option may be used if you like to read an archive with broken extended headers.

−not, −V

Invert the meaning of the pattern list. i.e. use those files which do not match any of the pattern. Note that this option only applies to patterns that have been specified via the pattern=pattern or pat=pattern option. Patterns specified as file type arguments will not be affected.

−notarg, −pax-c

Match all file or archive members except those specified by the pattern or file operands.

−nowarn

Do not print warning messages. This sometimes is useful to make the output more readable (e.g. when hundreds of files that are going to be extracted are not newer in the archive then on the filesystem).

−numeric

Use the numeric user/group fields in the listing rather than the default. The default allows to list the ASCII version of user/group of the file and to extract the owners of the files based on numeric values rather than the names. In 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.

This option is superseeded by the H=headertype option.

−o, −nochown

Do not restore owner and group of files. This may be used if super user privileges are needed to overwrite existing files but the local ownership of the existing files should not change.

−onull, −nullout

Do not actually write to the archive but compute and add the sizes. This is useful when trying to figure out if a tape may hold the current backup. Please only use the −onull option as it is a similar option as used by the sdd(1) command.

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. See manual page for star-match(1) for more details of the pattern matcher. All patterns are selection patterns by default. To make them exclude patterns, use the −not or the −V option.

−pax-c, −notarg

Match all file or archive members except those specified by the pattern or file operands.

−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-p string

PAX style privileges string. Several characters (each has it’s own meaning). The following characters are defined:

−prinodes

Print inode numbers in verbose list mode if the archive contains inode nubers.

−print−artype

Check the type of the archive, print the archive and compression type on a single line and exit.

−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.

−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 retore 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.

−s replstr

Modify file or archive member names named by a pattern according to the substitution expression replstr. The format of replstr is:

−s /old/new/[gp]

The old pattern may use regular expressions and the new string may contain the special character ’&’. The character ’&’ is substituted by the string that matches the old pattern. The optional trailing ’g’ means global substitution. If ’g’ is not used, a substitution pattern is only used once on a name. If the optional trailing ’p’ is used, the substitution is printed to standard error.

Up to 100 substitute options may be used. If more than one substitute option has been specified, star will loop over all substitute patterns until one matches.

If the name substitutes to the empty string, the file is skipped.

−secure−links

Do not extract hard links or symbolic links if the link name (the target of the link) starts with a slash (/) or if /../ is contained in the link name. Tar archives containing such links could be used to compromise the system. If they are unpacked together with a lot of other files, this may not even be noticed.

As the usability of a tar archiver would be limited if −secure−links checking would be done by default, star makes link checking optional.

If you unpacked a tar archive using the −secure−links and did not get a security warning at the end of the star run, all files and links have been extracted. If you get a warning, you should unpack the archive a second time and specify the options −k, −w and −nowarn in addition to the options used for the first run. See SECURITY NOTES for more information.

−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, pax, or suntar. 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. 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 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.

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.

−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).

tsize=#

Set tape volume size to # to enable multi volume tape support. See bs= for the possible syntax. By default, the number is multiplied by 512, so the value counts in units of 512 byte blocks. If the size specifier ends with a valid multiplication character (e.g ’.’ for bytes or ’M’ for MB) the specified size is used as specified and not multiplied by 512. With this option in effect, star is able to archive filesystems that are bigger then the tape size. If the option tsize=# without −multivol then no file will be split across volumes and each volume may in theory be read back separately. Files that do not fit on a single tape may not be stored in this mode. If −multivol has been specified in addition, star will split files when the maximum allowed tape size has been reached. If the tape volume size is not a multiple of the tape block size, the tape volume size is silently rounded down to a value that is a multiple of the tape block size.

See −multivol option for more information.

−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.

get/put ? Y(es)/N(o)/C(hange name) :

You may answer either ’N’ for No or <Return> to skip this file. If you answer ’Y’ the file is extracted or archived on tape with its original name. If you answer ’C’, you are prompted for a new name. This name is used for the filename on disk if star is in extract mode or for the archive name if star is in create mode.

See SECURITY NOTES for more information.
−wready

This option tells Star to wait up to two minutes for the drive to become ready. It has been added as a hack for a bug in the SunOS/Solaris st device driver. This driver has problems to sense the loading time with Exabyte drives with factory settings. It also makes sense to use −wready if multiple remote backups are made. In this case, the remote connection is closed while the remote tape server is still writing a file mark. If another remote backup is initiated before the old remote server did finish to write the file mark, it would be impossible to open the tape driver unless −wready is specified to tell star to wait for the drive to become ready again.

−wtardumps

Tell star to update the file that contains the tar dump dates data base if in dump mode. If the dump is not a full dump, the tar dump dates data base file is not written. See also tardumps=name and −C option or INCREMENTAL BACKUPS section for more information.

−xattr−linux

Store and extract extended file attributes as found on Linux systems. This option only makes sense when creating or extracting exustar archives as it is based on POSIX.1−2001 extended tar headers.

The method used in the current implementation could be used to store and extract extended file attributes from BSD too. Note that the current implementation is not generic enough to cover more general extended file attribute implementations as found on Solaris. If star starts to implement a method that covers extended file attributes on Solaris, the new method will be used then −xattr has been specified and −xattr−linux will refer to the old method. The method used with −xattr−linux may go away in the future.

xdebug=#, xd=#

Set extended debug level to #.

−xdev, −M

Do not descend mount points. This is useful when doing backups of complete file systems. See NOTES for more information.

−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.

star −c . | gzip | sdd ibs=4k obs=32k −fill of=/dev/rmt/1bn
or
star −c . | gzip | sdd ibs=4k obs=32k −fill ovsize=60m of=/dev/rmt/1bn
if the tape can hold 60 MB.

INCREMENTAL BACKUPS

Star is able to back up file system in full and incremental mode. To allow incremental backups, the file system must implement POSIX semantics.

The 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 inode numbers.

Detecting renamed files only works if star scans the whole file system tree for each full and incremental backup. This will work in case no files are excluded and the dump starts at the root directory of a file system. In case that no files are renamed from excluded parts to included parts, partial backups may be taken also. Partial backups only make sense if a complete directory sub tree is excluded (e.g. by using the pat= option) or if a partial backup starts at a sub directory that is not the root directory of the file system.

To create a level 0 dump call:

star −c −xdev −sparse −acl −link−dirs level=0 −wtardumps \     
f=archive-name −C /filestem-mount-point .

To create a level 1 dump call:

star −c −xdev −sparse −acl −link−dirs level=1 −wtardumps \     
f=archive-name -C /filestem-mount-point .

Backups from life 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.

Star includes options that help to deal with file system snapshots. The following example backs up a file system on Solaris using a file system snapshot:

echo > /tmp/snapstamp

mount -r ’fssnap -F ufs -o \     
backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs’ /mnt

star −c −xdev −sparse −acl −link−dirs level=0 −wtardumps \     
f=archive-name dumpdate=/tmp/snapstamp \     
fs-name=/export/nfs −C /mnt .

First a file with a current time stamp is created, then a snapshot for /export/nfs is created and mounted on /mnt. The following star command then creates a level 0 backup from the file system using the time the snapshot was created and the original mount point of the file system for /etc/tardumps and the archive header.

Note that if the backup is done on a life file system, it may be unreliable. A typical problem problem in this context is caused by growing log files. As growing files are not a real problem with backups, the best way of dealing with growing files is to set up a star error control file (see errctl= option) and to tell star to ignore growing files.

BACKUP SCHEDULES

Full (level 0) dumps should be made on a regular base (e.g. once a month). As a full dump may take a long time and takes a lot of tape, it is wise to make higher level incremental dumps with shorter intervals. The next table shows a dump level list that may be used if monthly full dumps take place:

Sun Mon Tue Wed Thu Fri

The level 9 dumps made between Monday and Friday accumulate all changes made within the week. If you don’t like this, use the following backup schedule:

Note that in this case, 7 dumps need to be restored if the a crash happens at the worst case date (after the Friday dump in week 2 or later).

INCREMENTAL RESTORES

Incremental restores should be made to an empty file system (except for the lost+found directory). Star is currently unable to perform incremental restores to a file system that contains active mount points.

The incremental restore procedure starts with restoring the last full (level 0) dump. Then the latest incremental dump of each dump level (with ascending order of dump levels) need to be restored.

Let us assume the first example from the section BACKUP SCHEDULES for the backup schedule. If a disk crash happens before the Thursday dump of week 3 has been made, the following restore procedure needs to be applied:
level 0

starting with an empty disk, the full (level 0) dump from week 1 is restored.

level 5

after the level 0 restore has been finished, the level 5 dump from Friday in week 2 is restored.

level 10

after the level 5 restore has been finished, the level 10 dump from Wednesday in week 3 is restored.

The disk now contains the same files as it did when the level 9 dump has been made on Wednesday of week 3.

To extract a level 0 dump call:

cd /filestem-mount-point
star −xpU −restore f=archive-name

This creates the directory star-tmpdir and the database star-symtable in the root directory of the new file system. Subsequent restores with higher level backups depend on these files.

To extract a level 1 (or higher) dump call:

cd /filestem-mount-point
star −xpU −restore f=archive-name

Note that the environment variable STAR_DEBUG exists, star does not remove files with link count 1 that have been removed between incremental dumps. These files are moved to the directory star-tmpdir. Before you start to extract the next incremental, you need to remove all files in star-tmpdir.

SYNCHRONIZING FILESYSTEMS

Star may be used to synchronize filesystem content. To do this, an initial copy of the current content of the source filesystem needs to be performed first.

To create an initial copy of a filesystem call:

star −c −xdev −sparse −acl −link−dirs level=0 −wtardumps \     
−C /filestem-mount-point . | \     
star −xpU −restore -C /extract-target-dir

In order to perform subsequent synchronization of the target filesystem with the content of the source filesystem, a modified incremental dump/restore procedure may be used.

To copy incremental content of a filesystem call:

star −c −xdev −sparse −acl −link−dirs level=1 −wtardumps \     
−cumulative −C /filestem-mount-point . | \     
star −xpU −restore -C /extract-target-dir

Note that like with backups in general, copies from a life filesystem should be avoided. On operating systems that support file system snapshots, copies should be made from a read-only mount of a snapshot. Be careful that all files that have been created between setting up a snapshot and starting an incremental copy may be missing from all copies unless the dumpdate=name option is used.

See section INCREMENTAL BACKUPS to learn how to modify the command line in case file system snapshots are used.

SIGNALS

If star handles a signal, it first prints the statistics. Star handles the following signals:

EXAMPLES

To get a listing in a way similar to ls −l one might use:

example% star −tv f=/dev/rmt/1bn

The same command as listed above in a POSIX tar command line syntax compliant way is:

example% star tvf /dev/rmt/1mbn

To copy the directory tree in /home/someuser to the 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

To copy a file tree including the Access Control List entries for all files use:

example% star −c −Hexustar −acl −C /home/someuser . | star −xp −acl −C /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

To compare all properties of two file trees, use:

example% star −c −dump −C fromdir . | star −C todir −diff −vv

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 ssh(1) connection for a backup to a remote tape server, one might use:

example# env RSH=/usr/bin/ssh star −cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .

To repair a corrupted filesystem for which no recent 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

ENVIRONMENT

STAR_COMPRESS_FLAG

If you like star to always create compressed files that use maximum compression, you may set the environment variable STAR_COMPRESS_FLAG to −9.

STAR_DEBUG

If this environment variable is present, star will not remove 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.

Note that this forces star to create a pipe to the rsh(1) program and disallows star to directly access the network socket to the remote server. This makes it impossible to set up performance parameters and slows down the connection compared to a root initiated rcmd(3) connection.

See BUGS section for more information.

FILES

/etc/default/star

Default values can be set for the following options in /etc/default/star. For example: CDR_FIFOSIZE=64m
STAR_FIFOSIZE

Sets the default size of the FIFO (see also fs=# option).

STAR_FIFOSIZE_MAX

Sets the maximum size of the FIFO (see also fs=# option). Setting STAR_FIFOSIZE_MAX in /etc/default/star allows to overwrite global values from backup scripts for machines with less memory.

archive0=
archive2=
archive3=
archive4=
archive5=
archive6=
archive7=
archive0=

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. It if 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-tmpdir

Is the temporary directory that is used as intermediate file storage by star if in incremental restore mode.

/dev/tty

Is used for the intercative user interface.

SEE ALSO

spax(1), suntar(1), scpio(1), tar(1), cpio(1), pax(1), rcp(1), mt(1), rmt-star(1), star-match(1), dd(1), sdd(1), rsh(1), ssh(1), star(4/5), rcmd(3), fssnap(1m)

DIAGNOSTICS

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

The number of full records, the number of bytes in partial records and the total amount of data in KBytes.

star: Total time x.yyysec (z kBytes/sec)

The time used and the transfer speed from/to the archive.

If there have been non fatal errors during the archive processing, star will display a delayed error summary before exiting.

NOTES

The command line syntax for the tar command (as defined in SUSv2 - UNIX-98) deviates from the command line syntax defined for all other commands. While the POSIX command line syntax requests all options to start with a dash (−) and allows to either write options separately or combined (in case of boolean flags), the tar command line syntax requires all options to be combined into a single string that does not start with a dash. Star by default assumes a command line syntax like a typical POSIX command and includes a 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 archive format uses a method that allows an POSIX.1−1988 compliant way of storing filenames, if the POSIX method would allow this. When the archive format is xustar, exustar or pax very long filenames are stored using 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 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.

SECURITY NOTES

If you unpack a tar archive in a non empty directory, any file in that directory may be overwritten unless you specify the −k option. If the archive contains symbolic links or hard links, star may even overwrite files outside the current directory. As many other commands, star usually has all possible permissions when run as root. Unpacking archives as root thus may have fatal results to any file on your system. Be very careful when you try to extract an archive that has not been created by you. It is possible to create hand crafted tar archives that may overwrite critical files (like /etc/passwd) on your system. In addition all tar archives that have been created with the list= option and tar archives where the C= option was not specified before all file type arguments may be critical.

A good advise is to extract all doubtful archives as non root in an empty directory and to specify the −secure−links option. If you get a warning, you should unpack the archive a second time and specify the options −k, −w and −nowarn in addition to the options used for the first run.

SUID NOTES

If star is installed suid root, star is able to make connections to remote archives for non root users. This is done by using the rcmd(3) interface to get a connection to a rmt(1) server.

Star resets its effective uid back to the real user id immediately after setting up the remote connection to the rmt server and before opening any other file.

If star has not been installed suid root and not called by root, it will try to create the remote connection via rsh(1) or ssh(1) (in case the environment RSH has been set to ssh). Note that in this case, the throughput to the remote tape server will be much lower than with a connection that has been initiated via rcmd(3).

LIMITATIONS

If star is running on a large file aware platform, star is able to handle files up to 8 GB in a mode that is compliant to the POSIX.1−1988 ustar format. With a nonstandard star specific extension, up to 95 bits may be used to code the filesize. This will handle files up to 200,000,000 TB. With the new POSIX.1−2001 extended headers used by the xustar, exustar and pax format, any filesize may be archived.

BUGS

The fact that the −f option has to be implemented in a way that is compatible with old tar implementations gives several problems. The options −fifostats, −force−hole, −force−remove and −fifo interfere with the −f option and the fact that they exist prevents users from using filenames like e.g. ifo using the 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.

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:

Sun already did accept a bug report for rsh(1)/ssh(1). Openssh.org accepted and fixed a bug for their implementation of ssh(1).

If you use star to create a remote connection via an unfixed rsh(1) or ssh(1), be prepared that terminal generated signals may interrupt the remote connection.

HISTORY

Star was first created in 1982 to extract tapes on a UNIX clone that had no tar command. In 1985 the first fully functional version has been released as mtar.

When the old star format extensions have been introduced in 1985, it was renamed to star (Schily tar). In 1994, Posix 1003.1−1988 extensions were added and star was renamed to star (Standard tar).

AUTHOR

Joerg Schilling
Seestr. 110
D−13353 Berlin
Germany

Mail bugs and suggestions to:

schilling [AT] fokus.de or js [AT] cs.tu−berlin.de or joerg [AT] schily.tu−berlin.de