Network protocol information ============================ Since May 2002, this protocol has an official port number from IANA, which is *3493*. The old number (3305) was a relic of the original code's ancestry, and conflicted with other services. Version 0.50.0 and up use 3493 by default. This protocol runs over TCP. UDP support was dropped in July 2003. It had been deprecated for some time and was only capable of the simplest query commands as authentication is impossible over a UDP socket. A library, named libupsclient, that implement this protocol is provided in both static and shared version to help the client application development. Old command removal notice -------------------------- Before version 1.5.0, a number of old commands were supported. These have been removed from the specification. For more information, consult an older version of the software. Command reference ----------------- Multi-word elements are contained within "quotes" for easier parsing. Embedded quotes are escaped with backslashes. Embedded backslashes are also escaped by representing them as \\. This protocol is intended to be interpreted with parseconf (NUT parser) or something similar. Revision history ---------------- Here's a table to present the various changes that happened to the NUT network protocol, over the time: [options="header",style="asciidoc",cols="^.^,^.^,<"] |=============================================================================== |Protocol version |NUT version |Description |1.0 |< 1.5.0 |Original protocol (legacy version) |1.1 |>= 1.5.0 |Original protocol (without old commands) .2+|1.2 .2+|>= 2.6.4 |Add "LIST CLIENTS" and "NETVER" commands |Add ranges of values for writable variables |=============================================================================== NOTE: any new version of the protocol implies an update of NUT_NETVERSION in *configure.in*. GET --- Retrieve a single response from the server. Possible sub-commands: NUMLOGINS ~~~~~~~~~ Form: GET NUMLOGINS GET NUMLOGINS su700 Response: NUMLOGINS NUMLOGINS su700 1 '' is the number of clients which have done LOGIN for this UPS. This is used by the master upsmon to determine how many clients are still connected when starting the shutdown process. This replaces the old "REQ NUMLOGINS" command. UPSDESC ~~~~~~~ Form: GET UPSDESC GET UPSDESC su700 Response: UPSDESC "" UPSDESC su700 "Development box" '' is the value of "desc=" from ups.conf for this UPS. If it is not set, upsd will return "Unavailable". This can be used to provide human-readable descriptions instead of a cryptic "upsname@hostname" string. VAR ~~~ Form: GET VAR GET VAR su700 ups.status Response: VAR "" VAR su700 ups.status "OL" This replaces the old "REQ" command. TYPE ~~~~ Form: GET TYPE GET TYPE su700 input.transfer.low Response: TYPE ... TYPE su700 input.transfer.low ENUM '' can be several values, and multiple words may be returned: - 'RW': this variable may be set to another value with SET - 'ENUM': an enumerated type, which supports a few specific values - 'STRING:n': this is a string of maximum length n - 'RANGE': this is an integer, comprised in the range (see LIST RANGE) ENUM, STRING and RANGE are usually associated with RW, but not always. The default , when omitted, is integer. This replaces the old "VARTYPE" command. DESC ~~~~ Form: GET DESC GET DESC su700 ups.status Response: DESC "" DESC su700 ups.status "UPS status" '' is a string that gives a brief explanation of the named variable. upsd may return "Unavailable" if the file which provides this description is not installed. Different versions of this file may be used in some situations to provide for localization and internationalization. This replaces the old "VARDESC" command. CMDDESC ~~~~~~~ Form: GET CMDDESC GET CMDDESC su700 load.on Response: CMDDESC "" CMDDESC su700 load.on "Turn on the load immediately" This is like DESC above, but it applies to the instant commands. This replaces the old "INSTCMDDESC" command. LIST ---- The LIST functions all share a common container format. They will return "BEGIN LIST" and then repeat the initial query. The list then follows, with as many lines are necessary to convey it. "END LIST" with the initial query attached then follows. The formatting may seem a bit redundant, but it makes a different form of client possible. You can send a LIST query and then go off and wait for it to get back to you. When it arrives, you don't need complicated state machines to remember which list is which. UPS ~~~ Form: LIST UPS Response: BEGIN LIST UPS UPS "" ... END LIST UPS BEGIN LIST UPS UPS su700 "Development box" END LIST UPS '' is a name from ups.conf, and is the value of desc= from ups.conf, if available. It will be set to "Unavailable" otherwise. This can be used to determine what values of are valid before calling other functions on the server. This is also a good way to handle situations where a single upsd supports multiple drivers. Clients which perform a UPS discovery process may find this useful. VAR ~~~ Form: LIST VAR LIST VAR su700 Response: BEGIN LIST VAR VAR "" ... END LIST VAR BEGIN LIST VAR su700 VAR su700 ups.mfr "APC" VAR su700 ups.mfr.date "10/17/96" ... END LIST VAR su700 This replaces the old "LISTVARS" command. RW ~~ Form: LIST RW LIST RW su700 Response: BEGIN LIST RW RW "" ... END LIST RW BEGIN LIST RW su700 RW su700 output.voltage.nominal "115" RW su700 ups.delay.shutdown "020" ... END LIST RW su700 This replaces the old "LISTRW" command. CMD ~~~ Form: LIST CMD LIST CMD su700 Response: BEGIN LIST CMD CMD ... END LIST CMD BEGIN LIST CMD su700 CMD su700 load.on CMD su700 test.panel.start ... END LIST CMD su700 This replaces the old "LISTINSTCMD" command. ENUM ~~~~ Form: LIST ENUM LIST ENUM su700 input.transfer.low Response: BEGIN LIST ENUM ENUM "" ... END LIST ENUM BEGIN LIST ENUM su700 input.transfer.low ENUM su700 input.transfer.low "103" ENUM su700 input.transfer.low "100" ... END LIST ENUM su700 input.transfer.low This replaces the old "ENUM" command. NOTE: this does not support the old "SELECTED" notation. You must request the current value separately. RANGE ~~~~~ Form: LIST RANGE LIST RANGE su700 input.transfer.low Response: BEGIN LIST RANGE RANGE "" "" ... END LIST RANGE BEGIN LIST RANGE su700 input.transfer.low RANGE su700 input.transfer.low "90" "100" RANGE su700 input.transfer.low "102" "105" ... END LIST RANGE su700 input.transfer.low CLIENT ~~~~~~ Form: LIST CLIENT LIST CLIENT ups1 Response: BEGIN LIST CLIENT CLIENT ... END LIST CLIENT BEGIN LIST CLIENT ups1 CLIENT ups1 ::1 CLIENT ups1 192.168.1.2 END LIST CLIENT ups1 SET --- Form: SET VAR "" SET VAR su700 ups.id "My UPS" INSTCMD ------- Form: INSTCMD INSTCMD su700 test.panel.start LOGOUT ------ Form: LOGOUT Response: OK Goodbye (recent versions) Goodbye... (older versions) Used to disconnect gracefully from the server. LOGIN ----- Form: LOGIN Response: OK (upon success) or <> NOTE: This requires "upsmon slave" or "upsmon master" in upsd.users Use this to log the fact that a system is drawing power from this UPS. The upsmon master will wait until the count of attached systems reaches 1 - itself. This allows the slaves to shut down first. NOTE: You probably shouldn't send this command unless you are upsmon, or a upsmon replacement. MASTER ------ Form: MASTER Response: OK (upon success) or <> NOTE: This requires "upsmon master" in upsd.users This function doesn't do much by itself. It is used by upsmon to make sure that master-level functions like FSD are available if necessary. FSD --- Form: FSD Response: OK FSD-SET (success) or <> NOTE: This requires "upsmon master" in upsd.users, or "FSD" action granted in upsd.users upsmon in master mode is the primary user of this function. It sets this "forced shutdown" flag on any UPS when it plans to power it off. This is done so that slave systems will know about it and shut down before the power disappears. Setting this flag makes "FSD" appear in a STATUS request for this UPS. Finding "FSD" in a status request should be treated just like a "OB LB". It should be noted that FSD is currently a latch - once set, there is no way to clear it short of restarting upsd or dropping then re-adding it in the ups.conf. This may cause issues when upsd is running on a system that is not shut down due to the UPS event. PASSWORD -------- Form: PASSWORD Response: OK (upon success) or <> Sets the password associated with a connection. Used for later authentication for commands that require it. USERNAME -------- Form: USERNAME Response: OK (upon success) or <> Sets the username associated with a connection. This is also used for authentication, specifically in conjunction with the upsd.users file. STARTTLS -------- Form: STARTTLS Response: OK STARTTLS or <> This tells upsd to switch to TLS mode internally, so all future communications will be encrypted. You must also change to TLS mode in the client after receiving the OK, or the connection will be useless. Other commands -------------- - HELP: lists the commands supported by this server - VER: shows the version of the server currently in use - NETVER: shows the version of the network protocol currently in use These three are not intended to be used directly by programs. Humans can make use of this program by using telnet or netcat. If you use telnet, make sure you don't have it set to negotiate extra options. upsd doesn't speak telnet and will probably misunderstand your first request due to the extra junk in the buffer. Error responses --------------- An error response has the following format: ERR [...] is always one element; it never contains spaces. This may be used to allow additional information () in the future. can have the following values: - 'ACCESS-DENIED' + The client's host and/or authentication details (username, password) are not sufficient to execute the requested command. - 'UNKNOWN-UPS' + The UPS specified in the request is not known to upsd. This usually means that it didn't match anything in ups.conf. - 'VAR-NOT-SUPPORTED' + The specified UPS doesn't support the variable in the request. + This is also sent for unrecognized variables which are in a space which is handled by upsd, such as server.*. - 'CMD-NOT-SUPPORTED' + The specified UPS doesn't support the instant command in the request. - 'INVALID-ARGUMENT' + The client sent an argument to a command which is not recognized or is otherwise invalid in this context. This is typically caused by sending a valid command like GET with an invalid subcommand. - 'INSTCMD-FAILED' + upsd failed to deliver the instant command request to the driver. No further information is available to the client. This typically indicates a dead or broken driver. - 'SET-FAILED' + upsd failed to deliver the set request to the driver. This is just like INSTCMD-FAILED above. - 'READONLY' + The requested variable in a SET command is not writable. - 'TOO-LONG' + The requested value in a SET command is too long. - 'FEATURE-NOT-SUPPORTED' + This instance of upsd does not support the requested feature. This is only used for TLS/SSL mode (STARTTLS) at the moment. - 'FEATURE-NOT-CONFIGURED' + This instance of upsd hasn't been configured properly to allow the requested feature to operate. This is also limited to STARTTLS for now. - 'ALREADY-SSL-MODE' + TLS/SSL mode is already enabled on this connection, so upsd can't start it again. - 'DRIVER-NOT-CONNECTED' + upsd can't perform the requested command, since the driver for that UPS is not connected. This usually means that the driver is not running, or if it is, the ups.conf is misconfigured. - 'DATA-STALE' + upsd is connected to the driver for the UPS, but that driver isn't providing regular updates or has specifically marked the data as stale. upsd refuses to provide variables on stale units to avoid false readings. + This generally means that the driver is running, but it has lost communications with the hardware. Check the physical connection to the equipment. - 'ALREADY-LOGGED-IN' + The client already sent LOGIN for a UPS and can't do it again. There is presently a limit of one LOGIN record per connection. - 'INVALID-PASSWORD' + The client sent an invalid PASSWORD - perhaps an empty one. - 'ALREADY-SET-PASSWORD' + The client already set a PASSWORD and can't set another. This also should never happen with normal NUT clients. - 'INVALID-USERNAME' + The client sent an invalid USERNAME. - 'ALREADY-SET-USERNAME' + The client has already set a USERNAME, and can't set another. This should never happen with normal NUT clients. - 'USERNAME-REQUIRED' + The requested command requires a username for authentication, but the client hasn't set one. - 'PASSWORD-REQUIRED' + The requested command requires a passname for authentication, but the client hasn't set one. - 'UNKNOWN-COMMAND' + upsd doesn't recognize the requested command. + This can be useful for backwards compatibility with older versions of upsd. Some NUT clients will try GET and fall back on REQ after receiving this response. - 'INVALID-VALUE' + The value specified in the request is not valid. This usually applies to a SET of an ENUM type which is using a value which is not in the list of allowed values. Future ideas ------------ Dense lists ~~~~~~~~~~~ The LIST commands may be given the ability to handle options some day. For example, "LIST VARS +DESC" would return the current value like now, but it would also append the description of that variable. Command status ~~~~~~~~~~~~~~ After sending an INSTCMD or SET, a client will eventually be able to poll to see whether it was completed successfully by the driver. Get collection ~~~~~~~~~~~~~~ Allow to request only a subtree, which can be a collection, or a sub collection.