STAR(1)

📦
version 2024.03.21 · 4 versions
, in fedora 44

STAR(1) 💫

Schily´s USER COMMANDS — it's giving legendary, it's giving the tape archiver, and bestie we are about to get into it 💅

✨ NAME ✨

star — the one and only unique standard tape archiver 👑

🎀 SYNOPSIS 🎀

okay so here's how you actually call her:

star  command [options] [-find] file1 ... filen [find_expr]
ustar command [options] [-find] file1 ... filen [find_expr]
star  command list=name [options] -find [find_expr]
tar   command [options]         file1 ... filen
star  -copy   [options] [-find] file1 ...  [f_expr] directory
star  -copy   [options] -C from_directory . to_directory
star  cli=name   ...

that's it, that's the whole vibe 💖

🌸 DESCRIPTION 🌸

So. star is a very fast tar(1)-like tape archiver with improved functionality. Like, she does everything tar does but better, no cap. She 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 (iconic, honestly), but it can be any file. And in all cases, when a directory name shows up, it refers to the files and (recursively) subdirectories of that directory. 🗂️

star's actions are controlled by the mandatory command flags from the list below (yes mandatory, bestie, you can't just vibe your way through this one). The way star acts may be modified by additional options.

⚠️ heads up!! unpacking tar archives may be a security risk because star may overwrite existing files. See SECURITY NOTES for more info. like, please read it, i'm begging 🙏

And if the first argument is in the form cli=name, the command line interface is selected to match name. See section CLI SELECTION below. 🌈

👑 FEATURES 👑

okay this is the part where I get to brag. sit down. 🫶

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. she ate. ✨

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 one to use find expressions, even in extract or list mode, directly on the content of an archive. The extensions to find(1) allow one 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 (unlike some people 💀). 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 implementations. star allows one to archive path names up to 8 GB on modern platforms. slay. 🦋

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 times. that's main character energy fr fr 👑

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 one 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. (she just knows. iconic.) 🔄

star is able to archive and restore Access Control Lists for files using POSIX.1-2001 extended headers. 🎀

🌈 CLI SELECTION 🌈

If the first argument is in the form cli=name, the command line interface is selected to match one of the supported CLI variants. The following interfaces are supported:

  • star — the star interface selects the command line interface described in this manual page. (hi, that's the one you're reading 💖)
  • 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).

more coming, bestie, don't go anywhere 🫶

✨ COMMAND ✨

Okay bestie, this is the part where we talk about how you actually tell star what to do. Sit with me. 🫶

In native mode, star is compatible to the command line syntax of a typical POSIX command, and for this reason it expects commands and options to start with a single dash (-). In this case, commands and options may be specified separately, and all boolean or increment type options may be specified either separately or combined. Combine away, queen. 💅

For compatibility with GNU programs, long options may alternatively start with a double dash. We love options (the pun kind). ✨

In compatibility mode to POSIX tar, star expects commands and options to appear as one single string that does not start with a dash. And in POSIX tar compatibility mode, additional non POSIX options may be specified but must appear after the POSIX options and their args, and they need to start with a dash. Order matters, no cap. 🔥

  • -c — Create a new tarfile and write named files into it. Writing starts at the beginning of tarfile. See the -v option for info 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. (We are protecting you from yourself, babe. 🙈)

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 one 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. A little preview moment, main character energy. 👀
  • -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. (Yes, that's a little cursed, but it's documented, so it's fine. 💀)
  • -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 archive 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. One. Not zero, not two. Pick a lane, bestie. 💅

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

🎀 OPTIONS 🎀

The buffet of flags. Grab a plate. 🍓

  • -help — Print a summary of the most important options for star(1). Your starter pack. ✨
  • -xhelp — Print a summary of the less important options for star(1). The deep lore. 👑
  • -/ — 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 the -w option). 💀

See SECURITY NOTES for more information.

  • -7z — Run the input or output through a p7zip pipe. See section COMPRESSION for details.
  • -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 parameters 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 💫

okay so this is the Old star standard format. It's an upward/downward compatible glow-up of the old (pre-Posix) UNIX tar format. It dropped in 1985, so bestie, it is not Posix compliant, we been knew.

The star format lets you archive special files (yes, even sockets 👀) and it records access time and creation time on top of 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 can copy the device nodes on HP-UX that have 24 bits in the minor device number — which is more than the 21 bits that the POSIX-1003.1-1988 archive format can do. iconic behavior, honestly.

The nonstandard extensions live in the space between the link name and the POSIX file name prefix. Since the star format does not use a POSIX magic string, the extensions don't 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 (even though it was designed after 1987) enhancement to the old tar format. The gnutar format was 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 — especially when sparse files are archived using the -sparse option. 💀

GNU tar is not able to extract files with long path names, but under some conditions it 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 it's sufficient for most gnutar archives. See NOTES for more info.

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, and 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, and 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. fancy, we love precision. ⭐

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 the 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, because the fields for the 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 in 1998 that omits the 'tar\0' signature at the end of the tar header. It is otherwise identical to the xstar format. Because some tar implementations don't 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, and 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. bestie said permissions but make it extra. 💅

The exustar format allows you 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 in dump mode, star archives all file types and in addition archives more meta data than usual.

File size is unlimited, uid/gid/uname/gidname is unlimited, and 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 it does not handle atime and ctime, and in addition it uses 'X' as the typeflag for the extended headers instead of the standard 'x'. not me noticing the lowercase/uppercase drama. 🙈

File size is unlimited, uid/gid/uname/gidname is unlimited, and 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. lowkey giving "legacy code we can't delete". 😭

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 you to archive nearly any file type. File size is limited to 8 GB, and 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 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 it limits the file size to 4 GB - 2 bytes — even though 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 — okay so this one is basically the asc cpio format, except it also slaps on a simple byte-based 32-bit checksum. Which means the archive type name CRC, the one AT&T uses, is honestly misleading. 🙈 Try to avoid the crc archive format bestie, its portability is limited. Like, don't.

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. she's retired 💅
  • -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 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. sneaky but valid ✨
  • -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 one 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. math girlie moment, do not skip it 🧮

  • 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. two whole personalities, pick one 🦋
  • -bz — Run the input or output through a bzip2 pipe. This option is an alias for -j. See section COMPRESSION for details.
  • 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. See section COMPRESSION for details.
  • -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 one 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 one 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. order matters, bestie 😭
  • -copysymlinks — This option allows one 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. aesthetic choice fr fr
  • -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. lazy girl option, we love her 💅
  • -D — no descending into directories while you're in create mode, bestie. Normally star will just walk the whole tree when it bumps into a directory in its file parameters. Heads up tho: -D is already the default if you're using the list=file option. Want star to descend into directories it finds in that list file anyway? Use the -dodesc option (it's down below 💅).
  • -d — don't store and don't create directories, periodt. Like, ancient versions of tar (we're talking the one shipped with the seventh edition of UNIX) literally can't handle directories inside tar archives at all, so if you generate a tar archive without directories you dodge a whole mess of problems with the tar implementations you find on SYSVr3 and earlier. And if you use it during extract, no intermediate missing directories get created either. Iconic but limited, iykyk.
  • -data-change-warn — if a file's size changes while it's being archived, treat that as a warning only, no non-zero exit code. You still get a warning message written, unless another rule from an errctl= option ignores it. This option works exactly as if the last error control option had been
errctl="WARN|GROW|SHRINK *"

Important tho: the -e option, or an ABORT entry in a condition set up by errctl=, has higher precedence than -data-change-warn. Also, this option is just ignored in extract or list mode. 🙈

  • -debug — print debug messages, obviously. Among other things you get debug output for header type recognition, tar type properties, EOF recognition, opening of remote archives and fifo internals. It's giving ✨behind the scenes✨.
  • diffopts=optlst — a comma separated list of diffopts, bestie. Here's every valid member of optlst:
    • help — print a summary of the possible members of the diffopts list.
    • ! — invert the meaning of the following string. No comma needed after the exclamation mark. (Also, if you're on csh(1) you might have trouble using ! because of its cursed parser — that's literally why the not alias exists. 🫶)
    • not — invert the meaning of all members in the diffopts list, i.e. exclude all present options from an initially complete set compare list.
    • perm — compare file permissions. With this in effect, star compares the low order 12 bits of the st_mode field.
    • mode — same as perm.
    • symperm — compare permissions even when the target file on the local filesystem is a symbolic link. By default star won't compare the permission of symbolic links since most systems can't even 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 the 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 lets you deal with filesystems that differ in their directory implementation. The link count of directories in POSIX equals the number of manually created additional hard links + 1 (same as with other file types), while on historical UNIX filesystems it equals 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. Compares all user/group related info of the 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 the case of a hard link.
    • data — compare content of file. If star already found that the size of the files differ, it won't compare the content anymore — and if the sizes 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 if they either have a characterwise identical link-name, or if they 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 the two files is sparse, a difference is flagged. This only works if the archive format is star, xstar, xustar, exustar, or gnutar.
  • atime — compare access time of file. This only works if the archive format is star, xstar, xustar, exustar, or pax/epax.
  • mtime — compare modification time of file.
  • ctime — this only works if the archive format is star, xstar, xustar, exustar, or pax/epax.
  • lmtime — compare the modification time even when the target file on the local filesystem is a symbolic link. By default star won't compare the modification time of symbolic links since most systems can't 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 filesystems 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 have supported a sub-second resolution since the early 1990s tend to support only a microsecond granularity. Since even in 2018, the POSIX.1-2008 feature pathconf(_PC_TIMESTAMP_RESOLUTION) has not yet been implemented on any platform, you may need to disable comparing 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 an 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, just like 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.

And if diffopts aren't specified at all? star compares everything but the access time of the files and the modification time of symbolic links. Slay, sensible defaults. 💖

  • dir-group=group — if star extracts archives as root, this option lets you control the group id of intermediate directories created by star.
  • dir-owner=user — if star extracts archives as root, this option lets you control the owner of intermediate directories created by
  • -dirmode — if you're in create mode (i.e. 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. ⏰ But listen: only use -dirmode if the archive needs to be extracted by an old tar implementation. And if star is used to extract an archive that was created with -dirmode, the directories will not get an old time stamp unless the option -U is used while extracting the archive. No cap.
  • -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 — bestie, this one forces star to actually descend into the directories it finds inside a list=file. It's giving "no, keep going, go deeper." Peep the -D option above for the related lore. Heads up tho: -dodesc only works in create mode. That's it, that's the rule. 💅
  • -dump — okay so this lets you create archives with the same number of attributes as an archive made with the level= option, but without all the restrictions that come with a true dump. The resulting archive is basically a level-less dump — it includes similar attributes to a level 0 dump, but it can span more than a single file system and it doesn't need a -C option. Iconic.

It was originally introduced to make it easier to implement a star version that supports true incremental dumps, but it's been kept around because it gives extra benefits. Star currently sets the archive type to exustar and, on top of that, archives more inode meta data inside POSIX.1-2001 extended headers. See also the level= option and the section INCREMENTAL BACKUPS for more info on true incremental dumps. ✨

  • -dump+ — works similar to -dump but creates more global archive header meta data, e.g. the SCHILY.volhdr.hostname tag. Which lowkey helps you understand where a tar archive was created. 🦋
  • -dump-cumulative — this tells star to do incremental dumps relatively to the last incremental dump of the same level. Normally, incremental dumps with a level higher than 0 are done relatively to the content of a previous dump with lower level. And here's the thing: if you're using incremental dumps and restores to synchronize filesystem content, every successive incremental dump will grow in size if -dump-cumulative is not used. 😭 See the section SYNCHRONIZING FILESYSTEMS for more.
  • dumpdate=name — tells star to use the mtime of the time stamp file name instead of using the start time of star itself. Why does this matter? Because you need it when star is run on file system snapshots. If star used its own start time with snapshots, all the files that got modified between the setup of the snapshot and the start of star would be missing from the backup. Not the vibe. 🙈

A solution: create the time stamp file, then create the snapshot, and later use the option dumpdate=name.

  • -dumpmeta — this one 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 results 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.
🚨 bestie I am begging you, read that last sentence twice. Use with extreme care. This one can bite.
  • -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 you to use the errctl= option together with the -e option, so you can ignore some error conditions while still aborting on all the other ones. Best of both worlds, honestly. 💅

  • errctl= name — add the content from file name to the error control definitions.
  • errctl= error control spec — add error control spec to the error control definitions.

More than one error control file, more than one error control spec, and even a mixture of both forms is possible. Go off. ✨

The reason for using error control is to make star quiet about error conditions that are known to be irrelevant to 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 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 identifiers from the list below (and if you're using more than one, separate them with a '|' character):

  • 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 least 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 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 errors 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 that 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.

Okay bestie, real talk for a sec: be VERY careful when using error control because you may ignore any error condition. If you ignore the wrong error conditions, you may not be able to see real problems anymore. Like, you literally blinded yourself. No cap. 😭
  • -exclude-from name — exclude from *name*d file, this is an alias for the -X option. See -X option for more information.
  • -F, -FF … — the fast and simple exclude option, for create mode only 💅. Here's the tea, level by level:
    • 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 sending 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 one 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 one 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 section COMPRESSION for details.
  • 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 — bestie, this one is for when you're doing incremental backups off a filesystem snapshot. It tells star to use mount_point when it records stuff in /etc/tardumps and when it compares against what's already in /etc/tardumps. The whole point? So /etc/tardumps and the archive get the real name of the filesystem, instead of the temporary mount point the snapshot device was hung on. Chef's kiss, very "no fake names on my records" energy. 💅
  • H=headertype — literally just peep the artype=headertype option, it's the same thing. BUT — and this is important — POSIX.1-2001 defines a -H option that follows symbolic links encountered on the command line. So because of that, this old-school star option H=headertype might just vanish one day, even though it's been living in cpio rent-free since 1989. 😭
  • -h, -L — follow symbolic links as if they were actual files. Normally star does NOT follow symlinks — it just stores their values in the tarfile. Also see the -L option. 🦋
  • -hardlinks — two moods, one flag:
    • In extract mode, it tells star to try and create a hardlink whenever it bumps into a symlink in the archive.
    • In create mode, it tells star to try and archive a hardlink whenever it bumps into a symlink in the filesystem.
  • -hpdev — allows 24 bits for the minor device number, using 8 octal digits. So real talk: yeah it lets you make tar archives that HP-UX tar can read, but those archives violate POSIX.1-1988. 🚨 You only need this if you want a POSIX.1-1988 based archive format that doesn't include extensions. If you're on the xstar format, star will use a base 256 extension that allows bigger major/minor numbers by default. And if you use xustar or exustar? No limitation at all, because those formats use POSIX.1-2001 extended headers to archive major/minor numbers by default. Slay. ✨
  • -i — ignore checksum errors on tar headers. With this on, star won't exit when it finds a header with a bad checksum — it'll just go hunting for the next valid header instead. Iconic resilience. 💪
  • -install — carefully replace existing files while extracting. It works like install(1): first extract the file into a temporary name, then rename it to the final name once that file's extraction succeeded. 🎀

Quick heads up though: since 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 #. Peep bs= for the possible syntax. This skip size is the number of bytes to ignore from the first tape record. You'd typically use it when a tar archive on a tape isn't read from the beginning and the tape has been forwarded before it's read — then iskip= 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. It's an alias for -bz. Go read the COMPRESSION section for the tea. 🌸
  • -keep-nonempty-dirs — don't complain about trying to remove nonempty directories in the case that -remove-recursive hasn't been specified. Chill vibes only. 😌
  • -keep_old_files — obsoleted by -keep-old-files. she's retired, respect her legacy 🫶
  • -keep-old-files, -k — keep existing files instead of restoring them from the tarfile. This saves your files from being clobbered even if the tarfile has a more recent version of the corresponding file. 🛡️

Go read SECURITY NOTES for more info, bestie, fr.

  • -L, -h — follow symbolic links as if they were files. Normally star will not follow symlinks, it just stores their values in the tarfile. See also the -h option. (yes this is the same as above, they're twins, it's giving mirrored energy ✨)
  • -l — don't print a warning message if not all links to hard linked files could be dumped. Careful, this option is evaluated in the opposite way to historic tar(1) implementations and to POSIX.1. POSIX.1 says that by default no warning messages get printed and -l enables warning messages when not all links could be archived. So like… don't trust your instincts here, trust the manpage. 💀
  • level=dumplevel — set the level for incremental dumps. This is the switch that flips star into true incremental dump mode. The dumplevel can be in the range 0..99.

In true incremental dump mode, a -C option followed by the name of a mount point and a dot (.) as the starting directory name is required. Only a single filesystem may be handled at a time. If the directory following -C doesn't refer to a root directory of a filesystem, the dump is called a partial dump. If the directory following -C does refer to a root directory of a filesystem, and no other restrictions apply that exclude certain files from the dump, it's called a full dump.

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

  • -link-data — again, two modes:
    • In create mode, include the data for files even if those files are hard links. Heads up: this feature in create mode is currently only available for the exustar archive format, and only when -sparse has not been specified.
    • In extract mode, it lets star deal with data in hard linked files even if the standard wouldn't allow that for the archive format being used.
  • -link-dirs — okay this one is long, buckle up 🎢

In create mode, try to find hard linked directories. Using -link-dirs forces star to keep track of all the directories that will go into the archive, which means a lot more memory gets allocated than in the default case.

If you want to extract a cpio archive that contains hard linked directories, you also need to specify -link-dirs in extract or diff mode. Why? Because many cpio implementations create buggy archives when it comes to hard links. If star looked for hard linked directories in all cases, it would detect tons of pseudo hard links to directories. So use -link-dirs with care when you extract cpio archives.

Also note: not all filesystems allow creating hard links to directories. And even though a non-root user can detect and archive hard linked directories, all known operating systems require the extraction to be done as root in order to create or remove hard links to directories. For this reason, it's only recommended to use this option when doing accurate backups and when hard links to directories are expected. 🫡

And when -link-dirs is not used and hard links to directories are present? The appendant sub-tree will appear more than once in the archive, and star will print Linkcount below zero warnings for non directory hard links inside the sub-tree. messy 😭

  • list=filename — read filenames for the store/create/list/diff command from filename. That file 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 it's used together with -find, no path list is accepted after the option -find.

Also see the option pkglist= for a way to specify filename, permission, owner and group.

Note: 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 all at once, star reads the directory name by name. This may cause star to close the directory if it runs out of file descriptors because of deeply nested directories. And if a directory then doesn't support telldir(3)/seekdir(3), star will fail. 💀
  • -lzip — run the input or output through a lzip pipe. See the COMPRESSION section for details. 🌈
  • -lzma — run the input or output through a lzma pipe. See the COMPRESSION section for details. ✨
  • -lzo — run the input or output through a lzop pipe. See the COMPRESSION section for details. 🦋
  • -M, -xdev — do not descend mount points. Super useful when you're doing backups of complete filesystems. See NOTES for more info.

When using -find, this may not always work as expected — e.g. when the /proc filesystem is involved. Use -xdev past -find for this reason. 💅

  • -m — do not restore access and modification time. Quick caveat: 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 gets excluded from the archive and from further directory scans. By default, star excludes the directory but still recursively scans the content of that directory, since complex patterns could allow files inside the directory tree to match. Using -match-tree lets you efficiently exclude whole trees from scanning — which helps avoid scanning directory trees that live on remote filesystems or contain excessive bad blocks. Efficiency queen 👑
  • maxsize=# — don't store files in the tarfile if they're bigger than #. See bs= for the possible syntax. By default the number gets multiplied by 1024, so the value counts in units of kBytes. But if the size specifier ends with a valid multiplication character (like . for bytes or M for MB), the specified size is used exactly as specified and is not multiplied by 1024. See the bs= option for all possible multipliers. 🔥
  • -meta — in create mode, -meta makes star archive all the meta data of the file (e.g. uid, permissions, ...) but not the file content. In extract mode, it makes star restore all the meta data but not the file content. And on top of that, in extract mode no plain file, special file or directory will be created. Meta files are needed to support incremental backups. 🧚
Warning, bestie, listen up fr fr: Do not try to extract star archives that contain meta files using other tar implementations if they don't know about star's meta file extensions. Star literally tries to force all the non-standard-compliant tar implementations to abort. Star also tries to make every non POSIX.1-2001 compliant tar implementation unable to find a valid filename. But here's the tea 😭 — when other POSIX.1-2001 aware tar implementations show up and they don't know about meta files, they will destroy files on disk. No cap.

The problems come 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'm looking for people and companies who'd like to support me so I can add the meta file concept to the POSIX.1-2005 standard. 🫶

  • -modebits — this option lets you create tar archives that include more than 12 bits from st_mode. Heads up tho: this creates tar archives that violate POSIX, but some tar implementations insist on reading such nonstandard archives anyway. 💅
  • mtskip=# — sets the initial archive skip amount to #. Peep 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 what you use as the parameter.

This option is used if a tar archive on a tape is not read from the beginning, so you can 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 info on the tape block size.

If mtskip=# has been specified, an iskip=# option is ignored and the value is rather computed from the mtskip=# parameter. Also, 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's 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 an EOT condition from writing the medium. This allows one 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's 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 one to verify the correct volume after a change during read back. It's recommended to use the exustar format for best results. In create mode, -multivol is only supported for archives types that allow writing 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 specifying 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 one 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 — bestie, this is the "be normal about old tar" button 💅. If star gets called with this, it makes archives that are fully compatible with old UNIX tar archives. And if you're in extract mode? star just ignores any extra info hanging out in the headers. But like — be so fr — this does not mean the archives it makes are binary equal to ones from old tar versions, and it also doesn't mean star is out here trying to comprehend every single bug those ancient tars had. Specifically: the old-tar bug that reverses a space and a NULL byte in the checksum field is not repeated. If you want signed checksums, you gotta also throw in the -signed-checksum option. And if you want directories to not get archived, for compatibility with very old historic tar archives, you need the -d option too.
Heads up: this option is superseded by the H=headertype option. She's a legacy queen 👑
  • -o, -nochown — do not restore owner and group of files 🫶. Use this when super user privileges are needed to overwrite existing files, but you don't want the local ownership of those existing files to change. Protect the vibes, protect the ownership.
  • -one-file — exit star after one file has been extracted as a result of a match with a pattern or with a command line argument ✨. This one's for the girlies who need to restore single files out of larger tape archives and do not wanna wait until the end of the tape is reached (literally who has the time 😭). To make star exit after the first file, call -one-file together with pat=*. This is e.g. useful together with the option mtskip=#.
  • -onull, -nullout — don't actually write to the archive, just compute and add the sizes 🧮. So useful for figuring out if a tape may hold the current backup. Please only use the -onull option, since it's a similar option as used by the sdd(1) command.
  • -P — let star write a partial record as the last record 🌸. Normally, star writes each record with the same size. This is useful on unblocked tapes — i.e. cartridge tapes like QIC tapes — as well as with archives that live in files. If you use this on local files, the size of the archive will be smaller. If you use this on cartridge tapes, it 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. Chain reaction, but make it organized 💫
  • -p — restore files and directories to their original permissions 👑. Without this option, they get 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's been called with the -p option. See also -no-p. And if the archive contains Access Control Lists (ACLs) in POSIX.1-2001 extended headers, star will restore the ACLs from the archive for files if the -acl option is specified. If -acl has not been specified, ACLs are not restored at all. No acl, no acl restore, periodt.
  • -partial — force an incremental restore even if the incremental dump is only a partial dump 🔥. See -wtardumps, level= and the sections INCREMENTAL BACKUPS and INCREMENTAL RESTORES for more info.
  • pattern=pattern, pat=pattern — set the matching pattern to pattern 🎀. A maximum of 100 pattern=pat options may be specified. And since each pattern is unlimited in length, that's honestly no real limitation. If more than one pattern is specified, a file matches if any of the specified patterns 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's 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 patterns, 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 they do allow restoring subtrees.

To extract a complete sub tree from the directory dir with star using the pattern= option, use pattern=dir/\*. If you'd rather select a subtree using the historic method, use dir as a file type argument. If you only want to extract the directory itself, use dir/ as a file type argument. See the manual page for match(1) for more details on the pattern matcher. All patterns are selection patterns by default — to make them exclude patterns, use the -not or the -V option 💖

  • pkglist=file — okay so 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 lets you 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 the 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. Either way, the link gets the last word 💅
  • -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, then the file is skipped. If you type '.', then the original file name is retained. If you type anything else, then that's taken as the new file name.
Note that -pax-i is an interactive option that prevents star from being used in non-interactive environments. So like… don't put her in a cron job, bestie 😭
  • -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. Same energy as -pax-H, different scope 🌈
  • -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. One and done, she's loyal 💅
  • -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 with 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's a silent fallback to the -s replstr option and the '\1' .. '\9' substitutions are not possible. No cap, that's just how it is.
  • -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 ✨. Quick lil vibe check and she's gone.
  • -qic24 — set tape volume size to 61440 kBytes. See the tsize=# option for more information.
  • -qic120 — set tape volume size to 128000 kBytes. See the tsize=# option for more information.
  • -qic150 — set tape volume size to 153600 kBytes. See the tsize=# option for more information.
  • -qic250 — set tape volume size to 256000 kBytes. See the tsize=# option for more information.
  • -qic525 — set tape volume size to 512500 kBytes. See the 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 🫠 bestie she's retired, move on
  • -refresh-old-files — the page gives this one no text of its own; the -refresh entry right below says it's literally the same option. slay, two names one vibe ✨
  • -refresh — okay so this one means do NOT create new files. Only files that already exist may be overwritten from the tarfile, and only if either newer versions are present in the archive, or if the -U flag is being used 💅. Why would you want that? Because it lets you overwrite files with more recent files from an archive that contains more files than the target directory should contain. And yes — the option -refresh-old-files is the same as the -refresh option. periodt.
  • -remove_first — obsoleted by -remove-first 💀
  • -remove-first — removes files before extraction 🧹. With this in effect, star will remove files before extracting a file from the archive. You need this if you wanna change the file type or if you need to break a hard link. And here's the tea: if you don't use either -ask-remove or -force-remove together with -remove-first, this option is useless and no files will be removed. it's giving decorative 🎀
  • -remove_recursive — obsoleted by -remove-recursive 💀
  • -remove-recursive — removes files recursively 🪆. When removing a file is permitted, star will normally only remove plain files, specials and empty directories. With this option in effect, star is allowed to recursively remove non-empty directories too. no cap, that's a lot of deleting 👑
  • -restore — flips star into true incremental restore mode ✨. A file named star-symtable and a directory named star-tmpdir get 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 the level= option and the section INCREMENTAL BACKUPS for more info, iykyk.
Note: do <strong>not</strong> use the -restore option if you only wanna restore a single file or a list of selected files. fr fr, that's not what she's for 😭
  • 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 the 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, and the current default is set up to use ssh. iconic honestly 🦋
  • -S — do not store/create special files 🙅‍♀️. A special file is any file except plain files, symbolic links and directories. And heads up bestie: you need to be super user to extract special files. main character privileges only 👑
  • -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 '&'. That '&' gets 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. Those up-to-100 substitute options are processed together with the -pax-s replstr options in the order they appear on the command line. And if the name substitutes to the empty string, the file is skipped. periodt.

  • -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. scary fr 😭

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, and it is always safe to unpack an unknown archive in an empty directory 💖

Many system installations contain plenty of symbolic links with absolute path names or with /../ inside. The usability of a tar archiver for system backups and in copy mode would be limited if -secure-links checking were done by default for backups or in copy mode — so star 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 that's 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 <strong>not</strong> get a security warning at the end of the star run, all files and links have been extracted 🎉. If you <em>do</em> 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 the 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 💀. And 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. lowkey annoying but ok
  • -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 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 🤫. she's quiet, she's mysterious
  • -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 finding 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 cause 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 🦋. little switcheroo, love that for her
  • -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 the tar dump dates database to name 🗂️. The default name is /etc/tardumps. Use this in combination with the level= option to create true incremental dumps. See also the -wtardumps option and the 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 the examples below). tarception, honestly iconic 🎀
  • -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 <strong>without</strong> 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 than the tape size 👑

If the option tsize=# is used <strong>without</strong> -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 <em>has</em> been specified in addition, star will split files when the maximum allowed tape size has been reached ✂️. And 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. sneaky but fine 🫶

See the -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. she said no gatekeeping today
  • umask=mask — set star's umask to mask 🎭. This allows one to control the permissions for intermediate directories that are created by star in extract mode. See also the -p option 💖
  • -uncond-rename — okay so when you're in interactive restore mode, or when you already passed -s, this makes star unconditionally ask for a new name, or apply a substitution. And bestie, it does this even when the current path name would've been skipped anyway — you know, when the file in the archive isn't newer than the file with the original name sitting on disk. No skipping, just asking. 💅
  • -v — bump that verbose level up by one, queen. Usually this means more output while star is doing its thing. Peep the description for the -t flag too. Normally star works in silence (mysterious, iconic). But if the verbose level is 2 or more and star is in create or update mode, star will produce a listing in the format of the ls -l output. ✨
  • -V, -not — inverts the meaning of the pattern list. i.e. use those files which do not match any of the pattern. Heads up though: this option only applies to patterns specified via the pattern=pattern or pat=pattern option. Patterns specified as file type arguments will not be affected. Not them. 🙈
  • -version — print version information and exit. Short, sweet, slay.
  • 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. So like, don't put it in your cron job, bestie. 💀
  • -wready — this option tells Star to wait up to two minutes for the drive to become ready. It's been added as a hack for a bug in the SunOS/Solaris st device driver. That driver has problems sensing the loading time with Exabyte drives with factory settings. It also makes sense to use -wready if multiple remote backups are made. In that 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 finished writing 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. Like... patience is a virtue fr fr. 🧚
  • -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 the -C option, or the INCREMENTAL BACKUPS section for more info. 👑
  • -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 the list= option. 🎀
  • -xattr — reserved for NFSv4 extended attributes. That's it, that's the whole vibe. She's reserved. 💅
  • -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's 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 when -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. Iconic combo, no notes. ✨
  • 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 the -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. She contains multitudes. 🌈
  • -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. One and done, periodt. 💜
  • -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's based on POSIX.1-2001 extended tar headers. See the 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 section COMPRESSION for details.
  • -Z — run the input or output through a compress pipe. See section COMPRESSION for details.
  • -z — run the input or output through a gzip pipe. See section COMPRESSION for details.
  • -zstd — run the input or output through a zstd pipe. See section COMPRESSION for details.

🌈 COMPRESSION 🌈

In most cases, star automatically detects compressed archives and executes an appropriate decompression program to assist it in extracting files from the archive. The compressed archive is first passed to standard input of the decompression program. Star reads the decompressed archive from standard output of the decompression program and processes it as usual. She just knows, bestie. 🔮

If the creation of a compressed archive is desired, or if this mechanism fails, the option compress-program=name can be used to configure name as a compression/decompression helper. Options -7z, -bz, -freeze, -j, -lzip, -lzma, -lzo, -xz, -Z, -z, and -zstd are available as shorthands for the most common compression/decompression helpers. For all of these helpers, star is capable of detecting that a compressed file needs one of them to be decompressed automatically. ✨

Compression and decompression helpers are expected to be filters reading from standard input and writing to standard output. By default, star passes the sole option -d to a decompression helper. Compression helpers are started without any options. Helper commands and options can be overridden using the name_CMD options in sections [compress] and [decompress] of /etc/default/star. See section FILES for details. 📁

If the environment variable STAR_COMPRESS_FLAG is set, its contents are appended to the argument list for compression helpers. This is useful to pass a compression level to programs like gzip(1). 🫶

💾 INCREMENTAL BACKUPS 💾

Star can back up a file system in full and incremental mode, bestie. But for incremental backups to even be a thing, your file system has to implement POSIX semantics. No POSIX, no incremental. That's the vibe check.

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 renaming 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. Case matters. It's giving lowercase-and-uppercase-are-different-people energy. 🎀

The incremental backup method that star uses depends on comparing the time stamps of all files against the time of the last backup. Heads up though: this method only works correctly if the level 0 backup and all higher level incrementals include the whole file system. But since star archives all inode meta data, it's able to detect renamed files by comparing the inode numbers of all files while in incremental restore mode. Renamed files, we see you. 👑

Detecting renamed files only works if star, while in backup mode, scans the whole file system tree for each full and incremental backup. That'll work in case no files are excluded and the dump starts at the root directory of a file system. In case 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. 😭 Sneaky, right?

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. The dot is the main character. Don't ghost it. 🫶

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. Snap, then restart, then breathe. 🌸

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. Look at us, being all precise. ✨

Note that if the backup is done on a live file system, it may be unreliable. A typical 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 the errctl= option) and to tell star to ignore growing files.

📅 BACKUP SCHEDULES 📅

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

                      Sun   Mon   Tue   Wed   Thu   Fri
          Week 1:     0     10    10    10    10    5
          Week 2:     10    10    10    10    10    5
          Week 3:     10    10    10    10    10    5
          Week 4:     10    10    10    10    10    5

The level 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. One dump, all the tea. 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). Seven. Girl. 💀

🦋 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. So clear the runway first. 🧹

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. Less frequently = bestie be careful.

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. Order matters, always.

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. Glow up complete. 💅

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. Do not touch them, do not delete them, do not look at them funny. 🎀

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. It's a consent checkbox, basically. 🙈

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. Yes, manually. Bestie, don't skip this. 😭

🔄 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 live filesystem should be avoided. On operating systems that support file system snapshots, copies should be made from a read-only mount of a snapshot. Be careful that all files that have been created between setting up a snapshot and starting an incremental copy may be missing from all copies unless the dumpdate=name option is used.

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

🌸 SIGNALS 🌸

ok so bestie, if star catches a signal, the first thing it does is spill the stats. every single time. 💅 here's the full roster of signals it handles:

  • SIGINT — this is the one you get when you smash ^C from the controlling tty. the moment it lands, star prints the statistics and dips out. but — and this is the important bit — if you're in create mode (aka storing files into an archive), it finishes up the file it's currently on so no half-written file sneaks into the archive, writes an eof record, and then exits. queen behavior honestly. 👑
  • SIGHUP — not something that comes from a tty, no. the actions are the exact same as when SIGINT shows up.
  • SIGQUIT
  • SIGINFO — usually generated by ^\ from the controlling tty. when SIGQUIT arrives, star prints statistics and keeps going with whatever it was doing. this is lowkey so useful for watching the progress of the current operation like a little live stream. 👀✨

💖 EXIT STATUS 💖

here's what star hands back when it's done. quick heads up though — those negative values are only available to modern shells and programs that use waitid(2) on a POSIX OS, so they can grab the full 32 bits of the star exit code. the positive-number variants are what you get when only the low 8 bits of the exit code survive. iykyk. 🫶

  • 0 — all files were processed successfully. slay, no notes. ✨
  • -64 / 192 — an exit code got used that doesn't fit into an 8-bit unsigned number and the environment variable COMERR_EXCODE has not been set. the value -64 / 192 here marks a clash. 💀
  • -4 / 252 — star got interrupted in create mode and the end of star was delayed until the current file had been archived completely. this error is only used in the case that no other error occurred and the tar archive only became shorter than expected.
  • -3 / 253 — star was called with the option -e, or the errctl= option was used to mark the current error fatal. 🚨
  • -2 / 254 — one or more files could not be processed successfully. 😭
  • -1 / 255 — command line parsing error. typo era. 🙈
  • >0 — other positive exit codes: the errno of the call that caused the fatal error.

🦋 EXAMPLES 🦋

okay bestie this is the fun part, let's get you some receipts. 🎀

wanna get a listing that kinda looks like ls -l? try:

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

and the exact same thing, but written in a way that's compliant with POSIX tar command line syntax:

example% star tvf /dev/rmt/1mbn

to copy the directory tree in /home/someuser over to the directory /home/fs, you'd do:

example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)

or, using star's own change directory option:

example% star -c -C /home/someuser . | star -xp -C /home/fs
ngl, both examples above are not the optimum way to copy a directory tree. 🙅 the more efficient route 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, you might use:

example% star -diff -v f=/dev/rmt/1bn

to compare two directory trees, one option is:

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 the files residing below /usr/openwin, you 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, you 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 lives on a read only filesystem, e.g. a CD, while having the shell's working directory on the CD, you might use:

example% star -zxp -C /tmp f=star-1.1.tar.gz

...and that extracts the files from the tar archive to the /tmp directory. 🫶

to back up a list of files generated by the find(1) command:

example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
⚠️ heads up: this does not work if the file names from the output of the find command include new line characters.

to extract a tarfile that contains a tarfile, you 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. nesting era. 🪆

to make a backup of the root filesystem to a tape drive connected to a remote machine, you 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 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, you 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 the -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're 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'd 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'd 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'd like to archive all files with a mtime of now, use:

example# star -c f=archive-name -find . -chmtime now

if you'd 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'd like to split the content of an archived tree into tar chunks of 1 GB, you could call:

example# star -c f=/tmp/v.tar tsize=1G \
new-volume-script='sh -c "mv /tmp/v.tar /tmp/v$(($1-1)).tar" nv' .

✨ ENVIRONMENT ✨

bestie, star also reads the vibes in your environment 💖 these variables let you set defaults so you don't have to type the same flags over and over. slay.

COMERR_EXCODE

okay so if this one is present, exit codes are not mapped — and that's intentional, 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. 💅

here's the tea: waitid(2) returns the full 32 bit exit code, but waitpid(2) masks the exit code with 0377. so without the environment COMERR_EXCODE, exit codes outside the range -63 .. 191 are mapped to -64 (192) to mark a clash. 😭

and if COMERR_EXCODE is set and the value starts with the character '0', an exitcode > 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. lowkey wild.

with a shell that supports the full exitcode and a POSIX compliant operating system, it is recommended to set the environment COMERR_EXCODE. periodt. 👑

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. that's it, that's the whole thing. maximum squeeze, no cap. 🔥

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. so it's giving "keep the receipts" energy.

STAR_FIFOSIZE

if you like to by default let star use a different fifo size, set this environment variable to the desired size. cute and customizable. ✨

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 extraction of a file to the filesystem was successful. 🫠 so like, speed over certainty, bestie.

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. hierarchy matters. 💅

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. quiet mode activated, shhh. 🤫

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. fr fr, don't skip this.

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. iconic fix for an iconic era. 💀

TAPE

unlike other tar(1) implementations, star defaults to use stdin/stdout for the archive. so if you like star to use the file name from the TAPE environment instead, you need to specify the -T option too. don't forget it, bestie. 📼

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. 😭 performance girlies, take note.

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. sneaky but that's how it is. 👑

see rmt= option for more information.

📁 FILES 💖

okay so here's the ✨lore✨ — the files star touches, and what lives inside them. bestie, some of these are config files you actually get to edit, and some of them are just star's own little side quests. let's go 🦋

/etc/default/star

this is the glow-up file 💅 — you can set default values for the following options in /etc/default/star. for example: CDR_FIFOSIZE=64m

  • STAR_FIFOSIZE — sets the default size of the FIFO (peep the fs=# option too 👀).
  • STAR_FIFOSIZE_MAX — sets the maximum size of the FIFO (again, see the fs=# option). setting STAR_FIFOSIZE_MAX in /etc/default/star lets you overwrite global values that come from backup scripts — which is exactly what you want on machines with less memory. very mindful, very demure 🧚
  • STAR_FSYNC — if you set this to N, star's default behavior acts as if the -no-fsync option had been specified the whole time.

this grants that star is always faster than other archivers, but it makes it impossible for star to check whether the extraction 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 you set this to N, star's default behavior acts as if the -no-secure-links option had 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=

these are the archive entries for the -[0..7] option. 🎀

a correct archive?= line has 3..4 space separated entries. the first one 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=. slay. ✨

example:

archive0=/dev/tape 256k 40G y

[compress], [decompress]

compression/decompression helpers 🫶 for each program passed via the option compress-program=name, a helper can be defined with the option name_CMD in the appropriate section. this helper is ran instead of name, permitting you to use a program with a different name or to pass different options from the defaults (see section COMPRESSION for details). heads up though: this feature is currently not available on DOS (DJGPP). 💀

the following example defines a compression/decompression helper for the PKZIP format, passing archives through zip(1) or unzip(1) as appropriate:

[compress]
ZIP_CMD=zip -9

[decompress]
ZIP_CMD=unzip

/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 said "that part's for the girlies, not for me")

./star-symtable

contains a database that is needed in incremental restore mode. 🗂️

./star-symdump

contains an intermediate dump of the 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). very protective, very main character energy 🛡️

/dev/tty

is used for the interactive user interface. 🌈

👀 SEE ALSO 👀

spax(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(5), rcmd(3), fssnap(1m), waitid(2), waitpid(2)

🩺 DIAGNOSTICS 🩺

when star finishes up it hits you with the receipts:

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

that's 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)

that's the time used and the transfer speed from/to the archive. 🏎️

and ngl, if there have been non fatal errors during the archive processing, star will display a delayed error summary before exiting. so don't close the tab too fast bestie, read the summary 🫶

📝 NOTES 📝

ok so bestie, buckle up, because this section is the "things you NEED to know or you will be confused forever" section 💅

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. like, it's the weird kid at the lunch table While the POSIX command line syntax requests all options to start with a dash (-) and allows one 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 one to specify a command line syntax as documented for the UNIX-98 tar command. So if you think you found a bug in the way star parses the command line — check your own command line first, bestie, please — 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. If 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. slay, free real estate ✨

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. we love a standards-compliant queen 👑

Some buggy tar implementations will generate incorrect filenames during a restore operation if the archive contains pathnames or linknames of exactly 100 chars length. exactly 100. the cursed number. iykyk 💀

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. the lore is deep, girlies

Star uses these four bytes since 1985 without problems. 1985!! a legend was born 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. nope. not a thing. don't ask. 💔

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. timing is everything, bestie

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. gnutar bestie... two. TWO. 😭

Old versions of tar found on SYSVr3 and earlier cannot read tar archives with a blocksize greater than 10 kBytes. grandma tar said no

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. ⚠️ future-you has been warned ⚠️

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. their loss tbh

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. just close your eyes and scroll 🙈

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. star said "i got you" 🫶

The filetype N (LF_NAMES) from gnutar (an obsolete method of storing long names) will never be implemented. periodt. 💅

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. no pipes = temp file = disk space said "bestie i'm full"

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. 🚨 this one is genuinely cursed, do not do this 🚨

🔒 SECURITY NOTES 🔒

okay this is the part where i hold your hand and we read very carefully, bestie. no skipping. 💖

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. FATAL. 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. ⚠️ hand crafted archives are giving villain origin story ⚠️

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. two-pass extraction, that's the self care routine ✨

See the ENVIRONMENT section and /etc/default/star for ways to configure the default behavior.

👑 SUID NOTES 👑

If star is installed suid root, star is able to make 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. drop the privileges, queen 💅

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). slower but still iconic 🦋

🚧 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. 200,000,000 TB. that's not a typo. that's a lifestyle. With the new POSIX.1-2001 extended headers used by the xustar, exustar and pax/epax format, any filesize may be archived. ANY. FILESIZE. 💖

💀 BUGS 💀

okay bestie, storytime: the whole reason -f is Like That is that it has to play nice with ancient tar implementations, and that compatibility tea comes with a few... consequences. 🙈

  • The options -fifostats, -force-hole, -force-remove and -fifo all beef with the -f option, and the fact that they even exist means you cannot use a filename like ifo the traditional way — y'know, where the filename just chills right after the string -f with no space in between. That's just not happening. 😭
  • BUT — plot twist — there is literally no problem using a file named ifo if you call it as -f ifo, f=ifo, -f=ifo or -f= ifo. So many options, so many vibes. ✨
  • ⚠️ Be careful not to typo the above options. Like, for real. The result could be that a file gets created because of your mistyped option. Not the glow-up you wanted. 💀

There is currently no way to set the fifo lowwater and highwater marks. no cap, that dial doesn't exist yet. 🎀

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 diagnostic output. that's the whole ritual, go off. 🔥

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. manifesting it. 🙏

If not invoked by the super user, star may not be able to extract files if they reside in read only directories. it's giving permission issues, and not the fun kind. 🙈

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. Lowkey fixable though:

  • in case of the ufs filesystem, this may be avoided if the backup is made off a ufs snapshot — go read the man page for fssnap(1m) bestie
  • for any filesystem, it could be avoided if the loopback filesystem had an option that tells lofs not to traverse mountpoints

Now for the ✨hall of shame✨ — 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). slay, openssh, we love growth. 👑

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. forewarned is forearmed, babe. 🫶

Mail other bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues.

The mailing list archive may be found at:

https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de.

🌈 HISTORY 🌈

A tar command appeared in Seventh Edition Unix, which was released in January, 1979. It replaced the tp program from Fourth Edition Unix — which itself replaced the tap program from First Edition Unix. it's giving generational hand-me-downs, honestly iconic. 💅

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. the glow-up arc was real. ⭐

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). character development fr fr. 🦋

👑 AUTHORS 👑

Joerg Schilling and the schilytools project authors.

🎀 SOURCE DOWNLOAD 🎀

The source code for star is included in the schilytools project and may be retrieved from the schilytools project at Codeberg at

https://codeberg.org/schilytools/schilytools.

The download directory is

https://codeberg.org/schilytools/schilytools/releases.

and that's a wrap, bestie 🫶 this whole thing is STAR(1) — the schilytools star manual, dated 2023/01/11, brought to you by Joerg Schilling. go forth and archive responsibly, ily 💖✨🌸

📦 where this page comes from
  • fedora 44: star 2024.03.21-6.fc44 · CDDL-1.0 AND BSD-2-Clause AND BSD-3-Clause AND BSD-4-Clause AND LicenseRef-Fedora-Public-Domain
  • Copyright 1982-2020 J. Schilling
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms