Alpine Linux - User contributions [en]

Nut-ups

2026-03-01T22:16:46Z

Antiz: Add a note about adding the udev-trigger service to a runlevel for the udev rule to automatically apply at boot

This wiki page shows how to install and configure the Network UPS Tools (NUT) package to monitor and report the statistics for a USB-attached Uninterruptible Power Supply (UPS) and make the UPS status available over the network, so that it can be monitored and used to trigger actions in a home automation system like [https://www.home-assistant.io/ Home Assistant].

The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] should work.

== Determine UPS USB parameters ==

The first step is to plug in the USB cable between your UPS and your Alpine Linux host to see how it appears to the system. Information about the UPS can be seen with the {{ic|dmesg}} command. See the example below.{{Cmd|<nowiki># dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>}}

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: '''idVendor=051d''' and '''idProduct=0002'''. These will be used later in the udev rules, so keep them handy.

These parameters can also simply be retrieved from {{ic|lsusb}}. See the example below.{{Cmd|<nowiki># lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.67-0-rpi dwc_otg_hcd DWC OTG Controller
Bus 001 Device 003: ID 0424:2514
Bus 001 Device 002: ID 0424:2514
Bus 001 Device 004: ID 0463:ffff EATON Ellipse ECO
Bus 001 Device 005: ID 0424:7800</nowiki>}}

From this output, we can see a EATON Ellipse ECO UPS has been detected. We can also see the two important parameters from the ID field, with '''0463''' being the '''idVendor''' and '''ffff''' being the '''idProduct'''.

== Installation ==

Install the {{pkg|nut}} package:{{Cmd|# apk add nut}}

== Configuration ==

All of the configuration files delivered with the package will be in the {{Path|/etc/nut}} subdirectory.

The following commands rename three original configuration files. {{Cmd|<nowiki># mv /etc/nut/nut.conf /etc/nut/nut.bak
# mv /etc/nut/ups.conf /etc/nut/ups.bak
# mv /etc/nut/upsd.conf /etc/nut/upsd.bak</nowiki>}}

Proceed to create the three files with only the configuration parameters needed for our example USB-attached APC Smart-UPS.

To instruct NUT to make the UPS status available on the network, create the {{Path|/etc/nut/nut.conf}} file with content as follows: {{Cat|/etc/nut/nut.conf|<nowiki>MODE=netserver</nowiki>}}

The content of {{Path|/etc/nut/ups.conf}} defines the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB-attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided that it is a USB-attached UPS. Create the file {{Path|/etc/nut/ups.conf}} with content as follows: {{Cat|/etc/nut/ups.conf|<nowiki>[SmartUPS_1000]
driver = usbhid-ups
port = auto</nowiki>}}

To tell NUT to make the UPS info available on all network interfaces instead of the default i.e localhost only, which is not very useful, create the {{Path|/etc/nut/upsd.conf}} file with content as follows: {{Cat|/etc/nut/upsd.conf|<nowiki>LISTEN 0.0.0.0 3493</nowiki>}}

{{Tip| Replace 0.0.0.0 with the network address of a specific interface if none of the interfaces are appropriate for your situation.}}

=== Configure udev rules ===

To avoid [[#Insufficient permissions on everything|permission errors]], configure '''udev''' for giving NUT access to the USB-attached Smart-UPS 1000. Create the file {{Path|/etc/udev/rules.d/62-nut-usbups.rules}} as follows:{{Cat|/etc/udev/rules.d/62-nut-usbups.rules|<nowiki>SUBSYSTEM=="usb", ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", GROUP="nut"</nowiki>}}
The ''idVendor'' and ''idProduct'' in the first part – i.e ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"'' – are unique to your UPS. They were found earlier in the [[#Determine UPS USB parameters| Determining UPS USB parameters]] section. The rest of the line tells '''udev''' what permissions and group ownership to use, and these should be the same regardless of the UPS make and model.

Use the {{ic|udevadm}} command to tell '''udev''' to read in and apply the changes:
{{Cmd|<nowiki># udevadm control --reload
# udevadm trigger</nowiki>}}

{{Tip|Make sure that the {{ic|udev-trigger}} service is added to a runlevel for the udev rule to automatically apply at boot: {{ic|# rc-update add udev-trigger}}.}}
{{Note|There is also a file {{Path|/lib/udev/rules.d/62-nut-usbups.rules}} that has information for all of the UPS models that NUT knows about. You may be able to simply copy this rather than constructing your own rules.}}

== Service configuration ==

The service is called {{ic|nut-upsd}} and can be managed using the standard start|stop|restart commands using standard [[OpenRC]] commands.

{{Tip|Remember to [[#Configure udev rules|configure '''udev''' rules]] and to [[#Testing the configuration|test the configuration]] before proceeding further.}}

Proceed to start the service as follows: {{Cmd|# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...}}

Notice that the directory {{Path|/run/nut}} is created automatically the first time.

[[#Verifying running state|Verify the running state]] before proceeding to configure the automatic startup of the {{ic|nut-upsd}}. If everything looks good, go ahead and set the service to auto-start when the system is booted:{{Cmd|# rc-update add nut-upsd
* service nut-upsd added to runlevel default}}

== Using NUT ==

Now, the {{ic|upsc}} command can be run against the name added in {{Path|/etc/nut/ups.conf}} to gather all status information about your UPS. Based on the example used on this wiki page:{{Cmd|$ upsc SmartUPS_1000}}
One can also gather specific status information by passing them as an argument: {{Cmd|$ upsc SmartUPS_1000 battery.charge}} This is useful to monitor specific values and/or to initiate actions (e.g. from a script) when specific thresholds are reached.

The [[#See also|See also]] section has documentation links about how to configure NUT to do useful things, such as sending an email, initiating a graceful shutdown when the main power is lost, and how to use Home Assistant to keep tabs on your UPS.

== Troubleshooting ==

=== Testing the configuration ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure that it was detected and that the ''idVendor'' and ''idProduct'' are correct.

Check the permissions on the files in the {{Path|/dev/bus/usb}} subdirectories. One of these represents your UPS. If the '''udev''' rules work correctly, the file should be the one with a group owner of ''nut'' and permissions of 0664. An example is shown below.{{Cmd|# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003}}

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from {{ic|dmesg}} should tip you off as to which directory and file it is. Look at the line below from {{ic|dmesg}} and compare the ''usb 1-3'' to the directory entry of the {{Path|/dev/bus/usb/001/003}}file. {{Cat|/dev/bus/usb/001/003|usb 1-3: Manufacturer: American Power Conversion}}

=== Verifying running state ===

A couple of quick commands will ensure that the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Insufficient permissions on everything ===

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

The error message above is due to the USB device having the wrong ownership and permissions. [[#Configure udev rules|Configure '''udev''' rules]] and restart the [[#Service configuration|service]].

== See also ==

* [https://networkupstools.org/ NUT home page]
* [https://networkupstools.org/stable-hcl.html list of NUT compatible models]
* [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant]
* [[Apcupsd]]

[[Category:Monitoring]]
[[Category:System Administration]]
[[Category:Networking]]

Nut-ups

2026-03-01T22:10:48Z

Antiz: Update udev rule: Add SUBSYSTEM=="usb" and remove the MODE parameter (which is not needed here)

This wiki page shows how to install and configure the Network UPS Tools (NUT) package to monitor and report the statistics for a USB-attached Uninterruptible Power Supply (UPS) and make the UPS status available over the network, so that it can be monitored and used to trigger actions in a home automation system like [https://www.home-assistant.io/ Home Assistant].

The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] should work.

== Determine UPS USB parameters ==

The first step is to plug in the USB cable between your UPS and your Alpine Linux host to see how it appears to the system. Information about the UPS can be seen with the {{ic|dmesg}} command. See the example below.{{Cmd|<nowiki># dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>}}

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: '''idVendor=051d''' and '''idProduct=0002'''. These will be used later in the udev rules, so keep them handy.

These parameters can also simply be retrieved from {{ic|lsusb}}. See the example below.{{Cmd|<nowiki># lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.67-0-rpi dwc_otg_hcd DWC OTG Controller
Bus 001 Device 003: ID 0424:2514
Bus 001 Device 002: ID 0424:2514
Bus 001 Device 004: ID 0463:ffff EATON Ellipse ECO
Bus 001 Device 005: ID 0424:7800</nowiki>}}

From this output, we can see a EATON Ellipse ECO UPS has been detected. We can also see the two important parameters from the ID field, with '''0463''' being the '''idVendor''' and '''ffff''' being the '''idProduct'''.

== Installation ==

Install the {{pkg|nut}} package:{{Cmd|# apk add nut}}

== Configuration ==

All of the configuration files delivered with the package will be in the {{Path|/etc/nut}} subdirectory.

The following commands rename three original configuration files. {{Cmd|<nowiki># mv /etc/nut/nut.conf /etc/nut/nut.bak
# mv /etc/nut/ups.conf /etc/nut/ups.bak
# mv /etc/nut/upsd.conf /etc/nut/upsd.bak</nowiki>}}

Proceed to create the three files with only the configuration parameters needed for our example USB-attached APC Smart-UPS.

To instruct NUT to make the UPS status available on the network, create the {{Path|/etc/nut/nut.conf}} file with content as follows: {{Cat|/etc/nut/nut.conf|<nowiki>MODE=netserver</nowiki>}}

The content of {{Path|/etc/nut/ups.conf}} defines the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB-attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided that it is a USB-attached UPS. Create the file {{Path|/etc/nut/ups.conf}} with content as follows: {{Cat|/etc/nut/ups.conf|<nowiki>[SmartUPS_1000]
driver = usbhid-ups
port = auto</nowiki>}}

To tell NUT to make the UPS info available on all network interfaces instead of the default i.e localhost only, which is not very useful, create the {{Path|/etc/nut/upsd.conf}} file with content as follows: {{Cat|/etc/nut/upsd.conf|<nowiki>LISTEN 0.0.0.0 3493</nowiki>}}

{{Tip| Replace 0.0.0.0 with the network address of a specific interface if none of the interfaces are appropriate for your situation.}}

=== Configure udev rules ===

To avoid [[#Insufficient permissions on everything|permission errors]], configure '''udev''' for giving NUT access to the USB-attached Smart-UPS 1000. Create the file {{Path|/etc/udev/rules.d/62-nut-usbups.rules}} as follows:{{Cat|/etc/udev/rules.d/62-nut-usbups.rules|<nowiki>SUBSYSTEM=="usb", ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", GROUP="nut"</nowiki>}}
The ''idVendor'' and ''idProduct'' in the first part – i.e ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"'' – are unique to your UPS. They were found earlier in the [[#Determine UPS USB parameters| Determining UPS USB parameters]] section. The rest of the line tells '''udev''' what permissions and group ownership to use, and these should be the same regardless of the UPS make and model.

Use the {{ic|udevadm}} command to tell '''udev''' to read in and apply the changes:
{{Cmd|<nowiki># udevadm control --reload
# udevadm trigger</nowiki>}}

{{Note|There is also a file {{Path|/lib/udev/rules.d/62-nut-usbups.rules}} that has information for all of the UPS models that NUT knows about. You may be able to simply copy this rather than constructing your own rules.}}

== Service configuration ==

The service is called {{ic|nut-upsd}} and can be managed using the standard start|stop|restart commands using standard [[OpenRC]] commands.

{{Tip|Remember to [[#Configure udev rules|configure '''udev''' rules]] and to [[#Testing the configuration|test the configuration]] before proceeding further.}}

Proceed to start the service as follows: {{Cmd|# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...}}

Notice that the directory {{Path|/run/nut}} is created automatically the first time.

[[#Verifying running state|Verify the running state]] before proceeding to configure the automatic startup of the {{ic|nut-upsd}}. If everything looks good, go ahead and set the service to auto-start when the system is booted:{{Cmd|# rc-update add nut-upsd
* service nut-upsd added to runlevel default}}

== Using NUT ==

Now, the {{ic|upsc}} command can be run against the name added in {{Path|/etc/nut/ups.conf}} to gather all status information about your UPS. Based on the example used on this wiki page:{{Cmd|$ upsc SmartUPS_1000}}
One can also gather specific status information by passing them as an argument: {{Cmd|$ upsc SmartUPS_1000 battery.charge}} This is useful to monitor specific values and/or to initiate actions (e.g. from a script) when specific thresholds are reached.

The [[#See also|See also]] section has documentation links about how to configure NUT to do useful things, such as sending an email, initiating a graceful shutdown when the main power is lost, and how to use Home Assistant to keep tabs on your UPS.

== Troubleshooting ==

=== Testing the configuration ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure that it was detected and that the ''idVendor'' and ''idProduct'' are correct.

Check the permissions on the files in the {{Path|/dev/bus/usb}} subdirectories. One of these represents your UPS. If the '''udev''' rules work correctly, the file should be the one with a group owner of ''nut'' and permissions of 0664. An example is shown below.{{Cmd|# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003}}

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from {{ic|dmesg}} should tip you off as to which directory and file it is. Look at the line below from {{ic|dmesg}} and compare the ''usb 1-3'' to the directory entry of the {{Path|/dev/bus/usb/001/003}}file. {{Cat|/dev/bus/usb/001/003|usb 1-3: Manufacturer: American Power Conversion}}

=== Verifying running state ===

A couple of quick commands will ensure that the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Insufficient permissions on everything ===

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

The error message above is due to the USB device having the wrong ownership and permissions. [[#Configure udev rules|Configure '''udev''' rules]] and restart the [[#Service configuration|service]].

== See also ==

* [https://networkupstools.org/ NUT home page]
* [https://networkupstools.org/stable-hcl.html list of NUT compatible models]
* [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant]
* [[Apcupsd]]

[[Category:Monitoring]]
[[Category:System Administration]]
[[Category:Networking]]

Nut-ups

2026-03-01T22:08:59Z

Antiz: Update udevadm commands to actually apply the rule

This wiki page shows how to install and configure the Network UPS Tools (NUT) package to monitor and report the statistics for a USB-attached Uninterruptible Power Supply (UPS) and make the UPS status available over the network, so that it can be monitored and used to trigger actions in a home automation system like [https://www.home-assistant.io/ Home Assistant].

The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] should work.

== Determine UPS USB parameters ==

The first step is to plug in the USB cable between your UPS and your Alpine Linux host to see how it appears to the system. Information about the UPS can be seen with the {{ic|dmesg}} command. See the example below.{{Cmd|<nowiki># dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>}}

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: '''idVendor=051d''' and '''idProduct=0002'''. These will be used later in the udev rules, so keep them handy.

These parameters can also simply be retrieved from {{ic|lsusb}}. See the example below.{{Cmd|<nowiki># lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.67-0-rpi dwc_otg_hcd DWC OTG Controller
Bus 001 Device 003: ID 0424:2514
Bus 001 Device 002: ID 0424:2514
Bus 001 Device 004: ID 0463:ffff EATON Ellipse ECO
Bus 001 Device 005: ID 0424:7800</nowiki>}}

From this output, we can see a EATON Ellipse ECO UPS has been detected. We can also see the two important parameters from the ID field, with '''0463''' being the '''idVendor''' and '''ffff''' being the '''idProduct'''.

== Installation ==

Install the {{pkg|nut}} package:{{Cmd|# apk add nut}}

== Configuration ==

All of the configuration files delivered with the package will be in the {{Path|/etc/nut}} subdirectory.

The following commands rename three original configuration files. {{Cmd|<nowiki># mv /etc/nut/nut.conf /etc/nut/nut.bak
# mv /etc/nut/ups.conf /etc/nut/ups.bak
# mv /etc/nut/upsd.conf /etc/nut/upsd.bak</nowiki>}}

Proceed to create the three files with only the configuration parameters needed for our example USB-attached APC Smart-UPS.

To instruct NUT to make the UPS status available on the network, create the {{Path|/etc/nut/nut.conf}} file with content as follows: {{Cat|/etc/nut/nut.conf|<nowiki>MODE=netserver</nowiki>}}

The content of {{Path|/etc/nut/ups.conf}} defines the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB-attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided that it is a USB-attached UPS. Create the file {{Path|/etc/nut/ups.conf}} with content as follows: {{Cat|/etc/nut/ups.conf|<nowiki>[SmartUPS_1000]
driver = usbhid-ups
port = auto</nowiki>}}

To tell NUT to make the UPS info available on all network interfaces instead of the default i.e localhost only, which is not very useful, create the {{Path|/etc/nut/upsd.conf}} file with content as follows: {{Cat|/etc/nut/upsd.conf|<nowiki>LISTEN 0.0.0.0 3493</nowiki>}}

{{Tip| Replace 0.0.0.0 with the network address of a specific interface if none of the interfaces are appropriate for your situation.}}

=== Configure udev rules ===

To avoid [[#Insufficient permissions on everything|permission errors]], configure '''udev''' for giving NUT access to the USB-attached Smart-UPS 1000. Create the file {{Path|/etc/udev/rules.d/62-nut-usbups.rules}} as follows:{{Cat|/etc/udev/rules.d/62-nut-usbups.rules|<nowiki>ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
</nowiki>}}
The ''idVendor'' and ''idProduct'' in the first part – i.e ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"'' – are unique to your UPS. They were found earlier in the [[#Determine UPS USB parameters| Determining UPS USB parameters]] section. The rest of the line tells '''udev''' what permissions and group ownership to use, and these should be the same regardless of the UPS make and model.

Use the {{ic|udevadm}} command to tell '''udev''' to read in and apply the changes:
{{Cmd|<nowiki># udevadm control --reload
# udevadm trigger</nowiki>}}

{{Note|There is also a file {{Path|/lib/udev/rules.d/62-nut-usbups.rules}} that has information for all of the UPS models that NUT knows about. You may be able to simply copy this rather than constructing your own rules.}}

== Service configuration ==

The service is called {{ic|nut-upsd}} and can be managed using the standard start|stop|restart commands using standard [[OpenRC]] commands.

{{Tip|Remember to [[#Configure udev rules|configure '''udev''' rules]] and to [[#Testing the configuration|test the configuration]] before proceeding further.}}

Proceed to start the service as follows: {{Cmd|# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...}}

Notice that the directory {{Path|/run/nut}} is created automatically the first time.

[[#Verifying running state|Verify the running state]] before proceeding to configure the automatic startup of the {{ic|nut-upsd}}. If everything looks good, go ahead and set the service to auto-start when the system is booted:{{Cmd|# rc-update add nut-upsd
* service nut-upsd added to runlevel default}}

== Using NUT ==

Now, the {{ic|upsc}} command can be run against the name added in {{Path|/etc/nut/ups.conf}} to gather all status information about your UPS. Based on the example used on this wiki page:{{Cmd|$ upsc SmartUPS_1000}}
One can also gather specific status information by passing them as an argument: {{Cmd|$ upsc SmartUPS_1000 battery.charge}} This is useful to monitor specific values and/or to initiate actions (e.g. from a script) when specific thresholds are reached.

The [[#See also|See also]] section has documentation links about how to configure NUT to do useful things, such as sending an email, initiating a graceful shutdown when the main power is lost, and how to use Home Assistant to keep tabs on your UPS.

== Troubleshooting ==

=== Testing the configuration ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure that it was detected and that the ''idVendor'' and ''idProduct'' are correct.

Check the permissions on the files in the {{Path|/dev/bus/usb}} subdirectories. One of these represents your UPS. If the '''udev''' rules work correctly, the file should be the one with a group owner of ''nut'' and permissions of 0664. An example is shown below.{{Cmd|# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003}}

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from {{ic|dmesg}} should tip you off as to which directory and file it is. Look at the line below from {{ic|dmesg}} and compare the ''usb 1-3'' to the directory entry of the {{Path|/dev/bus/usb/001/003}}file. {{Cat|/dev/bus/usb/001/003|usb 1-3: Manufacturer: American Power Conversion}}

=== Verifying running state ===

A couple of quick commands will ensure that the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Insufficient permissions on everything ===

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

The error message above is due to the USB device having the wrong ownership and permissions. [[#Configure udev rules|Configure '''udev''' rules]] and restart the [[#Service configuration|service]].

== See also ==

* [https://networkupstools.org/ NUT home page]
* [https://networkupstools.org/stable-hcl.html list of NUT compatible models]
* [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant]
* [[Apcupsd]]

[[Category:Monitoring]]
[[Category:System Administration]]
[[Category:Networking]]

Nut-ups

2026-03-01T22:06:08Z

Antiz: Add instructions to find the "idVendor" and "idProduct" parameters via 'lsusb'

This wiki page shows how to install and configure the Network UPS Tools (NUT) package to monitor and report the statistics for a USB-attached Uninterruptible Power Supply (UPS) and make the UPS status available over the network, so that it can be monitored and used to trigger actions in a home automation system like [https://www.home-assistant.io/ Home Assistant].

The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] should work.

== Determine UPS USB parameters ==

The first step is to plug in the USB cable between your UPS and your Alpine Linux host to see how it appears to the system. Information about the UPS can be seen with the {{ic|dmesg}} command. See the example below.{{Cmd|<nowiki># dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>}}

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: '''idVendor=051d''' and '''idProduct=0002'''. These will be used later in the udev rules, so keep them handy.

These parameters can also simply be retrieved from {{ic|lsusb}}. See the example below.{{Cmd|<nowiki># lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.67-0-rpi dwc_otg_hcd DWC OTG Controller
Bus 001 Device 003: ID 0424:2514
Bus 001 Device 002: ID 0424:2514
Bus 001 Device 004: ID 0463:ffff EATON Ellipse ECO
Bus 001 Device 005: ID 0424:7800</nowiki>}}

From this output, we can see a EATON Ellipse ECO UPS has been detected. We can also see the two important parameters from the ID field, with '''0463''' being the '''idVendor''' and '''ffff''' being the '''idProduct'''.

== Installation ==

Install the {{pkg|nut}} package:{{Cmd|# apk add nut}}

== Configuration ==

All of the configuration files delivered with the package will be in the {{Path|/etc/nut}} subdirectory.

The following commands rename three original configuration files. {{Cmd|<nowiki># mv /etc/nut/nut.conf /etc/nut/nut.bak
# mv /etc/nut/ups.conf /etc/nut/ups.bak
# mv /etc/nut/upsd.conf /etc/nut/upsd.bak</nowiki>}}

Proceed to create the three files with only the configuration parameters needed for our example USB-attached APC Smart-UPS.

To instruct NUT to make the UPS status available on the network, create the {{Path|/etc/nut/nut.conf}} file with content as follows: {{Cat|/etc/nut/nut.conf|<nowiki>MODE=netserver</nowiki>}}

The content of {{Path|/etc/nut/ups.conf}} defines the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB-attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided that it is a USB-attached UPS. Create the file {{Path|/etc/nut/ups.conf}} with content as follows: {{Cat|/etc/nut/ups.conf|<nowiki>[SmartUPS_1000]
driver = usbhid-ups
port = auto</nowiki>}}

To tell NUT to make the UPS info available on all network interfaces instead of the default i.e localhost only, which is not very useful, create the {{Path|/etc/nut/upsd.conf}} file with content as follows: {{Cat|/etc/nut/upsd.conf|<nowiki>LISTEN 0.0.0.0 3493</nowiki>}}

{{Tip| Replace 0.0.0.0 with the network address of a specific interface if none of the interfaces are appropriate for your situation.}}

=== Configure udev rules ===

To avoid [[#Insufficient permissions on everything|permission errors]], configure '''udev''' for giving NUT access to the USB-attached Smart-UPS 1000. Create the file {{Path|/etc/udev/rules.d/62-nut-usbups.rules}} as follows:{{Cat|/etc/udev/rules.d/62-nut-usbups.rules|<nowiki>ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
</nowiki>}}
The ''idVendor'' and ''idProduct'' in the first part – i.e ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"'' – are unique to your UPS. They were found earlier in the [[#Determine UPS USB parameters| Determining UPS USB parameters]] section. The rest of the line tells '''udev''' what permissions and group ownership to use, and these should be the same regardless of the UPS make and model.

Use the {{ic|udevadm}} command to tell '''udev''' to read in the changes:{{Cmd|# udevadm control --reload-rules}}

{{Note|There is also a file {{Path|/lib/udev/rules.d/62-nut-usbups.rules}} that has information for all of the UPS models that NUT knows about. You may be able to simply copy this rather than constructing your own rules.}}

== Service configuration ==

The service is called {{ic|nut-upsd}} and can be managed using the standard start|stop|restart commands using standard [[OpenRC]] commands.

{{Tip|Remember to [[#Configure udev rules|configure '''udev''' rules]] and to [[#Testing the configuration|test the configuration]] before proceeding further.}}

Proceed to start the service as follows: {{Cmd|# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...}}

Notice that the directory {{Path|/run/nut}} is created automatically the first time.

[[#Verifying running state|Verify the running state]] before proceeding to configure the automatic startup of the {{ic|nut-upsd}}. If everything looks good, go ahead and set the service to auto-start when the system is booted:{{Cmd|# rc-update add nut-upsd
* service nut-upsd added to runlevel default}}

== Using NUT ==

Now, the {{ic|upsc}} command can be run against the name added in {{Path|/etc/nut/ups.conf}} to gather all status information about your UPS. Based on the example used on this wiki page:{{Cmd|$ upsc SmartUPS_1000}}
One can also gather specific status information by passing them as an argument: {{Cmd|$ upsc SmartUPS_1000 battery.charge}} This is useful to monitor specific values and/or to initiate actions (e.g. from a script) when specific thresholds are reached.

The [[#See also|See also]] section has documentation links about how to configure NUT to do useful things, such as sending an email, initiating a graceful shutdown when the main power is lost, and how to use Home Assistant to keep tabs on your UPS.

== Troubleshooting ==

=== Testing the configuration ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure that it was detected and that the ''idVendor'' and ''idProduct'' are correct.

Check the permissions on the files in the {{Path|/dev/bus/usb}} subdirectories. One of these represents your UPS. If the '''udev''' rules work correctly, the file should be the one with a group owner of ''nut'' and permissions of 0664. An example is shown below.{{Cmd|# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003}}

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from {{ic|dmesg}} should tip you off as to which directory and file it is. Look at the line below from {{ic|dmesg}} and compare the ''usb 1-3'' to the directory entry of the {{Path|/dev/bus/usb/001/003}}file. {{Cat|/dev/bus/usb/001/003|usb 1-3: Manufacturer: American Power Conversion}}

=== Verifying running state ===

A couple of quick commands will ensure that the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Insufficient permissions on everything ===

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

The error message above is due to the USB device having the wrong ownership and permissions. [[#Configure udev rules|Configure '''udev''' rules]] and restart the [[#Service configuration|service]].

== See also ==

* [https://networkupstools.org/ NUT home page]
* [https://networkupstools.org/stable-hcl.html list of NUT compatible models]
* [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant]
* [[Apcupsd]]

[[Category:Monitoring]]
[[Category:System Administration]]
[[Category:Networking]]

Nut-ups

2025-09-28T19:00:41Z

Antiz: Add an accuracy/out-of-date note about the "Todo" section

{{Accuracy|The below "Todo" tag ''may'' be inaccurate/out-of-date. I've set up the udev rule as described in the article and no permissions (or any other) issue so far, despite a fair amount of system upgrade and reboot (on the latest stable branch).}}

{{Todo|The udev configuration presented here does not work consistently. A recent update and/or reboot has caused the libusb ''insufficient permissions on everything'' message to reappear. Even explicitly setting group ownership and permissions does not fix the problem.}}

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] 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 [https://www.home-assistant.io/ Home Assistant].

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. Information about the UPS can be seen with the '''dmesg''' command. See the example below.

<nowiki>
alpine:/# dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

<nowiki>
alpine:/# apk update && apk add nut

alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~

alpine:/# cat <<EOF >/etc/nut/nut.conf
MODE=netserver
EOF

alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~

alpine:/# cat <<EOF >/etc/nut/ups.conf
[SmartUPS_1000]
driver = usbhid-ups
port = auto
EOF

alpine:/# mv /etc/nut/upsd.conf /etc/nut/upsd.conf~
alpine:/# cat <<EOF >/etc/nut/upsd.conf
LISTEN 0.0.0.0 3493
EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will rename the original configuration file and then write a new file with only the configuration parameters needed.

* The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

* The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided it is a USB attached UPS.

* Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can replace 0.0.0.0 with the network address of a specific interface if all interfaces is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong ownership and permissions.

Below is an example of how to configure udev for giving NUT access to the USB attached Smart-UPS 1000.

<nowiki>
alpine:/# cd /etc/udev/rules.d

cat <<EOF >62-nut-usbups.rules
ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
EOF

alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

These are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

alpine:/# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from '''dmesg''' should tip you off as to which directory and file it is. Look at the line below from '''dmesg''' and compare the ''usb 1-3'' to the directory entry of ''/dev/bus/usb/001/003''.

usb 1-3: Manufacturer: American Power Conversion

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

alpine:/# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

alpine:/# rc-update add nut-upsd
* service nut-upsd added to runlevel default

=== Next Steps ===

You should now be able run the <code>upsc</code> command against the name added in <code>/etc/nut/ups.conf</code> to gather all status information about your UPS (e.g. with the example from this wiki page: <code>upsc SmartUPS_1000</code>). One can also gather specific status information by passing them as an argument (e.g. <code>upsc SmartUPS_1000 battery.charge</code>). This is useful to monitor specific values and/or initiate actions (e.g. from a script) when specific thresholds are reached.

NUT itself can also be configured to do useful things like send an email or initiate a graceful shutdown when the main power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Nut-ups

2025-09-28T18:11:27Z

Antiz: Mention the `upsc` command and give some usage examples

{{Todo|The udev configuration presented here does not work consistently. A recent update and/or reboot has caused the libusb ''insufficient permissions on everything'' message to reappear. Even explicitly setting group ownership and permissions does not fix the problem.}}

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] 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 [https://www.home-assistant.io/ Home Assistant].

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. Information about the UPS can be seen with the '''dmesg''' command. See the example below.

<nowiki>
alpine:/# dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

<nowiki>
alpine:/# apk update && apk add nut

alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~

alpine:/# cat <<EOF >/etc/nut/nut.conf
MODE=netserver
EOF

alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~

alpine:/# cat <<EOF >/etc/nut/ups.conf
[SmartUPS_1000]
driver = usbhid-ups
port = auto
EOF

alpine:/# mv /etc/nut/upsd.conf /etc/nut/upsd.conf~
alpine:/# cat <<EOF >/etc/nut/upsd.conf
LISTEN 0.0.0.0 3493
EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will rename the original configuration file and then write a new file with only the configuration parameters needed.

* The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

* The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided it is a USB attached UPS.

* Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can replace 0.0.0.0 with the network address of a specific interface if all interfaces is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong ownership and permissions.

Below is an example of how to configure udev for giving NUT access to the USB attached Smart-UPS 1000.

<nowiki>
alpine:/# cd /etc/udev/rules.d

cat <<EOF >62-nut-usbups.rules
ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
EOF

alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

These are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

alpine:/# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from '''dmesg''' should tip you off as to which directory and file it is. Look at the line below from '''dmesg''' and compare the ''usb 1-3'' to the directory entry of ''/dev/bus/usb/001/003''.

usb 1-3: Manufacturer: American Power Conversion

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

alpine:/# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

alpine:/# rc-update add nut-upsd
* service nut-upsd added to runlevel default

=== Next Steps ===

You should now be able run the <code>upsc</code> command against the name added in <code>/etc/nut/ups.conf</code> to gather all status information about your UPS (e.g. with the example from this wiki page: <code>upsc SmartUPS_1000</code>). One can also gather specific status information by passing them as an argument (e.g. <code>upsc SmartUPS_1000 battery.charge</code>). This is useful to monitor specific values and/or initiate actions (e.g. from a script) when specific thresholds are reached.

NUT itself can also be configured to do useful things like send an email or initiate a graceful shutdown when the main power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Nut-ups

2025-09-28T18:10:58Z

Antiz: Undo revision 31080 by Antiz (talk)

{{Todo|The udev configuration presented here does not work consistently. A recent update and/or reboot has caused the libusb ''insufficient permissions on everything'' message to reappear. Even explicitly setting group ownership and permissions does not fix the problem.}}

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] 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 [https://www.home-assistant.io/ Home Assistant].

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. Information about the UPS can be seen with the '''dmesg''' command. See the example below.

<nowiki>
alpine:/# dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

<nowiki>
alpine:/# apk update && apk add nut

alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~

alpine:/# cat <<EOF >/etc/nut/nut.conf
MODE=netserver
EOF

alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~

alpine:/# cat <<EOF >/etc/nut/ups.conf
[SmartUPS_1000]
driver = usbhid-ups
port = auto
EOF

alpine:/# mv /etc/nut/upsd.conf /etc/nut/upsd.conf~
alpine:/# cat <<EOF >/etc/nut/upsd.conf
LISTEN 0.0.0.0 3493
EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will rename the original configuration file and then write a new file with only the configuration parameters needed.

* The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

* The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided it is a USB attached UPS.

* Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can replace 0.0.0.0 with the network address of a specific interface if all interfaces is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong ownership and permissions.

Below is an example of how to configure udev for giving NUT access to the USB attached Smart-UPS 1000.

<nowiki>
alpine:/# cd /etc/udev/rules.d

cat <<EOF >62-nut-usbups.rules
ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
EOF

alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

These are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

alpine:/# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from '''dmesg''' should tip you off as to which directory and file it is. Look at the line below from '''dmesg''' and compare the ''usb 1-3'' to the directory entry of ''/dev/bus/usb/001/003''.

usb 1-3: Manufacturer: American Power Conversion

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

alpine:/# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

alpine:/# rc-update add nut-upsd
* service nut-upsd added to runlevel default

=== Next Steps ===

NUT can be configured to do useful things like send an email or initiate a graceful shutdown when the mains power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Nut-ups

2025-09-28T18:10:02Z

Antiz: Mention the `upsc` command and give some usage examples

=== Next Steps ===

You should now be able run the <code>upsc</code> command against the name added in <code>/etc/nut/ups.conf</code> to gather all status information about your UPS (e.g. with the example from this wiki page: <code>upsc SmartUPS_1000</code>). One can also gather specific status information by passing them as an argument (e.g. <code>upsc SmartUPS_1000 battery.charge</code>). This is useful to monitor specific values and/or initiate actions (e.g. from a script) when specific thresholds are reached.

NUT itself can also be configured to do useful things like send an email or initiate a graceful shutdown when the main power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Nut-ups

2025-09-27T19:30:52Z

Antiz: Fixing path in command examples

{{Todo|The udev configuration presented here does not work consistently. A recent update and/or reboot has caused the libusb ''insufficient permissions on everything'' message to reappear. Even explicitly setting group ownership and permissions does not fix the problem.}}

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] 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 [https://www.home-assistant.io/ Home Assistant].

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. Information about the UPS can be seen with the '''dmesg''' command. See the example below.

<nowiki>
alpine:/# dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

<nowiki>
alpine:/# apk update && apk add nut

alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~

alpine:/# cat <<EOF >/etc/nut/nut.conf
MODE=netserver
EOF

alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~

alpine:/# cat <<EOF >/etc/nut/ups.conf
[SmartUPS_1000]
driver = usbhid-ups
port = auto
EOF

alpine:/# mv /etc/nut/upsd.conf /etc/nut/upsd.conf~
alpine:/# cat <<EOF >/etc/nut/upsd.conf
LISTEN 0.0.0.0 3493
EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will rename the original configuration file and then write a new file with only the configuration parameters needed.

* The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

* The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided it is a USB attached UPS.

* Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can replace 0.0.0.0 with the network address of a specific interface if all interfaces is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong ownership and permissions.

Below is an example of how to configure udev for giving NUT access to the USB attached Smart-UPS 1000.

<nowiki>
alpine:/# cd /etc/udev/rules.d

cat <<EOF >62-nut-usbups.rules
ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
EOF

alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

These are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

alpine:/# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from '''dmesg''' should tip you off as to which directory and file it is. Look at the line below from '''dmesg''' and compare the ''usb 1-3'' to the directory entry of ''/dev/bus/usb/001/003''.

usb 1-3: Manufacturer: American Power Conversion

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

alpine:/# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

alpine:/# rc-update add nut-upsd
* service nut-upsd added to runlevel default

=== Next Steps ===

NUT can be configured to do useful things like send an email or initiate a graceful shutdown when the mains power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Nut-ups

2025-09-27T19:16:24Z

Antiz: Fixing path in command examples

{{Todo|The udev configuration presented here does not work consistently. A recent update and/or reboot has caused the libusb ''insufficient permissions on everything'' message to reappear. Even explicitly setting group ownership and permissions does not fix the problem.}}

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] 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 [https://www.home-assistant.io/ Home Assistant].

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. Information about the UPS can be seen with the '''dmesg''' command. See the example below.

<nowiki>
alpine:/# dmesg
[400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
[400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
[400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
[400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
[400269.580765] usb 1-3: Manufacturer: American Power Conversion
[400269.580771] usb 1-3: SerialNumber: AS0123456789
[400269.687883] usbcore: registered new interface driver usbhid
[400269.687894] usbhid: USB HID core driver
[400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

<nowiki>
alpine:/# apk update && apk add nut

alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~

alpine:/# cat <<EOF >/etc/nut/nut.conf
MODE=netserver
EOF

alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~

alpine:/# cat <<EOF >/etc/nut/ups.conf
[SmartUPS_1000]
driver = usbhid-ups
port = auto
EOF

alpine:/# mv /etc/nut/upsd.conf /etc/nut/upsd.conf~
alpine:/# cat <<EOF >upsd.conf
LISTEN 0.0.0.0 3493
EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will rename the original configuration file and then write a new file with only the configuration parameters needed.

* The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

* The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS, and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. Make and model should not make any difference here provided it is a USB attached UPS.

* Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can replace 0.0.0.0 with the network address of a specific interface if all interfaces is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

<nowiki>
libusb1: Could not open any HID devices: insufficient permissions on everything
No matching HID UPS found
upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong ownership and permissions.

Below is an example of how to configure udev for giving NUT access to the USB attached Smart-UPS 1000.

<nowiki>
alpine:/# cd /etc/udev/rules.d

cat <<EOF >62-nut-usbups.rules
ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
EOF

alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

These are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

alpine:/# ls -l /dev/bus/usb/001/003
crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

The output from '''dmesg''' should tip you off as to which directory and file it is. Look at the line below from '''dmesg''' and compare the ''usb 1-3'' to the directory entry of ''/dev/bus/usb/001/003''.

usb 1-3: Manufacturer: American Power Conversion

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

alpine:/# rc-service nut-upsd start
* /run/nut: creating directory
* /run/nut: correcting owner
Using subdriver: APC HID 0.100
* Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

alpine:/# rc-service nut-upsd status
* status: started
alpine:/# netstat -tln | grep 3493
tcp 0 0 0.0.0.0:3493 0.0.0.0:* LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

alpine:/# rc-update add nut-upsd
* service nut-upsd added to runlevel default

=== Next Steps ===

NUT can be configured to do useful things like send an email or initiate a graceful shutdown when the mains power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.

Include:Setup your system and account for building packages

2024-10-14T15:07:00Z

Antiz: Remove outdated instructions for security keys generation: Manually copying keys to /etc/apk/keys is not necessary anymore as it's now done by the `abuild-keygen -a -i` already

The {{Pkg|alpine-sdk}} is a metapackage that pulls in the most essential packages used to build new packages. Also install and configure a way to elevate privileges, such as sudo or doas, and an editor, such as vi, nano, micro.

{{Cmd|# apk add alpine-sdk}}

This would be a good time to [[Setting_up_a_new_user|create a normal user account for you to work in]]. To make life easier later, it's a good idea to add this user to the wheel group; operations that require superuser privileges can now be done with sudo or doas.

The [[Aports_tree|aports tree]] is in git so before we clone it, let's configure git.

{{Cmd|$ git config --global user.name "Your Full Name"
$ git config --global user.email "your@email.address"}}

Read carefully [[Development using git]] to grasp basic Git operations and how to configure for sending email patches.

Now we can clone the [[Aports_tree|aports tree]].

{{Cmd|$ git clone https://gitlab.alpinelinux.org/alpine/aports}}

Before we start creating or modifying [[APKBUILD_Reference|APKBUILD]] files, we need to setup abuild for our system and user. Edit the file {{Path|/etc/abuild.conf}} to your requirements.

Most of the defaults can be left alone, unless you are developing for a custom platform, in which case the comments in the file should guide you. The one field to edit is PACKAGER, so that you can get credit (or blame) for packages you create.

To use 'abuild -r' command to install dependency packages automatically (and other 'abuild' commands that require it).
{{Cmd|# addgroup <yourusername> abuild}}

{{Note|Remember to logout and login again for the group change to have effect.}}

The last step is to configure the security keys with the [[Abuild-keygen|abuild-keygen]] script for [[Abuild and Helpers|abuild]] with the command:

{{Cmd|# abuild-keygen -a -i}}

[[Category:Development]]

Include:Setup your system and account for building packages

2024-10-14T06:58:11Z

Antiz: Remove outdated / debatable instructions to setup the cache dir: /var/cache/distfiles is created by the "abuild" package and it already belongs to root:abuild with a 775 mode. Ensuring it exists with `mkdir -p` is not so useful and setting `chmod a+w` permissions to it (basically turning it into 777) is, at the very least, highly debatable security wise. The second approach implies changing the group to "abuild" and giving it write permissions, which is useless as it's already the default.