README
¶
hermes
Hermes provides a mechanism to notify someone about cronjob failures.
Installing and Getting Started
Hermes is currently a source-only distribution. Both a Unix-like system and Google Go is required to perform compilation. Check the go.mod file for the minimum required Go version.
Compilation
- Clone the repo.
cd hermes && make- The
cmd/hermes/hermesbinary should now exist.
Installation
The hermes executable can be simply cp'd into /usr/local/bin/ or somewhere reasonable.
However, a debian target exists in the Makefile which will generate a Debian package provided your system is able to execute dpkg-deb.
Configuration
Currently hermes supports both a file and an environment variable configuration mechanism. The prefered way is to use the file mechanism.
File Configuration Mechanism
Currently, there is no way to override the default configuration file location, which is: /opt/catloaf/etc/hermes.conf.
This file is a JSON file and if it exists, hermes will prefer its settings. The following format is used:
{
"Sender":"mysender",
"Receiver":"myreceiver",
"Host":"mymailhost",
"Port":"mymailport",
"Password":"secret"
}
To protect the file, a hermes user needs to be created to own the file. Make the hermes binary sgid to allow any user with
shell access to send messages with hermes. Or, don't set the sgid bit and require membership to the hermes group to limit shell user
access to the messaging capabilities provided by hermes.
- First, create the user and group:
adduser --disabled-login --no-create-home --uid $UID hermes - Next, take ownership of the binary and config file:
chown root:hermes /usr/local/bin/hermes && chown root:hermes /opt/catloaf/etc/hermes.conf" - Lastly, if desired, set the sgid bit:
chmod 2555 /usr/local/bin/hermes. Or, require group membership instead:chmod 0550 /usr/local/bin/hermes.
Edit /etc/crontab so that jobs which require notification use hermes as an OR branch.
For example:
0 4 15 * * root zpool scrub zp0 zp1
Becomes:
0 4 15 * * root (zpool scrub zp0 zp1) || hermes -m "Failed to initalize zpool scrub!!!"
Environment Variables Configuration Mechanism
The following environment variables need to be defined and placed into a file such as /etc/hermes.env
HERMES_SENDER="notifier@example.com"HERMES_RECEIVER="notifiee@example.com"HERMES_HOST="mail.example.com"HERMES_PORT="587"HERMES_PASSWD="notifiers_email_password"
Be sure to protect hermes.env via chown root:root hermes.env && chmod 0400 hermes.env.
Edit /etc/cronjob so that jobs which require notification use hermes as an OR branch.
For example:
0 4 15 * * root zpool scrub zp0 zp1
Becomes:
0 4 15 * * root (zpool scrub zp0 zp1) || (. /etc/hermes.env; hermes -m "Failed to initialize zpool scrub!!!")
Executing Tests
Hermes requires Ginkgo for testing. The test target in the Makefile is the recommended way to execute the test suite.
This will also display coverage metrics automatically.
Licensing
Hermes is released under the terms of the GPLv3 license, a copy of the GPL is provided in the COPYING file located at the root of this repo.
Documentation
¶
Index ¶
Constants ¶
const ( Sender = "HERMES_SENDER" Receiver = "HERMES_RECEIVER" Host = "HERMES_HOST" Port = "HERMES_PORT" Passwd = "HERMES_PASSWD" )
const (
MailNewLine = "\r\n"
)
Variables ¶
var ( ErrSenderNotSet = errSenderNotSet() ErrReceiverNotSet = errReceiverNotSet() ErrMailHostNotSet = errMailHostNotSet() ErrMailPortNotSet = errMailPortNotSet() ErrPasswdNotSet = errPasswdNotSet() )
var Version string
Functions ¶
func Hermes ¶
func Hermes(conn Connection, msg string) error
Types ¶
type Configuration ¶
type Configuration struct {
Sender string
Receiver string
MailHost string
MailPort string
Passwd string
}
func NewConfiguration ¶
func NewConfiguration() (*Configuration, error)
NewConfiguration is the default entry point for getting the hermes Configuration. Unless you have a good reason to do otherwise, NewConfiguration should be used over other methods. NewConfiguration uses a precedence when evaluating configuration mechanisms, the first to succeed wins. If no mechanism is able to succeed, Configuration is undefined and err != nil. Mechanism precedence is as follows: 1. Configuration file in the default location. [NewDefaultFileConfiguration()] 2. Environment variables. [NewEnvConfiguration()]
func NewDefaultFileConfiguration ¶ added in v1.1.0
func NewDefaultFileConfiguration() (*Configuration, error)
NewDefaultFileConfiguration returns a hermes Configuration with options based on a configuration file in the default location. If there is a problem reading the file, the returned Configuration is undefined and err != nil. The default location of the config file is: /opt/catloaf/etc/hermes.conf
func NewEnvConfiguration ¶ added in v1.1.0
func NewEnvConfiguration() (*Configuration, error)
NewEnvConfiguration returns a hermes Configuration with options based on environment variables. If any one of the environment variables is missing, the returned Configuration is undefined and err != nil. The following environment variables are used: HERMES_SENDER HERMES_RECEIVER HERMES_HOST HERMES_PORT HERMES_PASSWD
func NewFileConfiguration ¶ added in v1.1.0
func NewFileConfiguration(configFilePath string) (*Configuration, error)
NewFileConfiguration returns a hermes Configuration with options based on the specified configuration file. If there is a problem reading the file, the returned Configuration is undefined and err != nil.
type Connection ¶
type FileOptions ¶ added in v1.1.0
type SmtpConnection ¶
type SmtpConnection struct {
// contains filtered or unexported fields
}
func NewSmtpConnection ¶
func NewSmtpConnection(config *Configuration) (*SmtpConnection, error)
func (*SmtpConnection) From ¶
func (conn *SmtpConnection) From() string
func (*SmtpConnection) MailHost ¶
func (conn *SmtpConnection) MailHost() string
func (*SmtpConnection) SendMessage ¶
func (conn *SmtpConnection) SendMessage(msg string) error
func (*SmtpConnection) To ¶
func (conn *SmtpConnection) To() string
Source Files
Directories