The Configuration File

Location

The configuration file should be placed in the directory that is mapped to /config in the docker-compose or command line used to run NUTCase. To be found and used the configuration file should have the file name nutcase.yml or nutcase.yaml.

Valid sections

Section name	Purpose
rework	Sets a sequence of rules to generate new variables in the JSON output based on rework rules
webhooks	Defines a set of URLs which will be called under given conditions See WebHooks for details
settings	General settings which override the environment variables
servers	A list of servers & devices with specific settings

A simple example configuration file might be:

rework:
  - from: battery.runtime
    to: nutcase.battery.runtime
    style: time
    control: "%Mm %Ss"
settings:
  log_level: warning
webhooks:
  ok: http://X.X.X.X:3001/api/push/xxxxxxxxxxxx?status=up&msg=OK&ping=
  fail: http://X.X.X.X:3001/api/push/yyyyyyyyyyyy?status=down&msg=OK&ping=

Format

The format is YAML and consists of named sections that perform dedicated functions. The log file will tell you if there are errors in the configuration file when the app starts however, to check your YAML configuration before use I recommend the on-line YAML lint checker which will tell you if you configuration is properly formatted to the YAML standard.

1. The webhooks Section

The presence of this section is optional. If you don't use web hooks you can omit it.

Under webhooks comes a list of names. The name represents the purpose of the hook and for NUTCase valid names are: ok, fail & default

See WebHooks for an explanation of when each name is called.

Rules for calling

If a name is present it wall be called when the triggering event occurs. If the name is not present but the default hook is given then the default one will be called. If neither a named hook or the default are present then not action will be taken.

With this in mind, if you intend to use hooks then your configuration will probably look like one of these two examples:

webhooks:
  ok: http://X.X.X.X:3001/api/push/xxxxxxxxxxxx?status=up&msg=OK&ping=
  fail: http://X.X.X.X:3001/api/push/yyyyyyyyyyyy?status=down&msg=OK&ping=

In this example, any web hook which is triggered by an event will call the default URL.

webhooks:
  default: http://X.X.X.X:3001/api/push/xxxxxxxxxxxxx?status=up&msg=OK&ping=

Defining multiple hooks

If you have redundancy in your system with more than one monitoring instance you can define multiple web hooks per name. When a condition triggers web hook each URL on the list will be called in turn. Here is an example of how to give multiple URLs for any web hook name:

webhooks:
  ok:
    - http://X.X.X.X:3001/api/push/xxxxxxxxxxxx?status=up&msg=OK&ping=
    - http://Y.Y.Y.Y:3001/api/push/yyyyyyyyyyyy?status=up&msg=OK&ping=
  fail:
    - http://X.X.X.X:3001/api/push/aaaaaaaaaaaa?status=down&msg=OK&ping=
    - http://Y.Y.Y.Y:3001/api/push/bbbbbbbbbbbb?status=up&msg=OK&ping=

2. The settings Section

Entries in this section are optional but if a parameter is defined here then it overrides the corrosponding environment variable set on the Docker container.

Entry	Function	Options	Notes
log_level	Sets the level of detail in the log	DEBUGVV, DEBUGV, DEBUG, INFO, WARNING, ERROR, CRITICAL, FATAL	LOG_LEVEL
order_metrics	Print the metrics in a specific order	True False	ORDER_METRICS
coloured_log	Colour the log entries printed by the /log end point.	True False	COLOURED_LOG
default_log_lines	When the /log endpoint is called	Integer	DEFAULT_LOG_LINES
cache_period	The period (in seconds) after data is scraped from a server that it will be kept and sent should another request come from another end point or client. This mechanism reduces the impact on servers when Prometheus, Uptime Kuma and user GUI requests are all in play.	Integer	30 (seconds)
apc_strip_units	Numeric variables from an APC server often include the units after the value e.g. "LOADPCT"=" 32.7 Percent Load Capacity". When displaying these variables with HomePage this can look untidy. This option controls stripping the text to leave the numeric. E.g. "LOADPCT"="32.7"	Boolean	True
GUI Controls
ui_format_runtime	Specifies the format in which the runtime value is displayed. Any valid format from the Python strftime documentation will work.	String	"%-Hh %-Mm %Ss"

According to the YAML standard the following values are recognised as Boolean and are all case insensitive:

True	False
True, On and Yes	False, Off and No

An example settings section reiterating the default values would be:

settings:
  log_level: info
  order_metrics: True
  coloured_log: True
  default_log_lines: 20

All values are optional.

3. The servers Section

The servers section allows servers to be listed in the GUI Devices list as well as specifying server specific information.

The general format of this section is as follows:

servers:
  - server: "10.0.10.9"
    port: 3493
    default: true
    devices:
      - device: 'ups'
        power: 550
        displayname: 'Downstairs CyberPower'
  - server: "10.0.10.184"
    port: 3493
    devices:
      - device: 'SU600'
        mode: 'apc'
        power: 600
        displayname: 'Upstairs Eaton'

Each server has an entry which must include server, port and device. If a server is hosting more that one UPS device then there must be one entry for each device with the same server address. This is necessary to support login credentials. The optional entries are listed below.

Entry	Function	Options	Notes
server	Sets address of the NUT or APC server	IPv4
port	Sets port of the NUT or APC server	IPv4
displayname	Sets a friendly name that will be displayed on the GUI Devices menu.	String
device	Sets name of the UPS to which these settings belong	IPv4
mode	Specify whether this server is NUT or APC (apcupsd)	String 'apc' or 'nut'	'nut'
default	Add this to only one entry to mark it as the default to use when the root end point, / is called with not addr parameter.	Boolean	False
username	Specify a user name when the NUT server requires authentication to scrape data. For most systems this is not required.	String
password	Specify a password when the NUT server requires authentication to scrape data. For most systems this is not required.	String
power	Specify a figure for the device power in Watts. Many UPS devices do not send the ups.realpower.nominal or ups.power.nominal variables. This means that real power values can not be displayed on the GUI. If this affects your system, specifying power here will allow this data to be displayed.	Integer

4. The rework section

The rework section and it is used to specify the rework on the variables, see Reworking variables

The file should have a list of the rework operations in a section labelled rework. Each rework directive has a number of fields that control which variables from the UPS are used what happens to make a new variable.

rework:
  - from: .....
    to: .....
    style: .....
    control: .....
  - from: .....
    to: .....
    style: .....
    control: .....

Details of what reworking options are available are listed in Reworking variables