Use HCL for configuration #26

Closed
opened 2 years ago by momar · 3 comments
momar commented 2 years ago
Owner

With HCL, the configuration could stay just as beautifully easy, but leaves more room for future features. The biggest advantage to YAML is that it doesn't have to be explained that much, mostly regarding stray dashes (whoops, it's a list suddenly!) and spaces/tabs.

With [HCL](https://github.com/hashicorp/hcl), the configuration could stay just as beautifully easy, but leaves more room for future features. The biggest advantage to YAML is that it doesn't have to be explained that much, mostly regarding stray dashes (whoops, it's a list suddenly!) and spaces/tabs.
momar added this to the v2 milestone 2 years ago
momar added the
backend
critical
labels 2 years ago
momar added the
feature
label 2 years ago
Poster
Owner

This is the current draft of the documentation that should be followed by the implementation:

Configuration Example

check "diskspace" {
  command = "check_disk -w 15% -c 5%"
  verify = 2
  interval = "6h"
}
group "test" {
  server "example.org" {
    name = "Example Server"
    connection = "ssh chihuahua@example.org -p 2222"
    check "test2" {
        name = "Check as root"
        command = "check_sudo check_disk -w 15% -c 5%"
    }
    # ...
  }
  server "whatever" {
    # ...
  }
}

server "blah" {
  # ...
}

notifications "email" {
    provider = "sendmail"
    to = "hello@example.org"
}
notifications "sms" {
    provider = "clockworksms"
    token = "123abc"
    to = "491517777777"
}

Configuration Blocks

A configuration block always looks somewhat like this (which would be an example block):

example "an-example-id" {
  someProperty = "A value of the property"
}

check block

A single check that will be run on its parent, which can be either a single server or a group of servers. It can also be specified at the top level, in which case all servers will run the check, unless it's being overwritten by a check with the same ID. Checks can have the following properties:

name

This property sets the name displayed on the status page (defaults to the check's ID).

command

This required property defines the command to run as the check. It must work like a Monitoring Plugin so Chihuahua can parse the output and exit code.

General Properties

Those properties can (additionally to checks) also be set directly on a server or group block (or at the top level), and affect all checks at that level and below in that case:

disable

If this is true, the check will not run and won't show up on the status page (defaults to false).

notify

An array of notifier IDs who should receive notifications for this check (defaults to all notifiers, or ["/"]).

verify

A positive integer number that sets how many times a state change must be confirmed before a notification is being sent (defaults to 1).

interval

How often the check should be executed, as a duration string parsable by Go's time library (defaults to "5m").

server block

A single server with a single remote, push or local connection.
It can occur at the top level or as a child of a group block. It can also contain the general properties for checks, additionally to the following server properties:

name

This property sets the name displayed on the status page (defaults to the check's ID).

connection

This required property is used to define the remote server those checks should run on.

  • connection = "local"
    Uses /bin/sh on the local machine to run checks.
  • connection = "ssh xyz@example.org -p 2222"
    Uses an SSH connection with the specified arguments.
  • connection = "push your-push-token"
    Use a Chihuahua Push service to receive results passively. If no new result comes through after two intervals, the status will be "unknown".

group block

A group of servers or other groups.
It can occcur at the top level or as a child of another group block. It can also contain the general properties for checks.

name

This property sets the name displayed on the status page (defaults to the check's ID).

notifier block

A notification channel like "database-admins" or "clients", or "email" or "sms". Available properties depend on the value of the type property:

type

Currently supported types are:

  • type = "sendmail"
  • type = "smtp"
  • type = "clockworksms"
  • type = "gotify"
  • type = "webhook"
  • type = "command"
  • type = "group"

Each type has different properties, which you can find listed below.

sendmail notifier

Uses a sendmail-compatible command to send email notifications.

Example:

notifier "email" {
  type = "sendmail"
  to = "mail@example.org"
}
from

Set the sender address for emails (default is set by sendmail).

to

Array of recipients (required).

binary

Name/path of the sendmail binary (defaults to sendmail).

smtp notifier

Uses an external SMTP server to send email notifications, or sends emails directly to the recipient's mailserver (the latter approach is unreliable though!).

Example:

notifier "email" {
  type = "smtp"
  from = "noreply@example.org"
  to = "mail@example.org"
  server = "abcd:abcd@smtp.postmarkapp.com"
}
from

Set the sender address for emails (required).

to

Array of recipients (required).

server

Connection string of the SMTP server (defaults to an empty string, which means to send email directly to the recipient's server). Example: username:password@smtp.example.org:25

encryption

Either "none", "ssl"/"tls" (equivalent) or "starttls". An empty string (which is the default) results in automatic detection with encryption being the preferred option.

insecure

Either true (to trust any certificate), false (to use the system's trust store) or a string to a certificate file to trust for this server.

clockworksms notifier

Send notifications via SMS using clockworksms.com.

Example:

notifier "sms" {
  type = "clockworksms"
  to = "491517777777"
  token = "aaaaa..."
}
to

Array of recipient's phone numbers, according to https://www.clockworksms.com/doc/easy-stuff/http-interface/send-sms/#to (required).

from

The sender displayed on the phone, according to https://www.clockworksms.com/doc/easy-stuff/http-interface/send-sms/#from.

token

The API key from https://app3.clockworksms.com/Keys (required).

gotify notifier

Use a gotify.net server to deliver notifications.

Example:

notifier "push" {
  type = "gotify"
  server = "https://gotify.example.org"
  token = "aaaaa..."
}
server

URL to the root endpoint of the Gotify serer to use (required).

token

The application token generated in the Gotify web interface (required).

webhook notifier

Calls a remote URL using a HTTP POST request with a JSON payload containing further information.

Example:

notifier "custom" {
  type = "webhook"
  url = "https://example.org/webhook"
}
url

The URL to send the request to (required).

JSON Payload

TODO

command notifier

Executes a shell command with the notification details specified in environment variables.

Example:

notifier "custom" {
  type = "command"
  command = "echo 'Hello World' && reboot"
}
command

The shell command to execute (required).

Environment variables

TODO

group notifier

A group notifier can be used to notify multiple people at once.

Example:

notifier "example" {
  notifier "mail1" {
    type = "sendmail"
    to = "admin@example.org"
  }
  notifier "mail2" {
    type = "sendmail"
    to = "ceo@example.org"
  }
}
notifier

Object that contains other notifiers, which can be used in the notify property of e.g. checks by using groupname/notifiername (in this case, example/mail2). Using just the groupname implies all notifiers in that group (hence, / implies every notifier specified in the config).

This is the current draft of the documentation that should be followed by the implementation: ## Configuration Example ```hcl check "diskspace" { command = "check_disk -w 15% -c 5%" verify = 2 interval = "6h" } group "test" { server "example.org" { name = "Example Server" connection = "ssh chihuahua@example.org -p 2222" check "test2" { name = "Check as root" command = "check_sudo check_disk -w 15% -c 5%" } # ... } server "whatever" { # ... } } server "blah" { # ... } notifications "email" { provider = "sendmail" to = "hello@example.org" } notifications "sms" { provider = "clockworksms" token = "123abc" to = "491517777777" } ``` ## Configuration Blocks A configuration block always looks somewhat like this (which would be an `example` block): ```hcl example "an-example-id" { someProperty = "A value of the property" } ``` ### `check` block A single check that will be run on its parent, which can be either a single [`server`]() or a [`group`]() of servers. It can also be specified at the top level, in which case all servers will run the check, unless it's being overwritten by a check with the same ID. Checks can have the following properties: #### `name` This property sets the name displayed on the status page (defaults to the check's ID). #### `command` This **required** property defines the command to run as the check. It must work like a [Monitoring Plugin]() so Chihuahua can parse the output and exit code. #### General Properties Those properties can (additionally to checks) also be set directly on a [`server`]() or [`group`]() block (or at the top level), and affect all checks at that level and below in that case: ##### `disable` If this is `true`, the check will not run and won't show up on the status page (defaults to `false`). ##### `notify` An array of notifier IDs who should receive notifications for this check (defaults to all notifiers, or `["/"]`). ##### `verify` A positive integer number that sets how many times a state change must be confirmed before a notification is being sent (defaults to `1`). ##### `interval` How often the check should be executed, as a duration string [parsable by Go's time library]() (defaults to `"5m"`). ### `server` block A single server with a single remote, push or local connection. It can occur at the top level or as a child of a [`group`]() block. It can also contain the [general properties]() for checks, additionally to the following server properties: #### `name` This property sets the name displayed on the status page (defaults to the check's ID). #### `connection` This **required** property is used to define the remote server those checks should run on. - `connection = "local"` Uses /bin/sh on the local machine to run checks. - `connection = "ssh xyz@example.org -p 2222"` Uses an SSH connection with the specified arguments. - `connection = "push your-push-token"` Use a [Chihuahua Push]() service to receive results passively. If no new result comes through after two intervals, the status will be "unknown". ### `group` block A group of servers or other groups. It can occcur at the top level or as a child of another `group` block. It can also contain the [general properties]() for checks. #### `name` This property sets the name displayed on the status page (defaults to the check's ID). ### `notifier` block A notification channel like "database-admins" or "clients", or "email" or "sms". Available properties depend on the value of the `type` property: #### `type` Currently supported types are: - `type = "sendmail"` - `type = "smtp"` - `type = "clockworksms"` - `type = "gotify"` - `type = "webhook"` - `type = "command"` - `type = "group"` Each type has different properties, which you can find listed below. #### `sendmail` notifier Uses a `sendmail`-compatible command to send email notifications. Example: ```hcl notifier "email" { type = "sendmail" to = "mail@example.org" } ``` ##### `from` Set the sender address for emails (default is set by sendmail). ##### `to` Array of recipients (required). ##### `binary` Name/path of the `sendmail` binary (defaults to `sendmail`). #### `smtp` notifier Uses an external SMTP server to send email notifications, or sends emails directly to the recipient's mailserver (the latter approach is unreliable though!). Example: ```hcl notifier "email" { type = "smtp" from = "noreply@example.org" to = "mail@example.org" server = "abcd:abcd@smtp.postmarkapp.com" } ``` ##### `from` Set the sender address for emails (required). ##### `to` Array of recipients (required). ##### `server` Connection string of the SMTP server (defaults to an empty string, which means to send email directly to the recipient's server). Example: `username:password@smtp.example.org:25` ##### `encryption` Either `"none"`, `"ssl"`/`"tls"` (equivalent) or `"starttls"`. An empty string (which is the default) results in automatic detection with encryption being the preferred option. ##### `insecure` Either `true` (to trust any certificate), `false` (to use the system's trust store) or a string to a certificate file to trust for this server. #### `clockworksms` notifier Send notifications via SMS using clockworksms.com. Example: ```hcl notifier "sms" { type = "clockworksms" to = "491517777777" token = "aaaaa..." } ``` ##### `to` Array of recipient's phone numbers, according to https://www.clockworksms.com/doc/easy-stuff/http-interface/send-sms/#to (required). ##### `from` The sender displayed on the phone, according to https://www.clockworksms.com/doc/easy-stuff/http-interface/send-sms/#from. ##### `token` The API key from https://app3.clockworksms.com/Keys (required). #### `gotify` notifier Use a gotify.net server to deliver notifications. Example: ```hcl notifier "push" { type = "gotify" server = "https://gotify.example.org" token = "aaaaa..." } ``` ##### `server` URL to the root endpoint of the Gotify serer to use (required). ##### `token` The application token generated in the Gotify web interface (required). #### `webhook` notifier Calls a remote URL using a HTTP POST request with a JSON payload containing further information. Example: ```hcl notifier "custom" { type = "webhook" url = "https://example.org/webhook" } ``` ##### `url` The URL to send the request to (required). ##### JSON Payload TODO #### `command` notifier Executes a shell command with the notification details specified in environment variables. Example: ```hcl notifier "custom" { type = "command" command = "echo 'Hello World' && reboot" } ``` ##### `command` The shell command to execute (required). ##### Environment variables TODO #### `group` notifier A group notifier can be used to notify multiple people at once. Example: ```hcl notifier "example" { notifier "mail1" { type = "sendmail" to = "admin@example.org" } notifier "mail2" { type = "sendmail" to = "ceo@example.org" } } ``` ##### `notifier` Object that contains other notifiers, which can be used in the `notify` property of e.g. checks by using `groupname/notifiername` (in this case, `example/mail2`). Using just the groupname implies all notifiers in that group (hence, `/` implies every notifier specified in the config).
Poster
Owner

This is working mostly as specified here in the feature-hcl branch.

What's left to do:

  • re-enable and adjust the actual checking and notification logic
  • implement notifiers
  • some code cleanup
This is working mostly as specified here in the feature-hcl branch. What's left to do: - [ ] re-enable and adjust the actual checking and notification logic - [ ] implement notifiers - [ ] some code cleanup
momar self-assigned this 2 years ago
momar added the
waiting-for-merge
label 2 years ago
Collaborator

Approved!

Approved!
zottelchin closed this issue 2 years ago
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.