shush.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SHUSH" "1" "August 2015" "" ""
.
.SH "NAME"
\fBshush\fR \- Run a command and optionally report its output by email\.
.
.SH "SYNOPSIS"
\fBshush\fR [ \fB\-h\fR | \fB\-v\fR ]
.
.P
\fBshush\fR [ \fB\-c\fR \fIdir\fR ] [ \fB\-S\fR | \fB\-s\fR \fIfacility\fR ] [ \fB\-vmfk\fR ] \fIname\fR [ \fIID\fR ]
.
.P
\fBshush\fR [ \fB\-c\fR \fIdir\fR ] [ \fB\-H\fR \fIto\fR ] [ \fB\-R\fR \fIto\fR ] [ \fB\-T\fR \fIto\fR ] \fB\-C\fR \fIname\fR [ \fIstdout\fR [ \fIstderr\fR ] ]
.
.P
\fBshush\fR [ \fB\-i\fR | \fB\-u\fR | \fB\-r\fR ] [ \fB\-c\fR \fIdir\fR ]
.
.SH "DESCRIPTION"
\fBshush\fR runs a command and optionally reports on it\'s status by email\. By default, \fBshush\fR will not relay any script output to stdout or stderr, as everything is meant to be reported by email\. Because interrupting \fBshush\fR ignores the following signals: SIGHUP, SIGINT, SIGQUIT, SIGTERM\. Such signals should be sent to the running command, rather than \fBshush\fR\. If you need to kill \fBshush\fR, SIGKILL may be used, but only with the knowledge that it should be an action of last resort\.
.
.P
Configuration is managed from a directory (\fI$HOME/\.shush/\fR by default)\. For a command to be run using, it must have a configuration file with a unique name, as well as two optional files, suffixed with \.stdout and \.stderr respectively, in the configuration directory\. The contents of these files are described in the Configuration section\.
.
.P
When the \-C option is specified, \fBshush\fR will load the configuration file and send any emails, but will not run the commands\. Two files can be specified, which will be fed into \fBshush\fR to produce any necessary reports\. This can be useful for both checking configartion syntax and testing the report output\. Additionally, if \fBshush\fR failed to properly terminate while running a command, the stdout and stderr will left in the /tmp/ directory, allowing you to manually produce reports for the interrupted run\.
.
.P
\fBshush\fR is also able to manage \fBcrontab\fR(5) entries via the configuration files\. It will scan all files in the configuration directory for the schedule option, and will update the user\'s \fBcrontab\fR(5) accordingly\.
.
.SH "OPTIONS"
.
.TP
\fB\-h\fR
Display a brief help message\.
.
.TP
\fB\-V\fR
Display the version information\. Prefix with \fB\-v\fR to display compile time defaults\.
.
.TP
\fB\-c\fR \fIdir\fR
Specify the directory where configurations are stored\.
.
.TP
\fB\-s\fR \fIfacility\fR
Defines the syslog facility to use for logging\.
.
.TP
\fB\-S\fR
Disable syslog logging\.
.
.TP
\fB\-v\fR
Copy information log messages to the standard output\.
.
.TP
\fB\-f\fR
Fast mode: Any configured randomdelay is ignored\.
.
.TP
\fB\-m\fR
Monitor and display the command\'s standard output and error in real time\.
.
.TP
\fB\-k\fR
Keep the command\'s output log files instead of deleting them upon completion\.
.
.TP
\fB\-C\fR
Check the configuration without running any command\.
.
.TP
\fB\-H\fR \fIto\fR
Send a sample HTML report to the specified recipient(s)\.
.
.TP
\fB\-R\fR \fIto\fR
Send a sample enriched report to the specified recipient(s)\.
.
.TP
\fB\-T\fR \fIto\fR
Send a sample text report to the specified recipient(s)\.
.
.TP
\fB\-i\fR
Use crontab(1) to install a new \fBcrontab\fR(5) file for the current user\'s\. The user must not already have a \fBcrontab\fR(5) file\.
.
.TP
\fB\-u\fR
Use crontab(1) to update the current user\'s \fBcrontab\fR(5) file which must already exist\.
.
.TP
\fB\-r\fR
Remove any entry added by the \-u option from the current user\'s \fBcrontab\fR(5)\.
.
.SH "CONFIGURATION"
\fBshush\fR configuration files consist of a main section, report section(s) and parameters The main section defines global parameters as well as defaults for reports\. Each report section begins with the name of the report between brackets\. Lines beginning with the character "#" are ignored\. Parameters should be specified only once\. If specified multiple times, all but the last occurrence will be ignored, unless noted otherwise\. Parameters are defined using the following syntax:
.
.P
\fBname=value\fR
.
.P
or optionally:
.
.P
\fBname@hostname=value\fR
.
.P
The second format allows the value to only be applied to a specific hostname\.
.
.P
The following parameters appear only the the main section:
.
.SS "Main Section"
.
.TP
\fBcommand\fR
The command to run\.
.
.TP
\fBlock\fR
If set, \fBshush\fR attempts to obtain a lock file before running the command, and can also specify the action to take if the lockfile already exists\. The value format is a comma\-separated list of actions\. Valid actions are:
.
.IP
\fBabort\fR: Immediately exit\.
.
.IP
\fBignore\fR: Ignore any lockfile and run anyway\.
.
.IP
\fBloop\fR: Repeat the list of actions from the beginning\. Mostly useful when combined with a time duration\.
.
.IP
a valid time duration: \fBshush\fR will wait for the specified time, continually trying to obtain the lockfile\. Time durations may be specified in units of w(eeks), d(ays), h(ours), m(inutes) or s(econds)\. If no unit is specified, it is assumed to be minutes\.
.
.IP
\fBnotify=\fR\fI\fIemail\fR\fR: will notify the specified email that obtaining the lockfile failed\.
.
.TP
\fBlockfile\fR
By default, shush will use a file located in the same directory as the configuration file, and named after the configuration and host names\. An alternate filename may be specified using this option\.
.
.TP
\fBlockmsg\fR
If set, this string will be used as subject for lock notification(s) mail messages\.
.
.TP
\fBpath\fR
\fBshush\fR does not modify the environment, except to set the \fBPATH\fR variable if the path option is set\.
.
.TP
\fBrandomdelay\fR
If this option is set, shush will wait up the specified amount of time before starting the command unless invoked with the \fB\-f\fR\. Valid time units are: s(econds), m(inutes), h(ours), d(ays), w(eeks)\. If not unit is specified, it is assumed to be minutes\.
.
.TP
\fBschedule\fR
This defines when to run this command as a cron job in a \fBcrontab\fR(5) compatible format\. Multiple entries may be specified using the character ";" as separator\. Entries prefixed by the character "#" will be skipped\. This option is not directly used by shush to run the command, but used by the \-i and \-u options\.
.
.TP
\fBsendmail\fR
This may be used to override the command used to send mail\.
.
.TP
\fBshell\fR
By default, the Bourne shell \fBsh\fR(1) is used to run the command allowing any shell syntax to be used\. An alternate shell may be defined using this option\.
.
.TP
\fBstderr\fR
This defines how the command\'s standard errors are captured and reported to the user: "first", "mixed" or "last"\. When using "mixed", the name\.stderr file is ignored\.
.
.TP
\fBsyslog\fR
This option is \fIonly\fR used by the \fB\-i\fR and \fB\-u\fR options and has no other effect on shush\. It allows overriding the default syslog facility used for logging and defined at compile time\. If left blank, this supresses the use of syslog\.
.
.TP
\fBtimeout\fR
This option allows one to control how long the command may run\. It should be a comma separated list of actions\. Actions are executed in the order they are provided, and shush will wait forever if the command is still running once all the actions have been executed unless the string "loop" is one of defined actions\. Valid actions are:
.
.IP
a valid time duration: Simply wait for the command to terminate\. Time durations may be specified in units of w(eeks), d(ays), h(ours), m(inutes) or s(econds)\.
.
.IP
a signal (either \fISIGNAME\fR or \-\fISIGNUMBER\fR): To be sent the command\'s process group\.
.
.IP
a signal (either =\fISIGNAME\fR or =\fISIGNUMBER\fR): To be sent the shell used to spawn the command\.
.
.IP
\fBloop\fR: mark where to start again from when all actions have been executed
.
.IP
\fBnotify=\fR\fIemail\fR: mail addresses to which a notification mail should be sent\. If no unit is specified, it is assumed to be minutes\.
.
.SS "Any section"
.
.TP
\fBto\fR, \fBcc\fR, \fBbcc\fR
Where to send the mail report\.
.
.TP
\fBsubject\fR
Subject of the mail report\.
.
.TP
\fBheader\fR
Additional mail header(s)\. Note that this parameter may be repeated to specify multiple headers\. However, only headers from the report (if specified) or from the main section will be used for a given report\.
.
.TP
\fBhostprefix\fR
By default, specified subjects are prefixed with the host name between brackets\. This option allows to customize this prefix\. A positive integer indicates how many hostname components should be shown\. With a negative integer, trailing components of the hostname are shown\. The integer zero indicates that the prefix should be omitted\.
.
.TP
\fBuserprefix\fR
By default, specified subjects are prefixed with the username between brackets\. This option allows to disable this prefix\. Any non zero value indicates that the username should be shown while zero causes the prefix to be omitted\.
.
.TP
\fBformat\fR
Mail messages sending the output of the command may be sent in three different formats: "text" (the default), "enriched" text or "html"\.
.
.TP
\fBsizelimit\fR
By default, the entire output of the command is sent in mail reports\. This option may be used to limit the size of the output included in a report\. Note that the total size of mail sent will be greater as this limit has no effect upon mail headers\. The size can be specified in units of m, k, b, c (MB, KB, Bytes)\. If no unit is specified, it is assumed to be KB\. A limit of zero indicates that the output should not be truncated\.
.
.TP
\fBif\fR
A report is only sent if no if condition is specified or if the specified if condition is true\. The condition syntax allows for the usual logical operators (\fB||\fR, \fB&&\fR, \fB!\fR), comparison operators (\fB==\fR, \fB!=\fR, \fB<\fR, \fB<=\fR, \fB>\fR, \fB>=\fR) and basic arithmetic operators (\fB+\fR, \fB\-\fR)\. Asides from counters defined by the configuration, the following variables may be used:
.
.IP
\fB$exit\fR: If the command terminated normally, this is its exit code\. Otherwise, it is negative and indicates the signal number having caused the command to terminate (e\.g\. \-1 indicates signal number 1 caused the command to terminate)\.
.
.IP
\fB$size\fR: Output size (in bytes), same as "$outsize + $errsize"
.
.IP
\fB$outsize\fR: size (in bytes) of standard output
.
.IP
\fB$errsize\fR: size (in bytes) of standard error
.
.IP
\fB$lines\fR: number of lines output
.
.IP
\fB$outlines\fR: number of standard output lines
.
.IP
\fB$errlines\fR: number of standard error lines
.
.IP
\fB$runtime\fR: command run time (in seconds)
.
.IP
\fB$utime\fR: user time used by the command
.
.IP
\fB$stime\fR: system time used by the command
.
.IP
\fB$tty\fR: \fB1\fR if shush is run from a terminal (e\.g\. interactively), \fB0\fR otherwise\.
.
.SH "ENVIRONMENT VARIABLES"
.
.TP
\fBHOME\fR
If the \fB\-c\fR option is not used, shush will look for configuration files in \fB$HOME/\.shush\fR\.
.
.TP
\fBSHUSH_SENDMAIL\fR
If defined, this should point to the \fBsendmail\fR(1) binary\. This variable overrides the "sendmail" configuration setting and should be used with care\.
.
.TP
\fBTMPDIR\fR
Directory where temporary files are created\.
.
.SH "EXAMPLE"
The following configuration runs "shush \-c /etc/shush \-u" daily at 9:00, updating the user (root) crontab:
.
.IP "" 4
.
.nf

command=shush \-c /etc/shush \-u
schedule=0 9 * * *
lock=notify=root root\-logs,abort
timeout=5m,notify=root root\-logs
stderr=first
format=text
Subject=Crontab Daily Update
[logs]
to=root\-logs
[readers]
if=$exit != 0 || $outlines != 1 || $errsize > 0 || U
to=root
format=rich
.
.fi
.
.IP "" 0
.
.P
Assuming the configuration above was place in a file name \fBupdate_shush_cron\fR, the next two files would be called \fBupdate_shush_cron\.stdout\fR and \fBupdate_shush_cron\.stderr\fR respectively\.
.
.P
The associated configuration for standard output is:
.
.IP "" 4
.
.nf

Oshush: crontab updated\e\.$
U^(\.+)$
.
.fi
.
.IP "" 0
.
.P
and for standard error:
.
.IP "" 4
.
.nf

U^(\.+)$
.
.fi
.
.IP "" 0
.
.P
A lock will be set while running the command, and mail sent to "root" and "root\-logs" if the lock is held by another process when shush starts\. A mail will also be sent to "root" and "root\-logs" if "shush \-c /etc/shush \-u" runs for more than 5 minutes\. Upon completion, the output will always be sent to "root\-logs"\. Additionally, the output will be sent to "root" if the condition "$exit != 0 || $outlines != 1 || $errsize > 0 || U" is true\. For it to be true, one of the following must be true: the exit code is non zero, there was output on standard error or there was output on standard output other than the line "shush: crontab updated\."\. Any line of output other than "shush: crontab updated\." will be displayed in bold in mails sent to "root"\.
.
.SH "SEE ALSO"
\fBcrontab\fR(1), \fBpcre\fR(3), \fBregex\fR(3), \fBsendmail\fR(1), \fBsh\fR(1)\.
.
.SH "AVAILABILITY"
The latest release of shush is available on github\. The old version is available on http://web\.taranis\.org/shush/\.
.
.SH "AUTHOR"
Christophe Kalt \fIshush@taranis\.org\fR (Original author) Stephen Muth \fIsmuth4@gmail\.com\fR