NUT-SCANNER(8)

📦
version 2.8.5 · 18 versions
, in fedora 43, fedora 44

✨ NUT-SCANNER(8) ✨

okay bestie, pull up a chair 🫶 this is nut-scanner, part of the NUT Manual, and it's literally the little detective that goes snooping around your buses to find NUT devices. iykyk.

🌸 NAME 🌸

nut-scanner — the tool that scans communication buses looking for NUT devices 💖

🎀 SYNOPSIS 🎀

nut-scanner -h

nut-scanner [OPTIONS]

🦋 DESCRIPTION 🦋

so basically nut-scanner goes and scans all the communication buses it can reach, and then shows you every NUT-compatible device it found. no cap. 🔥

it can also hand you those detected devices in a bunch of different formats — including ups.conf — and it makes sure the device names it generates are unique across all the buses. slay 💅

🌈 INSTALLATION 🌈

lowkey important: nut-scanner only gets built if libltdl is available (that's part of the libtool development suite, bestie).

which scanning options you actually get (USB, SNMP, IPMI, UPower, …) depends on your compile-time and run-time dependencies. like, for example: if Net-SNMP is installed — so you've got the libsnmp libraries (*.so or *.dll) and the header files at compile time, plus at least the library files on the monitoring system — then SNMP discovery is available ✨. same energy with UPower discovery, which needs GDBus/libgio libraries.

💜 OPTIONS 💜

  • -h — shows you the help text. that's it, that's the whole vibe 🎀

🌟 DISPLAY OPTIONS 🌟

  • -Q | --disp_nut_conf_with_sanity_check — spits the result out in ups.conf format, with sanity-check warnings (if there are any) dropped in as comments. this is the default, bestie ✨
  • -N | --disp_nut_conf — spits the result out in ups.conf format, no extras.
  • -P | --disp_parsable — spits the result out in a parsable format.

🚌 BUS OPTIONS 🚌

  • -C | --complete_scan — scan every available communication bus (this is the default behavior 👑)
  • -U | --usb_scan — list all the NUT-compatible USB devices that are plugged in right now 🔌

you can pass this option several times for more hardware link-specific details. heads up though: those details can be counter-productive if USB enumeration changes over time 😭

  • -U — do not report any bus/device/busport details
  • -UU — report bus and busport, if available
  • -UUU — report bus/device/busport details
  • -UUUU — report bus/device/busport details, and bcdDevice (limited use and benefit)
Note for reliability, it's preferable to match just by vendor and product identification, plus a serial number if one's available and unique. fr fr 🙏
  • -S | --snmp_scan — scan SNMP devices. needs at least a start IP, and optionally an end IP. peep the specific SNMP OPTIONS below for community and security settings 👀
  • -M | --xml_scan — scan XML/HTTP devices. it can broadcast a network message on the current network interface(s) to retrieve XML/HTTP capable devices. no IP required in this mode 🎉 if IP address ranges are specified though, those get scanned instead of a broadcast.
  • -O | --oldnut_scan — scan NUT devices (aka the upsd daemon) on IP ranging from start IP to end IP.
  • -n | --nut_simulation_scan — scan NUT simulated devices (.dev files in the built-in "sysconfig" location).
Warning the NUT_CONFPATH environment variable override is not currently supported. don't come for me, that's just how it is 💀
  • -A | --avahi_scan — scan NUT servers using an Avahi request on the current network interface(s). no IP address options are required or used 🚫
  • -I | --ipmi_scan — scan NUT compatible power supplies available via IPMI on the current host, or over the network if IP address ranges are specified.
  • -J | --upower_scan — scan UPower devices. requires GDBus/libgio libraries to be available.
  • -E | --eaton_serial serial ports — scan Eaton devices (XCP and SHUT) available via the serial bus on the current host. this option must be requested explicitly, even for a complete scan 👑 serial ports can be expressed in various forms:
    • auto to scan all serial ports.
    • a single character indicating a port number (0 (zero) for /dev/ttyS0 and /dev/ttyUSB0 on Linux, 1 for COM1 on Windows, a for /dev/ttya on Solaris…)
    • a range of N characters, hyphen separated, describing the range of ports using X-Y syntax, where X and Y are characters referring to the port number.
    • a single port name.
    • a list of ports name, comma separated, like /dev/ttyS1,/dev/ttyS4.

🌐 NETWORK OPTIONS 🌐

Note the networked buses (like SNMP, NetXML, IPMI and "Old NUT") let you specify several IP (IPv4 or IPv6) address ranges, all the way down to individual single IP addresses. normally a new range is specified by a set of one -s and one -e option following each other (in any order on the command line). lone or consecutive -s or -e options present on the command line would translate to single-IP queries. also, a -m option squashed between two -s and -e options would be a new range, turning those two into single-IP queries. this feature does not by itself recombine "neighboring" addresses into one range, nor even check for duplicate or overlapping specifications 🙈 a single-address range may be a host name which would be resolved into one IP address by the system resolver. a CIDR using a host name and netmask length would be resolved into an IP address and subjected to the mask application, to query hosts "near" the named one.

also note that some buses require IP address(es) to scan, and others have a different behavior when exactly no addresses are specified (it is not currently possible to mix the two behaviors in one invocation of the nut-scanner tool 😭).

finally, note that currently even if multi-threaded support is available, each range specification is a separate fan-out of queries constrained by the timeout. requests to scan many single IP addresses will take a while to complete — much longer than if they were a single range. this will hopefully be fixed in later releases 🤞

Note colon-separated IPv6 addresses must be passed in square brackets 🎀
  • -t | --timeout timeout — set the network timeout in seconds. default timeout is 5 seconds ⏱️
  • -s | --start_ip start IP — set the first IP (IPv4 or IPv6) when a range of IP is required (SNMP, old_nut) or optional (XML/HTTP).
  • -e | --end_ip end IP — set the last IP (IPv4 or IPv6) when a range of IP is required (SNMP, old_nut) or optional (XML/HTTP). if this parameter is omitted, only the start IP is scanned. if end IP is less than start IP, both parameters are internally permuted 🔄
  • -m | --mask_cidr IP address/mask — set a range of IP addresses by using CIDR notation.

a special form -m auto allows nut-scanner to detect local IP address(es) and scan corresponding subnet(s) on supported platforms, and -m auto4 or -m auto6 limits the selected addresses to IPv4 and IPv6 respectively. only the first "auto*" request would be honoured, others ignored with a warning ⚠️

an /ADDRLEN suffix can be added to the option, to filter out discovered subnets with too many bits available for the host address part (avoiding millions of scans in the extreme cases 😳). for example, if the IPv4 network range of your LAN is 10.2.3.0/24, its address part is (32-24)=8. note that while this is applied to IPv6 networks also, their typical /64 subnets are not likely to have a NUT/SNMP/NetXML/... server that close nearby (in addressing terms), for a tight filter to find them. default is 8.

🔋 NUT DEVICE OPTION 🔋

  • -p | --port port number — set the port number of scanned NUT devices (default 3493).

🍓 SNMP V1 OPTION 🍓

  • -c | --community community — set SNMP v1 community name (default = public).

👑 SNMP V3 OPTIONS 👑

  • -l | --secLevel security level — set the security level used for SNMPv3 messages. allowed values are: noAuthNoPriv, authNoPriv and authPriv. this parameter is mandatory if you use non-trivial authentication 🔐
  • -u | --secName security name — set the security name used for authenticated SNMPv3 messages. this parameter is mandatory if you set security level.
  • -w | --authProtocol authentication protocol — set the authentication protocol used for authenticated SNMPv3 messages. allowed values are MD5, SHA, SHA256, SHA384 or SHA512 (depending on Net-SNMP library capabilities; check the help of the nut-scanner binary program for the run-time supported list 👀). default value is MD5.
  • -W | --authPassword authentication pass phrase — set the authentication pass phrase used for authenticated SNMPv3 messages. this parameter is mandatory if you set security level to authNoPriv or authPriv.
  • -x | --privProtocol privacy protocol — set the privacy protocol used for encrypted SNMPv3 messages. allowed values are DES, AES, AES192 or AES256 (depending on Net-SNMP library capabilities; check the help of the nut-scanner binary program for the run-time supported list 👀). default value is DES.
  • -X | --privPassword privacy pass phrase — set the privacy pass phrase used for encrypted SNMPv3 messages. this parameter is mandatory if you set security level to authPriv.

💀 IPMI OPTIONS 💀

Okay bestie, this is the remote-management-over-the-network corner of the house, and she is particular. Read every line, fr fr.

  • -b, --username username — Sets the username used for authenticating IPMI over LAN connections. This one is mandatory for IPMI over LAN, and there is no default — so if you leave it out, it's giving nothing and you get nothing. 🙈
  • -B, --password password — The password you authenticate with against the remote host. Also mandatory for IPMI over LAN, also no default. Yes you need both. No, it can't be skipped. 💅
  • -d, --authType authentication type — Picks the IPMI 1.5 authentication type to use with the remote host. Your options are NONE, STRAIGHT_PASSWORD_KEY, MD2, and MD5 (default is MD5). Heads up though: this forces the connection through the lan IPMI interface, so you're locked into IPMI 1.5 mode. No take-backs. 🔒
  • -L, --cipher_suite_id cipher suite identifier — Specifies the IPMI 2.0 cipher suite ID. A Cipher Suite ID is basically a whole fit — it bundles together a set of authentication, integrity, and confidentiality algorithms for IPMI 2.0 communication. Default is 3.

So what do those three things actually do? Let me break it down like a group chat:

  • the authentication algorithm decides what's used for session setup
  • the integrity algorithm decides what's used for session packet signatures
  • the confidentiality algorithm decides what's used for payload encryption

And here are the cipher suite ids currently supported, laid out as (Authentication; Integrity; Confidentiality):

  • 0: None; None; None
  • 1: HMAC-SHA1; None; None
  • 2: HMAC-SHA1; HMAC-SHA1-96; None
  • 3: HMAC-SHA1; HMAC-SHA1-96; AES-CBC-128
  • 6: HMAC-MD5; None; None
  • 7: HMAC-MD5; HMAC-MD5-128; None
  • 8: HMAC-MD5; HMAC-MD5-128; AES-CBC-128
  • 11: HMAC-MD5; MD5-128; None
  • 12: HMAC-MD5; MD5-128; AES-CBC-128
  • 15: HMAC-SHA256; None; None
  • 16: HMAC-SHA256; HMAC_SHA256_128; None
  • 17: HMAC-SHA256; HMAC_SHA256_128; AES-CBC-128

✨ MISCELLANEOUS OPTIONS ✨

The lil odds and ends that didn't fit anywhere else but still absolutely eat. 🍓

  • -V, --version — Displays the NUT version. That's it, that's the whole job. 👑
  • -a, --available — Displays the available buses that can be scanned, which depends entirely on how the nut-scanner binary program got compiled. (e.g. OLDNUT, USB, SNMP, XML, AVAHI, IPMI). Basically a vibe check of what your build can even do. 🌈
  • -q, --quiet — Displays only the scan result. No info about the bus currently being scanned, nothing extra. Minimal, clean, demure. 🤫
  • -D, --nut_debug_level — Raises the debugging level. Use it multiple times to see more and more details. Spam it like you're spamming a bestie. 🔥
Note 📝 The level of debugging you actually need depends on both nut-scanner and the specific problem you're trying to diagnose. So please, first explain the problem you're having with nut-scanner to a developer/maintainer before sending them debugging output. More often than not, if you just pick a level on your own, the output may be either too limited or too verbose to be of any use. Like, genuinely. Ask first, dump logs later. 🙏

🌸 EXAMPLES 🌸

Here's the part where we show you the moves. Copy these, run these, live your truth. 💖

To scan USB devices only:

:; nut-scanner -U

[nutdev-usb1]
        driver = "snmp-ups"
        port = "192.168.0.42"

To scan SNMP v1 device with public (default) community on address range 192.168.0.0 to 192.168.0.255:

:; nut-scanner -S -s 192.168.0.0 -e 192.168.0.255

[nutdev-snmp1]
        driver = "snmp-ups"
        port = "192.168.0.42"

The same using CIDR notation:

:; nut-scanner -S -m 192.168.0.0/24

[nutdev-snmp1]
        driver = "snmp-ups"
        port = "192.168.0.42"

To scan NUT servers with a timeout of 10 seconds on IP range 192.168.0.0 to 192.168.0.127 using CIDR notation:

:; nut-scanner -O -t 10 -m 192.168.0.0/25

[nutdev-nut1]
        driver = "dummy-ups"
        port = "dummy-test@192.168.1.28"

To scan for power supplies, through IPMI (1.5 mode) over the network, on address range 192.168.0.0 to 192.168.0.255 using CIDR notation:

:; nut-scanner -I -m 192.168.0.0/24 -b username -B password

To scan for Eaton serial devices on ports 0 and 1 (/dev/ttyS0, /dev/ttyUSB0, /dev/ttyS1 and /dev/ttyUSB1 on Linux):

:; nut-scanner --eaton_serial 0-1

To scan for Eaton serial devices on ports 1 and 2 (COM1 and COM2 on Windows):

:; nut-scanner --eaton_serial 1-2

To scan for UPower devices:

:; nut-scanner -J

[nutdev-upower1]
        driver = "upower"
        port = "/org/freedesktop/UPower/devices/ups_hiddev0"
        vendor = "APC"
        product = "Back-UPS ES 700G"
        serial = "5B1234567890"
        bus = "upower"

👀 SEE ALSO 👀

🌐 Internet resources:

okay that's the whole page bestie, you made it to the end and I'm so proud of you 🫶 this was Network UPS Tools 2.8.5, dated 10/07/2026 — that's NUT-SCANNER(8), signed, sealed, slayed. go scan something iconic. 💅✨🎀

📦 where this page comes from