TMPREAPER(8)						      System Manager's Manual						      TMPREAPER(8)

NAME

       tmpreaper - removes files which haven't been accessed for a period of time

SYNOPSIS

       tmpreaper  [-htvfmMsaT] [--help] [--test] [--verbose] [--force] [--delay=x] [--runtime=x] [--showdeleted] [--ctime] [--mtime] [--mtime-dir]
       [--symlinks] [--all] [[--protect '<shell_pattern>']...]	<time_spec> <dirs>...

DESCRIPTION

       tmpreaper recursively searches for and removes files and empty directories which haven't been accessed for a given number of seconds.  Nor-
       mally,  it's  used to clean up directories which are used for temporary holding space, such as "/tmp".  Please read the WARNINGS section of
       this manual.

       When changing directories, tmpreaper 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 chdir(".."), 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.

       tmpreaper 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, tmpreaper 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  --runtime=x
       option can be used to set the number of seconds after which the timeout occurs; the default setting is 55 seconds.

       tmpreaper  dates  files	by  their  atime, not their mtime, unless you select the --mtime option.  If files aren't being removed when ls -l
       implies they should be, use stat(1) or ls --time=access to examine the file's atime and see if that helps to explain the problem.

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

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

       The <time_spec> parameter defines the age threshold for removing files. If the file has not been accessed for <time_spec>, it becomes  eli-
       gible  for  removal.   The <time_spec> 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 tmpreaper to clean up.

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

OPTIONS

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

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

       -v, --verbose
	      Print a verbose display. Two levels of verbosity are available---use this option twice to get the most verbose output.   The  --test
	      option automaticly sets --verbose once.
	      Higher numbers mean more output (max. is 3).
	      To  force  normal  verbosity after --test, 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 --showdeleted description below).

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

       -f, --force
	      Remove files even if EUID doesn't have write access (akin to rm -f).  Normally, files owned by the current EUID, with no	write  bit
	      set are not removed.

       --delay=x
	      Delay  execution at the start for a random time, up to x 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.

       -T x, --runtime=x
	      Execution  of tmpreaper will aborted after x seconds; this is to prevent attacks that create many, many files.  By default the time-
	      out is set to 55 seconds.  A value of 0 will disable this feature, which is not advised as this feature prevents possible  race-con-
	      ditions between different instances of tmpreaper.

       -m, --mtime
	      Base the decision of whether to remove the file on its mtime, rather than on its atime.

       -M, --mtime-dir
	      Base the decision of whether to remove the directory on its mtime, rather than on its atime.

       -c, --ctime
	      Base  the  decision of whether to remove the file on its ctime, in addition to its atime.  Only applicable if the --mtime options is
	      not given!

       -s, --symlinks
	      Remove symlinks too, not just regular files and directories.

       -a, --all
	      Remove all file types, not just regular files, symlinks, and directories.

       --protect '<shell_pattern>'
	      Protect the files that match the <shell_pattern> 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 <shell_pattern> in single quotes, the shell will perform the expansion before tmpreaper reads its argument
	      array.  The program does not support that syntax, so you must use single quotes around the glob pattern.

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

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

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 immutable attribute set, to keep a subdirectory from being deleted.	Of course,
       you could just as easily use use the --protect option to obtain the same result.

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

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

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

WARNINGS

       Please  do  not ever run tmpreaper on `/'!!! There are no safeguards against this built into the program, because that would make it diffi-
       cult to use in a chrooted environment.

SEE ALSO

       chattr(1) chdir(2) chroot(8) cron(1) getopt_long(3) ls(1) lsattr(1) rm(1) stat(1)

       [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

       [2] info:(libc)Long Options

AUTHOR

	   Karl M. Hegbloom <karlheg@debian.org>

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

       Now being maintained for Debian by:
	   Paul Slootman <paul@debian.org>

4th Berkeley Distribution					  Mon May 19 2008						      TMPREAPER(8)