Section: Sample (1)
Updated: August 2007
Return to Main Contents
sample - interface to edit ~/.sample files
[-vnrlt] [-u user] [-e editor]
sample and its associated tools are intended to monitor ("sample") outdated/oversized files and handle them in a user-defined fashion. this can involve deleting, moving, or updating with new content among other things.
the sample program is a simple console-based interface used to make and validate ~/.sample files, similar to the respective use of the crontab program. however, the sample program is not required in any way to make your ~/.sample file, it can be created/modified completely manually.
if no command-line arguments are specified for sample it will attempt to edit the current user's ~/.sample file.
shows the version information of sample
if sample is making a new ~/.sample file, it will not include the "help" configuration comments
removes a user's ~/.sample file (this can be used in conjunction with the -u option)
(root-only) lists all potentially processable ~/.sample and spooled sample (~/.sample_spool/*) files. this is for admin maintenance/monitoring purposes (does not list /etc/sampletab/* files as they are already consolidated)
(root-only) switch to editing a user's "/etc/sampletab/username", instead of "/home/username/.sample" (this can be used in conjunction with the -u option, this feature is explained in the TABS section)
- -u user
(root-only) modify a specified user's ~/.sample file, instead of their own
- -e editor
specify an alternate editor to edit your ~/.sample file
the format of your ~/.sample file via the sample interface or by directly editing the file is a job-per-line format, similar to that of cron. the format is:
[TYPE] [TIME|SIZE] [PATH] [EXEC]
each value being separated by TABS (\t). the literal form of this is:
"if TYPE has past TIME for a file contained in PATH then run EXEC"
OR, for filesize comparisons:
"if TYPE is smaller/larger than SIZE for a file contained in PATH then run EXEC"
description of each field:
- field [TYPE]:
value must be set to one of the following:
A compare TIME to the last access of a file (older than)
a compare TIME to the last access of a file (newer than)
C compare TIME to the last status change of file (older than)
c compare TIME to the last status change of file (newer than)
M compare TIME to the last modification of file (older than)
m compare TIME to the last modification of file (newer than)
S compare SIZE to the size of file (greater than)
s compare SIZE to the size of file (less than)
the lowercase versions of the above are lowercase because they are deemed less commonly used than the uppercase versions.
- field [TIME]:
for types A, a, C, c, M and m. the value must be set to one or a combination of the following:
s seconds (ex. "60s")
m minutes (ex. "60m")
h hours (ex. "24h")
d days (ex. "7d")
w weeks (ex. "52w")
M months (ex. "12M")
Y years (ex. "1Y")
there should be no spaces in this field, for example "1h30m" would be the equivalent of matching a 90-minute or older file(s).
- field [SIZE]:
for types S and s. the value must be set to one or a combination of the following:
B bytes (ex. "1024B")
K kilobytes (ex. "1024K")
M megabytes (ex. "1024M")
G gigabytes (ex. "1G")
there should be no spaces in this field, for example "1M512K" would be the equivalent of matching a 1.5 meg file(s).
- field [PATH]:
the PATH field can be separated by colons (:) to include multiple paths to check for outdated/oversized files. this format follows the wildcard method supported by most shells, for example "~/*.txt:~/*.rtf" would attempt to find all outdated/oversized .txt and .rtf files in your home directory.
- field [EXEC]:
this is executed if sampled finds an outdated/oversized file is found in PATH, the following variables will be filled in with their corresponding value:
%% inserts a literal %
%s exact path to the file matched (shell-escaped)
%S exact path to the file matched (NON-escaped)
%f only the filename of the matched path (shell-escaped)
%F only the filename of the matched path (NON-escaped)
%p only the path of the matched path (shell-escaped)
%P only the path of the matched path (NON-escaped)
%l symbolic link path, becomes %s if none (shell-escaped)
%L symbolic link path, becomes %S if none (NON-escaped)
%u file owner's user id
%U file owner's user name
%g file owner's group id
%G file owner's group name
%m (octal) file mode (ex. "0777")
%M (string) file mode (ex. "-rwxrwxrwx")
%n size of the file in bytes
%i inode of file
%0-9 sub-directory hierarchy variables
sample tabs, found in /etc/sampletab/ by default, are sample files in exactly the same format as ~/.sample files except they are designed to be static and only editable by root.
in general terms; "/etc/sampletab/username" is the same as "/home/username/.sample", except the user cannot edit the sampletab version.
root can edit these files by appending the -t argument to the sample command.
- an example ~/.sample might look like:
# Set your desired shell. (may be restricted in some
# Move old file(s) in the home directory to a sub-folder if
# they haven't been accessed/read in over 6 months.
A 6M ~ mv -f -- %s ~/old/%f
# Remove (1.5 year old) unread inactive user's mail.
A 1Y6M /var/mail/ rm -f -- %s
# Remove files in /tmp/* and /var/tmp/* after 1 week of no
M 1w /tmp:/var/tmp rm -f -- %s
# Update/regenerate a static (rss) webpage every 90 minutes.
# ("90m" also works)
M 1h30m ~/www/site.rss perl ~/make_rss.pl > %s
# This would essentially make a drop folder/directory in /drop/,
# which would simply process and delete any file placed in
# the directory. (sampled, by default, runs on the minute.
# meaning this would not actually process every second)
M 1s /drop/ ~/proc.sh %s ; rm -f -- %s
# This would delete 100 meg or larger files in your home
S 100M ~ rm -f -- %s
# (root) Log rotation, make sure it's bash for this. this will
# rotate *.log files in /var/log when they grow over 10MB.
S 10M /var/log/*.log for ((i=5;i>=0;i--)); do mv -f %s.$i %s.$[i+1]; done; mv -f %s %s.0; touch %s
environmental variables can be set by placing VAR=VALUE on a blank line in your ~/.sample file.
sample interface variables:
used to determine the text editor to edit the ~/.sample file
used to determine the path of the text editor
Written by v9/fakehalo. [email@example.com]
Report bugs to <firstname.lastname@example.org>.
Copyright © 2007 fakehalo.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
samples(1) sample.conf(5) sampled(8) samputil(8)
- SEE ALSO
This document was created by
using the manual pages.