xetusoss/naemon repository overview

⁠Docker Naemon

A turnkey Naemon⁠ image ready for most deployment situations. The key features are:

1. Externalized naemon configuration through the /data volume
2. A rich set of default checks included in the container, as well as python, ruby, and perl support in the container for additional custom checks.
3. Optional LDAP authnentication support for Thruk
4. Optional SMTP server support via ssmtp⁠
5. Optional Jabber notification support via sendxmpp⁠

Warning: Since Naemon updates can include significant one-way changes, you shouldn't use the "latest" tag outside of testing. All examples in this documentation expect that the you will replace "TAG" with a recent version

⁠Quick start

The command below will setup a Naemon container with email notification support through an SMTP server, with an externalized configuration set for easy container replacement.

 docker run --name naemon -h naemon -d -p 80:80 \
  -e SMTP_HOST="smtp.example.com" \
  -e SMTP_PORT=25 \
  -e [email protected] \
  -e SMTP_PASS=naemonbotpass \
  -e NOTIFICATION_FROM="[email protected]"\
  -v /somepath/naemon_mnt:/data xetusoss/naemon:TAG

⁠Environment Variables

⁠SMTP support

• SMTP_HOST: The SMTP host to send notifications through. No default value.
• SMTP_PORT: The port to use on the SMTP host. Default is 25.
• SMTP_LOGIN: The username to use for SMTP authentication, only needed if the SMTP server requires authentication. No default.
• SMTP_PASS: The password for SMTP authentication, only needed if the SMTP server requires authentication. No default.
• SMTP_USE_TLS: Use TLS for SMTP connections. Default is true if the SMTP_PORT is anything other than 25, otherwise false.

⁠LDAP support

• WEB_LDAP_AUTH_ENABLED: Enable LDAP authentication for the Thuk UI. Default is true if WEB_LDAP_HOST is defined, otherwise false.
• WEB_LDAP_HOST: The LDAP host to authenticate against. No default value.
• WEB_LDAP_SSL: Enable SSL with the LDAP module. Default is false.
• WEB_LDAP_SSL_VERIFY: Enable certificate verification for the SSL certificate used by the LDAP server. Default is true if WEB_LDAP_SSL_CA is defined, otherwise false
• WEB_LDAP_PORT: The port to communicate with the LDAP host on. Default is 389 if WEB_LDAP_SSL is false, and 686 if true.
• WEB_LDAP_BIND_DN: The bind dn to use for LDAP authentication. No default value.
• WEB_LDAP_BIND_PASS: The password to use with the bind dn for LDAP authentication. No default value.
• WEB_LDAP_BASE_DN: The base dn for LDAP authentication. No default value.
• WEB_LDAP_UID: The UID attribute for entries in the LDAP server. Default is uid.
• WEB_LDAP_FILTER: The optional filter to use for LDAP user searching. No default value.

⁠Jabber support

• JABBER_USER: The jabber user to use for notifications. No default value.
• JABBER_PASS: The jabber password associated with the JABBER_USER. No default value.
• JABBER_HOST: The jabber host to connect to. Defaults to the fqdn after the @ symbol of the jabber user. For example a JABBER_USER of [email protected] would have a deafult of im.corp.com.
• JABBER_PORT: The jabber port to connect to. Default is 5222.

⁠Thruk user configuration

• WEB_ADMIN_PASSWORD: The password to use for the thrukadmin user. The default is a randomly generated password that will be output on the command line at initial setup.
• WEB_USERS_FULL_ACCESS: Allow all authenticated users full access to the Web UI monitoring. Useful for situations where the WEB_LDAP_FILTER already restricts access to users with specific attributes. Default false.

⁠Email notification configuration

• NOTIFICATION_FROM: The "from" address for Naemon notifications. Default is naemon@$HOSTNAME. _Note: This is changeable in the externalized configuration.

⁠Examples for different scenarios

⁠(1) LDAP support with group filter

The command below will setup a container with Thruk configured to authenticate users against an LDAP backend, but restricts access using the group filter.

 docker run --name naemon -h naemon -d -p 80:80 \
  -e SMTP_HOST="smtp.example.com" \
  -e SMTP_PORT=25 \
  -e [email protected] \
  -e SMTP_PASS=naemonbotpass \
  -e WEB_LDAP_HOST=ldap.example.com \
  -e WEB_LDAP_BIND_DN="uid=naemonuser,dc=example,dc=com"\
  -e WEB_LDAP_BIND_PASS=pass \
  -e WEB_LDAP_BASE_DN="dc=example,dc=com"\
  -e WEB_USERS_FULL_ACCESS=true\
  -e WEB_LDAP_FILTER="(memberof=cn=naemonusers,cn=groups,dc=example,dc=com)"\
  -e NOTIFICATION_FROM="[email protected]"\
  -v /somepath/naemon_mnt:/data xetusoss/naemon:TAG

⁠(2) Jabber support with SSL

The command below will setup a container configured to speak to a Jabber server over SSL for notifications.

 docker run --name naemon -h naemon -d -p 80:80 \
  -e [email protected] \
  -e JABBER_PASS='secret' \
  -e JABBER_PORT=5223 \
  -v /somepath/naemon_mnt:/data xetusoss/naemon:TAG

Note, this will only define the configuration commands for jabber notifications - service checks still need to be configured to use it! See "Managing Naemon Configuration" below

⁠Managing Naemon Configuration

The Naemon configuration can be found under data volume at /data/etc/naemon/ and is intended to be managed either directly on the file system or via Thruk.

⁠Adding custom check or event handler scripts

It is recommended to add any custom scripts under the /data/ volume. By keeping customizations isolated to the /data/ volume, it makes swapping out the Naemon container a trivial task.

⁠Using the built-in Jabber support

When using the Jabber-related environment variables, notification commands are added to the Naemon configuration in the /data/etc/naemon/notify_jabber_commands.cfg. By default, there are two sets of commands which can be used for different scenarios, and their names are fairly intuitive.

1. notify-[host|service]-by-jabber-chatroom-ssl
2. notify-[host|service]-by-jabber-user-ssl
3. notify-[host|service]-by-jabber-chatroom
4. notify-[host|service]-by-jabber-user

Of course, these commands can't work without being used within a contact. Below is an example of a chatroom contact that will receive messages via the jabber:

define contact {
  contact_name                    sysadmins
  alias                           System Admins
  use                             generic-contact
  email                           [email protected]
  address1	                  [email protected]
  host_notification_commands      notify-host-by-jabber-chatroom-ssl
  service_notification_commands   notify-service-by-jabber-chatroom-ssl
}

⁠Change Log

⁠Version 1.0.6-1

• SSL support for the web interface has been removed. If SSL is needed to protect access to the interface, it's better to use an HTTP proxy such as HAProxy or NGINX.
• check_http_json.py has been added to the container plugin set
• The separation between initial setup and container configuration has been removed.

⁠Contributing

Contributions and feedback are welcome. Pull request and issues will be accepted via github.