ssh-cron(1)

📦
version 2.00.00 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 ssh-cron(1) — the ssh-aware, cron-like daemon bestie 💖

okay so. gather round. this is ssh-cron, aka the cron-like daemon that can actually do ssh, and honestly? she's iconic. let me tell you everything, no gatekeeping.

✨ NAME ✨

ssh-cron — a cron-like daemon that's able to use ssh-connections. periodt. 🫶

🌸 SYNOPSIS 🌸

ssh-cron [OPTIONS] [crontab-file]
[OPTIONS] - cf. section OPTIONS
[crontab-file] - file containing jobs to run.

so [OPTIONS] are the flags (see the OPTIONS section below, we get there), and [crontab-file] is the file with the jobs to run. easy.

🦋 DESCRIPTION 🦋

okay bestie, picture this: there's a computer that every now and then has to reach out to some remote computer and do useful stuff over there (like running a stealth(1) file integrity scan, yk, very spy-core). to do that, the computer has to be allowed to make ssh(1) connections to that remote machine. but here's the plot twist 😭 — the commands aren't run by you, they're run by cron(1). which means the ssh-keys needed to get into the remote computer cannot use passphrases.

and that is... not the vibe. it's genuinely an undesirable situation: if the computer running those ssh commands ever gets compromised, then the remote computers are compromised too, because the attacker can just waltz in using ssh keys that have no passphrases. 💀

Ssh-Cron offers a way out of this whole mess, while still letting commands run on remote computers. here's how it's done:

  • normally, ssh-cron runs as a daemon program. when ssh-cron starts it first reads and parses a crontab-like specification file. after that, ssh-cron spawns a child process, and terminates.
  • Ssh-Cron's daemon process itself spawns an ssh-agent(1) child process, which executes all the scheduled commands.
  • also, ssh-cron's daemon sets up communication channels between itself and its ssh-agent(1) child process;
  • Ssh-Cron's daemon sends the command ssh-add(1) to its child process as its first command to execute, and by using normal user-interaction means (e.g., using ssh-askpass(1)) ssh-agent gets handed the required passphrase for the ssh key(s). 🔑
  • Ssh-Cron's daemon now just monitors the time, firing off scheduled commands at their required moments in time. and if those commands need access to remote computers? access is granted, because ssh-agent is able to provide the passphrase. slay.
  • if an ssh-cron daemon process is already running, then the --reload option (see below) can be used to load the ssh-cron daemon with the commands and environment variable settings from a specified crontab-file, replacing the currently stored commands and environment settings with the ones from the reloaded file.

when shell control characters (like redirection symbols) have to be used in command specifications, they should be escaped. e.g., like this: echo hello world \> /dev/null.

users sharing a computer each define their own ssh-cron specification file. and when a user logs out and leaves the system, the daemon process just keeps on running, executing its scheduled commands at their scheduled times, using ssh-keys whenever required. she doesn't need you there. main character energy honestly. 👑

if the accounts for which ssh-cron jobs are running ever get compromised, the remote computers stay safe, because the passphrases of the available ssh-keys remain unavailable. 🛡️

to prevent unauthorized modifications of the commands scheduled by the ssh-cron daemon themselves, a passphrase is required when starting ssh-cron's daemon process. the passphrase itself is not stored in the daemon (instead, it stores a sha256(1) hash value), which avoids access to the ssh-cron 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 ssh-cron program's crontab file. don't skip this, fr fr.

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

🎀 RETURN VALUE 🎀

Ssh-Cron returns 0 if the daemon was successfully started. otherwise 1 is returned. that's it, that's the whole rule. ✨

💅 OPTIONS 💅

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 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's explicitly mentioned at the relevant options).

the configuration file (not to be confused with the file containing the scheduled commands, which is provided as the ssh-cron command-line file argument) ignores empty lines and all information on lines starting at a hash-mark (#, optionally preceded by blanks and/or tabs). the configuration file is used to specify ssh-cron's options using their long variants. BUT — in the configuration file the initial hyphens of command-line options must be omitted, and optionally a colon may be appended to these long option names. also note: multi-word option arguments should not be surrounded by quotes. examples:

stdout
syslog-facility: LOCAL0
mailer: /usr/bin/mail -s "some subject" me@c-plusplus.nl

command-line options always override configuration file options. always. 💯

  • --agent=agent — absolute path to the agent program (plus its argument(s)) providing the ssh-keys. by default /usr/bin/ssh-agent /bin/bash is used.
  • --config=path (-c) — config file containing long option specifications. by default ~/.ssh-cron is used. this option cannot be specified in the configuration file.
  • --forground — ssh-cron is not run as a daemon. to properly end ssh-cron when it's not running as a daemon, execute ssh-cron --terminate in a separate process, or end it using ctrl-C, or by sending the process a SIGTERM signal. this option cannot be specified in the configuration file.
  • --help (-h) — ssh-cron ends after writing basic usage information to the standard output stream. this option cannot be specified in the configuration file.
  • --list (-l) — list the currently defined environment settings and cron-commands (the crontab-file argument must be omitted). this option is incompatible with --reload and --terminate. this option cannot be specified in the configuration file.
  • --log=path (-L) — log messages are appended to path. if path does not exist, it is first created.
  • --mailer=command (-m) — information written to the standard output or standard error streams of the commands executed by ssh-cron is sent by e-mail to the current user. use --mailer to redefine (or to suppress sending e-mail by specifying an empty mailer command, i.e., --mailer ""). by default /usr/bin/mail -s \"Ssh-cron $*\" $USER@localhost is used, with $* replaced by the executed command as specified in the crontab file argument.
  • --reload (-r) — reload the running ssh-cron program with the cron-commands defined in the crontab-file argument (which must be provided). this option is incompatible with --list and --terminate. this option cannot be specified in the configuration file.
  • --stdout (-s) — 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 ssh-cron runs as a daemon process. this option cannot be specified in the configuration file.
  • --syslog — use this option to send messages to the syslog daemon. by default syslog messages are written to the syslog's DAEMON facility with priority NOTICE.
  • --syslog-facility=facility — the syslog facility used when writing messages to the syslog daemon. by default this is DAEMON. for an overview of facilities and their meanings, see, e.g., syslog(3). with ssh-cron the facilities DAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, and USER can be used. by default facility DAEMON is used.
  • --syslog-priority=priority — the syslog priority used when writing messages to the syslog daemon. by default this is NOTICE. for an overview of priorities and their meanings, see, e.g., syslog(3). with ssh-cron all defined priorities can be used. e.g., EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO and DEBUG. by default priority NOTICE is used.
  • --syslog-tag=tag — syslog messages can be provided with a tag, which simplifies locating them in the syslog log-files. see also section RSYSLOG FILTERING below. by default the tag SSH-CRON is used.
  • --terminate (-t) — terminate a running ssh-cron daemon. the crontab-file argument must be omitted. this option is incompatible with the (--list) and --reload options. this option cannot be specified in the configuration file.
  • --uds=path (-u) — when ssh-cron runs as a daemon or in the foreground, then path specifies the location of its Unix domain socket. when ssh-cron is called with the options --list, --reload, or --terminate then it uses the uds file to communicate with the running ssh-cron program. when the running ssh-cron program ends it removes the uds file. if the uds file couldn't be removed (e.g., ssh-cron received a SIGKILL signal) then the uds file must be removed by hand before ssh-cron can start again. 😬 by default ~/.ssh-cron.uds is used.
  • --verbose — additional messages about ssh-cron's mode of operation are sent to ssh-cron's log facilities (specified by --log, --syslog, and/or --stdout).
  • --version (-v) — ssh-cron's version number is written to the standard output stream. this option cannot be specified in the configuration file.

🌈 RSYSLOG FILTERING 🌈

when using 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., SSH-CRON) use

: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 syslog-tag option.

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

🔍 SEE ALSO 🔍

ok so if you wanna go deeper (and bestie, you know you do 💅), these are the pages that live in the same universe as ssh-cron:

(yes there is literally a stray empty entry in that list and no i will not be fixing it, it's part of the lore now 🫶)

🐛 BUGS 🐛

None reported.

not a single one?? the way this program is just out here being flawless. main character energy fr fr ✨

This is free software, distributed under the terms of the GNU General Public License. Copyright remains with the author. ssh-cron is available at https://fbb-git.gitlab.io/ssh-cron/.

free software!! iconic behaviour. the copyright stays with the author, the license is GNU GPL, and the home base is that gitlab link up there — go say hi 💖

🏛️ ORGANIZATION 🏛️

University of Groningen.

shoutout to the University of Groningen for hosting this whole situation, we love a supportive institution 🌸

👑 AUTHOR 👑

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

the legend. the icon. the moment. thank you Frank, no cap 🙇‍♀️💜

and that's a wrap on the whole page bestie!! 🎀 this was version ssh-cron_2.00.00, dated 2014-2025, and yes, it's the ssh-cron(1) manual — go forth and schedule your ssh stuff like the absolute queen you are. slay, stay hydrated, and don't let your keys expire 💅🦋✨

📦 where this page comes from