some of these data will be redundant with ups.* information during a transition period. The ups.* data will then be removed.
| Name | Description | Example value |
|---|---|---|
device.model | Device model | BladeUPS |
device.mfr | Device manufacturer | Eaton |
device.serial | Device serial number (opaque string) | WS9643050926 |
device.type | Device type (ups, pdu, scd, psu, ats) | ups |
device.description | Device description (opaque string) | Some ups |
device.contact | Device administrator name (opaque string) | John Doe |
device.location | Device physical location (opaque string) | 1st floor |
device.part | Device part number (opaque string) | 123456789 |
device.macaddr | Physical network address of the device | 68:b5:99:f5:89:27 |
device.uptime | Device uptime in seconds | 1782 |
device.count | Total number of daisychained devices | 1 |
When present, device.count implies daisychain support. For more
information, refer to the NUT daisychain support notes chapter
of the user manual and developer guide.
| Name | Description | Example value |
|---|---|---|
ups.status | UPS status | |
ups.alarm | UPS alarms | OVERHEAT |
ups.time | Internal UPS clock time (opaque string) | 12:34 |
ups.date | Internal UPS clock date (opaque string) | 01-02-03 |
ups.model | UPS model | SMART-UPS 700 |
ups.mfr | UPS manufacturer | APC |
ups.mfr.date | UPS manufacturing date (opaque string) | 10/17/96 |
ups.serial | UPS serial number (opaque string) | WS9643050926 |
ups.vendorid | Vendor ID for USB devices | 0463 |
ups.productid | Product ID for USB devices | 0001 |
ups.firmware | UPS firmware (opaque string) | 50.9.D |
ups.firmware.aux | Auxiliary device firmware | 4Kx |
ups.temperature | UPS temperature (degrees C) | 042.7 |
ups.load | Load on UPS (percent) | 023.4 |
ups.load.high | Load when UPS switches to overload condition ("OVER") (percent) | 100 |
ups.id | UPS system identifier (opaque string) | Sierra |
ups.delay.start | Interval to wait before restarting the load (seconds) | 0 |
ups.delay.reboot | Interval to wait before rebooting the UPS (seconds) | 60 |
ups.delay.shutdown | Interval to wait after shutdown with delay command (seconds) | 20 |
ups.timer.start | Time before the load will be started (seconds) | 30 |
ups.timer.reboot | Time before the load will be rebooted (seconds) | 10 |
ups.timer.shutdown | Time before the load will be shutdown (seconds) | 20 |
ups.test.interval | Interval between self tests (seconds) | 1209600 (two weeks) |
ups.test.result | Results of last self test (opaque string) | Bad battery pack |
ups.test.date | Date of last self test (opaque string) | 07/17/12 |
ups.display.language | Language to use on front panel (* opaque) | E |
ups.contacts | UPS external contact sensors (* opaque) | F0 |
ups.efficiency | Efficiency of the UPS (ratio of the output current on the input current) (percent) | 95 |
ups.power | Current value of apparent power (Volt-Amps) | 500 |
ups.power.nominal | Nominal value of apparent power (Volt-Amps) | 500 |
ups.realpower | Current value of real power (Watts) | 300 |
ups.realpower.nominal | Nominal value of real power (Watts) | 300 |
ups.beeper.status | UPS beeper status (enabled, disabled or muted) | enabled |
ups.type | UPS type (* opaque) | offline |
ups.watchdog.status | UPS watchdog status (enabled or disabled) | disabled |
ups.start.auto | UPS starts when mains is (re)applied | yes |
ups.start.battery | Allow to start UPS from battery | yes |
ups.start.reboot | UPS coldstarts from battery (enabled or disabled) | yes |
ups.shutdown | Enable or disable UPS shutdown ability (poweroff) | enabled |
When present, the value of ups.start.auto has an impact on
shutdown.* commands. For the sake of coherence, shutdown commands
will set ups.start.auto to the right value before issuing the command.
That is, shutdown.stayoff will first set ups.start.auto to no,
while shutdown.return will set it to yes.
When possible, time-stamps and dates should be expressed as detailed above in the Time and Date format chapter.
| Name | Description | Example value |
|---|---|---|
input.voltage | Input voltage (V) | 121.5 |
input.voltage.maximum | Maximum incoming voltage seen (V) | 130 |
input.voltage.minimum | Minimum incoming voltage seen (V) | 100 |
input.voltage.status | Status relative to the thresholds | critical-low |
input.voltage.low.warning | Low warning threshold (V) | 205 |
input.voltage.low.critical | Low critical threshold (V) | 200 |
input.voltage.high.warning | High warning threshold (V) | 230 |
input.voltage.high.critical | High critical threshold (V) | 240 |
input.voltage.nominal | Nominal input voltage (V) | 120 |
input.voltage.extended | Extended input voltage range | no |
input.transfer.delay | Delay before transfer to mains (seconds) | 60 |
input.transfer.reason | Reason for last transfer to battery (* opaque) | T |
input.transfer.low | Low voltage transfer point (V) | 91 |
input.transfer.high | High voltage transfer point (V) | 132 |
input.transfer.low.min | smallest settable low voltage transfer point (V) | 85 |
input.transfer.low.max | greatest settable low voltage transfer point (V) | 95 |
input.transfer.high.min | smallest settable high voltage transfer point (V) | 131 |
input.transfer.high.max | greatest settable high voltage transfer point (V) | 136 |
input.eco.switchable | Input High Efficiency (aka ECO) mode switch (0-2) | normal |
input.sensitivity | Input power sensitivity | H (high) |
input.quality | Input power quality (* opaque) | FF |
input.current | Input current (A) | 4.25 |
input.current.nominal | Nominal input current (A) | 5.0 |
input.current.status | Status relative to the thresholds | critical-high |
input.current.low.warning | Low warning threshold (A) | 4 |
input.current.low.critical | Low critical threshold (A) | 2 |
input.current.high.warning | High warning threshold (A) | 10 |
input.current.high.critical | High critical threshold (A) | 12 |
input.feed.color | Color of the input feed (opaque string) | 3831236 |
input.feed.desc | Description of the input feed | Feed A |
input.frequency | Input line frequency (Hz) | 60.00 |
input.frequency.nominal | Nominal input line frequency (Hz) | 60 |
input.frequency.status | Frequency status | out-of-range |
input.frequency.low | Input line frequency low (Hz) | 47 |
input.frequency.high | Input line frequency high (Hz) | 63 |
input.frequency.extended | Extended input frequency range | no |
input.transfer.boost.low | Low voltage boosting transfer point (V) | 190 |
input.transfer.boost.high | High voltage boosting transfer point (V) | 210 |
input.transfer.trim.low | Low voltage trimming transfer point (V) | 230 |
input.transfer.trim.high | High voltage trimming transfer point (V) | 240 |
input.transfer.eco.low | Low voltage ECO transfer point (V) | 218 |
input.transfer.bypass.low | Low voltage Bypass transfer point (V) | 184 |
input.transfer.eco.high | High voltage ECO transfer point (V) | 241 |
input.transfer.bypass.high | High voltage Bypass transfer point (V) | 264 |
input.transfer.frequency.bypass.range | Frequency range Bypass transfer point (percent of nominal Hz) | 10 |
input.transfer.frequency.eco.range | Frequency range ECO transfer point (percent of nominal Hz) | 5 |
input.transfer.hysteresis | Threshold of switching protection modes, voltage transfer point (V) | 10 |
input.transfer.forced | Input forced transfer modes (enabled or disabled) | enabled |
input.bypass.switch.on | Put the UPS in bypass mode | on |
input.bypass.switch.off | Take the UPS out of bypass mode | disabled |
input.load | Load on (ePDU) input (percent of full) | 25 |
input.realpower | Current sum value of all (ePDU) phases real power (W) | 300 |
input.realpower.nominal | Nominal sum value of all (ePDU) phases real power (W) | 850 |
input.power | Current sum value of all (ePDU) phases apparent power (VA) | 500 |
input.source | The current input power source | 1 |
input.source.preferred | The preferred power source | 1 |
input.phase.shift | Voltage dephasing between input sources (degrees) | 181 |
The input voltage hysteresis concept refers to a specific behavior related to how some UPS models can handle changes in input voltage.
When the UPS is running normally (powered by utility or generator), it maintains a steady output voltage for your critical equipment. But what if the input voltage "wiggles" a bit due to fluctuations or other minor disturbances?
Rapid switching between UPS protection modes (utility power to battery and vice versa) can stress both the UPS and its connected devices.
So, some UPS models set up thresholds: If the input voltage drops below a certain "Low" level, the UPS won’t immediately switch to battery mode. Instead, it waits until it is sure the voltage stays consistently low for a bit. Similarly, if the input voltage rises above another threshold (the "High" level), the UPS won’t rush back to normal mode. It waits for stability.
By introducing hysteresis, such an UPS avoids unnecessary toggling, ensuring smoother transitions and better protection for your sensitive and expensive gear.
| Name | Description | Example value |
|---|---|---|
output.voltage | Output voltage (V) | 120.9 |
output.voltage.nominal | Nominal output voltage (V) | 120 |
output.frequency | Output frequency (Hz) | 59.9 |
output.frequency.nominal | Nominal output frequency (Hz) | 60 |
output.current | Output current (A) | 4.25 |
output.current.nominal | Nominal output current (A) | 5.0 |
The additions for three-phase measurements would produce a very long table due to all the combinations that are possible, so these additions are broken down to their base components.
input.phases (3 for three-phase, absent or 1 for 1phase)
output.phases (as for input.phases)
Any input or output is considered a valid DOMAIN.
input (should really be called input.mains, but keep this for compat)
output (should really be called output.load, but keep this for compat)
Voltage, current, frequency, etc are considered to be a specification of the measurement.
With this notation, the old 1phase naming scheme becomes DOMAIN.SPEC
Example: input.current
When in three-phase mode, we need some way to specify the target for most measurements in more detail. We call this the CONTEXT.
With this notation, the naming scheme becomes DOMAIN.CONTEXT.SPEC when in three-phase mode.
Example: input.L1.current
L1-L2 \ L2-L3 \ L3-L1 for voltage measurements L1-N / L2-N / L3-N /
L1 \ L2 for current and power measurements L3 / N - for current measurement
For cursory readers — the following couple of tables lists just the
short SPEC component of the larger DOMAIN.CONTEXT.SPEC naming scheme
for phase-aware values, as discussed in other sections of this chapter.
Valid with/without context (i.e. per phase or aggregated/averaged)
| Name | Description |
|---|---|
alarm | Alarms for phases, published in ups.alarm |
current | Current (A) |
current.maximum | Maximum seen current (A) |
current.minimum | Minimum seen current (A) |
current.status | Status relative to the thresholds |
current.low.warning | Low warning threshold (A) |
current.low.critical | Low critical threshold (A) |
current.high.warning | High warning threshold (A) |
current.high.critical | High critical threshold (A) |
current.peak | Peak current |
voltage | Voltage (V) |
voltage.nominal | Nominal voltage (V) |
voltage.maximum | Maximum seen voltage (V) |
voltage.minimum | Minimum seen voltage (V) |
voltage.status | Status relative to the thresholds |
voltage.low.warning | Low warning threshold (V) |
voltage.low.critical | Low critical threshold (V) |
voltage.high.warning | High warning threshold (V) |
voltage.high.critical | High critical threshold (V) |
power | Apparent power (VA) |
power.maximum | Maximum seen apparent power (VA) |
power.minimum | Minimum seen apparent power (VA) |
power.percent | Percentage of apparent power related to maximum load |
power.maximum.percent | Maximum seen percentage of apparent power |
power.minimum.percent | Minimum seen percentage of apparent power |
realpower | Real power (W) |
powerfactor | Power Factor (dimensionless value between 0.00 and 1.00) |
crestfactor | Crest Factor (dimensionless value greater or equal to 1) |
load | Load on (ePDU) input |
Valid without context (i.e. aggregation of all phases):
| Name | Description |
|---|---|
frequency | Frequency (Hz) |
frequency.nominal | Nominal frequency (Hz) |
realpower | Current value of real power (Watts) |
power | Current value of apparent power (Volt-Amps) |
Partial Three phase — Three phase example:
input.phases: 3 input.frequency: 50.0 input.L1.current: 133.0 input.bypass.L1-L2.voltage: 398.3 output.phases: 3 output.L1.power: 35700 output.powerfactor: 0.82
Partial Three phase — One phase example:
input.phases: 3 input.L2.current: 48.2 input.N.current: 3.4 input.L3-L1.voltage: 405.4 input.frequency: 50.1 output.phases: 1 output.current: 244.2 output.voltage: 120 output.frequency.nominal: 60.0
| Name | Description | Example value |
|---|---|---|
battery.charge | Battery charge (percent) | 100.0 |
battery.charge.approx | Rough approximation of battery charge (opaque, percent) | <85 |
battery.charge.low | Remaining battery level when UPS switches to LB (percent) | 20 |
battery.charge.restart | Minimum battery level for UPS restart after power-off | 20 |
battery.charge.warning | Battery level when UPS switches to "Warning" state (percent) | 50 |
battery.charger.status | Status of the battery charger (see the note below) | charging |
battery.voltage | Battery voltage (V) | 24.84 |
battery.voltage.cell.max | Maximum battery voltage seen of the Li-ion cell (V) | 3.44 |
battery.voltage.cell.min | Minimum battery voltage seen of the Li-ion cell (V) | 3.41 |
battery.voltage.nominal | Nominal battery voltage (V) | 024 |
battery.voltage.low | Minimum battery voltage, that triggers FSD status | 21,52 |
battery.voltage.high | Maximum battery voltage (i.e. battery.charge = 100) | 26,9 |
battery.capacity | Battery capacity (Ah) | 7.2 |
battery.capacity.nominal | Nominal battery capacity (Ah) | 8.0 |
battery.current | Battery current (A) | 1.19 |
battery.current.total | Total battery current (A) | 1.19 |
battery.status | Health status of the battery (opaque string) | ok |
battery.temperature | Battery temperature (degrees C) | 050.7 |
battery.temperature.cell.max | Maximum battery temperature seen of the Li-ion cell (degrees C) | 25.85 |
battery.temperature.cell.min | Minimum battery temperature seen of the Li-ion cell (degrees C) | 24.85 |
battery.runtime | Battery runtime (seconds) | 1080 |
battery.runtime.low | Remaining battery runtime when UPS switches to LB (seconds) | 180 |
battery.runtime.restart | Minimum battery runtime for UPS restart after power-off (seconds) | 120 |
battery.alarm.threshold | Battery alarm threshold | 0 (immediate) |
battery.date | Battery installation or last change date (opaque string) | 11/14/20 |
battery.date.maintenance | Battery next change or maintenance date (opaque string) | 11/13/24 |
battery.mfr.date | Battery manufacturing date (opaque string) | 2005/04/02 |
battery.packs | Number of internal battery packs | 1 |
battery.packs.bad | Number of bad battery packs | 0 |
battery.packs.external | Number of external battery packs | 1 |
battery.type | Battery chemistry (opaque string) | PbAc |
battery.protection | Prevent deep discharge of battery | yes |
battery.energysave | Switch off when running on battery and no/low load | no |
battery.energysave.load | Switch off UPS if on battery and load level lower (percent) | 5 |
battery.energysave.delay | Delay before switch off UPS if on battery and load level low (min) | 3 |
battery.energysave.realpower | Switch off UPS if on battery and load level lower (Watts) | 10 |
NOTE:
battery.charger.status replaces the historic flags CHRG and DISCHRG
that were exposed through ups.status.
The battery.charger.status can have one of the following values:
charging: battery is charging,
discharging: battery is discharging,
floating: battery has completed its charge cycle,
and waiting to go to resting mode,
resting: the battery is fully charged, and not charging nor discharging.
When possible, time-stamps and dates should be expressed as detailed above in the Time and Date format chapter.
n stands for the sensors index. A special case is "ambient.0" which is equivalent to "ambient" (without index), and represents the default sensor of the device. This is not to be confused with the device embedded sensor, which is published as ups.temperature. The most important data is "ambient.count", used to iterate over the whole set of outlets. For more information, refer to the NUT sensors management notes chapter of the user manual.
| Name | Description | Example value |
|---|---|---|
ambient.count | Total number of sensors | 2 |
ambient.n.name | Ambient sensor name | sensor 1 |
ambient.n.id | Ambient sensor identifier (opaque string) | 80f09325-2838-5637-b62a-cef9cbe2747 |
ambient.n.address | Ambient sensor address (opaque string) | 1 |
ambient.n.parent.serial | Ambient sensor parent serial number (opaque string) | U603E34000 |
ambient.n.mfr | Ambient sensor manufacturer | EATON |
ambient.n.model | Ambient sensor model | EMPDT1H1C2 |
ambient.n.firmware | Ambient sensor firmware | 01.03.0011 |
ambient.n.present | Ambient sensor presence | yes |
ambient.n.temperature | Ambient temperature (degrees C) | 25.40 |
ambient.n.temperature.alarm | Temperature alarm (enabled/disabled) | enabled |
ambient.n.temperature.status | Ambient temperature status relative to the thresholds | warning-low |
ambient.n.temperature.high | Temperature threshold high (degrees C) | 60 |
ambient.n.temperature.high.warning | Temperature threshold high warning (degrees C) | 40 |
ambient.n.temperature.high.critical | Temperature threshold high critical (degrees C) | 60 |
ambient.n.temperature.low | Temperature threshold low (degrees C) | 5 |
ambient.n.temperature.low.warning | Temperature threshold low warning (degrees C) | 10 |
ambient.n.temperature.low.critical | Temperature threshold low critical (degrees C) | 5 |
ambient.n.temperature.maximum | Maximum temperature seen (degrees C) | 37.6 |
ambient.n.temperature.minimum | Minimum temperature seen (degrees C) | 18.1 |
ambient.n.humidity | Ambient relative humidity (percent) | 038.8 |
ambient.n.humidity.alarm | Relative humidity alarm (enabled/disabled) | enabled |
ambient.n.humidity.status | Ambient humidity status relative to the thresholds | warning-low |
ambient.n.humidity.high | Relative humidity threshold high (percent) | 80 |
ambient.n.humidity.high.warning | Relative humidity threshold high warning (percent) | 70 |
ambient.n.humidity.high.critical | Relative humidity threshold high critical (percent) | 80 |
ambient.n.humidity.low | Relative humidity threshold low (percent) | 10 |
ambient.n.humidity.low.warning | Relative humidity threshold low warning (percent) | 20 |
ambient.n.humidity.low.critical | Relative humidity threshold low critical (percent) | 10 |
ambient.n.humidity.maximum | Maximum relative humidity seen (percent) | 60 |
ambient.n.humidity.minimum | Minimum relative humidity seen (percent) | 13 |
ambient.n.contacts.x.status | State of the dry contact sensor x | open |
ambient.n.contacts.x.config | Configuration of the dry contact sensor x | normal-open |
ambient.n.contacts.x.name | Name of the dry contact sensor x | smoke-detector1 |
NOTE: - ambient.n.contacts.x.status may either be the raw status (open or closed), or may relate to ambient.n.contacts.x.config. In this case, the value can be active or inactive.
n stands for the outlet index. A special case is "outlet.0" which is equivalent to "outlet" (without index), and represent the whole set of outlets of the device. The most important data is "outlet.count", used to iterate over the whole set of outlets. For more information, refer to the NUT outlets management and PDU notes chapter of the user manual.
| Name | Description | Example value |
|---|---|---|
outlet.count | Total number of outlets | 12 |
outlet.switchable | General outlet switch ability of the unit (yes/no) | yes |
outlet.n.id | Outlet system identifier (opaque string) | 1 |
outlet.n.name | Outlet name (opaque string) | A1 |
outlet.n.desc | Outlet description (opaque string) | Main outlet |
outlet.n.groupid | Identifier of the group to which the outlet belongs to | 1 |
outlet.n.switch | Outlet switch control (on/off) | on |
outlet.n.status | Outlet switch status (on/off) | on |
outlet.n.protect.status | Outlet protection status (0-2) | protected |
outlet.n.alarm | Alarms for outlets and PDU, published in ups.alarm | outlet 1 low voltage warning |
outlet.n.switchable | Outlet switch ability (yes/no) | yes |
outlet.n.ecocontrol | Master Outlet used to automatically power off the slave outlets | The outlet is not ECO controlled |
outlet.n.autoswitch.charge.low | Remaining battery level to power off this outlet (percent) | 80 |
outlet.n.battery.charge.low | Remaining battery level to power off this outlet (percent) | 80 |
outlet.n.delay.shutdown | Interval to wait before shutting down this outlet (seconds) | 180 |
outlet.n.delay.start | Interval to wait before restarting this outlet (seconds) | 120 |
outlet.n.timer.shutdown | Time before the outlet load will be shutdown (seconds) | 20 |
outlet.n.timer.start | Time before the outlet load will be started (seconds) | 30 |
outlet.n.current | Current (A) | 0.19 |
outlet.n.current.maximum | Maximum seen current (A) | 0.56 |
outlet.n.current.status | Current status relative to the thresholds | good |
outlet.n.current.low.warning | Low warning threshold (A) | 0.10 |
outlet.n.current.low.critical | Low critical threshold (A) | 0.05 |
outlet.n.current.high.warning | High warning threshold (A) | 0.30 |
outlet.n.current.high.critical | High critical threshold (A) | 0.40 |
outlet.n.realpower | Current value of real power (W) | 28 |
outlet.n.voltage | Voltage (V) | 247.0 |
outlet.n.voltage.status | Voltage status relative to the thresholds | good |
outlet.n.voltage.low.warning | Low warning threshold (V) | 205 |
outlet.n.voltage.low.critical | Low critical threshold (V) | 200 |
outlet.n.voltage.high.warning | High warning threshold (V) | 230 |
outlet.n.voltage.high.critical | High critical threshold (V) | 240 |
outlet.n.powerfactor | Power Factor (dimensionless, value between 0 and 1) | 0.85 |
outlet.n.crestfactor | Crest Factor (dimensionless, equal to or greater than 1) | 1.41 |
outlet.n.power | Apparent power (VA) | 46 |
outlet.n.type | Physical outlet type | french |
This is a refinement of the outlet collection, providing grouped management for a set of outlets. The same principles and data than the outlet collection apply to outlet.group, especially for the indexing n and "outlet.group.count".
Most of the data published for outlets also apply to outlet.group, including: id, name (similar as outlet "desc"), color, status, current and voltage (including status, alarm and thresholds). Other actions and settings also apply ({delay,timer}.{shutdown,start})
Some specific data to outlet groups exists:
| Name | Description | Example value |
|---|---|---|
outlet.group.n.type | Type of outlet group (OPAQUE) | outlet-section |
outlet.group.n.color | Color-coding of the outlets in this group (OPAQUE) | yellow |
outlet.group.n.count | Number of outlets in the group | 12 |
outlet.group.n.phase | Electrical phase to which the physical outlet group (Gang) is connected to | L1 |
outlet.group.n.input | Input to which an outlet group is connected | 1 |
Example:
outlet.group.1.current: 0.00 outlet.group.1.current.high.critical: 16.00 outlet.group.1.current.high.warning: 12.80 outlet.group.1.current.low.warning: 0.00 outlet.group.1.current.nominal: 16.00 outlet.group.1.current.status: good outlet.group.1.id: 1 outlet.group.1.name: Branch Circuit A outlet.group.1.phase: L1 outlet.group.1.status: on outlet.group.1.voltage: 244.23 outlet.group.1.voltage.high.critical: 265.00 outlet.group.1.voltage.high.warning: 255.00 outlet.group.1.voltage.low.critical: 180.00 outlet.group.1.voltage.low.warning: 190.00 outlet.group.1.voltage.status: good ... outlet.group.count: 3.00
| Name | Description | Example value |
|---|---|---|
driver.name | Driver name | usbhid-ups |
driver.version | Driver version (NUT release) | X.Y.Z |
driver.version.internal | Internal driver version | 1.23.45 |
driver.version.data | Version of the internal data mapping, for generic drivers | Eaton HID 1.31 |
driver.version.usb | USB library version | libusb-1.0.21 |
driver.parameter.xxx | Parameter xxx (ups.conf or cmdline -x) setting | (varies) |
driver.flag.xxx | Flag xxx (ups.conf or cmdline -x) status | enabled (or absent) |
driver.state | Current state in driver’s lifecycle, primarily to help readers discern long-running init (with full device walk) or cleanup stages from the stable working loop | init.starting, init.quiet, init.device, init.info, init.updateinfo (first walk), reconnect.trying, reconnect.updateinfo, updateinfo, quiet, dumping, cleanup.upsdrv, cleanup.exit |
| Name | Description | Example value |
|---|---|---|
server.info | Server information | Network UPS Tools upsd vX.Y.Z - https://www.networkupstools.org/ |
server.version | Server version | X.Y.Z |