.TH TMPREAPER 8 "Sat May 30 1998"
.UC 4
.SH NAME
tmpreaper \- removes files which haven't been accessed for a period of time
.SH SYNOPSIS
\fBtmpreaper\fR [-htvfsa] [--help] [--test] [--verbose] [--force]
[--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 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.

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.

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

.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-m, -\-mtime\fR
Base the decision of whether to remove the file on its \fImtime\fR,
rather than on its \fIatime\fR.

.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{/*,}}' --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.

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

[1]  http://www.geek-girl.com/bugtraq/1996_2/0054.html

http://www.redhat.com/linux-info/lg/issue18/tmp.html

[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