nut-formula

Travis CI Build Status Semantic Release

A SaltStack formula to install and configure Network UPS Tools.

1. General notes

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

If you need (non-default) configuration, please pay attention to the pillar.example file and/or Special notes section.

2. Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute for more details.

3. Usage

NUT has server and client applications and packages are usually separated in those two categories, so the states reflect this situation:

  • <server> states are required to manage the packages that directly deal with the UPS (driver, nut-server, etc.)

  • <client> states are required to manage the packages that communicate with the nut-server (upsmon, upssched, etc.)

4. Special notes

Following NUT's configuration logic, when nut.mode: 'none', the .running states will do nothing and skip the services management. Therefore, they’ll be left as the OS packages set them.

5. Available states

For each of the components, there are meta-states named after the component that will include other states in the component subdir that perform the actual work.

For example, using server will include, in order:

  • server.package.install

  • server.config.mode

  • server.config.ups

  • server.config.upsd

  • server.config.users

  • server.service.running

You can use individual states, like

  • client.package.install

  • client.config.upsmon

5.1. nut

Meta-state (This is a state that includes other states).

This installs the nut server and client packages, manages the nut configuration files and then starts the associated nut services.

5.2. nut.<component>.package

This state will install the nut <component> packages only.

5.3. nut.<component>.config

This state will configure the nut <component> service/s and has a dependency on nut.<component>.package.install via include list.

5.4. nut.<component>.service

This state will start the nut <component> service/s and has a dependency on nut.<component>.config via include list.

5.5. nut.clean

Meta-state (This is a state that includes other states).

this state will undo everything performed in the nut meta-state in reverse order, i.e. stops the service, removes the configuration file and then uninstalls the packages.

5.6. nut.<component>.service.clean

This state will stop the nut <component> service/s and disables them at boot time.

5.7. nut.<component>.config.clean

This state will remove the configuration of the nut <component> service and has a dependency on nut.<component>.service.clean via include list.

5.8. nut.<component>.package.clean

This state will remove the nut <component> package/s and has a depency on nut.<component>.config.clean via include list.

5.9. nut.<component>

Meta-state (This is a state that includes other states).

This state installs, configures and manage a <component> and starts the associated services.

6. Testing

Linux testing is done with kitchen-salt.

6.1. Requirements

  • Ruby

  • Docker

$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

6.2. bin/kitchen converge

Creates the docker instance and runs the nut main state, ready for testing.

6.3. bin/kitchen verify

Runs the inspec tests on the actual instance.

6.4. bin/kitchen destroy

Removes the docker instance.

6.5. bin/kitchen test

Runs all of the stages above in one go: i.e. destroy + converge
verify + destroy.

6.6. bin/kitchen login

Gives you SSH access to the instance for manual testing.