Datum Networks Driver



Presented at the Workshop on Synchronization in Telecommunication Systems (WSTS) in 2012, this paper provides insight into the drivers for synchronization in the network, the ongoing migration from traditional to packet based networks and how evolving core, edge, and wireless networks drive the need for frequency and phase synchronization. Insyde Software is leading worldwide provider of UEFI firmware systems management (BMC firmware) solutions, and custom engineering services for companies in the mobile, desktop, server, embedded and IoT (Internet-of-Things) computing industries.

NUT is an uninterruptible power supply (UPS) monitoring system that allows the sharing of one (or more) UPS systems between several computers. It has a 'server' component, which monitors the UPS status and notifies a 'client' component when the UPS has a low battery. There can be multiple computers running the client component and each can be configured to shut down cleanly in a power failure (before the UPS batteries run out of charge).

Monitor a direct-local connected UPS

After installing the NUT Package there are six example configuration files in /etc/nut/.
Connect to your IPFire system using ssh as root.

Device Driver

Identify your UPS in the NUT Hardware Compatibility List.

Then configure the ups.conf file. For a UPS connected directly with USB it should look like this:

filename = ups.conf

In this example the [apc-1500] is the name of the UPS which will be referred to later. So it is best to keep your alias simple.

The desc is a short description which you can skip.

Optional Settings

Configure these if your UPS sets the Low Battery flag too early or calculates run time in an odd way.

ignorelb

When you specify this, the driver ignores a low battery condition flag that is reported by the UPS (some devices will switch off almost immediately after setting this flag, or will report this as soon as the mains fails). Instead it will use either of the following conditions to determine when the battery is low:

The idea is to set the battery.charge.low and/or battery.runtime.low levels in ups.conf to a value that gives enough time to cleanly shutdown your system:

In order for this to work, your UPS should be able to (reliably) report charge and/or runtime remaining on battery. Use with caution!

Datum networks driver app

Optional. Set a default value for which is used in case the UPS doesn't provide a value, but will be overwritten if a value is available from the UPS:

The above will report the nominal input voltage to be 230, unless the UPS tells us differently.

Optional. Set a value for that overrides any value that may be read from the UPS. Used for overriding values from the UPS that are clearly wrong (some devices report wrong values for battery voltage for instance):

Use with caution! This will only change the appearance of the variable to the outside world, internally in the UPS the original value is used.

All other fields are passed through to the hardware-specific part of the driver. See those manuals (FIXME add a link to NUT documentation here) for the list of what is allowed.

Now we should be able to start only the device module of NUT and talk to the UPS
upsdrvctl start
And it should respond with the following output:

This tells us that NUT was able to launch the USB driver and found a UPS with this driver.

Next configure the daemon which collects data from the UPS and provides it to a local monitor daemon and/or to daemon from the network.

Daemon Config

The daemon is configured in upsd.conf

filename = upsd.conf

In this example 192.168.10.1 is the IP-Address of the green interface. You can skip the port number 3493 as it is the default port.

To configure NUT in a standalone configuration only these lines are required as IPFire only uses IPv4.

A user account must be configured to connect with to the daemon. there for we use the upsd.users file.

filename = upsd.users

[admin] is the username, for rest please check out the NUT manpage (FIXME add link to man page here).

Now start the NUT daemon:
upsd{bash}

and read the status of our UPS with this command:

upsc apc-1500@localhost{bash}

we will get something like this (localhost can be skipped):

Datum Networks Driver Download

if you want only the value of one single line (for scripting, see later) just add the name of the value to the command, like this:
upsc apc-1500@localhost battery.charge{bash} will return 100

Next configure the NUT monitor daemon who will monitoring the UPS and trigger the system shutdown if desired.

Datum networks driver download

Monitor deamon config

The deamon monitor will be configured with upsmon.conf:

I will here only explain some important option to get the whole picture please take a look in the example config file.

RUN_AS_USER root for more security you may want to create a new user under which NUT will run, but this user must have access to the USB or SERIAL device, read-only access to the config file and so on.

Or we run NUT as root, since NUT can shutdown the System anyway.

If you skip this NUT will run as user NOBODY which as no access to read the config file (config file access chown comes later down).

MONITOR apc-1500@localhost 1 admin xxxx master very important here you setup which UPS NUT should monitoring, also use the right username and password form the upsd.users file.

SHUTDOWNCMD '/sbin/shutdown -h +0' this command will be triggered if UPS sends the BL (Battery Low) flag.

NOTIFYCMD /usr/sbin/upssched only needet if you will follow this how-to to the end and want to use additional notifiying.

POLLFREQ 2 how often it will call the deamon to update the monitor status, for a local unit 1-2 second is fine, for network 5-10 should be ok (depends of how much net traffic you want have).

POLLFREQALERT 1 same as above but will only be used if the monitor knows that the UPS is on battery, so it may be lower than our default pollferquence so we keep in touch with the UPS (important for network monitoring, you wont miss the FSD flag from master).

HOSTSYNC 15 delay which the master will wait till all the slave hosts have pulled an update (if the master system shuts down).

DEADTIME 15 time the monitor keep an UPS state to be vaild and before it set it to stale if the monitor loss connection with that UPS. (If the UPS was on battery and the deadtime runs out [no update] the monitor will trigger immediately the FSD flag (Force ShutDown) and start the shutdown sequence)

POWERDOWNFLAG /etc/killpower todo if missing will display a note form init script on system shutdown

format of the massages that the monitor can send to wall, syslog or script:

here you select what kind of actions the monitor will take if he notice an event, if you following this how-to you can keep this settings. For basic UPS monitoring just remove the +EXEC

NOCOMMWARNTIME 600 will repeat the trigger NOCOMM every 600 seconds

The system will now shutdown when the UPS runtime or battery charge false below the low value!

which is by APC as default very far down the road, so we will set this parameter to a higher value to keep some reserves in the UPS

upsrw apc-1500@localhost{bash}

will list all aviable varibles you can set in your UPS

so we will set the parameter for minimum runtime to 15 min and the minimum charge to 40%

Datum Networks Driver Jobs

after each command it will ask for the username and passwort from our deamon user config upsd.users

If your UPS does not support this you may check out the value override guide in the device driver section

Schedule Config (Optional)

the NUT schedule module is basically a timer/trigger customized for the notify events of NUT

I stored the upssched-cmd file also in the /etc/nut/ folder so it will be included in the IP-Fire backup

in this file you just set up witch timer will be started at which event.

So AT ONBATT * START-TIMER onbatt 300 will start the timeronbatt with 5 min if any (*) of the UPS will paste the ONBATT event to upssched (which we configured in the upsmon.confnotifycmd=... and the flags with the +EXEC) if the timer reach zero it will execute onbatt in the upssched-cmd bash script

AT ONLINE * CANCEL-TIMER onbatt online this will cancel the timeronbatt the event ONLINE get paste, if the timer has already be running out (or timer has not run) the command online in the bash script will be executed

well and AT SHUTDOWN * EXECUTE powerdown will directly EXECUTE the script powerdown

Schedule CMD file

For this script you will need the sendmail addon (sendEmail configuration) and maybe some bash scripting knowledge :)

This script will just send an Email with the UPS Status depending on the event

the '&' at the and of the sendmail command is mandatory upssched will only wait a few ms for the end of the script but sendmail may take up to 3-5 seconds to send the mail, so upssched will try to hit the trigger again and will also only wait a few ms till it get a return code so in the end it will send 3-5 emails instant of only one. With the & the sendmail command will be send to background and the script returns immediately the error 0 and all are happy :)

Config NUT Mode

Finally we will set the startup mode for NUT tostandalone in the nut.conf file:

User rights (chmod)

for all files in /etc/nut/ user-rights must be set to

except the upssched-cmd needs

chmod 0:740 /etc/nut/upssched-cmd{bash}

Now NUT with all sub modules can be started with /etc/init.d/nut start

The init scripts are already shipped with the packed so no further action has to be taken to autostart NUT on system boot.

To see NUT as running in the service tap of the WGI we do a restart of the system or use
/etc/init.d/nut force-reload{bash}

to only restart NUT

Plug-in for SysInfo script

Datum Networks Driver

Here is a quickplug-in for the sysinfo script (System Status via eMail)

for the head-part:

for the body-part:

filename = sysinfo.sh

Datum Networks Driver Updater

Monitor a network UPS

There Driver and Daemon Part is not needed to monitor a network UPS,
you only need to change the Monitor entry in the upsmon.conf to

MONITOR apc-1500@192.168.1.1 1 username password slave

instead of localhost enter the IP of the device where the UPS is connected and NUT is running, and use the right username and password form the upsd.users file on that device.

Also you have to change the mode in the nut.conf to

MODE=netclient

this way NUT will only start the monitor and if you configured the Schedule module

What happen on Power Events

http://www.networkupstools.org/docs/user-manual.chunked/ar01s06.html#Shutdown_design
Here are the steps that occur when a critical power event happens:

  1. The UPS goes on battery

  2. The UPS reaches low battery (a 'critical' UPS), that is to say upsc displays:

ups.status: OB LB

The exact behavior depends on the specific device, and is related to:

Datum Networks Driver Download

  1. The upsmon master notices and sets 'FSD' - the 'forced shutdown' flag to tell all slave systems that it will soon power down the load.
    (If you have no slaves, skip to step 6)

  2. upsmon slave systems see 'FSD' and:

  1. The upsmon master system waits up to HOSTSYNC seconds (typically 15) for the slaves to disconnect from upsd. If any are connected after this time, upsmon stops waiting and proceeds with the shutdown process.

  2. The upsmon master:

Datum Networks Driver App

  1. On most systems, init takes over, kills your processes, syncs and unmounts some filesystems, and remounts some read-only.

  2. init then runs your shutdown script. This checks for the POWERDOWNFLAG, finds it, and tells the UPS driver(s) to power off the load.

  3. The system loses power.

  4. Time passes. The power returns, and the UPS switches back on.

  5. All systems reboot and go back to work.





Comments are closed.