~ubuntu-branches/ubuntu/saucy/nut/saucy

« back to all changes in this revision

Viewing changes to docs/protocol.txt

  • Committer: Chuck Short
  • Date: 2013-05-13 12:57:25 UTC
  • Revision ID: zulcss@ubuntu.com-20130513125725-llq8wsohyhq9idsy
* Merge from Debian.  Remaining changes:
  - debian/control:
    + remove Build-Depends on libpowerman0-dev
    + remove nut-powerman-pdu
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now
  - debian/{nut-cgi,nut-server}.postinst: add nut to the dialout and nut
    groups unconditonally to handle the upgrade from hardy release.
  - debian/source_nut.py, debian/{nut,nut-server,nut-client}.install,
    debian/rules: Install apport hooks for all top-level nut packages.
  - debian/rules: Use udev version for Ubuntu
  - debian/series, debian/patches/backport-fix-lp753661.patch: re-enabled
* Non-maintainer upload with fixes for wheezy.
* debian/nut-client.preinst: also revert /etc/nut/nut.conf mangling done
  by postinst during upgrade from lenny to squeeze (Really closes: #677054)
  Thanks to Andreas Beckmann for the review.
* Merge from Debian.  Remaining changes:
  - debian/control:
    + remove Build-Depends on libpowerman0-dev
    + remove nut-powerman-pdu
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now
  - debian/{nut-cgi,nut-server}.postinst: add nut to the dialout and nut
    groups unconditonally to handle the upgrade from hardy release.
  - debian/source_nut.py, debian/{nut,nut-server,nut-client}.install,
    debian/rules: Install apport hooks for all top-level nut packages.
  - debian/rules: Use udev version for Ubuntu
  - debian/series, debian/patches/backport-fix-lp753661.patch: re-enabled
* Dropped the following patches, no longer required:
  - debian/patches/CVE-2012-2944.patch (included upstream)
* Non-maintainer upload with fixes for wheezy.
* Only remove /etc/init.d/nut from previous versions of nut in nut-server
  postinst if there are no local changes.
* Also remove /etc/init.d/nut in nut-client postinst. Thanks to 
  Laurent Bigonville for the hint.
* Only fix permissions of configfiles on first install.
* debian/control: Fix typo in package description. Thanks to Julien Cristau
  for spotting this.
* Non-maintainer upload.
* debian/nut-client.preinst: revert /etc/nut/nut.conf mangling done by older
  versions of the postinst (Closes: #677054)
* debian/rules: Stop the nut-client before nut-server on systems using
  static
  boot ordering (Closes: #679451)
* debian/nut-server.postinst: Remove /etc/init.d/nut on upgrade
  (Closes: #677822)
* Rename nut-server.lintian-overrides to nut-client.lintian-overrides and
  adjust overrides now that ups-monitor is shipped in nut-client package
  (Closes: #677947)
* Add debian/patches/0001-fix-upsmon-regression.patch: Fix upsmon/upssched
  regression (Taken from upstream) (Closes: #679513)
* Move nut metapackage to Section: metapackages
* Also create nut user when installing nut-client package and do not delete
  it on purge anymore (Closes: #682000)
* Drop /etc/default/nut → /etc/nut/nut.conf migration code, migration
  happends before squeeze release and this was against policy to have a
  maintainer script modifying a conffile in the first place (Closes: #684392)
* Add dependency against adduser and lsb-base on nut-client package
* Be sure that client is stopped before the server also when using
  dependencies based boot
* Fix package descriptions (Closes: #678068)
* Also install /bin/upssched-cmd in nut-client package as this script is
  referenced in default upssched.conf config file
* debian/watch: Update watch file
* Be sure that all maintainer scripts are returning 0 at their end
* New upstream release (Closes: #671444)
* acknowledges NMU (Closes: #613643)
* debian/nut-client.init: fix action "start" and use of log_*_*msg
  LSB log functions (Closes: #675619)
* debian/nut-server.preinst: remove obsolete file(s) left in
  /etc/udev/rules.d and related processing: udev files are now located
  in /lib/udev/rules, and there is no reason to modify the dedicated
  USB UPS rules (52-nut-usbups.rules) (Closes: #660072)
* debian/nut-server.init: rewrite to match upsd / drivers startup scope
* debian/nut-client.init: created to match upsmon startup scope
  (Closes: #634858)
* debian/nut.TODO.Debian, debian/Makefile.am: updated to reflect the above
* debian/rules: install nut-client.init, and update to reflect the above
* debian/control, debian/Makefile.am: updated to reflect the above
* debian/control:
  - add Breaks on nut-server (<< 2.6.3-1~)
  - bump Standards-Version to 3.9.3
* debian/nut-client.links: renamed from debian/nut-server.links, since
  ups-monitor is now provided by nut-client initscript
* debian/nut.README.Debian: renamed from nut-server.README.Debian,
  to provide it with both client and server packages
* debian/nut-server.install: add missing drivers (clone-outlet,
  liebert-esp2 and microdowell)
* debian/nut-server.manpages: add missing manual pages (apcsmart-old,
  ivtscd, liebert-esp2 and microdowell)
* SECURITY UPDATE: remote denial of service
 - debian/CVE-2012-2944.patch: limit the set of parsed characters to ' '
   through '~'
 - CVE-2012-2944
* Merge from Debian testing.  Remaining changes:
  - debian/control: Drop Build-Depends on libpowerman0-dev (currently in 
    universe)
  - debian/{nut-cgi,nut-server}.postinst: add nut to the dialout and nut 
    groups unconditonally to handle the upgrade from hardy release.
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now.
  - debian/source_nut.py, debian/{nut,nut-server,nut-client}.install, 
    debian/rules: Install apport hooks for all top-level nut packages.
  - debian/rules: Use udev version for Ubuntu.
  - debian/series, debian/patches/backport-fix-lp753661.patch: re-enabled.
* New upstream release (Closes: #635186, #598741, #633756, #638221)
* debian/nut-server.{install,manpages}: add richcomm_usb
* debian/nut-server.install, debian/rules: install Avahi service file
* debian/rules, nut-client.install: install Augeas lenses
* debian/nut-server.README.Debian: clarify udev explanation (Closes: #529664)
* debian/patches/0001-fix_spelling_and_typo.patch,
  debian/patches/0003-libupsclient-version.patch: removed since these are now
  fixed upstream
* debian/patches/series: updated
* Merge from debian unstable.  Remaining changes:
  - debian/control: Drop Build-Depends on libpowerman0-dev (currently in 
    universe)
  - debian/{nut-cgi,nut-server}.postinst: add nut to the dialout and nut 
    groups unconditonally to handle the upgrade from hardy release.
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now.
  - debian/source_nut.py, debian/{nut,nut-server,nut-client}.install, 
    debian/rules: Install apport hooks for all top-level nut packages.
  - debian/rules: Use udev version for Ubuntu.
  - debian/series, debian/patches/backport-fix-lp753661.patch: re-enabled.
* New upstream release (Closes: #594989)
* debian/control:
  - remove legacy Build-Depends for nut-hal-drivers on libdbus and libglib
  - Build-Depends-Indep on docbook-xsl for offline document
    generation (Closes: #635347)
* debian/nut-server.install: add apcsmart-old
* debian/nut-server.init:
  - add udev as Required-Start/Stop (Closes: #642412)
  - remove legacy support for /etc/default/nut (Closes: #638021)
* debian/patches/0003-libupsclient-version.patch: added to fix the missing
  libupsclient version info bump
* debian/libupsclient1-dev.links: update link name
* debian/libupsclient1.symbols: add with upscli_tryconnect
* debian/nut.TODO.Debian: update and complete the TODO list
* Fix FTBFS for Ubuntu (LP: #815760):
  - debian/control: Build-Depends-Indep on docbook-xsl for offline 
    document generation.
* Merge from Debian unstable (LP: #811976). Remaining changes:
  - debian/control: Drop Build-Depends on libpowerman0-dev (currently in 
    universe)
  - debian/{nut-cgi,nut-server}.postinst: add nut to the dialout and nut 
    groups unconditonally to handle the upgrade from hardy release.
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now.
  - debian/source_nut.py, debian/{nut,nut-server,nut-client}.install, 
    debian/rules: Install apport hooks for all top-level nut packages.
  - debian/rules: Use udev version for Ubuntu.
  - debian/series, debian/patches/backport-fix-lp753661.patch: re-enabled.
* debian/nut.README.Debian: Adjust udev rules naming for permissions override
  (Closes: #529664)
* Re-add and refresh debian/patches/0001-fix_spelling_and_typo.patch:
  Some typos and spelling errors remain.
* Split nut package into nut-client and nut-server, keep nut package as
  metapackage
* Generate PDF and html doc and install it in nut-doc package
* debian/rules:
  - List non-installed files
  - Includes python-module.mk
  - Add flags to build documentation and install it
* debian/control:
  - Add python-nut package and add python build-dependency
  - Set nut-powerman-pdu priority to extras
  - Add nut-monitor package
  - Add nut-doc package and add required C/R/P
  - Add libups-nut-perl package
* debian/nut-server.prerm: Remove /var/run/nut during removal
* Merge from debian unstable.  Remaining changes:
  - debian/control:
    + Drop Build-Depends on libpowerman0-dev (currently in universe)
  - debian/{nut-cgi,nut}.postinst: add nut to the dialout and nut groups
    unconditonally to handle the upgrade from hardy release.
  - debian/nut-powerman-pdu.{install,manpages}: dropped for now.
  - debian/source_nut.py, debian/nut.install, debian/rules: Install apport hook.
  - debian/rules: Use udev version for Ubuntu.
* debian/patches/backport-fix-lp753661.patch: Refreshed.
* Drop changes due to .pc being not clean.
* New upstream release (Closes: #595953, #614842, #595773)
* debian/patches/*.patch: removed since these are now fixed upstream
* Drop HAL package and build-dependencies (Closes: #613197)
* debian/control:
  - Bump Standards-Version to 3.9.2 (no further changes)
  - Drop autotools build-dependencies (not needed anymore)
  - Drop non-existing build-dependencies
* debian/rules:
  - Correctly pass flags to configure
* Merge from debian unstable (LP: #789323).  Remaining changes:
  + debian/control:
    - Update maintainer as per spec.
    - Add Breaks on nut-hal-drivers to ensure we have correct udev version.
    - Drop libpowerman0-dev from the Build-Depends (currently in universe)
  + debian/{nut-cgi,nut}.postinst: add nut to the dialout and nut groups
    unconditonally to handle the upgrade from hardy release.
  + debian/nut-powerman-pdu.install, debian/nut-powerman-pdu.manpages: dropped for now.
  + debian/nul-hal-drivers.{docs,install,postinst,preinst}: Dropped since hal is in universe now
  + debian/nut.links: must create the init script link, used if the upse needs to be powered down
    (LP: #357583)
  + debian/source_nut.py, debian/nut.install, debian/rules: Install apport hook.
  + debian/patches/backport-fix-lp753661.patch
  + Dropped:
    - debian/patches/fix_pc_file.patch: replaced by debian's 0002-fix_libupsclient_pc.patch
* debian/patches/fix_pc_file.patch: add DEP3 patch header
* debian/patches/debian-changes-2.6.0-1: remove that accidental file
* debian/nut-snmp.docs: Distribute snmp.txt doc file (Closes: #548295)
* d/p/0001-fix_spelling_and_typo.patch: Update and refresh
* debian/nut.lintian-overrides: Fix typo
* debian/patch/0002-fix_libupsclient_pc.patch: Fix libupsclient.pc (Closes:
  #624255)
* debian/rules:
  - Switch to cdbs
  - Remove not existing configure options (Closes: #611813)
  - Drop Phony rules (Closes: #613699)
* debian/control:
  - Add cdbs build-dependency
* debian/patches/backport-fix-lp753661.patch: Backport fix 
  to trim extraneous end-of-line, in buggy HID string tables, 
  which results in upsc breaking the communication pipe.
  (LP: #753661)
* fix_pc_file.patch: fix .pc source files by using LIBSSL_LIBS instead of
  LIBSSL_LDFLAGS to avoid a FTBFS in packages that uses libupsclient.pc
  (LP: #743484)
* Merge from Debian unstable, remaining changes:
  + debian/control:
    - Update maintainer as per spec.
    - Add Breaks on nut-hal-drivers to ensure we have correct udev version.
    - Drop libpowerman0-dev from the Build-Depends (currently in universe)
  + debian/{nut-cgi,nut}.postinst: add nut to the dialout and nut groups
    unconditonally to hanle the upgrade from hardy release.
  + debian/nut-powerman-pdu.install, debian/nut-powerman-pdu.manpages: dropped for now.
  + debian/nul-hal-drivers.{docs,install,postinst,preinst}: Dropped since hal is in universe now
  + debian/nut.links: must create the init script link, used if the upse needs to be powered down
    (LP: #357583)
  + debian/source_nut.py, debian/nut.install, debian/rules: Install apport hook.
  + Dropped:
    - debian/patches/0002-fix_udev_action.patch: Accepted upstream.
    - debian/patches/0004-netvision-improvements-lp-600950: no longer needed.
    - debian/patches/0005-fix-nut-m4.patch: no longer needed.
    - debian/patches/9999-autoconf.patch: no longer needed.
* New upstream release (Closes: #575176, #588648, #609597, #687985)
* debian/patches/*.patch: removed since these are now fixed upstream
* debian/patches/0001-fix_spelling_and_typo.patch,
  debian/patches/series: reworked to match the new upstream release
* debian/nut.install, debian/nut.manpages: remove obsolete reference to
  megatec and megatec_usb, now respectively replaced by blazer_ser and
  blazer_usb
* debian/nut.docs: limit distributed documentation
* debian/control:
  - Wrap build-dependencies
  - Change nut-cgi Recommends to apache2 | httpd-cgi
* debian/nut.postinst: Only trigger USB subsystem, should Closes: #574769
* debian/patches/0002-fix_udev_action.patch: Use SUBSYSTEM instead of BUS
* debian/control, debian/rules, 
  debian/nut-hal-drivers.{docs,install,postinst,preinst}: Drop
  nut-hal-drivers since Nut doesnt go into universe.
* Split patches/debian-changes-2.4.3-2ubuntu1 into
  patches/0005-fix-nut-m4.patch and patches/9999-autoconf.patch
* Readd lost debian/patches0004-netvision-improvements-lp-600950.patch patch
  (LP: #707050)
* debian/patches/0002-fix_udev_action.patch:
  Change BUS to SUBSYSTEMS, since the former is deprecated. (LP: #692171)
* debian/nut.postinst: Uncomment missing call to adduser
* debian/control: Drop hal build dependency, we don't need the daemon to
  build the package. Add a hal dependency to nut-hal-drivers, which is the
  only thing that actually needs it.
* Merge from debian unstable.  Remaining changes:
  + debian/control:
    - Update maintainer as per spec.
    - Add Breaks on nut-hal-drivers to ensure we have correct udev version.
    - Drop libpowerman0-dev from the Build-Depends (currently in universe)
  + debian/{nut-cgi,nut}.postinst: add nut to the dialout and nut groups
    unconditonally to hanle the upgrade from hardy release.
  + debian/nut-powerman-pdu.install, debian/nut-powerman-pdu.manpages: dropped for now.
  + debian/nut.links: must create the init script link, used if the upse needs to be powered down
    (LP: #357583)
  + debian/nut.postinst: Update udevadm trigger.
    "libusb_get_report: error sending control message: 
     Operation not permitted" error on some UPS devices. (LP: #572262)
  + debian/source_nut.py, debian/nut.install, debian/rules: Install apport hook.
  + debian/patches/netvision-improvements-lp-600950.patch: Add improvements
    for netvision UPSes
  + Fix FTBFS with ld --as-needed.
  + Dropped:
    - debian/patches/03_udev_rules_change.dpatch: Use debian's instead.
    - debian/patches/04_nut_small-buffers.dpatch: Use debian's instead.
* debian/control:
  - Bump Standards-Version to 3.9.1
  - Update Vcs-* fields to new GIT repository
  - Add myself as Uploaders
* Switch to dpkg-source 3.0 (quilt) format (Closes: #573601)
* debian/patches/0001-low_speed_usb_ups.patch: Use patch system for changes
  that were applied directly in the source
* Add debian/gbp.conf file
* debian/watch: Bump version to 3
* Add debian/patches/0002-fix_udev_action.patch: Also set permission for
  "change" udev ACTION (Closes: #557178)
* debian/nut.postrm: Do not try to remove nut user is deluser is not
  installed anymore
* debian/nut.manpages: Install manpage nut.conf.5 (Closes: #528222)
* debian/copyright: Fix copyright-with-old-dh-make-debian-copyright
* Remove nut-snmp.lintian-overrides, not needed anymore
* debian/patches/0003-fix_spelling_and_typo.patch: Fix some spelling errors
* Add debian/libupsclient1.symbols file
* Add debian/nut.links: Re-add /etc/init.d/ups-monitor that was lost for
  some reasons (Closes: #592351)
* debian/nut.lintian-overrides: Add override for
  init.d-script-does-not-provide-itself /etc/init.d/ups-monitor
* Drop libupsclient1.post{inst,rm}: ldconfig call is added automatically by
  debhelper
* debian/libupsclient1-dev.install: Do not ship /lib/libupsclient.la anymore
* debian/rules: Remove dpatch logic as we are using package source version
  '3.0 (quilt)'
* debian/compat: Bump debhelper compatibility to 8
* Non-maintainer upload.
* drivers/libhid.c: Apply r2407 from upstream to fix bug with some
  low speed UPS devices. (Closes: #583371)
* Fix FTBFS with ld --as-needed.
* debian/patches/netvision-improvements-lp-600950.patch: Add improvements for netvision UPSes 
  (LP: #600950) 
* debian/source_nut.py, debian/nut.install, debian/rules: Install apport hook. 
* debian/patches/04_nut-small-buffers.dpatch: Fix "libusb_get_report: error sending control message: 
  Operation not permitted" error on some UPS devices. (LP: #572262)
* debian/nut.postinst: Revert dropping of --action=change. "add" events must
  not ever be triggered automatically.
* Add 03_udev_rules_change.dpatch: Run udev rules on change events, too.
* debian/control: grr...fix ftbfs. 
* Merge from debian testing.  Remaining changes (LP: #535152):
  + debian/control:
    - Update maintainer as per spec.
    - Add Breaks on nut-hal-drivers to ensure we have correct udev version.
    - Drop libpowerman0-dev from the Build-Depends (currently in universe)
  + debian/{nut-cgi,nut}.postinst: add nut to the dialout and nut groups
    unconditonally to hanle the upgrade from hardy release.
  + debian/nut-powerman-pdu.install, debian/nut-powerman-pdu.manpages: dropped for now.
  + debian/nut.links: must create the init script link, used if the upse needs to be powered down
    (LP: #357583)
  + debian/nut.postinst: Update udevadm trigger.
  + Dropped:
    - debian/patches/02-fix-trust-pw4130m.dpatch: No longer needed.
* New upstream release (Closes: #544390, #528222, #539747, #526811,
  #562064)
* debian/nut.install, debian/nut.manpages:
  - remove cyberpower driver and manpage
  - add bestfortress, clone and ivtscd drivers and manpages
* debian/rules:
  - change udev dir to /lib/udev (Closes: #522327)
  - replace deprecated calls to 'dh_clean -k' by dh_prep (Closes: #536599)
* debian/rules, debian/nut.install, debian/nut.install,
  debian/nut.README.Debian: install configuration files, without the
  sample suffix (Closes: #528641)
* debian/nut.links: restored (Closes: #522506)
* debian/nut.init:
  - source nut.conf instead of default/nut for POWEROFF_WAIT(Closes:
    #538173)
  - fix status checking (Closes: #538785)
  - improve detection of non configured system and beautify related
    output (Closes: #563112)
  - use 'invoke-rc.d' instead of calling the reboot script directly
  - add $remote_fs to Required-Start and Required-Stop
* debian/nut.postrm: remove udev files and simplify cleanup (Closes:
  #541629)
* debian/control:
  - remove Luca Filipozzi from the Uploaders list (Closes: #568987)
  - update Standards-Version to 3.8.4
  - remove the debconf dependency
  - bump debhelper version to (>= 7) in Build-Depends, for dh_prep
  - add Breaks on nut-hal-drivers to ensure we have correct udev version
* Remove debconf support since it was related to really old nut
  version (Closes: #518056):
  - remove nut-cgi.config, nut.config, nut-cgi.templates, nut.templates,
    and po/ directory
  - update nut-cgi.postinst
* debian/nut.dirs: remove /var/run/nut to conform to Debian Policy
* debian/nut.postint:
  - create /var/run/nut if needed
  - improve security checks
* debian/nut.README.Debian: add a security note for ups.conf
* debian/watch: URL update
* debian/patches/02-fix-trust-pw4130m.dpatch: Fix issues with Trust
  PW-4130M UPS. (LP: #447586) 

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
Desc: Network protocol info
2
 
File: protocol.txt
3
 
Date: 18 February 2004
4
 
Auth: Russell Kroll <rkroll@exploits.org>
5
 
 
6
 
As of May 2002, this protocol now has an official port number from IANA,
7
 
which is 3493.  The old number (3305) was a relic of the original code's
8
 
ancestry, and conflicted with other services.  Version 0.50.0 and up
9
 
use 3493 by default.
10
 
 
11
 
This protocol runs over TCP.  UDP support was dropped in July 2003.  It
12
 
had been deprecated for some time and was only capable of the simplest
13
 
query commands as authentication is impossible over a UDP socket.
14
 
 
15
 
A library, named libupsclient, that implement this protocol is provided
16
 
in both static and shared version to help the client application development.
17
 
 
18
 
Old command removal notice
19
 
==========================
20
 
 
21
 
Before version 1.5.0, a number of old commands were supported.  These
22
 
have been removed from the specification.  For more information, consult
23
 
an older version of the software.
24
 
 
25
 
Command reference
26
 
=================
27
 
 
28
 
Multi-word elements are contained within "quotes" for easier parsing.  
29
 
Embedded quotes are escaped with backslashes.  Embedded backslashes are
30
 
also escaped by representing them as \\.  This protocol is intended to
31
 
be interpreted with parseconf or something similar.
32
 
 
33
 
GET
34
 
===
35
 
 
36
 
Retrieve a single response from the server.
37
 
 
38
 
Possible sub-commands:
39
 
 
40
 
NUMLOGINS
41
 
---------
42
 
 
43
 
    Form: GET NUMLOGINS <upsname>
44
 
          GET NUMLOGINS su700
45
 
 
46
 
Response: NUMLOGINS <upsname> <value>
47
 
          NUMLOGINS su700 1
48
 
 
49
 
<value> is the number of clients which have done LOGIN for this UPS.
50
 
This is used by the master upsmon to determine how many clients are
51
 
still connected when starting the shutdown process.
52
 
 
53
 
This replaces the old "REQ NUMLOGINS" command.
54
 
 
55
 
UPSDESC
56
 
-------
57
 
 
58
 
    Form: GET UPSDESC <upsname>
59
 
          GET UPSDESC su700
60
 
 
61
 
Response: UPSDESC <upsname> "<description>"
62
 
          UPSDESC su700 "Development box"
63
 
 
64
 
<description> is the value of "desc=" from ups.conf for this UPS.  If it
65
 
is not set, upsd will return "Unavailable".
66
 
 
67
 
This can be used to provide human-readable descriptions instead of a
68
 
cryptic "upsname@hostname" string.
69
 
 
70
 
VAR
71
 
---
72
 
 
73
 
    Form: GET VAR <upsname> <varname>
74
 
          GET VAR su700 ups.status
75
 
 
76
 
Response: VAR <upsname> <varname> "<value>"
77
 
          VAR su700 ups.status "OL"
78
 
 
79
 
This replaces the old "REQ" command.
80
 
 
81
 
TYPE
82
 
----
83
 
 
84
 
    Form: GET TYPE <upsname> <varname>
85
 
          GET TYPE su700 input.transfer.low
86
 
 
87
 
Response: TYPE <upsname> <varname> <type>...
88
 
          TYPE su700 input.transfer.low ENUM
89
 
 
90
 
<type> can be several values, and multiple words may be returned:
91
 
 
92
 
      RW - this variable may be set to another value with SET
93
 
    ENUM - an enumerated type, which supports a few specific values
94
 
STRING:n - this is a string of maximum length n
95
 
 
96
 
ENUM and STRING are usually associated with RW, but not always.
97
 
 
98
 
This replaces the old "VARTYPE" command.
99
 
 
100
 
DESC
101
 
----
102
 
 
103
 
    Form: GET DESC <upsname> <varname>
104
 
          GET DESC su700 ups.status
105
 
 
106
 
Response: DESC <upsname> <varname> "<description>"
107
 
          DESC su700 ups.status "UPS status"
108
 
 
109
 
<description> is a string that gives a brief explanation of the named
110
 
variable.  upsd may return "Unavailable" if the file which provides this
111
 
description is not installed.
112
 
 
113
 
Different versions of this file may be used in some situations to
114
 
provide for localization and internationalization.
115
 
 
116
 
This replaces the old "VARDESC" command.
117
 
 
118
 
CMDDESC
119
 
-------
120
 
 
121
 
    Form: GET CMDDESC <upsname> <cmdname>
122
 
          GET CMDDESC su700 load.on
123
 
 
124
 
Response: CMDDESC <upsname> <cmdname> "<description>"
125
 
          CMDDESC su700 load.on "Turn on the load immediately"
126
 
 
127
 
This is like DESC above, but it applies to the instant commands.
128
 
 
129
 
This replaces the old "INSTCMDDESC" command.
130
 
 
131
 
LIST
132
 
====
133
 
 
134
 
The LIST functions all share a common container format.  They will
135
 
return "BEGIN LIST" and then repeat the initial query.  The list then
136
 
follows, with as many lines are necessary to convey it.  "END LIST" with
137
 
the initial query attached then follows.
138
 
 
139
 
The formatting may seem a bit redundant, but it makes a different form
140
 
of client possible.  You can send a LIST query and then go off and wait
141
 
for it to get back to you.  When it arrives, you don't need complicated
142
 
state machines to remember which list is which.
143
 
 
144
 
UPS
145
 
---
146
 
 
147
 
    Form: LIST UPS
148
 
 
149
 
Response: BEGIN LIST UPS
150
 
          UPS <upsname> "<description>"
151
 
          ...
152
 
          END LIST UPS
153
 
 
154
 
          BEGIN LIST UPS
155
 
          UPS su700 "Development box"
156
 
          END LIST UPS
157
 
 
158
 
<upsname> is a name from ups.conf, and <description> is the value of
159
 
desc= from ups.conf, if available.  It will be set to "Unavailable"
160
 
otherwise.
161
 
 
162
 
This can be used to determine what values of <upsname> are valid before
163
 
calling other functions on the server.  This is also a good way to
164
 
handle situations where a single upsd supports multiple drivers.
165
 
 
166
 
Clients which perform a UPS discovery process may find this useful.
167
 
 
168
 
VAR
169
 
---
170
 
 
171
 
    Form: LIST VAR <upsname>
172
 
          LIST VAR su700
173
 
 
174
 
Response: BEGIN LIST VAR <upsname>
175
 
          VAR <upsname> <varname> "<value>"
176
 
          ...
177
 
          END LIST VAR <upsname>
178
 
 
179
 
          BEGIN LIST VAR su700
180
 
          VAR su700 ups.mfr "APC"
181
 
          VAR su700 ups.mfr.date "10/17/96"
182
 
          ...
183
 
          END LIST VAR su700
184
 
 
185
 
This replaces the old "LISTVARS" command.
186
 
 
187
 
RW
188
 
--
189
 
 
190
 
    Form: LIST RW <upsname>
191
 
          LIST RW su700
192
 
 
193
 
Response: BEGIN LIST RW <upsname>
194
 
          RW <upsname> <varname> "<value>"
195
 
          ...
196
 
          END LIST RW <upsname>
197
 
 
198
 
          BEGIN LIST RW su700
199
 
          RW su700 output.voltage.nominal "115"
200
 
          RW su700 ups.delay.shutdown "020"
201
 
          ...
202
 
          END LIST RW su700
203
 
 
204
 
This replaces the old "LISTRW" command.
205
 
 
206
 
CMD
207
 
---
208
 
 
209
 
    Form: LIST CMD <upsname>
210
 
          LIST CMD su700
211
 
 
212
 
Response: BEGIN LIST CMD <upsname>
213
 
          CMD <upsname> <cmdname>
214
 
          ...
215
 
          END LIST CMD <cmdname>
216
 
 
217
 
          BEGIN LIST CMD su700
218
 
          CMD su700 load.on
219
 
          CMD su700 test.panel.start
220
 
          ...
221
 
          END LIST CMD su700
222
 
 
223
 
This replaces the old "LISTINSTCMD" command.
224
 
 
225
 
ENUM
226
 
----
227
 
 
228
 
    Form: LIST ENUM <upsname> <varname>
229
 
          LIST ENUM su700 input.transfer.low
230
 
 
231
 
Response: BEGIN LIST ENUM <upsname> <varname>
232
 
          ENUM <upsname> <varname> "<value>"
233
 
          ...
234
 
          END LIST ENUM <upsname> <varname>
235
 
 
236
 
          BEGIN LIST ENUM su700 input.transfer.low
237
 
          ENUM su700 input.transfer.low "103"
238
 
          ENUM su700 input.transfer.low "100"
239
 
          ...
240
 
          END LIST ENUM su700 input.transfer.low
241
 
 
242
 
This replaces the old "ENUM" command.
243
 
 
244
 
Note: this does not support the old "SELECTED" notation.  You must
245
 
request the current value separately.
246
 
 
247
 
SET
248
 
---
249
 
 
250
 
   Form: SET VAR <upsname> <varname> "<value>"
251
 
         SET VAR su700 ups.id "My UPS"
252
 
 
253
 
INSTCMD
254
 
-------
255
 
 
256
 
   Form: INSTCMD <upsname> <cmdname>
257
 
         INSTCMD su700 test.panel.start
258
 
 
259
 
LOGOUT
260
 
======
261
 
 
262
 
Form: LOGOUT
263
 
 
264
 
Returns: OK Goodbye     (recent versions)
265
 
 
266
 
Used to disconnect gracefully from the server.
267
 
 
268
 
Older versions just said "Goodbye...".
269
 
 
270
 
LOGIN
271
 
=====
272
 
 
273
 
Form: LOGIN <upsname>
274
 
 
275
 
Returns: OK     (upon success)
276
 
         or various errors
277
 
 
278
 
Requires: "upsmon slave" or "upsmon master" in upsd.users
279
 
 
280
 
Use this to log the fact that a system is drawing power from this UPS.
281
 
The upsmon master will wait until the count of attached systems reaches
282
 
1 - itself.  This allows the slaves to shut down first.
283
 
 
284
 
NOTE: You probably shouldn't send this command unless you are upsmon,
285
 
      or a upsmon replacement.
286
 
 
287
 
MASTER
288
 
======
289
 
 
290
 
Form: MASTER <upsname>
291
 
 
292
 
Returns: OK     (upon success)
293
 
         or various errors
294
 
 
295
 
Requires: "upsmon master" in upsd.users
296
 
 
297
 
This function doesn't do much by itself.  It is used by upsmon to make
298
 
sure that master-level functions like FSD are available if necessary.
299
 
 
300
 
FSD
301
 
===
302
 
 
303
 
Form: FSD <upsname>
304
 
 
305
 
Returns: OK FSD-SET     (success)
306
 
         or various errors
307
 
 
308
 
Requires: "upsmon master" in upsd.users
309
 
          or "FSD" action granted in upsd.users
310
 
 
311
 
upsmon in master mode is the primary user of this function.  It sets this
312
 
"forced shutdown" flag on any UPS when it plans to power it off.  This is
313
 
done so that slave systems will know about it and shut down before the
314
 
power disappears.
315
 
 
316
 
Setting this flag makes "FSD" appear in a STATUS request for this UPS.
317
 
Finding "FSD" in a status request should be treated just like a "OB LB".
318
 
 
319
 
It should be noted that FSD is currently a latch - once set, there is  
320
 
no way to clear it short of restarting upsd or dropping then re-adding
321
 
it in the ups.conf.  This may cause issues when upsd is running on a
322
 
system that is not shut down due to the UPS event.
323
 
 
324
 
PASSWORD
325
 
========
326
 
 
327
 
Form: PASSWORD <password>
328
 
 
329
 
Returns: OK     (upon success)
330
 
         or various errors
331
 
 
332
 
Sets the password associated with a connection.  Used for later
333
 
authentication for commands that require it.
334
 
 
335
 
USERNAME
336
 
========
337
 
 
338
 
Form: USERNAME <username>
339
 
 
340
 
Returns: OK     (upon success)
341
 
         or various errors
342
 
 
343
 
Sets the username associated with a connection.  This is also used for
344
 
authentication, specifically in conjunction with the upsd.users file.
345
 
 
346
 
STARTTLS
347
 
========
348
 
 
349
 
Form: STARTTLS
350
 
 
351
 
Returns: OK STARTTLS
352
 
         or various errors
353
 
 
354
 
This tells upsd to switch to TLS mode internally, so all future
355
 
communications will be encrypted.  You must also change to TLS mode in
356
 
the client after receiving the OK, or the connection will be useless.   
357
 
 
358
 
Other commands
359
 
==============
360
 
 
361
 
HELP - lists the commands supported by this server
362
 
VER  - shows the version of the server currently in use
363
 
 
364
 
These two are not intended to be used directly by programs.  Humans can
365
 
make use of this program by using telnet or netcat.  If you use
366
 
telnet, make sure you don't have it set to negotiate extra options.
367
 
upsd doesn't speak telnet and will probably misunderstand your first
368
 
request due to the extra junk in the buffer.
369
 
 
370
 
Error responses
371
 
===============
372
 
 
373
 
ERR <message> [<extra>...]
374
 
 
375
 
<message> is always one element; it never contains spaces.  This may
376
 
be used to allow additional information (<extra>) in the future.
377
 
 
378
 
ACCESS-DENIED
379
 
 
380
 
 - The client's host and/or authentication details (username, password)
381
 
   are not sufficient to execute the requested command.
382
 
 
383
 
UNKNOWN-UPS
384
 
 
385
 
 - The UPS specified in the request is not known to upsd.  This usually
386
 
   means that it didn't match anything in ups.conf.
387
 
 
388
 
VAR-NOT-SUPPORTED
389
 
 
390
 
 - The specified UPS doesn't support the variable in the request.
391
 
 
392
 
   This is also sent for unrecognized variables which are in a space
393
 
   which is handled by upsd, such as server.*.
394
 
 
395
 
CMD-NOT-SUPPORTED
396
 
 
397
 
 - The specified UPS doesn't support the instant command in the request.
398
 
 
399
 
INVALID-ARGUMENT
400
 
 
401
 
 - The client sent an argument to a command which is not recognized or
402
 
   is otherwise invalid in this context.  This is typically caused by
403
 
   sending a valid command like GET with an invalid subcommand.
404
 
 
405
 
INSTCMD-FAILED
406
 
 
407
 
 - upsd failed to deliver the instant command request to the driver. 
408
 
   No further information is available to the client.  This typically
409
 
   indicates a dead or broken driver.
410
 
 
411
 
SET-FAILED
412
 
 
413
 
 - upsd failed to deliver the set request to the driver.  This is 
414
 
   just like INSTCMD-FAILED above.
415
 
 
416
 
READONLY
417
 
 
418
 
 - The requested variable in a SET command is not writable.
419
 
 
420
 
TOO-LONG
421
 
 
422
 
 - The requested value in a SET command is too long.
423
 
 
424
 
FEATURE-NOT-SUPPORTED
425
 
 
426
 
 - This instance of upsd does not support the requested feature.  This
427
 
   is only used for TLS/SSL mode (STARTTLS) at the moment.
428
 
 
429
 
FEATURE-NOT-CONFIGURED
430
 
 
431
 
 - This instance of upsd hasn't been configured properly to allow the
432
 
   requested feature to operate.  This is also limited to STARTTLS for
433
 
   now.
434
 
 
435
 
ALREADY-SSL-MODE
436
 
 
437
 
 - TLS/SSL mode is already enabled on this connection, so upsd can't
438
 
   start it again.
439
 
 
440
 
DRIVER-NOT-CONNECTED
441
 
 
442
 
 - upsd can't perform the requested command, since the driver for that
443
 
   UPS is not connected.  This usually means that the driver is not 
444
 
   running, or if it is, the ups.conf is misconfigured.
445
 
 
446
 
DATA-STALE
447
 
 
448
 
 - upsd is connected to the driver for the UPS, but that driver isn't
449
 
   providing regular updates or has specifically marked the data
450
 
   as stale.  upsd refuses to provide variables on stale units to avoid
451
 
   false readings.
452
 
 
453
 
   This generally means that the driver is running, but it has lost
454
 
   communications with the hardware.  Check the physical connection
455
 
   to the equipment.
456
 
 
457
 
ALREADY-LOGGED-IN
458
 
 
459
 
 - The client already sent LOGIN for a UPS and can't do it again.
460
 
   There is presently a limit of one LOGIN record per connection.
461
 
 
462
 
INVALID-PASSWORD
463
 
 
464
 
 - The client sent an invalid PASSWORD - perhaps an empty one.
465
 
 
466
 
ALREADY-SET-PASSWORD
467
 
 
468
 
 - The client already set a PASSWORD and can't set another.  This also
469
 
   should never happen with normal NUT clients.
470
 
 
471
 
INVALID-USERNAME
472
 
 
473
 
 - The client sent an invalid USERNAME.
474
 
 
475
 
ALREADY-SET-USERNAME
476
 
 
477
 
 - The client has already set a USERNAME, and can't set another.  This
478
 
   should never happen with normal NUT clients.
479
 
 
480
 
USERNAME-REQUIRED
481
 
 
482
 
 - The requested command requires a username for authentication,
483
 
   but the client hasn't set one.
484
 
 
485
 
PASSWORD-REQUIRED
486
 
 
487
 
 - The requested command requires a passname for authentication,
488
 
   but the client hasn't set one.
489
 
 
490
 
UNKNOWN-COMMAND
491
 
 
492
 
 - upsd doesn't recognize the requested command.
493
 
 
494
 
   This can be useful for backwards compatibility with older versions
495
 
   of upsd.  Some NUT clients will try GET and fall back on REQ after
496
 
   receiving this response.
497
 
 
498
 
INVALID-VALUE
499
 
 
500
 
 - The value specified in the request is not valid.  This usually 
501
 
   applies to a SET of an ENUM type which is using a value which is
502
 
   not in the list of allowed values.
503
 
 
504
 
Future ideas
505
 
============
506
 
 
507
 
Dense lists
508
 
-----------
509
 
 
510
 
The LIST commands may be given the ability to handle options some day.
511
 
For example, "LIST VARS <ups> +DESC" would return the current value
512
 
like now, but it would also append the description of that variable.
513
 
 
514
 
Command status
515
 
--------------
516
 
 
517
 
After sending an INSTCMD or SET, a client will eventually be able to
518
 
poll to see whether it was completed successfully by the driver.