bionic (8) tmpreaper.8.gz

Provided by: tmpreaper_1.6.13+nmu1+deb9u1build0.18.04.1_amd64 bug

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.  Normally, 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 eligible 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/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.

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