Difference between revisions of "Uninterruptable Power Supply"

From SME Server
Jump to navigationJump to search
m
 
(93 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 
{{Languages}}
 
{{Languages}}
 +
{{usefulnote}}
  
−
==Introduction==
+
==Uninterruptable Power Supply==
 +
 
 +
{{Level|Advanced}}
 +
 
 +
===Introduction===
 
The primary goal of the Network UPS Tools (NUT) project is to provide reliable monitoring of UPS hardware and ensure safe shutdowns of the systems which are connected.  
 
The primary goal of the Network UPS Tools (NUT) project is to provide reliable monitoring of UPS hardware and ensure safe shutdowns of the systems which are connected.  
  
 
The default configuration of NUT, will keep your connected systems operational until a critical battery state is reached (ie battery is nearing exhaustion) and then power down your server/equipment in a controlled fashion. See http://www.networkupstools.org/
 
The default configuration of NUT, will keep your connected systems operational until a critical battery state is reached (ie battery is nearing exhaustion) and then power down your server/equipment in a controlled fashion. See http://www.networkupstools.org/
  
−
==Default Configuration (USB)==
+
If you have an APC UPS, see also [[Uninterruptable_Power_Supply:APC]] for an alternative to the standard SME ''Nut'' implementation
−
The default configuration in SME Server as set by the database properties for 'nut' is
+
 
−
  Model = usbhid-ups
+
If you have Dell UPS, this might Help [[Uninterruptable_Power_Supply:LatestGeekery]]
 +
 
 +
===Default Configuration (USB)===
 +
The default configuration in SME Server for 'NUT' is set by the configuration database properties
 +
  Model = usbhid-ups
 
  status = disabled
 
  status = disabled
−
  type = service
+
  type   = service
 
{{Note box|Absence of a 'Master' property setting defaults the configuration to being a Master setup. That is a UPS connected directly to the server via USB or serial cable is assumed. See later for setting as a Slave.
 
{{Note box|Absence of a 'Master' property setting defaults the configuration to being a Master setup. That is a UPS connected directly to the server via USB or serial cable is assumed. See later for setting as a Slave.
  
−
The default is for nut to be disabled, that is no UPS connected}}
+
The default is for NUT to be disabled, that is no UPS connected}}
 +
 
 +
Most USB connected UPS's will work with these default settings. If using a USB connection just enable NUT as follows:
  
−
Most USB connected UPS's will work with these default settings. If using a USB connection just enable nut as follows:
+
<tabs container>
 +
<tab name="SME 10">
 +
For '''SME 10''', systemd is now in use. We have created a generic service for your convenience:
  
 +
config setprop nut status enabled
 +
signal-event e-smith-nutUPS-update
 +
systemctl restart nut-server.service
 +
systemctl restart nut-monitor.service
 +
systemctl restart nut.service
 +
</tab>
 +
<tab name="SME 9 and earlier">
 
  config setprop nut status enabled
 
  config setprop nut status enabled
 
  signal-event post-upgrade
 
  signal-event post-upgrade
 
  signal-event reboot
 
  signal-event reboot
  
 +
</tab>
 +
</tabs>
 
If your USB UPS does not work properly OR you have a '''serial device''' then follow the Configuration Options below as required.
 
If your USB UPS does not work properly OR you have a '''serial device''' then follow the Configuration Options below as required.
  
−
==Configuration Options==
+
===Configuration Options===
  
 
Not all UPS's are supported by USB or the usbhid-ups driver. However NUT supports many UPS's and can be configured under SME Server easily.
 
Not all UPS's are supported by USB or the usbhid-ups driver. However NUT supports many UPS's and can be configured under SME Server easily.
  
−
===Serial Connection===
+
====Serial Connection====
  
−
<ol></li><li>Find the configuration details for your model of UPS. Refer to:  http://www.networkupstools.org/compat/stable.html and make note of the driver name and upstype number (if any) in the third column.  
+
<ol><li>Find the configuration details for your model of UPS. Refer to:  http://www.networkupstools.org/stable-hcl.html and make note of the driver name and upstype number (if any) in the third column.  
  
 
{{Warning box|Always use the serial cable supplied with the UPS.  Standard serial cables won't work with a serial UPS and have been known to cause damage to the UPS. Pay particular attention to any references to cable in in the UPS Model column.}}
 
{{Warning box|Always use the serial cable supplied with the UPS.  Standard serial cables won't work with a serial UPS and have been known to cause damage to the UPS. Pay particular attention to any references to cable in in the UPS Model column.}}
  
−
</li><li>From the consol issue the following commands:
+
</li><li>From the console issue the following commands:
−
 
 
 
  config setprop nut Model <model>  
 
  config setprop nut Model <model>  
 
  config setprop nut Device <device>
 
  config setprop nut Device <device>
Line 55: Line 76:
 
Alternatively, '''without''' NUT running or requiring a server reboot:
 
Alternatively, '''without''' NUT running or requiring a server reboot:
  
−
  expand-template /etc/sysconfig/ups
+
  signal-event console-save
−
expand-template /etc/ups/ups.conf
+
  service nut start
−
expand-template /etc/ups/upssched.conf
 
−
expand-template /etc/ups/upsmon.conf
 
−
expand-template /etc/ups/upsd.users
 
−
expand-template /etc/ups/upsd.conf
 
−
  /etc/rc7.d/S38nut start
 
  
 
</li><li>Confirm server is communicating with UPS:
 
</li><li>Confirm server is communicating with UPS:
Line 69: Line 85:
 
</li></ol>
 
</li></ol>
  
−
===Configuring as a slave===
+
====Configuring as a master====
 +
edit the file /etc/ups/nut.conf, and modify the line
 +
MODE=netserver
 +
 
 +
Set configuration values:
 +
config setprop nut access private TCPPort 3493
 +
expand-template /etc/ups/upsd.conf
 +
expand-template /etc/rc.d/init.d/masq
 +
systemctl restart masq
 +
systemctl restart nut-server
 +
 
 +
====Configuring as a slave====
 
Set configuration values:
 
Set configuration values:
 
  config setprop nut SlaveUPS UPS@192.168.33.11
 
  config setprop nut SlaveUPS UPS@192.168.33.11
Line 79: Line 106:
 
  signal-event post-upgrade
 
  signal-event post-upgrade
 
  signal-event reboot  
 
  signal-event reboot  
 +
 +
or (for SME10):
 +
signal-event e-smith-nutUPS-update
  
 
Confirm server is communicating with master:
 
Confirm server is communicating with master:
 
  upsc UPS@192.168.33.11
 
  upsc UPS@192.168.33.11
  
−
===Conecting multiple UPS's===
+
====Connecting multiple UPS's====
−
To be added http://bugs.contribs.org/show_bug.cgi?id=629
+
As reference to http://bugs.contribs.org/show_bug.cgi?id=629 and https://bugs.koozali.org/show_bug.cgi?id=626#c2
 +
 
 +
1- you will need to do<syntaxhighlight lang="bash">
 +
mkdir -p /etc/e-smith/templates-custom/ups/ups.conf/
 +
cp /etc/e-smith/templates/ups/ups.conf/UPS /etc/e-smith/templates-custom/ups/ups.conf/UPS2
 +
</syntaxhighlight>then edit content to replace the header to UPS2 and Model and Device to Model2 and Device2
 +
 
 +
 
 +
2- Then you need to do<syntaxhighlight lang="bash">
 +
mkdir -p /etc/e-smith/templates-custom/ups/upsmon.conf/
 +
cp /etc/e-smith/templates/ups/upsmon.conf/MONITOR /etc/e-smith/templates-custom/ups/ups.conf/MONITOR2
 +
</syntaxhighlight>Then edit it to change UPS to UPS2.  Then you set Device2 and Model2.
  
−
==UPS Variables and Commands==
+
 
 +
 
 +
3- Repeat the steps 1 and 2 for as many UPS you have, then finish by<syntaxhighlight lang="bash">
 +
signal-event console-save
 +
</syntaxhighlight>
 +
 
 +
===UPS Variables and Commands===
 
In some cases you may wish to modify variables on the actual UPS such as the Low Charge/LOWBATTERY setting. This requires the use of the '''upsrw''' command and UPS administrative privileges.
 
In some cases you may wish to modify variables on the actual UPS such as the Low Charge/LOWBATTERY setting. This requires the use of the '''upsrw''' command and UPS administrative privileges.
  
Line 92: Line 139:
 
{{Warning box|In general, the UPS data should be left protected and changes to it or issuing of commands well thought out. If you wish to make data changes or issue commands then the administrative privileges can be enabled as below and should then be disabled.}}
 
{{Warning box|In general, the UPS data should be left protected and changes to it or issuing of commands well thought out. If you wish to make data changes or issue commands then the administrative privileges can be enabled as below and should then be disabled.}}
  
−
===UPS Administrative Privileges===
+
====UPS Administrative Privileges====
 +
<tabs container>
 +
<tab name="SME 10">
 +
You should check your new password ( AdminPass ) to run '''upsrw''' & '''upscmd'''. Of course, you could change your password for a easier one to use.
 +
 
 +
config show nut
 +
 
 +
To set new admin password in database. The new password would be admin ( change it to suit your need )
 +
 
 +
config setprop nut AdminPass admin
 +
 
 +
To enabled administrative privileges and run command to ups.
 +
 
 +
config setprop nut AdminUser enabled
 +
 
 +
Now, to get '''upsd''' to recognise admin modification for administrative privileges we expand the template and reload the '''upsd''' configuration
 +
 
 +
/sbin/e-smith/expand-template /etc/ups/upsd.users
 +
/usr/sbin/upsd -c reload
 +
 
 +
{{Note box|To disabled the administrative privileges once you have changed the UPS parameters or issued commands as required, issue the commands
 +
config setprop nut AdminUser disabled
 +
/sbin/e-smith/expand-template /etc/ups/upsd.users
 +
/usr/sbin/upsd -c reload
 +
}}
 +
 
 +
</tab>
 +
<tab name="SME 9">
 +
 
 +
{{Warning box|Be sure to have e-smith-nutUPS-2.4.0-9.el6.sme.noarch or higher to carry on with these instructions. If you get a lower version, just follow SME8 instruction.}}
 +
 
 +
rpm -qa e-smith-nutUPS
 +
 
 +
If you get NUT running with administrative privileges modification from sme8 instruction, you need to remove the custom template created for this. These variables are taken in charge by the new package.
 +
 
 +
First you need to delete the custom template file.( This command delete the directory, be sure you don't have personal file present. If the case, delete manualy the file created for administrative privileges )
 +
 +
rm -rf /etc/e-smith/templates-custom/etc/ups/upsd.users
 +
 
 +
Now, to get '''upsd''' to recognise the modification of user, we need to expand the template and reload the '''upsd''' configuration
 +
 +
/sbin/e-smith/expand-template /etc/ups/upsd.users
 +
/usr/sbin/upsd -c reload
 +
 
 +
 
 +
 
 +
You should check your new password ( AdminPass ) to run '''upsrw''' & '''upscmd'''. Of course, you could change your password for a easier one to use.
 +
 
 +
config show nut
 +
 
 +
To set new admin password in database. The new password would be admin ( change it to suit your need )
 +
 
 +
config setprop nut AdminPass admin
 +
 
 +
To enabled administrative privileges and run command to ups.
 +
 
 +
config setprop nut AdminUser enabled
 +
 
 +
Now, to get '''upsd''' to recognise admin modification for administrative privileges we expand the template and reload the '''upsd''' configuration
 +
 
 +
/sbin/e-smith/expand-template /etc/ups/upsd.users
 +
/usr/sbin/upsd -c reload
 +
 
 +
{{Note box|To disabled the administrative privileges once you have changed the UPS parameters or issued commands as required, issue the commands
 +
config setprop nut AdminUser disabled
 +
/sbin/e-smith/expand-template /etc/ups/upsd.users
 +
/usr/sbin/upsd -c reload
 +
}}
 +
 
 +
</tab>
 +
<tab name="SME 8">
 
In order to be able to use '''upsrw''' and '''upscmd''' it is necessary to have a suitable additional user defined in the '''upsd.users''' configuration file.  
 
In order to be able to use '''upsrw''' and '''upscmd''' it is necessary to have a suitable additional user defined in the '''upsd.users''' configuration file.  
  
−
In order to create a suitable user we will use SME Servers templating system and configuration database.
+
In order to create a suitable user we will use SME Servers templating system and configuration database. This is based on an original forum thread[http://forums.contribs.org/index.php?topic=40668.0].
  
−
First we need to create a suitable template fragment
+
First we need to create a suitable custom template directory
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upsd.users
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upsd.users
 
  cd /etc/e-smith/templates-custom/etc/ups/upsd.users
 
  cd /etc/e-smith/templates-custom/etc/ups/upsd.users
  
−
Create and edit a new file called 'admin'
+
Create and edit a new file called 'admin' with the following content:
 
  {
 
  {
 
     # create admin user for upsd to allow setting of
 
     # create admin user for upsd to allow setting of
Line 108: Line 225:
 
     $OUT .= "";
 
     $OUT .= "";
 
     return unless (($nut{AdminUser} || 'disabled') eq 'enabled');
 
     return unless (($nut{AdminUser} || 'disabled') eq 'enabled');
−
     return unless (($nut{AdminPass} || '') ne '');
+
     return unless (($nut{AdminPass} || <nowiki>''</nowiki>) ne <nowiki>''</nowiki>);
 
   
 
   
 
     $OUT .= "\n";
 
     $OUT .= "\n";
Line 135: Line 252:
 
  /usr/sbin/upsd -c reload
 
  /usr/sbin/upsd -c reload
 
}}
 
}}
 +
</tab>
 +
</tabs>
  
−
===Setting UPS Variables===
+
==== UPS access ====
−
In order to set UPS variables it is necessary to have enabled a user with administrative privileges as above first.
+
The access of the ups is controled by database properties. The default propertie is set to localhost and give permission to run '''upsrw''' & '''upscmd''' from localhost only if administrative privileges is set to enabled as above. No slave ups could be connected in this mode. Three choices is available to set access.
  
−
In the examples below, it is assumed your UPS name is '''UPS''', that it is local, that the administrative user is '''admin'' and password '''admin'''. You can verify your UPS name via:
+
 
 +
* localhost: the ups access is only from the local machine ( UPS master ).
 +
 
 +
* private: the ups access is from your local machine and local network as per define in server-manager panel.
 +
 
 +
* public: the ups access is similar to localhost.
 +
 
 +
 
 +
To set access properties in the database ( example: localhost )
 +
 
 +
config setprop nut access localhost 
 +
/sbin/e-smith/expand-template /etc/ups/upsd.conf
 +
  /usr/sbin/upsd -c reload
 +
 
 +
In localhost or public mode ( no remote access ), access to your ups is ( UPS name is '''UPS''' )
 +
UPS@localhost
 +
 
 +
In private mode,  access to your ups is ( UPS name is '''UPS''' )
 +
UPS@localhost or UPS@192.168.1.1 ( ups master IP )
 +
slave ups get access with UPS@192.168.1.1 ( ups master IP )
 +
 
 +
 
 +
====Setting UPS Variables====
 +
In order to set UPS variables it is necessary to have enabled the administrative privileges as above first and you get the possibility to run command from slave ups if access is set to private as above.
 +
 
 +
In the examples below, it is assumed your UPS name is '''UPS''', that it is local, that the administrative user is '''admin''' and password '''admin'''. You can verify your UPS name via:
 
  upsc -l
 
  upsc -l
  
−
To view a complete list of the UPS variables
+
To view a complete list of the UPS variables, both informational and modifiable
 
  upsc UPS
 
  upsc UPS
  
−
To determine the modifiable variables for your UPS execute the command:
+
To determine the modifiable variables for your UPS, their current settings and their available setting values execute the command:
 
  upsrw UPS
 
  upsrw UPS
  
−
You can now modify the variables you wish using a command similar to:
+
You can now modify the variables you wish using a command similar to the following (Note the order of the arguments is important, and you may need quotes around the value being set, "20"):
 
  upsrw -s battery.charge.low=20 -u admin -p admin UPS
 
  upsrw -s battery.charge.low=20 -u admin -p admin UPS
 +
 +
For remote host (slave UPS ), we need to add the IP from master UPS to run command.
 +
upsrw -s battery.charge.low=20 -u admin -p admin UPS@192.168.2.1
  
 
Where the value after '''-s''' should be one of the parameters identified by the '''upsrw ups''' command. You can of course verify your changes using     
 
Where the value after '''-s''' should be one of the parameters identified by the '''upsrw ups''' command. You can of course verify your changes using     
Line 156: Line 303:
 
  upsc UPS
 
  upsc UPS
  
−
After you are done, clean up by disabling the '''upsd''' administrative user '''admin''':
+
After you are done, clean up by disabling the '''upsc''' administrative privileges:
−
 
+
{{Warning box|Make sure you understand the meaning or the UPS variables and their available setting options. Verify that your changes meet your intended behaviour!}}
−
{{Warning box|Verify that your changes meet your intended behaviour!}}
 
  
 
More information on upsrw can be found at:
 
More information on upsrw can be found at:
Line 164: Line 310:
 
- Manual page: man upsrw
 
- Manual page: man upsrw
  
−
- Upsrw examples: [http://opensource.mgeups.com/howto.htm]
+
=====Changing battery date=====
 +
An example to update you battery date upon changing it. (use your own password)<syntaxhighlight lang="bash">
 +
upsrw -s  battery.mfr.date=2020/08/31 -u admin -p admin UPS
 +
</syntaxhighlight>
 +
 
 +
====Issuing UPS Commands====
 +
In order to issue UPS commands it is necessary to have enabled the administrative privileges as above first and you get the possibility to run command from slave ups if access is set to private as above.
 +
 
 +
In the examples below, it is assumed your UPS name is '''UPS''', that it is local, that the administrative user is '''admin''' and password '''admin'''. You can verify your UPS name via:
 +
upsc -l
 +
 
 +
To view a complete list of available commands for your UPS:
 +
upscmd -l UPS
 +
 
 +
You can now issue a command to the localhost UPS with similar to the following:
 +
upscmd -u admin -p admin UPS test.battery.start
 +
 
 +
For remote host (slave UPS ), we need to add the IP from master UPS to run command.
 +
upscmd -u admin -p admin UPS@192.168.2.1 test.battery.start
 +
 
 +
Where the command '''test.battery.start''' is a valid command for your UPS as previously determined by '''upscmd -l UPS'''. Depending upon the command issued you may get broadcast messages and emails relating to and confirming what the UPS is doing.
 +
 
 +
After you are done, clean up by disabling the '''upsc''' administrative privileges.
 +
{{Warning box|Before issuing any commands verify what they do for your particular UPS via the relevant documentation and ensure that the command meets your intended behavioural requirement!
 +
 
 +
Issuing commands could shutdown your server unexpectedly!}}
  
−
==Modifying shutdown time delay==
+
=Scheduling Events=
 +
====Shutdown Time Delay Example====
  
−
The following changes to NUT configuration will shut down the server a specified time after receiving the "on battery" signal (the example given is for 2 minutes).
+
By default NUT will issue a shutdown command as soon as it receives a low battery event from the UPS. There may be instances and installation configurations that require a shutdown sooner, or other events with timed or schedules outcomes. See the '''man''' pages etc for further info and example situations.
  
−
To create a timed shutdown before the BATTLOW signal is received, it is necessary to configure upssched and have a script handle the UPS events (upsmon cannot do this).
+
In essence the '''upsmon''' program monitors the relevant UPS and for each '''NOTIFYFLAG''' event in '''upsmon.conf''' takes immediate action as defined. In order to delay or schedule any actions, the events need to be passed to '''upssched''' which can set timers and schedule events.
−
config setprop nut status enabled
+
 
−
config setprop nut Model megatec_usb
+
The following changes to standard SME Server NUT configuration will shut down the server a specified time after receiving the "on battery" signal (the example given is for 2 minutes). It assumes you already have an enabled and working NUT configuration and UPS
−
config setprop nut Type auto
 
  
−
Create and edit a custom template
+
To create a timed shutdown before the '''BATTLOW''' signal is received, it is necessary to configure '''upssched''' and have a script handle the UPS events ('''upsmon''' cannot do this).
 +
 +
First we need to create a new custom template directory:
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upsmon.conf
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upsmon.conf
−
  pico -w /etc/e-smith/templates-custom/etc/ups/upsmon.conf/NOTIFYCMD
+
  cd /etc/e-smith/templates-custom/etc/ups/upsmon.conf
  
−
Add the following:
+
Create and edit a new file called 'NOTIFYCMD' with the following content:
 
  NOTIFYCMD /usr/sbin/upssched
 
  NOTIFYCMD /usr/sbin/upssched
  
−
Save & exit
+
Expand the template:
−
  Ctrl o
+
  /sbin/e-smith/expand-template /etc/ups/upsmon.conf
−
Ctrl x
 
  
−
Create and edit a custom template
+
Now create another a custom template directory
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upssched.conf
 
  mkdir -p /etc/e-smith/templates-custom/etc/ups/upssched.conf
−
  pico -w /etc/e-smith/templates-custom/etc/ups/upssched.conf/01CONFIG
+
  cd /etc/e-smith/templates-custom/etc/ups/upssched.conf
  
−
Add the following:
+
Create and edit a new file called '01CONFIG' with the following content:
 
  CMDSCRIPT /sbin/e-smith/nutUPS.cmd
 
  CMDSCRIPT /sbin/e-smith/nutUPS.cmd
 
  PIPEFN /tmp/upspipe
 
  PIPEFN /tmp/upspipe
Line 207: Line 379:
 
to how many seconds after ONBATT signal you want to shut down
 
to how many seconds after ONBATT signal you want to shut down
  
−
Save & exit
+
Expand the template:
−
  Ctrl o
+
  /sbin/e-smith/expand-template /etc/ups/upssched.conf
−
Ctrl x
 
  
−
Create the script
+
Create and edit a new script file at:
−
  pico -w /sbin/e-smith/nutUPS.cmd
+
  /sbin/e-smith/nutUPS.cmd
  
−
Add the following:
+
Add the following content:
  
 
  #! /bin/sh
 
  #! /bin/sh
Line 253: Line 424:
 
         esac
 
         esac
  
 +
Now make it executable by '''nut''' user
 +
chmod 754 /sbin/e-smith/nutUPS.cmd
 +
chown root:nut /sbin/e-smith/nutUPS.cmd
 +
 +
Nut requires to use sudo for this process to work, so sudo needs configuring to enable the user nut. By default the /etc/sudoers file is not part of the SME Server template system. To workaround this create a custom template directory:
 +
mkdir -p /etc/e-smith/templates-custom/etc/sudoers
 +
cd /etc/e-smith/templates-custom/etc/sudoers
  
−
Create a custom template
+
To preserve the content of the original /etc/sudoers file copy that into the custom template directory:
−
  mkdir -p /etc/e-smith/templates-custom/etc/sudoers/30nut
+
  cp /etc/sudoers 10sudoers
  
−
Add the following
+
Create and edit a new file called '30nut' with the following content:
 
  nut  ALL=NOPASSWD: ALL
 
  nut  ALL=NOPASSWD: ALL
  
−
To complete the process
+
Then run:
 +
/sbin/e-smith/expand-template /etc/sudoers
 +
 
 +
Finally to complete the process:
 
  signal-event post-upgrade
 
  signal-event post-upgrade
 
  signal-event reboot
 
  signal-event reboot
  
 +
While testing with the SMEServer v9.1 (circa March 2016), the above <tt>nutUPS.cmd</tt> script with entries in <tt>01CONFIG</tt> template fails due to lack of permissions at the <tt>shutdownnow</tt> case at:
 +
/usr/bin/sudo /sbin/e-smith/signal-event halt
 +
 +
Tweaking the <tt>/etc/sudoers</tt> did not mitigate it.
 +
 +
The error in the <tt>/var/log/messages</tt> is:
 +
<pre>
 +
Mar 14 13:22:16 svr01 upssched[3507]: Timer daemon started
 +
Mar 14 13:22:16 svr01 upssched[3507]: New timer: shutdownnow (120 seconds)
 +
Mar 14 13:25:16 svr01 upssched[3507]: Event: shutdownnow
 +
Mar 14 13:25:16 svr01 wall[3539]: wall: user nut broadcasted 1 lines (70 chars)
 +
Mar 14 13:25:16 svr01 upssched[3507]: exec_cmd(/sbin/e-smith/nutUPS.cmd shutdownnow) returned 1
 +
</pre>
 +
 +
However, the '''nut''' user has the necessary shutdown permissions:
 +
/usr/bin/sudo -u nut /usr/bin/sudo /sbin/e-smith/signal-event halt
 +
 +
=Configure Nut-cgi Monitor Scripts=
 +
 +
The nut-cgi rpm contains scripts that can be run via the webserver to monitor the UPS(s).
 +
 +
===Download and install===
 +
<tabs container><tab name="For SME 10">
 +
You have to enable the epel repository:
 +
yum install smeserver-extrarepositories-epel -y
 +
 +
then install nut-cgi:
 +
yum install --enablerepo=epel nut-cgi
 +
 +
then configure it the SME way:
 +
Edit file /etc/ups/hosts.conf and add.
 +
mkdir -p /etc/e-smith/templates-custom/etc/ups/hosts.conf
 +
echo 'MONITOR UPS@localhost "local UPS"' >/etc/e-smith/templates-custom/etc/ups/hosts.conf/10localhost
 +
expand-template /etc/ups/hosts.conf
 +
 +
Httpd template
 +
 +
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
 +
Now edit and create a new file 92nutupscmon with the following content
 +
 +
{
 +
    $OUT = "";
 +
    my $allow = 'all';
 +
    my $pass = '0';
 +
    my $satisfy = 'all';
 +
    my $name = $nut{'Name'} || 'NUT UPS Daemon Monitoring';
 +
    my $PublicAccess = $nut{'PublicAccess'} || "local";
 +
 +
    for ('exit-if-none')
 +
    {
 +
      if ($PublicAccess eq 'none')
 +
          {
 +
            next;
 +
          }
 +
      elsif ($PublicAccess eq 'local')
 +
          {
 +
            $allow  = "ip $localAccess";
 +
            $pass    = 0;
 +
            $satisfy = 'All';
 +
          }
 +
      elsif ($PublicAccess eq 'local-pw')
 +
          {
 +
            $allow  = "ip $localAccess";
 +
            $pass    = 1;
 +
            $satisfy = 'All';
 +
          }
 +
      elsif ($PublicAccess eq 'global')
 +
          {
 +
            $allow  = 'all granted';
 +
            $pass    = 0;
 +
            $satisfy = 'All';
 +
          }
 +
      elsif ($PublicAccess eq 'global-pw')
 +
          {
 +
            $allow  = 'all granted';
 +
            $pass    = 1;
 +
            $satisfy = 'All';
 +
          }
 +
      elsif ($PublicAccess eq 'global-pw-remote')
 +
          {
 +
            $allow  = "ip $localAccess";
 +
            $pass    = 1;
 +
            $satisfy = 'Any';
 +
          }
 +
 
 +
      $OUT .= "#------------------------------------------------------------\n";
 +
      $OUT .= "# nut multimon - $name\n";
 +
      $OUT .= "#------------------------------------------------------------\n";
 +
 +
      {
 +
        if ((exists $nut{'URL'}) && ($nut{'URL'} ne <nowiki>''</nowiki>)) {
 +
          $OUT .= "Alias  /$nut{'URL'}  /var/www/nut-cgi-bin\n";
 +
        } 
 +
      }
 +
 +
      $OUT .= "Alias  /nut  /var/www/nut-cgi-bin\n";
 +
 +
      $OUT .= "\n";
 +
      $OUT .= "<Directory /var/www/nut-cgi-bin>\n";
 +
      $OUT .= "    DirectoryIndex upsstats.cgi\n";
 +
      $OUT .= "    Options +ExecCGI\n";
 +
      $OUT .= "    <Require$satisfy>\n" if ($pass);
 +
      $OUT .= "    Require $allow\n";
 +
      if ($pass)
 +
      {
 +
          $OUT .= "    AuthName $name\n";
 +
          $OUT .= "    AuthType Basic\n";
 +
          $OUT .= "    AuthExternal pwauth\n";
 +
          $OUT .= "    require valid-user\n";
 +
          $OUT .= "    </Require$satisfy>\n";
 +
      }
 +
      $OUT .= "</Directory>\n";
 +
    }
 +
}
 +
 +
Configure databases and expand the template
 +
 +
config setprop nut PublicAccess local
 +
/sbin/e-smith/expand-template /etc/httpd/conf/httpd.conf
 +
 +
{{Note box|The above sets access to the scripts to ''local'' ip addresses only. See the [[Web_Application_RPM#New_DB_settings]] for further info and settings}}
 +
 +
Restart the web server
 +
 +
systemctl restart httpd-e-smith
 +
 +
</tab><tab name="For SME 9  and before">
 +
You have to enable the '''[[epel]]''' repositories.
 +
yum install --enablerepo=epel nut-cgi
  
−
==Aditional Information==
+
Edit file /etc/ups/hosts.conf and add.
  
−
There are template fragments in /etc/e-smith/templates/etc/ups that control the config files located in /etc/ups. The default settings should be OK for most situations.
+
MONITOR UPS@localhost "local UPS"
  
−
An example of doing this can be found in the forum: http://forums.contribs.org/index.php?topic=40668.0
+
The nut-cgi rpm contains three cgi scripts. The rpm does not install them correctly for SME however so the following modifications are needed.
 +
 
 +
mkdir -p /opt/nut-cgi-bin
 +
chown root:www /opt/nut-cgi-bin
 +
mv /var/www/nut-cgi-bin/upsstats.cgi /opt/nut-cgi-bin
 +
mv /var/www/nut-cgi-bin/upsset.cgi /opt/nut-cgi-bin
 +
mv /var/www/nut-cgi-bin/upsimage.cgi /opt/nut-cgi-bin
 +
chown root:www /opt/nut-cgi-bin/*
 +
chmod 750 /opt/nut-cgi-bin/*
 +
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
 
 +
Now edit and create a new file 92nutupscmon with the following content
 +
 
 +
{
 +
    $OUT = "";
 +
    my $allow = 'all granted';
 +
    my $pass = '0';
 +
    my $satisfy = 'All';
 +
    my $name = $nut{'Name'} || 'NUT UPS Daemon Monitoring';
 +
 
 +
    for ('exit-if-none')
 +
    {
 +
      if ($nut{'PublicAccess'})
 +
      {
 +
          if ($nut{'PublicAccess'} eq 'none')
 +
          {
 +
            next;
 +
          }
 +
          elsif ($nut{'PublicAccess'} eq 'local')
 +
          {
 +
            $allow  = $localAccess;
 +
            $pass    = 0;
 +
            $satisfy = 'all';
 +
          }
 +
          elsif ($nut{'PublicAccess'} eq 'local-pw')
 +
          {
 +
            $allow  = $localAccess;
 +
            $pass    = 1;
 +
            $satisfy = 'all';
 +
          }
 +
          elsif ($nut{'PublicAccess'} eq 'global')
 +
          {
 +
            $allow  = 'all';
 +
            $pass    = 0;
 +
            $satisfy = 'all';
 +
          }
 +
          elsif ($nut{'PublicAccess'} eq 'global-pw')
 +
          {
 +
            $allow  = 'all';
 +
            $pass    = 1;
 +
            $satisfy = 'all';
 +
          }
 +
          elsif ($nut{'PublicAccess'} eq 'global-pw-remote')
 +
          {
 +
            $allow  = $localAccess;
 +
            $pass    = 1;
 +
            $satisfy = 'any';
 +
          }
 +
      }
 +
 +
      $OUT .= "#------------------------------------------------------------\n";
 +
      $OUT .= "# nut multimon - $name\n";
 +
      $OUT .= "#------------------------------------------------------------\n";
 +
 +
      {
 +
        if ((exists $nut{'URL'}) && ($nut{'URL'} ne <nowiki>''</nowiki>)) {
 +
          $OUT .= "Alias  /$nut{'URL'}  /opt/nut-cgi-bin\n";
 +
        } 
 +
      }
 +
 +
      $OUT .= "Alias  /nut  /opt/nut-cgi-bin\n";
 +
 +
      $OUT .= "\n";
 +
      $OUT .= "<Directory /opt/nut-cgi-bin>\n";
 +
      $OUT .= "    DirectoryIndex upsstats.cgi\n";
 +
      $OUT .= "    Options +ExecCGI\n";
 +
      $OUT .= "    order deny,allow\n";
 +
      $OUT .= "    deny from all\n";
 +
      $OUT .= "    allow from $allow\n";
 +
      if ($pass)
 +
      {
 +
          $OUT .= "    AuthName $name\n";
 +
          $OUT .= "    AuthType Basic\n";
 +
          $OUT .= "    AuthExternal pwauth\n";
 +
          $OUT .= "    require valid-user\n";
 +
          $OUT .= "    Satisfy $satisfy\n";
 +
      }
 +
      $OUT .= "</Directory>\n";
 +
    }
 +
}
 +
 
 +
Configure databases and expand the template
 +
 
 +
config setprop nut PublicAccess local
 +
/sbin/e-smith/expand-template /etc/httpd/conf/httpd.conf
 +
 
 +
{{Note box|The above sets access to the scripts to ''local'' ip addresses only. See the [[Web_Application_RPM#New_DB_settings]] for further info and settings}}
 +
 
 +
Restart the web server
 +
 
 +
sv t httpd-e-smith
 +
</tab>
 +
</tabs>
 +
 
 +
===Usage of Nut-cgi Scripts===
 +
 
 +
Now go to http://yourdomain.tld/nut to see the statistics and information for the UPS at localhost.
 +
 
 +
By editing <tt>/etc/ups/hosts.conf</tt> and adding additional network UPS details, nut-cgi can be used to monitor more than one UPS. By the modification above, only the localhost is monitored.
 +
 
 +
=Additional Information=
 +
 
 +
There are template fragments in /etc/e-smith/templates/etc/ups that control the config files located in /etc/ups. The default settings should be OK for most situations. The <tt>/etc/nut.conf</tt> file must be manually edited like <tt>mode=standalone</tt> as the templates do not touch this file. In this case it would be:
 +
sed -e 's/^MODE.*/MODE=standalone/' -i /etc/ups/nut.conf
 +
 
 +
By default, NUT is configured for a USB connected UPS in Master mode, but is disabled. When enabled, NUT will monitor the UPS and take various actions when certain notifications are received. This is controlled by the '''/etc/ups/upsmon.conf''' file which among other things lists the notifications and the actions to be taken for each. For example an ''On Battery'' event is captured by the '''NOTIFYFLAG ONBATT''' entry and the following '''SYSLOG+WALL+EXEC''' command string. This string tells '''upsmon''' to write the event to the System Log, broadcast a message to all users via Wall, and execute the command denoted by the '''NOTIFYCMD''' entry.
 +
 
 +
SME Server sets the '''NOTIFYCMD''' to '''/sbin/e-smith/nutUPS.notify''', and this executable file simply sends an email to the SME admin user with a notification of the event.
 +
 
 +
Apart from the various events that the UPS and '''upsmon''' may notify via the '''NOTIFYFLAGS''' a ''Low Battery'' event will automatically and immediately cause '''upsmon''' to issue the '''SHUTDOWNCMD''' as defined in '''upsmon.conf''' (signal-event halt) and set a flag '''POWERDOWNFLAG''' so it knows on future restart that it is a UPS recovery.
  
 
For information on configuration parameters:
 
For information on configuration parameters:
Line 282: Line 714:
 
  man nutupsdrv
 
  man nutupsdrv
  
−
The NUT website is here
+
==Timeout Issues==
 +
 
 +
If you have comms problems like this you can add a custom timeout:
 +
 
 +
"USBDEVFS_CONTROL failed cmd blazer_usb rqt 33 rq 9 len 8 ret -110"
  
−
http://www.networkupstools.org/
+
Add a new config item. The default is 2
  
−
From that website you can glean which configuration setting does what function
+
config setprop nut pollInterval 4
  
−
Then modify the NUT config file, by creating a custom template, expanding template and restarting service
+
Modify the template
  
 +
mkdir -p /etc/e-smith/templates-custom/etc/ups/ups.conf
 +
cp /etc/e-smith/templates/etc/ups/ups.conf/UPS /etc/e-smith/templates-custom/etc/ups/ups.conf/UPS
 +
nano /etc/e-smith/templates-custom/etc/ups/ups.conf/UPS
 +
 +
Add the bits between the # comments
 +
 +
{
 +
    my $model = $nut{Model} || "usbhid-ups";
 +
    my $device = $nut{Device} || "/var/lib/ups/hiddev0";
 +
    my $type = $nut{Type};
 +
    my $mfr = $nut{mfr};
 +
    my $mdl = $nut{mdl};
 +
 +
    # Add this
 +
    my $poll = $nut{pollInterval} || '2';
 +
    if ($poll ne '2') {
 +
      $OUT .= "pollinterval = $poll\n";
 +
    }
 +
    # ends here
 +
 +
    $OUT .= "[UPS]\n";
 +
    $OUT .= "\tdriver = $model\n";
 +
 +
expand-template /etc/ups/ups.conf
 +
cat /etc/ups/ups.conf
 +
 +
You should see something like this:
 +
 +
# Copyright (C) 1999-2006 Mitel Networks Corporation
 +
#------------------------------------------------------------
 +
pollinterval = 4
 +
[UPS]
 +
 +
Restart nut
 +
 +
service nut restart
 +
 +
Now check to see the correct timeout:
 +
 +
upsc UPS | grep driver.parameter.pollinterval
 +
 +
driver.parameter.pollinterval: 4
 +
 +
To reset either delete the key, or set it to the default of 2
 +
 +
==Further reading==
 +
 +
The NUT website is here: [http://www.networkupstools.org/ NUT]
 +
 +
From the above references you can glean which configuration setting does what function, etc.
 +
 +
If you want to modify the operation of NUT from the standard configuration, then you should generally modify the NUT config files by creating custom templates, expanding the templates and restarting service. This will ensure modifications survive a future reboot or reconfiguration.
 +
 +
An example of doing this can be found in the forum [http://forums.contribs.org/index.php?topic=40668.0] and in the section above for UPS Administrative Privileges
 +
 +
See also [[KnownProblems#Restarting_NUT| Known Problem - Restarting Nut]]
 
----
 
----
−
<noinclude>[[Category:Howto]]</noinclude>
+
 
 +
===Documentation===
 +
 
 +
Nut is a Software well documented, you can find the [http://www.networkupstools.org/docs/user-manual.chunked/index.html TOC here] and with [http://www.networkupstools.org/docs/user-manual.chunked/ar01s02.html an overview]
 +
<noinclude>
 +
[[Category:Howto]]
 +
</noinclude>
 +
<noinclude>
 +
[[Category:Administration]]
 +
</noinclude>
 +
__FORCETOC__

Latest revision as of 21:06, 14 February 2024

Geographylogo.png Languages: 

English  • Deutsch  • français


Is this article helpful to you?
Please consider donating or volunteering
Thank you!

Uninterruptable Power Supply

PythonIcon.png Skill level: Advanced
The instructions on this page may require deviations from standard procedures. A good understanding of linux and Koozali SME Server is recommended.


Introduction

The primary goal of the Network UPS Tools (NUT) project is to provide reliable monitoring of UPS hardware and ensure safe shutdowns of the systems which are connected.

The default configuration of NUT, will keep your connected systems operational until a critical battery state is reached (ie battery is nearing exhaustion) and then power down your server/equipment in a controlled fashion. See http://www.networkupstools.org/

If you have an APC UPS, see also Uninterruptable_Power_Supply:APC for an alternative to the standard SME Nut implementation

If you have Dell UPS, this might Help Uninterruptable_Power_Supply:LatestGeekery

Default Configuration (USB)

The default configuration in SME Server for 'NUT' is set by the configuration database properties 

Model  = usbhid-ups
status = disabled
type   = service
Important.png Note:
Absence of a 'Master' property setting defaults the configuration to being a Master setup. That is a UPS connected directly to the server via USB or serial cable is assumed. See later for setting as a Slave.

The default is for NUT to be disabled, that is no UPS connected


Most USB connected UPS's will work with these default settings. If using a USB connection just enable NUT as follows:

For SME 10, systemd is now in use. We have created a generic service for your convenience: 

config setprop nut status enabled
signal-event e-smith-nutUPS-update
systemctl restart nut-server.service
systemctl restart nut-monitor.service
systemctl restart nut.service

config setprop nut status enabled
signal-event post-upgrade
signal-event reboot

If your USB UPS does not work properly OR you have a serial device then follow the Configuration Options below as required.

Configuration Options

Not all UPS's are supported by USB or the usbhid-ups driver. However NUT supports many UPS's and can be configured under SME Server easily.

Serial Connection

  1. Find the configuration details for your model of UPS. Refer to: http://www.networkupstools.org/stable-hcl.html and make note of the driver name and upstype number (if any) in the third column.
    Warning.png Warning:
    Always use the serial cable supplied with the UPS. Standard serial cables won't work with a serial UPS and have been known to cause damage to the UPS. Pay particular attention to any references to cable in in the UPS Model column.

  2. From the console issue the following commands: config setprop nut Model <model> config setprop nut Device <device> config setprop nut Type <type> config setprop nut status enabled Where:
    <model> and <type> are the driver name and type number found above.
    <device> is the serial port that the UPS is connected to eg. /dev/ttyS0. It also possible to use a more readable symlink. See HowTo on udev - symlinks for details. Note: The case of Model, Device and Type.
  3. Check: config show nut
  4. Apply changes and restart server: signal-event post-upgrade signal-event reboot Alternatively, without NUT running or requiring a server reboot: signal-event console-save service nut start
  5. Confirm server is communicating with UPS: upsc UPS@localhost Whenever a UPS event occurs Emails are sent to the admin account.

Configuring as a master

edit the file /etc/ups/nut.conf, and modify the line 

MODE=netserver

Set configuration values: 

config setprop nut access private TCPPort 3493 
expand-template /etc/ups/upsd.conf
expand-template /etc/rc.d/init.d/masq
systemctl restart masq
systemctl restart nut-server

Configuring as a slave

Set configuration values: 

config setprop nut SlaveUPS UPS@192.168.33.11
config setprop nut Master no

Where 192.168.33.11 is your UPS master, that is the computer that is in direct communication with the UPS. The hostname of that computer may also work.

Apply changes and restart server: 

signal-event post-upgrade
signal-event reboot

or (for SME10): 

signal-event e-smith-nutUPS-update

Confirm server is communicating with master: 

upsc UPS@192.168.33.11

Connecting multiple UPS's

As reference to http://bugs.contribs.org/show_bug.cgi?id=629 and https://bugs.koozali.org/show_bug.cgi?id=626#c2

1- you will need to do

mkdir -p /etc/e-smith/templates-custom/ups/ups.conf/
cp /etc/e-smith/templates/ups/ups.conf/UPS /etc/e-smith/templates-custom/ups/ups.conf/UPS2

then edit content to replace the header to UPS2 and Model and Device to Model2 and Device2


2- Then you need to do

mkdir -p /etc/e-smith/templates-custom/ups/upsmon.conf/
cp /etc/e-smith/templates/ups/upsmon.conf/MONITOR /etc/e-smith/templates-custom/ups/ups.conf/MONITOR2

Then edit it to change UPS to UPS2. Then you set Device2 and Model2.


3- Repeat the steps 1 and 2 for as many UPS you have, then finish by

signal-event console-save

UPS Variables and Commands

In some cases you may wish to modify variables on the actual UPS such as the Low Charge/LOWBATTERY setting. This requires the use of the upsrw command and UPS administrative privileges.

You may also want to control the UPS directly from the command line by issuing UPS commands. This requires use of the upscmd command and UPS administrative privileges.

Warning.png Warning:
In general, the UPS data should be left protected and changes to it or issuing of commands well thought out. If you wish to make data changes or issue commands then the administrative privileges can be enabled as below and should then be disabled.


UPS Administrative Privileges

You should check your new password ( AdminPass ) to run upsrw & upscmd. Of course, you could change your password for a easier one to use. 

config show nut

To set new admin password in database. The new password would be admin ( change it to suit your need ) 

config setprop nut AdminPass admin

To enabled administrative privileges and run command to ups. 

config setprop nut AdminUser enabled

Now, to get upsd to recognise admin modification for administrative privileges we expand the template and reload the upsd configuration 

/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload


Important.png Note:
To disabled the administrative privileges once you have changed the UPS parameters or issued commands as required, issue the commands 
config setprop nut AdminUser disabled
/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload


Warning.png Warning:
Be sure to have e-smith-nutUPS-2.4.0-9.el6.sme.noarch or higher to carry on with these instructions. If you get a lower version, just follow SME8 instruction. 

rpm -qa e-smith-nutUPS

If you get NUT running with administrative privileges modification from sme8 instruction, you need to remove the custom template created for this. These variables are taken in charge by the new package.

First you need to delete the custom template file.( This command delete the directory, be sure you don't have personal file present. If the case, delete manualy the file created for administrative privileges ) 

rm -rf /etc/e-smith/templates-custom/etc/ups/upsd.users

Now, to get upsd to recognise the modification of user, we need to expand the template and reload the upsd configuration 

/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload


You should check your new password ( AdminPass ) to run upsrw & upscmd. Of course, you could change your password for a easier one to use. 

config show nut

To set new admin password in database. The new password would be admin ( change it to suit your need ) 

config setprop nut AdminPass admin

To enabled administrative privileges and run command to ups. 

config setprop nut AdminUser enabled

Now, to get upsd to recognise admin modification for administrative privileges we expand the template and reload the upsd configuration 

/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload


Important.png Note:
To disabled the administrative privileges once you have changed the UPS parameters or issued commands as required, issue the commands 
config setprop nut AdminUser disabled
/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload

In order to be able to use upsrw and upscmd it is necessary to have a suitable additional user defined in the upsd.users configuration file.

In order to create a suitable user we will use SME Servers templating system and configuration database. This is based on an original forum thread[1].

First we need to create a suitable custom template directory 

mkdir -p /etc/e-smith/templates-custom/etc/ups/upsd.users
cd /etc/e-smith/templates-custom/etc/ups/upsd.users

Create and edit a new file called 'admin' with the following content: 

{
    # create admin user for upsd to allow setting of
    # UPS parameters via upsrw

    $OUT .= "";
    return unless (($nut{AdminUser} || 'disabled') eq 'enabled');
    return unless (($nut{AdminPass} || '') ne '');

    $OUT .= "\n";
    $OUT .= "       [admin]\n";
    $OUT .= "               password  = $nut{AdminPass}\n";
    if ( ($nut{Master} || 'yes') ne 'no') {
       $OUT .= "               allowfrom = localhost\n";
    } else {
       $OUT .= "               allowfrom = localhost localnet\n";
    }
    $OUT .= "               actions   = set\n";
    $OUT .= "               instcmds  = all\n";
}

Create two new database properties for nut 

config setprop nut AdminUser enabled                (This enables the creation of the user in the template above)
config setprop nut AdminPass admin                  (This sets a password for the admin user. Set to whatever you want)

Now, to get upsd to recognise the new user with the required administrative privileges we expand the template and reload the upsd configuration 

/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload


Important.png Note:
To disabled the admin user once you have changed the UPS parameters or issued commands as required, issue the commands 
config setprop nut AdminUser disabled
/sbin/e-smith/expand-template /etc/ups/upsd.users
/usr/sbin/upsd -c reload

UPS access

The access of the ups is controled by database properties. The default propertie is set to localhost and give permission to run upsrw & upscmd from localhost only if administrative privileges is set to enabled as above. No slave ups could be connected in this mode. Three choices is available to set access.


  • localhost: the ups access is only from the local machine ( UPS master ).
  • private: the ups access is from your local machine and local network as per define in server-manager panel.
  • public: the ups access is similar to localhost.


To set access properties in the database ( example: localhost ) 

config setprop nut access localhost  
/sbin/e-smith/expand-template /etc/ups/upsd.conf
 /usr/sbin/upsd -c reload

In localhost or public mode ( no remote access ), access to your ups is ( UPS name is UPS ) 

UPS@localhost

In private mode, access to your ups is ( UPS name is UPS ) 

UPS@localhost or UPS@192.168.1.1 ( ups master IP )
slave ups get access with UPS@192.168.1.1 ( ups master IP )


Setting UPS Variables

In order to set UPS variables it is necessary to have enabled the administrative privileges as above first and you get the possibility to run command from slave ups if access is set to private as above.

In the examples below, it is assumed your UPS name is UPS, that it is local, that the administrative user is admin and password admin. You can verify your UPS name via: 

upsc -l

To view a complete list of the UPS variables, both informational and modifiable 

upsc UPS

To determine the modifiable variables for your UPS, their current settings and their available setting values execute the command: 

upsrw UPS

You can now modify the variables you wish using a command similar to the following (Note the order of the arguments is important, and you may need quotes around the value being set, "20"): 

upsrw -s battery.charge.low=20 -u admin -p admin UPS

For remote host (slave UPS ), we need to add the IP from master UPS to run command. 

upsrw -s battery.charge.low=20 -u admin -p admin UPS@192.168.2.1

Where the value after -s should be one of the parameters identified by the upsrw ups command. You can of course verify your changes using 

upsrw UPS

or 

upsc UPS

After you are done, clean up by disabling the upsc administrative privileges:

Warning.png Warning:
Make sure you understand the meaning or the UPS variables and their available setting options. Verify that your changes meet your intended behaviour!


More information on upsrw can be found at:

- Manual page: man upsrw

Changing battery date

An example to update you battery date upon changing it. (use your own password)

upsrw -s  battery.mfr.date=2020/08/31 -u admin -p admin UPS

Issuing UPS Commands

In order to issue UPS commands it is necessary to have enabled the administrative privileges as above first and you get the possibility to run command from slave ups if access is set to private as above.

In the examples below, it is assumed your UPS name is UPS, that it is local, that the administrative user is admin and password admin. You can verify your UPS name via: 

upsc -l

To view a complete list of available commands for your UPS: 

upscmd -l UPS

You can now issue a command to the localhost UPS with similar to the following: 

upscmd -u admin -p admin UPS test.battery.start

For remote host (slave UPS ), we need to add the IP from master UPS to run command. 

upscmd -u admin -p admin UPS@192.168.2.1 test.battery.start

Where the command test.battery.start is a valid command for your UPS as previously determined by upscmd -l UPS. Depending upon the command issued you may get broadcast messages and emails relating to and confirming what the UPS is doing.

After you are done, clean up by disabling the upsc administrative privileges.

Warning.png Warning:
Before issuing any commands verify what they do for your particular UPS via the relevant documentation and ensure that the command meets your intended behavioural requirement!

Issuing commands could shutdown your server unexpectedly!


Scheduling Events

Shutdown Time Delay Example

By default NUT will issue a shutdown command as soon as it receives a low battery event from the UPS. There may be instances and installation configurations that require a shutdown sooner, or other events with timed or schedules outcomes. See the man pages etc for further info and example situations.

In essence the upsmon program monitors the relevant UPS and for each NOTIFYFLAG event in upsmon.conf takes immediate action as defined. In order to delay or schedule any actions, the events need to be passed to upssched which can set timers and schedule events.

The following changes to standard SME Server NUT configuration will shut down the server a specified time after receiving the "on battery" signal (the example given is for 2 minutes). It assumes you already have an enabled and working NUT configuration and UPS

To create a timed shutdown before the BATTLOW signal is received, it is necessary to configure upssched and have a script handle the UPS events (upsmon cannot do this).

First we need to create a new custom template directory: 

mkdir -p /etc/e-smith/templates-custom/etc/ups/upsmon.conf
cd /etc/e-smith/templates-custom/etc/ups/upsmon.conf

Create and edit a new file called 'NOTIFYCMD' with the following content: 

NOTIFYCMD /usr/sbin/upssched

Expand the template: 

/sbin/e-smith/expand-template /etc/ups/upsmon.conf

Now create another a custom template directory 

mkdir -p /etc/e-smith/templates-custom/etc/ups/upssched.conf
cd /etc/e-smith/templates-custom/etc/ups/upssched.conf

Create and edit a new file called '01CONFIG' with the following content: 

CMDSCRIPT /sbin/e-smith/nutUPS.cmd
PIPEFN /tmp/upspipe
LOCKFN /tmp/upslock
AT COMMBAD * EXECUTE commbad
AT COMMOK * EXECUTE commok
AT NOCOMM * EXECUTE nocomm
AT ONBATT * EXECUTE powerout
AT ONBATT * START-TIMER shutdownnow 120     
AT LOWBATT * EXECUTE shutdowncritical
AT ONLINE * CANCEL-TIMER shutdownnow
AT ONLINE * EXECUTE powerup

In the above set the line AT ONBATT * START-TIMER shutdownnow 120 to how many seconds after ONBATT signal you want to shut down

Expand the template: 

/sbin/e-smith/expand-template /etc/ups/upssched.conf

Create and edit a new script file at: 

/sbin/e-smith/nutUPS.cmd

Add the following content: 

#! /bin/sh
       case $1 in
               commbad)
                       /bin/echo "UPS communications failure on `date`." | /bin/mail -s"UPS communications LOST" admin
                       /usr/bin/wall "UPS communications failure."
                       ;;
               commok)
                       /bin/echo "UPS communications restored on `date`." | /bin/mail -s"UPS communications restored" admin
                       /usr/bin/wall "UPS communications restored."
                       ;;
               nocomm)
                       /bin/echo "UPS communications cannot be established on `date`." | /bin/mail -s"UPS uncontactable" admin
                       /usr/bin/wall "UPS communications cannot be established."
                       ;;
               powerout)
                       /bin/echo "Power failure on `date`." | /bin/mail -s"UPS on battery" admin
                       /usr/bin/wall "UPS on battery. Shutdown in 60 seconds...."
                       ;;
               shutdownnow)
                       /bin/echo "UPS has been on battery for 60 seconds. Starting orderly shutdown on `date`." | /bin/mail -s"UPS on battery for 60 seconds" admin
                       /usr/bin/wall "UPS has been on battery for 60 seconds. Shutting down NOW!!!!"
                       /usr/bin/sudo /sbin/e-smith/signal-event halt
                       ;;
               shutdowncritical)
                       /bin/echo "UPS battery level CRITICAL. Starting EMERGENCY shutdown on `date`." | /bin/mail -s"UPS battery CRITICAL" admin
                       /usr/bin/wall "UPS battery level CRITICAL. Shutting down NOW!!!!"
                       /usr/bin/sudo /sbin/e-smith/signal-event halt
                       ;;
               powerup)
                       /bin/echo "Power restored on `date`." | /bin/mail -s"UPS on line" admin
                       /usr/bin/wall "UPS on line. Shutdown aborted."
                       ;;
               *)
                       /bin/echo "Unrecognized command: $1"
                       ;;
       esac

Now make it executable by nut user 

chmod 754 /sbin/e-smith/nutUPS.cmd
chown root:nut /sbin/e-smith/nutUPS.cmd

Nut requires to use sudo for this process to work, so sudo needs configuring to enable the user nut. By default the /etc/sudoers file is not part of the SME Server template system. To workaround this create a custom template directory: 

mkdir -p /etc/e-smith/templates-custom/etc/sudoers
cd /etc/e-smith/templates-custom/etc/sudoers

To preserve the content of the original /etc/sudoers file copy that into the custom template directory: 

cp /etc/sudoers 10sudoers

Create and edit a new file called '30nut' with the following content: 

nut   ALL=NOPASSWD: ALL

Then run: 

/sbin/e-smith/expand-template /etc/sudoers

Finally to complete the process: 

signal-event post-upgrade
signal-event reboot

While testing with the SMEServer v9.1 (circa March 2016), the above nutUPS.cmd script with entries in 01CONFIG template fails due to lack of permissions at the shutdownnow case at: 

/usr/bin/sudo /sbin/e-smith/signal-event halt

Tweaking the /etc/sudoers did not mitigate it.

The error in the /var/log/messages is: 

Mar 14 13:22:16 svr01 upssched[3507]: Timer daemon started
Mar 14 13:22:16 svr01 upssched[3507]: New timer: shutdownnow (120 seconds)
Mar 14 13:25:16 svr01 upssched[3507]: Event: shutdownnow
Mar 14 13:25:16 svr01 wall[3539]: wall: user nut broadcasted 1 lines (70 chars)
Mar 14 13:25:16 svr01 upssched[3507]: exec_cmd(/sbin/e-smith/nutUPS.cmd shutdownnow) returned 1

However, the nut user has the necessary shutdown permissions: 

/usr/bin/sudo -u nut /usr/bin/sudo /sbin/e-smith/signal-event halt

Configure Nut-cgi Monitor Scripts

The nut-cgi rpm contains scripts that can be run via the webserver to monitor the UPS(s).

Download and install

You have to enable the epel repository: 

yum install smeserver-extrarepositories-epel -y

then install nut-cgi: 

yum install --enablerepo=epel nut-cgi

then configure it the SME way: Edit file /etc/ups/hosts.conf and add. 

mkdir -p /etc/e-smith/templates-custom/etc/ups/hosts.conf
echo 'MONITOR UPS@localhost "local UPS"' >/etc/e-smith/templates-custom/etc/ups/hosts.conf/10localhost
expand-template /etc/ups/hosts.conf

Httpd template 

mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf

Now edit and create a new file 92nutupscmon with the following content 

{
    $OUT = "";
    my $allow = 'all';
    my $pass = '0';
    my $satisfy = 'all';
    my $name = $nut{'Name'} || 'NUT UPS Daemon Monitoring';
    my $PublicAccess = $nut{'PublicAccess'} || "local";

    for ('exit-if-none')
    {
      if ($PublicAccess eq 'none')
          {
           next;
          }
      elsif ($PublicAccess eq 'local')
          {
            $allow   = "ip $localAccess";
            $pass    = 0;
            $satisfy = 'All';
          }
      elsif ($PublicAccess eq 'local-pw')
          {
            $allow   = "ip $localAccess";
            $pass    = 1;
            $satisfy = 'All';
          }
      elsif ($PublicAccess eq 'global')
          {
            $allow   = 'all granted';
            $pass    = 0;
            $satisfy = 'All';
          }
      elsif ($PublicAccess eq 'global-pw')
          {
            $allow   = 'all granted';
            $pass    = 1;
            $satisfy = 'All';
          }
      elsif ($PublicAccess eq 'global-pw-remote')
          {
            $allow   = "ip $localAccess";
            $pass    = 1;
            $satisfy = 'Any';
          }
 
      $OUT .= "#------------------------------------------------------------\n";
      $OUT .= "# nut multimon - $name\n";
      $OUT .= "#------------------------------------------------------------\n";

      {
        if ((exists $nut{'URL'}) && ($nut{'URL'} ne '')) {
          $OUT .= "Alias  /$nut{'URL'}  /var/www/nut-cgi-bin\n"; 
        }  
      }

      $OUT .= "Alias  /nut  /var/www/nut-cgi-bin\n";

      $OUT .= "\n";
      $OUT .= "<Directory /var/www/nut-cgi-bin>\n";
      $OUT .= "    DirectoryIndex upsstats.cgi\n";
      $OUT .= "    Options +ExecCGI\n";
      $OUT .= "    <Require$satisfy>\n" if ($pass);
      $OUT .= "    Require $allow\n";
      if ($pass)
      {
          $OUT .= "    AuthName $name\n";
          $OUT .= "    AuthType Basic\n";
          $OUT .= "    AuthExternal pwauth\n";
          $OUT .= "    require valid-user\n";
          $OUT .= "    </Require$satisfy>\n";
      }
      $OUT .= "</Directory>\n";
    }
}

Configure databases and expand the template 

config setprop nut PublicAccess local
/sbin/e-smith/expand-template /etc/httpd/conf/httpd.conf


Important.png Note:
The above sets access to the scripts to local ip addresses only. See the Web_Application_RPM#New_DB_settings for further info and settings

Restart the web server 

systemctl restart httpd-e-smith

You have to enable the epel repositories. 

yum install --enablerepo=epel nut-cgi

Edit file /etc/ups/hosts.conf and add. 

MONITOR UPS@localhost "local UPS"

The nut-cgi rpm contains three cgi scripts. The rpm does not install them correctly for SME however so the following modifications are needed. 

mkdir -p /opt/nut-cgi-bin
chown root:www /opt/nut-cgi-bin
mv /var/www/nut-cgi-bin/upsstats.cgi /opt/nut-cgi-bin
mv /var/www/nut-cgi-bin/upsset.cgi /opt/nut-cgi-bin
mv /var/www/nut-cgi-bin/upsimage.cgi /opt/nut-cgi-bin
chown root:www /opt/nut-cgi-bin/*
chmod 750 /opt/nut-cgi-bin/*
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf

Now edit and create a new file 92nutupscmon with the following content 

{
    $OUT = "";
    my $allow = 'all granted';
    my $pass = '0';
    my $satisfy = 'All';
    my $name = $nut{'Name'} || 'NUT UPS Daemon Monitoring';
 
    for ('exit-if-none')
    {
      if ($nut{'PublicAccess'})
      {
          if ($nut{'PublicAccess'} eq 'none')
          {
           next;
          }
          elsif ($nut{'PublicAccess'} eq 'local')
          {
            $allow   = $localAccess;
            $pass    = 0;
            $satisfy = 'all';
          }
          elsif ($nut{'PublicAccess'} eq 'local-pw')
          {
            $allow   = $localAccess;
            $pass    = 1;
            $satisfy = 'all';
          }
          elsif ($nut{'PublicAccess'} eq 'global')
          {
            $allow   = 'all';
            $pass    = 0;
            $satisfy = 'all';
          }
          elsif ($nut{'PublicAccess'} eq 'global-pw')
          {
            $allow   = 'all';
            $pass    = 1;
            $satisfy = 'all';
          }
          elsif ($nut{'PublicAccess'} eq 'global-pw-remote')
          {
            $allow   = $localAccess;
            $pass    = 1;
            $satisfy = 'any';
          }
      } 

      $OUT .= "#------------------------------------------------------------\n";
      $OUT .= "# nut multimon - $name\n";
      $OUT .= "#------------------------------------------------------------\n";

      {
        if ((exists $nut{'URL'}) && ($nut{'URL'} ne '')) {
          $OUT .= "Alias  /$nut{'URL'}  /opt/nut-cgi-bin\n"; 
        }  
      }

      $OUT .= "Alias  /nut  /opt/nut-cgi-bin\n";

      $OUT .= "\n";
      $OUT .= "<Directory /opt/nut-cgi-bin>\n";
      $OUT .= "    DirectoryIndex upsstats.cgi\n";
      $OUT .= "    Options +ExecCGI\n";
      $OUT .= "    order deny,allow\n";
      $OUT .= "    deny from all\n";
      $OUT .= "    allow from $allow\n";
      if ($pass)
      {
          $OUT .= "    AuthName $name\n";
          $OUT .= "    AuthType Basic\n";
          $OUT .= "    AuthExternal pwauth\n";
          $OUT .= "    require valid-user\n";
          $OUT .= "    Satisfy $satisfy\n";
      }
      $OUT .= "</Directory>\n";
    }
}

Configure databases and expand the template 

config setprop nut PublicAccess local
/sbin/e-smith/expand-template /etc/httpd/conf/httpd.conf


Important.png Note:
The above sets access to the scripts to local ip addresses only. See the Web_Application_RPM#New_DB_settings for further info and settings

Restart the web server 

sv t httpd-e-smith

Usage of Nut-cgi Scripts

Now go to http://yourdomain.tld/nut to see the statistics and information for the UPS at localhost.

By editing /etc/ups/hosts.conf and adding additional network UPS details, nut-cgi can be used to monitor more than one UPS. By the modification above, only the localhost is monitored.

Additional Information

There are template fragments in /etc/e-smith/templates/etc/ups that control the config files located in /etc/ups. The default settings should be OK for most situations. The /etc/nut.conf file must be manually edited like mode=standalone as the templates do not touch this file. In this case it would be: 

sed -e 's/^MODE.*/MODE=standalone/' -i /etc/ups/nut.conf

By default, NUT is configured for a USB connected UPS in Master mode, but is disabled. When enabled, NUT will monitor the UPS and take various actions when certain notifications are received. This is controlled by the /etc/ups/upsmon.conf file which among other things lists the notifications and the actions to be taken for each. For example an On Battery event is captured by the NOTIFYFLAG ONBATT entry and the following SYSLOG+WALL+EXEC command string. This string tells upsmon to write the event to the System Log, broadcast a message to all users via Wall, and execute the command denoted by the NOTIFYCMD entry.

SME Server sets the NOTIFYCMD to /sbin/e-smith/nutUPS.notify, and this executable file simply sends an email to the SME admin user with a notification of the event.

Apart from the various events that the UPS and upsmon may notify via the NOTIFYFLAGS a Low Battery event will automatically and immediately cause upsmon to issue the SHUTDOWNCMD as defined in upsmon.conf (signal-event halt) and set a flag POWERDOWNFLAG so it knows on future restart that it is a UPS recovery.

For information on configuration parameters: 

man ups.conf
man upsd.conf
man upsd.users
man upsmon.conf
man upssched.conf

For general information: 

man upsd
man nutupsdrv

Timeout Issues

If you have comms problems like this you can add a custom timeout:

"USBDEVFS_CONTROL failed cmd blazer_usb rqt 33 rq 9 len 8 ret -110"

Add a new config item. The default is 2 

config setprop nut pollInterval 4

Modify the template 

mkdir -p /etc/e-smith/templates-custom/etc/ups/ups.conf
cp /etc/e-smith/templates/etc/ups/ups.conf/UPS /etc/e-smith/templates-custom/etc/ups/ups.conf/UPS
nano /etc/e-smith/templates-custom/etc/ups/ups.conf/UPS

Add the bits between the # comments 

{
   my $model = $nut{Model} || "usbhid-ups";
   my $device = $nut{Device} || "/var/lib/ups/hiddev0";
   my $type = $nut{Type};
   my $mfr = $nut{mfr};
   my $mdl = $nut{mdl};

   # Add this
   my $poll = $nut{pollInterval} || '2';
   if ($poll ne '2') {
     $OUT .= "pollinterval = $poll\n";
   }
   # ends here

   $OUT .= "[UPS]\n";
   $OUT .= "\tdriver = $model\n";

expand-template /etc/ups/ups.conf
cat /etc/ups/ups.conf

You should see something like this: 

# Copyright (C) 1999-2006 Mitel Networks Corporation
#------------------------------------------------------------
pollinterval = 4
[UPS]

Restart nut 

service nut restart

Now check to see the correct timeout: 

upsc UPS | grep driver.parameter.pollinterval

driver.parameter.pollinterval: 4

To reset either delete the key, or set it to the default of 2

Further reading

The NUT website is here: NUT

From the above references you can glean which configuration setting does what function, etc.

If you want to modify the operation of NUT from the standard configuration, then you should generally modify the NUT config files by creating custom templates, expanding the templates and restarting service. This will ensure modifications survive a future reboot or reconfiguration.

An example of doing this can be found in the forum [2] and in the section above for UPS Administrative Privileges

See also Known Problem - Restarting Nut

Documentation

Nut is a Software well documented, you can find the TOC here and with an overview


Retrieved from "https://wiki.koozali.org/index.php?title=Uninterruptable_Power_Supply&oldid=42513"