security.txt

Notes on securing NUT
=====================

//////////////////////////////////////////////////////////////////////////////
// You can find a rendered variant of this document on the web at
// https://networkupstools.org/docs/user-manual.chunked/NUT_Security.html
//////////////////////////////////////////////////////////////////////////////

The NUT Team is very interested in providing the highest security level to its
users.

Many internal and external mechanisms exist to secure NUT. And several steps
are needed to ensure that your NUT setup meets your security requirements.

This chapter will present you these mechanisms, by increasing order of security
level. This means that the more security you need, the more mechanisms you will
have to apply.

NOTE: You may want to have a look at NUT Quality Assurance, since some
topics are related to NUT security and reliability.


[[verifySourceSig]]
How to verify the NUT source code signature
-------------------------------------------

In order to verify the NUT source code signature for releases, perform the
following steps:

- Retrieve the link:https://www.networkupstools.org/download.html[NUT source code]
  (nut-X.Y.Z.tar.gz) and the matching signature (nut-X.Y.Z.tar.gz.sig)
- Retrieve the link:https://www.networkupstools.org/source/nut-key.gpg[NUT
maintainer's signature keyring]:

	$ gpg --fetch-keys https://www.networkupstools.org/source/nut-key.gpg

[NOTE]
======
As of NUT 2.8.0, a new release key is used, but the `nut-key.gpg` should
be cumulative with older chain key files (includes them). You can view the key
list in a downloaded copy of the URL above with:

	$ gpg --with-colons --import-options import-show --dry-run --import < nut-key.gpg

...and as of this writing, it should contain two key sets for various identities
of "Arnaud Quette" and one set of "Jim Klimov".
======

Just in case, the previous key file used since NUT 2.7.3 release is stored as
link:https://www.networkupstools.org/source/nut-key-2.7.3.gpg[NUT
old maintainer's signature for 2.7.3-2.7.4 releases]

In order to verify an even older release, please use
link:https://www.networkupstools.org/source/nut-old-key.gpg[NUT
old maintainer's signature since 2002 until 2.7.3 release]

- Launch the GPG checking using the following command:

	$ gpg --verify nut-X.Y.Z.tar.gz.sig

- You should see a message mentioning a "Good signature", with formatting which
  depends on your gpg version, like:

	gpg: Signature made Thu Jun  1 00:10:16 2023 CEST
	...
	gpg: Good signature from "Jim Klimov ..."
	...
	Primary key fingerprint: B834 59F7 76B9 0224 988F  36C0 DE01 84DA 7043 DCF7
	...

[NOTE]
======
The previously used maintainer's signatures would output (with markup of
older gpg tools here):

	gpg: Signature made Wed Apr 15 15:55:30 2015 CEST using RSA key ID 55CA5976
	gpg: Good signature from "Arnaud Quette ..."
	...

or:

	gpg: Signature made Thu Jul  5 16:15:05 2007 CEST using DSA key ID 204DDF1B
	gpg: Good signature from "Arnaud Quette ..."
	...
======

////////
Maintainer notes for posterity:

* See https://github.com/networkupstools/nut/issues/1963 and
  https://github.com/networkupstools/nut/issues/1410 for recent
  forays into this area.

* Repo is https://github.com/networkupstools/nut-source-archive.git

* Keys in the file can be viewed with:
----
:; gpg --with-colons --import-options import-show --dry-run --import < nut-key.gpg
----

* Old keys as well as a new maintainer key can be imported first into
  a temporary keyring (existing target file and a slash in its path
  name argument are allegedly important):
----
:; rm -f tmpring.gpg ; touch tmpring.gpg
:; gpg --no-default-keyring --keyring ./tmpring.gpg --import nut-key.gpg
:; gpg --no-default-keyring --keyring ./tmpring.gpg --import nut-old-key.gpg
:; gpg --no-default-keyring --keyring ./tmpring.gpg --import nut-key-2.7.3.gpg
:; gpg --no-default-keyring --keyring ./tmpring.gpg --import ~/.gnupg/HEXCODEMYNEWKEYDATA.pub
----

** Note that whenever the key owner edits the primary key data, e.g. to add or
   remove "uid" entries with e-mail aliases, or sub-keys dedicated for specific
   purposes, the `~/.gnupg/HEXCODEMYNEWKEYDATA.pub` is changed and should be
   re-published to OpenPGP servers, to nut-website, to GitHub account, etc.

* This (binary) keychain can be exported into ASCII-armor format, and also
  update the keychain file used by default:
----
:; gpg --no-default-keyring --keyring ./tmpring.gpg --export -a > nut-key.gpg
----
////////

How to verify the NUT source code checksum
------------------------------------------

As a weaker but simpler alternative to verifying a *signature*, you can verify
just the accompanying checksums of the source archive file. This is useful
primarily to check against bit-rot in original storage or in transit. As far
as disclaimers go: ideally, you should cover all provided algorithms -- e.g.
MD5 and SHA256 -- to minimize the chance that intentional malicious tampering
on the wire goes undetected. A myriad tools can check that on various platforms;
some examples follow:

	# Example original checksum to compare with, from NUT website:
	$ cat nut-2.8.0.tar.gz.sha256
	c3e5a708da797b7c70b653d37b1206a000fcb503b85519fe4cdf6353f792bfe5  nut-2.8.0.tar.gz

	# Generate checksum of downloaded archive with perl (a NUT build dependency
	# generally, though you may have to install Digest::SHA module from CPAN):
	$ perl -MDigest::SHA=sha256_hex -le "print sha256_hex <>" nut-2.8.0.tar.gz
	c3e5a708da797b7c70b653d37b1206a000fcb503b85519fe4cdf6353f792bfe5

	# Generate checksum of downloaded archive with openssl (another optional
	# NUT build dependency):
	$ openssl sha256 nut-2.8.0.tar.gz
	SHA256(nut-2.8.0.tar.gz)= c3e5a708da797b7c70b653d37b1206a000fcb503b85519fe4cdf6353f792bfe5

	# Generate checksum of downloaded archive with coreutils:
	$ sha256sum nut-2.8.0.tar.gz
	c3e5a708da797b7c70b653d37b1206a000fcb503b85519fe4cdf6353f792bfe5  nut-2.8.0.tar.gz

	# Auto-check downloaded checksum against downloaded archive with coreutils:
	$ sha256sum -c nut-2.8.0.tar.gz.sha256
	nut-2.8.0.tar.gz: OK

	# Generate checksum of downloaded archive with GPG:
	$ gpg --print-md SHA256 nut-2.8.0.tar.gz
	nut-2.8.0.tar.gz: C3E5A708 DA797B7C 70B653D3 7B1206A0
	                  00FCB503 B85519FE 4CDF6353 F792BFE5

System level privileges and ownership
-------------------------------------

All configuration files should be protected so that the world can't read them.
Use the following commands to accomplish this:

	chown root:nut /etc/nut/*
	chmod 640 /etc/nut/*


Finally, the <<StatePath,state path>> directory, which holds the
communication between the driver(s) and `upsd`, should also be secured.

	chown root:nut /var/state/ups
	chmod 0770 /var/state/ups


NUT level user privileges
-------------------------

Administrative commands such as setting variables and the instant commands
are powerful, and access to them needs to be restricted.

NUT provides an internal mechanism to do so, through
linkman:upsd.users[5].

This file defines who may access instant commands and settings, and what
is available.

During the initial
<<NUT_user_creation,NUT user creation>>, we have created a
monitoring user for `upsmon`.

You can also create an `administrator` user in NUT with full power using:

	[administrator]
		password = mypass
		actions = set
		instcmds = all

For more information on how to restrict actions and instant commands, refer
to linkman:upsd.users[5] manual page.

NOTE: NUT administrative user definitions should be used in conjunction with
<<TCP_Wrappers,TCP Wrappers>>.


Network access control
----------------------

If you are not using NUT on a standalone setup, you will need to enforce
network access to `upsd`.

There are various ways to do so.

NUT LISTEN directive
~~~~~~~~~~~~~~~~~~~~

linkman:upsd.conf[5].

	LISTEN interface port

Bind a listening port to the interface specified by its Internet address.
This may be useful on hosts with multiple interfaces.  You should not rely
exclusively on this for security, as it can be subverted on many systems.

Listen on TCP port `port` instead of the default value which was compiled into
the code.  This overrides any value  you  may  have  set  with `configure
--with-port`.  If you don't change it with configure or this value, `upsd` will
listen on port 3493 for this interface.

Multiple LISTEN addresses may be specified.  The default is to bind to
`127.0.0.1` if no LISTEN addresses are specified (and `::1` if IPv6 support is
compiled in).

	   LISTEN 127.0.0.1
	   LISTEN 192.168.50.1
	   LISTEN ::1
	   LISTEN 2001:0db8:1234:08d3:1319:8a2e:0370:7344

As a special case, `LISTEN * <port>` (with an asterisk) will try to
listen on "ANY" IP address for both IPv6 (`::0`) and IPv4 (`0.0.0.0`),
subject to `upsd` command-line arguments, or system configuration or support.
Note that if the system supports IPv4-mapped IPv6 addressing per RFC-3493,
and does not allow to disable this mode, then there may be one listening
socket to handle both address families.

This parameter will only be read at startup.  You'll need to restart (rather
than reload) `upsd` to apply any changes made here.


Firewall
~~~~~~~~

NUT has its own official IANA port: 3493/tcp.

The `upsmon` process on secondary systems, as well as any other NUT client
(such as `upsc`, `upscmd`, `upsrw`, NUT-Monitor, ...) connects to the `upsd`
process on the system which manages the UPS, via this TCP port. Usually an
`upsmon` process runs on the latter system in "primary" mode for the devices
connected to it.

The `upsd` process does not initiate outgoing connections.

Certain NUT drivers (for network-managed devices) can initiate their own
connections to various ports according to corresponding vendor protocol.

You should use this to restrict network access.

[[UFW]]

include::../scripts/ufw/README.adoc[]

[[TCP_Wrappers]]
TCP Wrappers
~~~~~~~~~~~~

If the server is build with tcp-wrappers support enabled, it will check if the
NUT username is allowed to connect from the client address through the
`/etc/hosts.allow` and `/etc/hosts.deny` files.

NOTE: This will only be done for commands that require the user to be logged
into the server.

`hosts.allow`:

	upsd : admin@127.0.0.1/32
	upsd : observer@127.0.0.1/32 observer@192.168.1.0/24

`hosts.deny`:

	upsd : ALL

Further details are described in linkmanext:hosts_access[5].


Configuring SSL
---------------

SSL is available as a build option (`--with-ssl`).

It encrypts sessions between `upsd` and clients, and can also be used to
authenticate servers.

This means that stealing port 3493 from `upsd` will no longer net you interesting
passwords.

Several things must happen before this will work, however. This chapter will
present these steps.

SSL is available via two back-end libraries : NSS and OpenSSL (historically).
You can choose to use one of them by specifying it with a build option
(`--with-nss` or `--with-openssl`). If neither is specified, the configure
script will try to detect one of them, with a precedence for OpenSSL.

Starting with NUT v2.8.5, you can check the actual support of your NUT build
with `upsd -Dh` for the server, and `upsmon -Dh` for the typical client, e.g.:

------
   0.000000     [D1] Network UPS Tools version 2.8.4....
   0.019319     [D1] NUT data server was built with SSL support: OpenSSL;
                     without client certificate validation
------

The NUT Integration Test (NIT) suite handles verification of server and clients
with OpenSSL and NSS support. You can investigate the `tests/NIT/nit.sh` script
in the NUT source tree about creation of files for a new Certificate Authority,
requesting and signing individual server and client certificates, and setting
up NUT configuration files to use them.  That script roughly follows the steps
documented below.


OpenSSL backend usage
~~~~~~~~~~~~~~~~~~~~~

This section describes how to enable NUT SSL support using
link:http://www.openssl.org[OpenSSL].

Install OpenSSL
^^^^^^^^^^^^^^^

Install link:http://www.openssl.org[OpenSSL] as usual, either from source
or binary packages. If using binary packages, be sure to include the developer
libraries.

Recompile and install NUT
^^^^^^^^^^^^^^^^^^^^^^^^^

Recompile NUT from source, starting with `configure --with-openssl`.

Then install everything as usual.

Create a certificate and key for upsd
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

openssl (the program) should be in your PATH, unless you installed it from
source yourself, in which case it may be in `/usr/local/ssl/bin`.

Use the following command to create the certificate:

	openssl req -new -x509 -nodes -out upsd.crt -keyout upsd.key

You can also put a `-days nnn` in there to set the expiration.  If
you skip this, it may default to 30 days.  This is probably not what
you want.

It will ask several questions.  What you put in there doesn't matter a whole
lot, since nobody is going to see it for now.  Future versions of the
clients may present data from it, so you might use this opportunity to
identify each server somehow.

Figure out the hash for the key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the following command to determine the hash of the certificate:

	openssl x509 -hash -noout -in upsd.crt

You'll get back a single line with 8 hex characters.  This is the
hash of the certificate, which is used for naming the client-side
certificate.  For the purposes of this example the hash is *0123abcd*.

Install the client-side certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the following commands to install the client-side certificate:

	mkdir <certpath>
	chmod 0755 <certpath>
	cp upsd.crt <certpath>/<hash>.0

Example:

	mkdir /usr/local/ups/etc/certs
	chmod 0755 /usr/local/ups/etc/certs
	cp upsd.crt /usr/local/ups/etc/certs/0123abcd.0

If you already have a file with that name in there, increment the
`0` part until you get a unique filename that works.

If you have multiple client systems (like `upsmon` instances in
secondary mode), be sure to install this file on them as well.

We recommend making a directory under your existing confpath to
keep everything in the same place.  Remember the path you created,
since you will need to put it in `upsmon.conf` later.

It must not be writable by unprivileged users, since someone could
insert a new client certificate and fool `upsmon` into trusting a
fake `upsd`.

Create the combined file for upsd
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To do so, use the below commands:

	cat upsd.crt upsd.key > upsd.pem
	chown root:nut upsd.pem
	chmod 0640 upsd.pem

This file must be kept secure, since anyone possessing it could
pretend to be `upsd` and harvest authentication data if they get a
hold of port 3493.

Having it owned by `root` and readable by group `nut` allows `upsd`
to read the file without being able to change the contents.  This
is done to minimize the impact if someone should break into `upsd`.
NUT reads the key and certificate files after dropping privileges
and forking.

Note on certification authorities (CAs) and signed keys
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are probably other ways to handle this, involving keys which have
been signed by a CA you recognize.  Contact your local SSL guru.

Install the server-side certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Install the certificate with the following command:

	mv upsd.pem <upsd certfile path>

Example:

	mv upsd.pem /usr/local/ups/etc/upsd.pem

After that, edit your `upsd.conf` and tell it where to find it:

	CERTFILE /usr/local/ups/etc/upsd.pem

Clean up the temporary files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	rm -f upsd.crt upsd.key

Restart upsd
^^^^^^^^^^^^

It should come back up without any complaints.  If it says something
about keys or certificates, then you probably missed a step.

If you run `upsd` as a separate user id (like `nutsrv`), make sure that
user can read the `upsd.pem` file.

Point upsmon at the certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Edit your `upsmon.conf`, and tell it where the `CERTPATH` is:

	CERTPATH <path>

Example:

	CERTPATH /usr/local/ups/etc/certs

Recommended: make upsmon verify all connections with certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Put this in `upsmon.conf`:

	CERTVERIFY 1

Without this, there is no guarantee that the `upsd` is the right host.
Enabling this greatly reduces the risk of man in the middle attacks.

This effectively forces the use of SSL, so don't use this unless
all of your `upsd` hosts are ready for SSL and have their certificates
in order.

Recommended: force upsmon to use SSL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Again in `upsmon.conf`:

	FORCESSL 1

If you don't use `CERTVERIFY 1`, then this will at least make sure
that nobody can sniff your sessions without a large effort.  Setting
this will make `upsmon` drop connections if the remote `upsd` doesn't
support SSL, so don't use it unless all of them have it running.

NSS backend usage
~~~~~~~~~~~~~~~~~

This section describes how to enable NUT SSL support using
link:http://www.mozilla.org/projects/security/pki/nss/[Mozilla NSS].

Install NSS
^^^^^^^^^^^

Install link:http://www.mozilla.org/projects/security/pki/nss/[Mozilla NSS]
as usual, either from source or binary packages. If using binary packages,
be sure to include the developer libraries, and nss-tools (for `certutil`).

Recompile and install NUT
^^^^^^^^^^^^^^^^^^^^^^^^^

Recompile NUT from source, starting with `configure --with-nss`.

Then install everything as usual.

Create certificate and key for the host
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NSS (package generally called libnss3-tools) will install a tool called
`certutil`.
It will be used to generate certificates and manage certificate database.

Certificates should be signed by a certification authorities (CAs).
Following commands are typical samples, contact your SSL guru or security
officer to follow your company procedures.

.Generate a server certificate for `upsd`:
- Create a directory where store the certificate database: `mkdir cert_db`
- Create the certificate database : `certutil -N -d cert_db`
- Import the CA certificate:
	`certutil -A -d cert_db -n "My Root CA" -t "TC,," -a -i rootca.crt`
- Create a server certificate request (here called "My nut server"):
	`certutil -R -d cert_db -s "CN=My nut server,O=MyCompany,ST=MyState,C=US" -a -o server.req`
- Make your CA sign the certificate (produces server.crt)
- Import the signed certificate into server database:
	`certutil -A -d cert_db -n "My nut server" -a -i server.crt -t ",,"`
- Display the content of certificate server:
	`certutil -L -d cert_db`

Clients and servers in the same host could share the same certificate to
authenticate them or use different ones in same or different databases.
The same operation can be done in same or different databases to generate
other certificates.

Create a self-signed CA certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NSS provides a way to create self-signed certificate which can act as
CA certificate, and to sign other certificates with this CA certificate.
This method can be used to provide a CA certification chain without using
an "official" certificate authority.

.Generate a self-signed CA certificate:
- Create a directory where store the CA certificate database: `mkdir CA_db`
- Create the certificate database:
	`certutil -N -d CA_db`
- Generate a certificate for CA:
	`certutil -S -d CA_db -n "My Root CA" -s "CN=My CA,O=MyCompany,ST=MyState,C=US" -t "CT,," -x -2`
(Do not forget to answer `Yes` to the question "Is this a CA certificate [y/N]?")
- Extract the CA certificate to be able to import it in `upsd` (or `upsmon`)
certificate database:
	`certutil -L -d CA_db -n "My Root CA" -a -o rootca.crt`
- Sign a certificate request with the CA certificate (simulate a real CA
signature):
	`certutil -C -d CA_db -c "My Root CA" -a -i server.req -o server.crt -2 -6`

Install the server-side certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Just copy the database directory (just the directory and included 3
database .db files) to the right place, such as `/usr/local/ups/etc/`:

	mv cert_db /usr/local/ups/etc/


upsd (required): certificate database and self certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Edit the `upsd.conf` to tell where find the certificate database:

	CERTPATH /usr/local/ups/etc/cert_db

Also tell which is the certificate to send to clients to authenticate itself
and the password to decrypt private key associated to certificate:

	CERTIDENT "certificate name" "database password"

NOTE: Generally, the certificate name is the server domain name, but is not
a hard rule. The certificate can be named as useful.

upsd (optional): client authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NOTE: This functionality is disabled by default. To activate it, initially
`configure --with-ssl-client-validation` or just recompile NUT with macro
`WITH_CLIENT_CERTIFICATE_VALIDATION` defined:

	make CFLAGS="-DWITH_CLIENT_CERTIFICATE_VALIDATION"

UPSD can accept three levels of client authentication. Just specify it with
the directive `CERTREQUEST` with the corresponding numeric or string value
in the `upsd.conf` file:

- ('0') 'NO': no client authentication.
- ('1') 'REQUEST': a certificate is requested from the client, but it is not
  strictly validated.
+
NOTE: If the client does not send *any* certificate, the connection is closed.
- ('2') 'REQUIRE': a certificate is requested from the client, and if it is
  not valid (no trusted validation chain) the connection is closed.

Like CA certificates, you can add many "trusted" client and CA certificates
in server's certificate databases.

NOTE: You may have to use linkman:nutauth.conf[5] for stock and modernized
third-party NUT clients to even have a way to present some certain certificate.

upsmon (required): upsd authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order for `upsmon` to securely connect to `upsd`, it must authenticate it.
You must associate an `upsd` host name to security rules in `upsmon.conf`
with the directive `CERTHOST`.

`CERTHOST` associates a hostname to a certificate name. It also determines
whether a SSL connection is mandatory, and if the server certificate must be
validated.

	CERTHOST "hostname" "certificate name" "certverify" "forcessl"

If the flag `forcessl` is set to `1`, and `upsd` answers that it can not
connect with SSL, the connection closes.

If the flag `certverify` is set to `1` and the connection is done in SSL,
the certificate presented by `upsd` is verified and its name must be the
specified value of `"certificate name"`.

To prevent security leaks, you should set all `certverify` and `forcessl`
flags to `1` (force SSL connection and validate all certificates for all
peers).

You can specify `CERTVERIFY` and `FORCESSL` directive (to `1` or `0`) to
define a default security rule to apply to all host not specified with a
dedicated `CERTHOST` directive.

If a host is not specified in a `CERTHOST` directive, its expected certificate
name is its hostname.


upsmon (optional): certificate database and self certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Like `upsd`, `upsmon` may need to authenticate itself to the data server
with a client certificate (if `CERTREQUEST` directive in `upsd.conf` was
set to `REQUEST` or `REQUIRE`).

The client must access to a certificate (and its private key) in a certificate
database configuring `CERTPATH` and `CERTIDENT` in `upsmon.conf` in the
same way as `upsd`.

	CERTPATH /usr/local/ups/etc/cert_db
	CERTIDENT "certificate name" "database password"


Restart upsd
~~~~~~~~~~~~

It should come back up without any complaints.  If it says something
about keys or certificates, then you probably missed a step.

If you run `upsd` as a separate user ID (like `nutsrv`), make sure that
user can read files in the certificate directory. NUT reads the keys and
certificates after forking and dropping privileges.

Restart upsmon
~~~~~~~~~~~~~~

You should see something like this in the syslog from `upsd`:

	foo upsd[1234]: Client mon@localhost logged in to UPS [myups] (SSL)

If `upsd` or `upsmon` give any error messages, or the `(SSL)` is missing,
then something isn't right.

If in doubt about `upsmon`, start it with `-D` so it will stay in
the foreground and print debug messages.  It should print something
like this every couple of seconds:

	polling ups: myups@localhost [SSL]

Obviously, if the `[SSL]` isn't there, something's broken.

Recommended: sniff the connection to see it for yourself
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using tcpdump, Wireshark (Ethereal), or another network sniffer tool,
tell it to monitor port 3493/tcp and see what happens.  You should only
see `STARTTLS` go out, `OK STARTTLS` come back, and the rest will be
certificate data and then seemingly random characters.

If you see any plaintext besides that (USERNAME, PASSWORD, etc.)
then something is not working.

Potential problems
~~~~~~~~~~~~~~~~~~

If you specify a certificate expiration date, you will eventually
see things like this in your syslog:

	Oct 29 07:27:25 rktoy upsmon[3789]: Poll UPS [for750@rktoy] failed -
	SSL error: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE: certificate verify failed

You can verify that it is expired by using openssl to display the date:

	openssl x509 -enddate -noout -in <certfile>

It'll display a date like this:

	notAfter=Oct 28 20:05:32 2002 GMT

If that date is before the current date, you need to generate another
cert/key pair using the procedure above.

Conclusion
~~~~~~~~~~

SSL support should be considered stable but purposely under-documented
since various bits of the implementation or configuration may change in
the future. In other words, if you use this and it stops working after
an upgrade, come back to this file to find out what changed.

See linkman:upsd.conf[5], linkman:upsmon.conf[5] and linkman:nutauth.conf[5]
for the SSL configuration directives.

There are also potential licensing issues for people who ship binary
packages since NUT is GPL and OpenSSL is not compatible with it.  You
can still build and use it yourself, but you can't distribute the
results of it.  Or maybe you can.  It depends on what you consider
"essential system software", and some other legal junk that we're not
going to touch.

Other packages have solved this by explicitly stating that an exception
has been granted.  That is (purposely) impossible here, since NUT is the
combined effort of many people, and all of them would have to agree to a
license change.  This is actually a feature, since it means nobody can
unilaterally run off with the source -- not even the NUT team.

Note that the replacement of OpenSSL by Mozilla Network Security Services
(NSS) should avoid the above licensing issues.


chrooting and other forms of paranoia
-------------------------------------

It has been possible to run the drivers and `upsd` in a chrooted jail for
some time, but it involved a number of evil hacks.  From the 1.3 series,
a much saner chroot behavior exists, using BIND 9 as an inspiration.

The old way involved creating an entire tree, complete with libraries, a
shell (!), and many auxiliary files.  This was hard to maintain and
could have become an interesting playground for an intruder.  The new
way is minimal, and leaves little in the way of usable materials within
the jail.

This document assumes that you already have created at least one user
account for the software to use.  If you're still letting it fall back
on "nobody", stop right here and go figure that out first.  It also
assumes that you have everything else configured and running happily all
by itself.

Generalities
~~~~~~~~~~~~

Essentially, you need to create your configuration directory and state
path in their own little world, plus a special device or two.

For the purposes of this example, the chroot jail is `/chroot/nut`.  The
programs have been built with the default prefix, so they are using
`/usr/local/ups`.  First, create the confpath and bring over a few files.

	mkdir -p /chroot/nut/usr/local/ups/etc
	cd /chroot/nut/usr/local/ups/etc
	cp -a /usr/local/ups/etc/upsd.users .
	cp -a /usr/local/ups/etc/upsd.conf .
	cp -a /usr/local/ups/etc/ups.conf .

We're using `cp -a` to maintain the permissions on those files.

Now bring over your state path, maintaining the same permissions as
before.

	mkdir -p /chroot/nut/var/state
	cp -a /var/state/ups /chroot/nut/var/state

Next we must put `/etc/localtime` inside the jail, or you may get very
strange readings in your syslog.  You'll know you have this problem if
`upsd` shows up as UTC in the syslog while the rest of the system doesn't.

	mkdir -p /chroot/nut/etc
	cp /etc/localtime /chroot/nut/etc

Note that this is not `cp -a`, since we want to copy the *content*, not
the symlink that it may be on some systems.

Finally, create a tiny bit of `/dev` so the programs can enter the
background properly -- they redirect file descriptors into the bit
bucket to make sure nothing else grabs fds 0-2.

	mkdir -p /chroot/nut/dev
	cp -a /dev/null /chroot/nut/dev

Try to start your driver(s) and make sure everything fires up as before.

	upsdrvctl -r /chroot/nut -u nutdev start

Once your drivers are running properly, try starting `upsd`.

	upsd -r /chroot/nut -u nutsrv

Check your syslog.  If nothing is complaining, try running clients like
`upsc` and `upsmon`.  If they seem happy, then you're done.

symlinks
~~~~~~~~

After you do this, you will have two copies of many things, like the
confpath and the state path.  I recommend deleting the "real"
`/var/state/ups`, replacing it with a symlink to
`/chroot/nut/var/state/ups`.  That will let other programs reference the
`.pid` files without a lot of hassle.

You can also do this with your confpath and point `/usr/local/ups/etc` (or
equivalent on your system) at `/chroot/nut/usr/local/ups/etc` unless you're
worried about something hurting the files inside that directory.  In that
case, you should maintain a "golden" copy and push it into the chroot path
after making changes.

The `upsdrvctl` itself does not chroot, so the `ups.conf` still needs to be
in the usual confpath.

upsmon
~~~~~~

This has not yet been applied to `upsmon`, since it can be quite
complicated when there are notifiers that need to be run.  One
possibility would be for `upsmon` to have three instances:

	- privileged root parent that listens for a shutdown command

	- unprivileged child that listens for notify events

	- unprivileged chrooted child that does network I/O

This one is messy, and may not happen for some time, if ever.

Config files
~~~~~~~~~~~~

You may now set `chroot=` and `user=` in the global section of `ups.conf`.

The `upsd` chroots before opening any config files, so there is no way to
add support for that in `upsd.conf` at the present time.