Apcupsd: Difference between revisions
No edit summary |
m (→Configuring and Testing Email Alerts: Use path and cmd templates as appropriate.) |
||
| (2 intermediate revisions by 2 users not shown) | |||
| Line 9: | Line 9: | ||
The first step is to add the alpine package for apcupsd. After that, we'll rename the default configuration file and replace them with the parameters needed for our example USB attached APC Smart-UPS. | The first step is to add the alpine package for apcupsd. After that, we'll rename the default configuration file and replace them with the parameters needed for our example USB attached APC Smart-UPS. | ||
Installation is by an APK package | Installation is by an APK package: | ||
{{cmd|# apk add {{pkg|apcupsd}}}} | |||
There is one main configuration file called ''/etc/apcupsd/apcupsd.conf'' that has all the tunable parameters along with many comments. We'll keep the original as a reference and then edit the parameters to suit. | There is one main configuration file called ''/etc/apcupsd/apcupsd.conf'' that has all the tunable parameters along with many comments. We'll keep the original as a reference and then edit the parameters to suit. | ||
{{cmd|<nowiki># mv /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf~ | |||
# grep -v '^\s*$\|^\s*\#' /etc/apcupsd/apcupsd.conf~ >/etc/apcupsd/apcupsd.conf</nowiki>}} | |||
Now, edit the parameters in | Now, edit the parameters in {{path|/etc/apcupsd/apcupsd.conf}} using the backup copy of the original file as a reference for comments. Some of the important parameters are listed below in order of appearance. | ||
* UPSNAME - This is to identify your UPS. Exact format is not important, but keep it short and don't use spaces. | * UPSNAME - This is to identify your UPS. Exact format is not important, but keep it short and don't use spaces. | ||
| Line 27: | Line 25: | ||
* DEVICE - For a USB attached UPS, the parameter is not needed. Comment this line by using a # at the beginning. | * DEVICE - For a USB attached UPS, the parameter is not needed. Comment this line by using a # at the beginning. | ||
These four changes are enough to get started. Everything else can be left as default. Read the comments in the original | These four changes are enough to get started. Everything else can be left as default. Read the comments in the original {{path|apcupsd.conf~}} file to find out what the other parameters do and if you want to use them. | ||
{{Note|The comments in the config file say UPSNAME should be eight characters or less. This appears to be a limitation of using the parameter for storing the name in the UPS's EPROM. If you're not planning to update EPROM, longer names do not appear to cause problems. See the config section after ''Configuration statements used in updating the UPS EPROM'' for more detail. }} | {{Note|The comments in the config file say UPSNAME should be eight characters or less. This appears to be a limitation of using the parameter for storing the name in the UPS's EPROM. If you're not planning to update EPROM, longer names do not appear to cause problems. See the config section after ''Configuration statements used in updating the UPS EPROM'' for more detail. }} | ||
| Line 65: | Line 63: | ||
{{Note|In order to receive notifications, you must have mail delivery setup and working on your Alpine host. In addition, you should have an alias that sends email intended for root to a regular user. See the Alpine HOWTO [[Small-Time_Email_with_Exim_and_Dovecot]] for help with that.}} | {{Note|In order to receive notifications, you must have mail delivery setup and working on your Alpine host. In addition, you should have an alias that sends email intended for root to a regular user. See the Alpine HOWTO [[Small-Time_Email_with_Exim_and_Dovecot]] for help with that.}} | ||
apcupsd will send alerts for important events using shell scripts in the /etc/apcupsd directory. These scripts and their alert functions are listed below. | apcupsd will send alerts for important events using shell scripts in the {{path|/etc/apcupsd}} directory. These scripts and their alert functions are listed below. | ||
* changeme - sends an alert when batteries have reached the end of their useful life | * changeme - sends an alert when batteries have reached the end of their useful life | ||
| Line 75: | Line 73: | ||
All of the scripts have a similar setup and rely on two environment variables, SYSADMIN and APCUPSD_MAIL, to deliver email alerts. To test the alerts, temporarily export these two variables and run one of the scripts from the command-line. The example below shows how to send a test alert for battery change. | All of the scripts have a similar setup and rely on two environment variables, SYSADMIN and APCUPSD_MAIL, to deliver email alerts. To test the alerts, temporarily export these two variables and run one of the scripts from the command-line. The example below shows how to send a test alert for battery change. | ||
{{cmd|<nowiki># export SYSADMIN=root | |||
# export APCUPSD_MAIL=mail | |||
# sh /etc/apcupsd/changeme</nowiki>}} | |||
If all goes well, you should receive an email telling you the UPS battery needs changing NOW. If you find you need to use different values for SYSADMIN or APCUPSD_MAIL, be sure to make those changes in /etc/apcupsd/apccontrol. The exported variables used in the test are temporary and will lost after you log out. | If all goes well, you should receive an email telling you the UPS battery needs changing NOW. If you find you need to use different values for SYSADMIN or APCUPSD_MAIL, be sure to make those changes in {{path|/etc/apcupsd/apccontrol}}. The exported variables used in the test are temporary and will lost after you log out. | ||
== Next Steps == | == Next Steps == | ||
Further configuration can be done to initiate automatic shutdown using the parameters in apcupsd.conf (see the original commented file apcupsd.conf~ for details.) You may also monitor the UPS via home automation using Home Assistant and the [https://www.home-assistant.io/integrations/apcupsd/ APC UPS Daemon integration]. | Further configuration can be done to initiate automatic shutdown using the parameters in apcupsd.conf (see the original commented file apcupsd.conf~ for details.) You may also monitor the UPS via home automation using Home Assistant and the [https://www.home-assistant.io/integrations/apcupsd/ APC UPS Daemon integration]. | ||
Latest revision as of 22:29, 14 October 2024
Using apcupsd to Monitor a USB-Attached APC UPS
This wiki page shows how to install and configure the apcupsd package to monitor and report the statistics for an APC branded USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any APC or compatible model should work.
The end goal is to make the UPS status available over the network so it can be monitored and used to trigger actions in a home automation system like Home Assistant.
Installing and Configuring apcupsd
The first step is to add the alpine package for apcupsd. After that, we'll rename the default configuration file and replace them with the parameters needed for our example USB attached APC Smart-UPS.
Installation is by an APK package:
# apk add apcupsd
There is one main configuration file called /etc/apcupsd/apcupsd.conf that has all the tunable parameters along with many comments. We'll keep the original as a reference and then edit the parameters to suit.
# mv /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf~ # grep -v '^\s*$\|^\s*\#' /etc/apcupsd/apcupsd.conf~ >/etc/apcupsd/apcupsd.conf
Now, edit the parameters in /etc/apcupsd/apcupsd.conf using the backup copy of the original file as a reference for comments. Some of the important parameters are listed below in order of appearance.
- UPSNAME - This is to identify your UPS. Exact format is not important, but keep it short and don't use spaces.
- UPSCABLE - For a USB attached UPS, use the value usb
- USBTYPE - Similar to USBCABLE, use usb
- DEVICE - For a USB attached UPS, the parameter is not needed. Comment this line by using a # at the beginning.
These four changes are enough to get started. Everything else can be left as default. Read the comments in the original apcupsd.conf~ file to find out what the other parameters do and if you want to use them.
Starting apcupsd
The apcupsd package installs a service that allows you to control apcupsd using the standard tools. The following example shows how to start it and ensure it starts each time the system boots.
alpine:/# rc-service apcupsd start * Starting APC UPS daemon ... alpine:/# rc-update add apcupsd * service apcupsd added to runlevel default
Checking the Configuration
The apcaccess command will communicate with the UPS via the apcupsd daemon's network port and report back what it finds. This is a good way to test your connection and configuration.
A successful test will look similar to what's shown below.
alpine:/# apcaccess APC : 001,043,1022 DATE : 2024-10-12 15:31:10 +0000 HOSTNAME : alpine.home VERSION : 3.14.14 (31 May 2016) unknown UPSNAME : SmartUPS_1000 CABLE : USB Cable DRIVER : USB UPS Driver UPSMODE : Stand Alone ...
The actual list of reported parameters is much longer, but the first few lines show the ones that have been customized in the configuration thus far. If you see the message Error contacting apcupsd @ localhost:3551: Connection refused, check to ensure the apcupsd service is running.
Configuring and Testing Email Alerts
apcupsd will send alerts for important events using shell scripts in the /etc/apcupsd directory. These scripts and their alert functions are listed below.
- changeme - sends an alert when batteries have reached the end of their useful life
- commfailure - apcupsd cannot communicate with the UPS
- commok - communication with the UPS has been restored after a failure
- offbattery - the UPS is back to running on mains power after running on battery
- onbattery - the ups has switched to battery power
All of the scripts have a similar setup and rely on two environment variables, SYSADMIN and APCUPSD_MAIL, to deliver email alerts. To test the alerts, temporarily export these two variables and run one of the scripts from the command-line. The example below shows how to send a test alert for battery change.
# export SYSADMIN=root # export APCUPSD_MAIL=mail # sh /etc/apcupsd/changeme
If all goes well, you should receive an email telling you the UPS battery needs changing NOW. If you find you need to use different values for SYSADMIN or APCUPSD_MAIL, be sure to make those changes in /etc/apcupsd/apccontrol. The exported variables used in the test are temporary and will lost after you log out.
Next Steps
Further configuration can be done to initiate automatic shutdown using the parameters in apcupsd.conf (see the original commented file apcupsd.conf~ for details.) You may also monitor the UPS via home automation using Home Assistant and the APC UPS Daemon integration.