gagmacrowarning(cron argument phrase key passphrase)

includefile(../../release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)

gagmacrowarning(ssh-cron)
mailto(f.b.brokken@rug.nl)

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)
DEFINEMACRO(s)(0)(bf(ssh-cron))
DEFINEMACRO(S)(0)(bf(Ssh-Cron))

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))


manpage(ssh-cron)(1)(_CurYrs_)(ssh-cron__CurVers_)
        (ssh-cron - ssh-aware cron-like daemon)

manpagename(ssh-cron)(cron-like daemon able to use ssh-connections)

manpagesynopsis()
       bf(ssh-cron) [OPTIONS] tt([crontab-file]) nl()
        [OPTIONS] - cf. section bf(OPTIONS)nl()
        [crontab-file] - file containing jobs to run.nl()

manpagedescription()

Consider the situation where a computer every now and then must access a
remote computer to do some useful things at that remote computer (like running
a bf(stealth)(1) file integrity scan). In order to do so the computer must be
allowed to make bf(ssh)(1) connections to the remote computer. But since the
commands are not executed by the user but by bf(cron)(1), the ssh-keys which
are required to access the remote computer cannot use passphrases.

This is an undesirable situation: if the computer running the tt(ssh) commands
gets compromised, then the remote computers are compromised as well, since the
attacker may access these remote systems using ssh keys not requiring
passphrases.

S() offers a way out of this undesirable situation, while still allowing
commands to be executed on remote computers. Here's how this is realized:

itemization(
    it() Normally, s() runs as a daemon program. When s() starts it first
        reads and parses a crontab-like specification file. Following this,
        s() spawns a child process, and terminates.

    it() S()'s daemon process itself spawns an bf(ssh-agent)(1) child
        process, executing all scheduled commands.
    
    it() In addition, s()'s daemon defines communication channels between
       itself and its bf(ssh-agent)(1) child process;

    it() S()'s daemon sends the command bf(ssh-add)(1) to its child process as
       its first command to execute, and using normal user-interaction means
       (e.g., using bf(ssh-askpass)(1)) em(ssh-agent) is provided with the
       required passphrase for the ssh key(s).

    it() S()'s daemon now monitors the time, firing off scheduled commands at
       their required moments in time. If these commands require access to
       remote computers, then this access is granted, as em(ssh-agent) is able
       to provide the passphrase.

    it() If an s() daemon process is already running, then the tt(--reload)
       option (see below), can be used to load the s() daemon with the
       commands and environment variable settings from a specified
       tt(crontab-file), replacing the currently stored commands and
       environment settings by the ones provided in the reloaded file.
    )

When shell control characters (like redirection symbols) must be used in
command specifications, they should be escaped. E.g., as in tt(echo hello
world \> /dev/null).

Users sharing a computer each define their own s() specification file. When a
user logs out and leaves the
system the daemon process continues to run, executing its scheduled commands
at their scheduled times, using ssh-keys whenever required.

If the accounts for which s() jobs are running are ever compromised,
the remote computers remain safe, as the passphrases of the available 
ssh-keys remain unavailable.

To prevent unauthorized modifications of the commands scheduled by the s()
daemon themselves a passphrase is required when starting s()'s daemon
process. The passphrase itself is not stored in the daemon (instead, it stores
a bf(sha256)(1) hash value), which avoids access to the s() daemon's
passphrase by browsing the computer's memory. The passphrase must be at least
10 characters long and must be provided when reloading or listing a running
s() program's tt(crontab) file.

The above mentioned facilities are not supported by bf(crontab)(1) itself.
bf(Cron)(1), which is responsible for executing scheduled crontab commands,
has no access to the passphrases of ssh-keys (which are otherwise provided
em(ssh-agent)).

manpagesection(RETURN VALUE)

    S() returns 0 if the daemon was successfully started. Otherwise 1 is
returned. 

manpageoptions()

    Where available, single letter options are listed between parentheses
following their associated long-option variants. Single letter options require
arguments if their associated long options also require arguments.

Several options have default values. Run tt(ssh-cron --help) for an overview
of the implemented default option values. Also, several options can be
specified in a configuration file (where this doesn't hold true, it is
explicitly mentioned at the relevant options).

The configuration file (not to be confused with the file containing the
scheduled commands, which is provided as s() command-line file argument)
ignores empty lines and all information on lines starting at a hash-mark
(tt(#), optionally preceded by blanks and/or tabs). The configuration file is
used to specify s()'s options using their long variants. However, in the
configuration file the initial hyphens of command-line options must be
omitted, and optionally a colon may be appended to these long options
names. Note that multi-word option arguments should not be surrounded by
quotes. Examples:
            verb(
    stdout
    syslog-facility: LOCAL0
    mailer: /usr/bin/mail -s "some subject" me@c-plusplus.nl
            )
    Command-line options always override configuration file options.

    itemization(
    it() laoption(agent)(agent)nl()
       absolute path to the agent program (plus its argument(s)) providing the
        ssh-keys. 

        By default tt(/usr/bin/ssh-agent /bin/bash) is used.

    it() lsoption(config)(c)(path)nl()
        config file containing long option specifications.

        By default tt(~/.ssh-cron) is used.

        This option cannot be specified in the configuration file.

    it() loption(forground) nl()
       s() is not run as a daemon. To properly end s() when it's not running
        as a daemon, execute  s() bf(--terminate) in a separate process or end
        it using tt(ctrl-C) or by sending the process a tt(SIGTERM) signal.

       This option cannot be specified in the configuration file.

    it() loption(help) (soption(h))nl()
       s() ends after writing basic usage information to the standard output
        stream.

        This option cannot be specified in the configuration file.

    it() loption(list) (soption(l))nl()
       list the currently defined environment settings and cron-commands (the
        tt(crontab-file) argument must be omitted). This option is
        incompatible with tt(--reload) and tt(--terminate).

        This option cannot be specified in the configuration file.

    it() lsoption(log)(L)(path)nl()
       log messages are appended to tt(path). If tt(path) does not exist, it
        is first created.
 
    it() lsoption(mailer)(m)(command)nl()
       information written to the standard output or standard error streams of
        the commands executed by s() is sent by e-mail to the current
        user. Use tt(--mailer) to redefine (or to suppress sending e-mail by
        specifying an empty mailer command (i.e., tt(--mailer ""))).

        By default tt(/usr/bin/mail -s \"Ssh-cron $*\" $USER@localhost) is
        used, with tt($*) replaced by the exected command as specified in the
        tt(crontab) file argument.
 
    it() loption(reload) (soption(r))nl()
       reload the running s() program with de cron-commands defined in the
        tt(crontab-file) argument (which must be provided). This option is
        incompatible with tt(--list) and tt(--terminate).

        This option cannot be specified in the configuration file.

    it() loption(stdout) (soption(s))nl() 
       in addition to using a log file and/or writing syslog messages send all
        messages to the standard output. This option is not available if 
        s() runs as a daemon process.

        This option cannot be specified in the configuration file.

    it() loption(syslog)nl()
       use this option to send messages to the syslog daemon.  By default
        syslog messages are written to the syslog's tt(DAEMON) facility with
        priority tt(NOTICE).

    it() laoption(syslog-facility)(facility)nl()
       the syslog facility used when writing messages to the syslog daemon.
        By default this is tt(DAEMON). For an overview of facilities and their
        meanings, see, e.g., bf(syslog)(3). With s() the facilities tt(DAEMON,
        LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7), and
        tt(USER) can be used.

        By default facility tt(DAEMON) is used.

    it() laoption(syslog-priority)(priority)nl()
       the syslog priority used when writing messages to the syslog daemon.
        By default this is tt(NOTICE). For an overview of priorities and their
        meanings, see, e.g., bf(syslog)(3). With s() all defined priorities
        can be used. E.g., tt( EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO)
        and tt(DEBUG).

        By default priority tt(NOTICE) is used.

    it() laoption(syslog-tag)(tag)nl()
       syslog messages can be provided with a em(tag), which simplifies
        locating them in the syslog log-files. See also section tt(RSYSLOG
        FILTERING) below.

        By default the tag tt(SSH-CRON) is used.  

    it() loption(terminate) (soption(t))nl()
       terminate a running s() daemon. The tt(crontab-file) argument must be
        omitted. This option is incompatible tt with the (--list) and
        tt(--reload) options.

        This option cannot be specified in the configuration file.

   it() lsoption(uds)(u)(path)nl()
       when s() runs as a daemon or in the foreground, then tt(path) specifies
        the location of its tt(Unix) domain socket. When s() is called with
        the options tt(--list, --reload), or tt(--terminate) then it uses the
        tt(uds) file to communicate with the running s() proram. When the
        running s() program ends it removes the tt(uds) file. If the tt(uds)
        file couldn't be removed (e.g., s() received a tt(SIGKILL) signal)
        then the tt(uds) file must be removed `by hand' before s() can start
        again.

        By default tt(~/.ssh-cron.uds) is used.
 
    it() loption(verbose)nl() 
       additional messages about s()'s mode of operation are sent to
        s()'s log facilities (specified by tt(--log, --syslog,) and/or
        tt(--stdout)). 

    it() loption(version) (soption(v))nl()
       s()'s version number is written to the standard output stream.

        This option cannot be specified in the configuration file.

    ) 
    
manpagesection(RSYSLOG FILTERING)

    When using bf(rsyslogd)(1) property based filters may be used to filter
syslog messages and write them to a file of your choice. E.g., to filter
messages starting with the syslog message tag (e.g., tt(SSH-CRON)) use
        verb(
:syslogtag, isequal, "SSH-CRON:"   /var/log/ssh-cron.log
:syslogtag, isequal, "SSH-CRON:"   stop
        )
    Note that the colon is part of the tag, but is not specified with the 
tt(syslog-tag) option.

    This results in writing all messages having the tt(SSH-CRON:) tag to be
written on tt(/var/log/ssh-cron.log). More extensive filtering is also
supported, see, e.g., tt(http://www.rsyslog.com/doc/rsyslog_conf_filter.html)
and tt(http://www.rsyslog.com/doc/property_replacer.html)

manpageseealso() 

bf(cron)(1), bf(crontab)(1), bf(crontab)(5), , bf(rsyslogd)(1), bf(ssh)(1), 
bf(ssh-add)(1), bf(ssh-agent)(1), bf(ssh-askpass)(1), bf(stealth)(1), 
bf(syslog)(3)

manpagebugs()
    None reported.

manpagesection(COPYRIGHT)
    This is free software, distributed under the terms of the `GNU General
Public License'. Copyright remains with the author. s() is available at
tt(https://fbb-git.gitlab.io/ssh-cron/).

manpagesection(ORGANIZATION)
    University of Groningen.

manpageauthor()
    Frank B. Brokken (bf(f.b.brokken@rug.nl)).