Na}{

File Content: `tmpreaper.8`

.TH TMPREAPER 8 "Sat Jan  5 2019"
.UC 4
.SH NAME
tmpreaper \- removes files which haven't been accessed for a period of time
.SH SYNOPSIS
\fBtmpreaper\fR [\-htvfmMsaT] [\-\-help] [\-\-test] [\-\-verbose]
[\-\-force]
[\-\-delay=x]
[\-\-runtime=x]
[\-\-showdeleted]
[\-\-ctime] [\-\-mtime] [\-\-mtime-dir] [\-\-symlinks] [\-\-all]
[[\-\-protect '<shell_pattern>']...]
<time_spec> <dirs>...

.SH DESCRIPTION
\fBtmpreaper\fR recursively searches for and removes files and empty
directories which haven't been accessed for a given number of seconds.
Normally, it's used to clean up directories which are used for temporary
holding space, such as "/tmp".  Please read the \fBWARNINGS\fR section of
this manual.

When changing directories, \fBtmpreaper\fR is very sensitive to possible race
condition security exploits[1], and will exit with an error if one is
detected.  It does not follow symbolic links in the directories it's cleaning
(even if a symbolic link is given as its argument), never performs
\fBchdir("..")\fR, will not switch file systems, and only removes empty
directories and regular files. Unless your machine is one with lots of
relatively untrusted users, such as an ISP or school, you don't need this
program; `find ... -exec rm ...' works just as well when you don't have to be
concerned about people trying to exploit the race condition on you.

\fBtmpreaper\fR will stop itself after almost one minute with an appropriate
warning message, as attempts to keep it running long enough so that it
runs in parallel with another instance of itself may also lead to possible
vulnerabilities. Normally, \fBtmpreaper\fR won't need that amount of time.
If your system is so slow that it does, try to configure things so that this
doesn't happen. As a last resort, the \fB\-\-runtime=x\fR option can be used to
set the number of seconds after which the timeout occurs; the default setting
is 55 seconds.

\fBtmpreaper\fR dates files by their \fIatime\fR, not their \fImtime\fR,
unless you select the \fB\-\-mtime\fR option.  If files aren't being removed
when \fBls \-l\fR implies they should be, use \fBstat(1)\fR or \fBls
\-\-time=access\fR to examine the file's \fIatime\fR and see if that helps to
explain the problem.

Additionally, \fBtmpreaper\fR can be instructed to also check the \fIctime\fR
(inode change time, which is updated e.g. when the file is created or
permissions are changed). This is primarily useful when \fBtmpreaper\fR is
used to clean up directories that are accessible as a Samba share; DOS (and
Windows) PCs preserve the \fImtime\fR and the \fIatime\fR when copying to a
new file, so that it appears that the newly created file is old.
\fBtmpreaper\fR will remove such files is the \fIatime\fR is beyond the
removal time, even though they were just created. This is avoided by using the
\fB\-\-ctime\fR option.

As testing the contents of subdirectories will update those directories'
\fIatime\fR, empty directories won't be removed. To circumvent this problem
you can use the \fB\-\-mtime\-dir\fR option, which will switch on \fImtime\fR
checking for directories only. Using \fB\-\-mtime\-dir\fR in addition to
\fB-\-mtime\fR doesn't do anything useful.

The \fI<time_spec>\fR parameter defines the age threshold for removing
files. If the file has not been accessed for \fI<time_spec>\fR, it
becomes eligible for removal.  The \fI<time_spec>\fR should be a
number, defaulting to hours, optionally suffixed by one character: `d'
for days, `h' for hours, `m' for minutes, or `s' for seconds.
Following the time option, one or more directories must be given for
\fBtmpreaper\fR to clean up.

On linux ext2/ext3/ext4 filesystems, no errors will be given when trying to
remove files marked as immutable. A common situation for this was the
ext3 .journal file. However, there may of course be other files marked as
such by the system administrator.

.SH OPTIONS
.TP
\fB<noargs>, \-h, \-\-help\fR
Print a brief version, copyright, and usage statement on stderr, then exit
with error status 1.

.TP
\fB\-t, \-\-test\fR
Don't actually remove any files, but go through the motions, checking
through the directory, then pretend to remove the eligible files.

.TP
\fB\-v, \-\-verbose\fR
Print a verbose display. Two levels of verbosity are available---use this
option twice to get the most verbose output.  The \fB\-\-test\fR option
automaticly sets \fB\-\-verbose\fR once.
.br
Higher numbers mean more output (max. is 3).
.br
To force normal verbosity after \fB\-\-test\fR, use "\-\-verbose=0".
This will generally only show error messages. Use "\-\-test
\-\-verbose=0 \-\-showdeleted" to give a shellscript-like list of
actions that would have been done (see the \fB\-\-showdeleted\fR
description below).

.TP
\fB\-\-showdeleted\fR
Show what files and directories are deleted. The output is in the form of
shell commands, i.e. "rm /dir/dir2/file" and "rmdir /dir/dir2".
.br
When used together with \-\-test, this option will still cause the "shell
commands" to be printed, although nothing is really done. Note that this
may show more than without \-\-test, as problems removing the file won't
be detected (e.g. immutable files).

.TP
\fB\-f, \-\-force\fR
Remove files even if EUID doesn't have write access (\fIakin to \fBrm -f\fR).
Normally, files owned by the current EUID, with no write bit set are not removed.

.TP
\fB\-\-delay=x\fR
Delay execution at the start for a random time, up to \fIx\fR seconds;
if no value is specified, the default maximum time to delay is 256 seconds.
This is an option useful in cron scripts to make the execution of tmpreaper
less predictable, thus making things a little harder for those who would
attempt to use tmpreaper to thwart security.

.TP
\fB\-T x, \-\-runtime=x\fR
Execution of tmpreaper will aborted after \fIx\fR seconds; this is to prevent
attacks that create many, many files.
By default the timeout is set to 55 seconds.
A value of 0 will disable this feature, which is not advised as this feature
prevents possible race-conditions between different instances of
\fBtmpreaper\fR.

.TP
\fB\-m, \-\-mtime\fR
Base the decision of whether to remove the file on its \fImtime\fR,
rather than on its \fIatime\fR.

.TP
\fB\-M, \-\-mtime-dir\fR
Base the decision of whether to remove the directory on its \fImtime\fR,
rather than on its \fIatime\fR.

.TP
\fB\-c, \-\-ctime\fR
Base the decision of whether to remove the file on its \fIctime\fR,
\fBin addition to\fR its \fIatime\fR.
Only applicable if the \fB\-\-mtime\fR options is not given!

.TP
\fB\-s, \-\-symlinks\fR
Remove symlinks too, not just regular files and directories.

.TP
\fB\-a, \-\-all\fR
Remove all file types, not just regular files, symlinks, and directories.

.TP
\fB\-\-protect \fI'<shell_pattern>'\fR
Protect the files that match
the \fI<shell_pattern>\fR from deletion.  This option may be used more
than once.  It has no one letter abbreviation, you must spell out the
full word "protect".

If you do not enclose the \fI<shell_pattern>\fR in single quotes, the
shell will perform the expansion before \fBtmpreaper\fR reads its
argument array.  The program does not support that syntax, so you
\fImust\fR use single quotes around the glob pattern.

\fBtmpreaper\fR will \fIchdir(2)\fR into each of the directories
you've specified for cleanup, and check for files matching the
\fI<shell_pattern>\fR there.  It then builds a list of them, and
uses that to protect them from removal.  For example:

\fBtmpreaper\fR \-\-test \-\-verbose \-\-protect \\
 '.X*\-{lock,unix,unix/*}' \-\-protect '.ICE\-{unix{/*,}}' \\
 5d /tmp  # 5 day grace period

.SH TIPS
As long as there are files present inside a subdirectory, it won't get
removed.  You can use a non-writable, self-owned file, perhaps named
".tmpreaper", or, if you are su, a file that has the ext2fs \fIimmutable\fR
attribute set, to keep a subdirectory from being deleted.  Of course, you
could just as easily use use the \fB\-\-protect\fR option to obtain the same
result.

Because the command line argument processing is implemented with GNU
\fBgetopt_long(3)\fR[2], you may order the arguments thusly, if it pleases
you:

\fBtmpreaper\fR \-\-test \-\-verbose 5h \\
 \-\-protect './tmp/{blah?,dir{/blah4,}}' ./tmp \\
 \-\-protect '/tmp/.X*' /tmp

 ... Note that if you use \fB\-\-all\fR or \fB\-\-symlinks\fR, it will
have global effect.  If you only want it turned on for one directory,
you must use separate commands.

.SH WARNINGS

\fBPlease do not ever run \fBtmpreaper\fR on `/'!!!\fR There are no
safeguards against this built into the program, because that would make it
difficult to use in a chrooted environment.

.\" Note that using braces in the patterns as shown above only work
.\" if the glob() function on your system understands them.
.\" Yours apparently doesn't (at least, it wasn't detected during
.\" compilation).
.\" Write out the patterns explicitly: "--protect "/tmp/X*-{lock,unix}"
.\" becomes "--protect /tmp/X*-lock --protect /tmp/X*-unix" .

.SH SEE ALSO
.IR chattr (1)
.IR chdir (2)
.IR chroot (8)
.IR cron (1)
.IR getopt_long (3)
.IR ls (1)
.IR lsattr (1)
.IR rm (1)
.IR stat (1)

.nf
[1]  http://seclists.org/lists/bugtraq/1996/May/0046.html or
     http://www.security-express.com/archives/bugtraq/1996_2/0054.html

     http://linuxgazette.net/18/tmp.html
     (formerly http://www.linuxgazette.com/issue18/tmp.html)

     http://linuxgazette.net/20/followup.html
.fi

[2] info:(libc)Long Options

.SH AUTHOR
.nf
    Karl M. Hegbloom <karlheg@debian.org>
.fi

Mostly based on `tmpwatch-1.2/1.4', by:
.nf
    Erik Troan <ewt@redhat.com>
.fi

Now being maintained for Debian by:
.nf
    Paul Slootman <paul@debian.org>
.fi
File Content: tmpreaper.8

File Content: `tmpreaper.8`
