Prev |  | Next

## 5. Installation instructions

This chapter describes the various methods for installing Network UPS Tools.

Whenever it is possible, prefer installing from packages. Packagers have done an excellent and hard work at improving NUT integration into their operating system. On the other hand, distributions and appliances tend to package "official releases" of projects such as NUT, and so do not deliver latest and greatest fixes, new drivers, bugs and other features.

Stable distributions also tend to deliver minor fixes to the version of third-party software (like NUT) a particular release of the operating system has initially delivered, so those release lines can be years behind development in terms of new features (or bug fixes, if they are not trivial to patch into the old code base snapshot used to create the package).

### 5.1. Installing from source

These are the essential steps for compiling and installing this software from distribution archives (usually "release tarballs") which include a pre-built copy of the `configure` script and some other generated source files.

To build NUT from a Git checkout you may need some additional tools (referenced just a bit below) and run `./autogen.sh` to generate the needed files. For common developer iterations, porting to new platforms, or in-place testing, running the `./ci_build.sh` script can be helpful. The "Building NUT for in-place upgrades or non-disruptive tests" section details some more hints about such workflow, including some `systemd` integration.

The NUT Packager Guide, which presents the best practices for installing and integrating NUT, is also a good reading.

The NUT Quality Assurance Guide (or `docs/config-prereqs.txt` in NUT sources for up-to-date information) document suggests prerequisite packages with tools and dependencies available and needed to build and test as much as possible of NUT on numerous platforms, written from perspective of CI testing (if you are interested in getting updated drivers for a particular device, you might select a sub-set of those suggestions).

### Note

This "Config Prereqs" document for latest NUT iteration can be found at https://github.com/networkupstools/nut/blob/master/docs/config-prereqs.txt or as `docs/config-prereqs.txt` in your build workspace (from Git or tarball).

### Keep in mind that…

- the paths shown below are the default values you get by just calling configure by itself. If you have used --prefix or similar, things will be different. Also, if you didn’t install this program from source yourself, the paths will probably have a number of differences.

- by default, your system probably won’t find the man pages, since they install to /usr/local/ups/man. You can fix this by editing your MANPATH, or just do this:

      man -M /usr/local/ups/man <man page>

- if your favorite system offers up to date binary packages, you should always prefer these over a source installation (unless there are known deficiencies in the package or one is too obsolete). Along with the known advantages of such systems for installation, upgrade and removal, there are many integration issues that have been addressed.

#### Prepare your system

##### System User creation

Create at least one system user and a group for running this software. You might call them "ups" and "nut". The exact names aren’t important as long as you are consistent.

The process for doing this varies from one system to the next, and explaining how to add users is beyond the scope of this document.

For the purposes of this document, the user name and group name will be ups and nut respectively.

Be sure the new user is a member of the new group! If you forget to do this, you will have problems later on when you try to start upsd.

#### Build and install

### Note

See also Building NUT for in-place upgrades or non-disruptive tests.

##### Configuration

Configure the source tree for your system. Add the --with-user and --with-group switch to set the user name and group that you created above.

    ./configure --with-user=ups --with-group=nut

If you need any other switches for configure, add them here. For example:

- to build and install USB drivers, add --with-usb (note that you need to install libusb development package or files).
- to build and install SNMP drivers, add --with-snmp (note that you need to install libsnmp development package or files).
- to build and install CGI scripts, add --with-cgi.

See Configure options from the User Manual, docs/configure.txt or ./configure --help for all the available options.

If you alter paths with additional switches, be sure to use those new paths while reading the rest of the steps.

Reference: Configure options from the User Manual.

##### Build the programs

    make

This will build the NUT client and server programs and the selected drivers. It will also build any other features that were selected during configuration step above.

### Note

NUT is regularly tested with GNU, BSD and Sun implementations of `make`.

##### Installation

### Note

You should now gain privileges for installing software if necessary, e.g.:

    su -

or prefix installation (not build/check!) commands with `sudo`, e.g.:

    sudo make install ...

### Note

If you install NUT for direct consumption on the system that has just built it from source, you might be aided for some of the steps listed and explained below by running (as `root`):

    make install-as-root

This should not only install the software, but also create directories such as the state path, assign ownership and access permissions to certain directories and sample configuration files which NUT user and/or group accounts should be able to read and/or write, and, on some platforms, also (re-)start the NUT daemons/services.

See above "System User creation", that should be done first!

Install the files to a system level directory:

    make install

This will install the compiled programs and man pages, as well as some data files required by NUT. Any optional features selected during configuration will also be installed.

This will also install sample versions of the NUT configuration files. Sample files are installed with names like ups.conf.sample so they will not overwrite any existing real config files you may have created.

If you are packaging this software, then you will probably want to use the DESTDIR variable to redirect the build into another place, also known as a "prototype directory" or a "staging area", i.e.:

    make DESTDIR=/tmp/package install
    make DESTDIR=/tmp/package install-conf

##### State path creation

### Note

See above about `make install-as-root`, if you use that — skip this step here.

Create the state path directory for the driver(s) and server to use for storing UPS status data and other auxiliary files, and make it group-writable by the group of the system user you created, e.g.:

    mkdir -p /var/state/ups
    chmod 0770 /var/state/ups
    chown root:nut /var/state/ups

##### Ownership and permissions

Set ownership data and permissions on your serial or USB ports that go to your UPS hardware. Be sure to limit access to just the user you created earlier.

These examples assume the second serial port (ttyS1) on a typical Slackware system. On FreeBSD, that would be cuaa1. Serial ports vary greatly, so yours may be called something else.

    chmod 0660 /dev/ttyS1
    chown root:nut /dev/ttyS1

The setup for USB ports is slightly more complicated. Device files for USB devices, such as /proc/bus/usb/002/001, are usually created "on the fly" when a device is plugged in, and disappear when the device is disconnected. Moreover, the names of these device files can change randomly. To set up the correct permissions for the USB device, you may need to set up (operating system dependent) hotplugging scripts. Sample scripts and information are provided in the scripts/hotplug and scripts/udev directories. For most users, the hotplugging scripts will be installed automatically by "make install".

(If you want to try if a driver works without setting up hotplugging, you can add the "-u root" option to upsd, upsmon, and drivers; this should allow you to follow the below instructions. However, don’t forget to set up the correct permissions later!).

### Note

If you are using something like udev or devd, make sure these permissions stay set across a reboot. If they revert to the old values, your drivers may fail to start.

You are now ready to configure NUT, and start testing and using it.

You can jump directly to the NUT configuration.

### 5.2. Building NUT for in-place upgrades or non-disruptive tests

### Note

The NUT GitHub Wiki article at https://github.com/networkupstools/nut/wiki/Building-NUT-for-in%E2%80%90place-upgrades-or-non%E2%80%90disruptive-tests may contain some more hints as contributed by the community.

#### Overview

Since late 2022/early 2023 NUT codebase supports "in-place" builds which try their best to discover the configuration of an earlier build (configuration and run-time paths and OS accounts involved, maybe an exact configuration if stored in deployed binaries).

This optional mode is primarily intended for several use-cases:

- Test recent GitHub "master" branch or a proposed PR to see if it solves a practical problem for a particular user;

- Replace an existing deployment, e.g. if OS-provided packages deliver obsolete code, to use newer NUT locally in "production mode".

  - In such cases ideally get your distribution, NAS vendor, etc. to provide current NUT — and benefit from a better integrated and tested product.

Note that "just testing" often involves building the codebase and new drivers or tools in question, and running them right from the build workspace (without installing into the system and so risking an unpredictable-stability state). In case of testing new driver builds, note that you would need to stop the normally running instances to free up the communications resources (USB/serial ports, etc.), run the new driver program in data-dump mode, and restart the normal systems operations.

Such tests still benefit from matching the build configuration to what is already deployed, in order to request same configuration files and system access permissions (e.g. to own device nodes for physical-media ports involved, and to read the production configuration files).

##### Pre-requisites

The NUT Quality Assurance Guide (or `docs/config-prereqs.txt` in NUT sources for up-to-date information) document details tools and dependencies that were added on NUT CI build environments, which now cover many operating systems. This should provide a decent starting point for the build on yours (PRs to update the document are welcome!)

Note that unlike distribution tarballs, Git sources do not include a `configure` script and some other files — these should be generated by running `autogen.sh` (or `ci_build.sh` that calls it).

##### Getting the right sources

To build the current tip of development iterations (usually after PR merges that passed CI, reviews and/or other tests), just clone the NUT repository and "master" branch should get checked out by default (also can request that explicitly, per example posted below).

If you want to quickly test a particular pull request, see the link on top of the PR page that says `... wants to merge ... from : ...` and copy the proposed-source URL of that "from" part.

For example, in some PR this says `jimklimov:issue-1234` and links to `https://github.com/jimklimov/nut/tree/issue-1234`. For manual git-cloning, just paste that URL into the shell and replace the `/tree/` with "`-b`" CLI option for branch selection; it also helps to keep the workspace directory name dedicated to that PR, like this:

    :; cd /tmp
    ### Checkout https://github.com/jimklimov/nut/tree/issue-1234
    :; git clone https://github.com/jimklimov/nut -b issue-1234 nut-issue-1234
    :; cd nut-issue-1234
    ### OPTIONALLY fetch known git tags, so semantic versions look better
    :; git fetch --tags --all
    ### Proceed with build (common instructions below)

#### Testing with CI helper

### Note

This uses the `ci_build.sh` script to arrange some rituals and settings, in this case primarily to default the choice of drivers to auto-detection of what can be built, and to skip building documentation. Also note that this script supports many other scenarios for CI and developers, managed by `BUILD_TYPE` and other environment variables, which are not explored here.

An "in-place" testing build and run would probably go along these lines:

    :; cd /tmp
    :; git clone -b master https://github.com/networkupstools/nut
    :; cd nut
    ### OPTIONALLY fetch known git tags, so semantic versions look better
    :; git fetch --tags --all
    ### Proceed with build
    :; ./ci_build.sh inplace
    ### Temporarily stop your original drivers
    :; ./drivers/nutdrv_qx -a DEVNAME_FROM_UPS_CONF -d1 -DDDDDD \
        # -x override...=... -x subdriver=...
    ### Can start back your original drivers
    ### Analyze and/or post back the data-dump

### Note

To probe a device for which you do not have an `ups.conf` section yet, you must specify `-s name` and all config options (including `port`) on command-line with `-x` arguments, e.g.:

    :; ./drivers/nutdrv_qx -s temp-ups \
        -d1 -DDDDDD -x port=auto \
        -x vendorid=... -x productid=... \
        -x subdriver=...

#### Replacing a NUT deployment

While `ci_build.sh inplace` can be a viable option for preparation of local builds, you may want to have precise control over `configure` options (e.g. choice of required drivers, or enabled documentation).

A sound starting point would be to track down packaging recipes used by your distribution (e.g. RPM spec or DEB rules files, etc.) to detail the same paths if you intend to replace those, and copy the parameters for `configure` script from there — especially if your system is not currently running NUT v2.8.1 or newer (which embeds this information to facilitate in-place upgrade rebuilds).

Note that the primary focus of in-place automated configuration mode is about critical run-time options, such as OS user accounts, configuration location and state/PID paths, so it alone might not replace your driver binaries that the package would put into an obscure location like `/lib/nut`. It would however install init-scripts or systemd units that would refer to new locations specified by the current build, so such old binaries would just consume disk space but not run.

It is recommended to first try installing into a prototyping area, so you can review which files get delivered and perhaps which locations you may have to tune for a more tightly tailored replacement of an older (packaged) installation, in case whole swathes of files that you expect to be present in the current system (libraries, drivers, docs) are not getting installed by the new build into same path names:

    :; rm -rf /tmp/nut ; make DESTDIR=/tmp/nut install -j 8
    :; (cd /tmp/nut && find . | sort) | while read N ; \
       do [ -e "/$N" ] || echo "=== MISSING: /$N" >&2 ; done

##### Replacing any NUT deployment

### Note

For deployments on OSes with `systemd` see the next section.

This goes similar to usual build and install from Git:

    :; cd /tmp
    :; git clone https://github.com/networkupstools/nut
    :; cd nut
    ### OPTIONALLY fetch known git tags, so semantic versions look better
    :; git fetch --tags --all
    ### Proceed with build
    :; ./autogen.sh
    :; ./configure --enable-inplace-runtime # --maybe-some-other-options
    :; make -j 4 all && make -j 4 check && sudo make install

Note that `make install` does not currently handle all the nuances that packaging installation scripts would, such as customizing filesystem object ownership, daemon restarts, etc. or even creating locations like `/var/state/ups` and `/var/run/nut` as part of the `make` target (but e.g. the delivered `systemd-tmpfiles` configuration can handle that for a large part of the audience). This aspect is tracked as issue #1298

At this point you should revise the locations for PID files (e.g. `/var/run/nut`) and pipe files (e.g. `/var/state/ups`) that they exist and permissions remain suitable for NUT run-time user selected by your configuration, and typically stop your original NUT drivers, data-server (upsd) and upsmon, and restart them using the new binaries.

##### Replacing a systemd-enabled NUT deployment

For modern Linux distributions with `systemd` this replacement procedure could be enhanced like below, to also re-enable services (creating proper symlinks) and to get them started:

    :; cd /tmp
    :; git clone https://github.com/networkupstools/nut
    :; cd nut
    ### OPTIONALLY fetch known git tags, so semantic versions look better
    :; git fetch --tags --all
    ### Proceed with build
    :; ./autogen.sh
    :; ./configure --enable-inplace-runtime # --maybe-some-other-options
    :; make -j 4 all && make -j 4 check && \
        { sudo systemctl stop nut-monitor nut-server || true ; } && \
        { sudo systemctl stop nut-driver.service || true ; } && \
        { sudo systemctl stop nut-driver.target || true ; } && \
        { sudo systemctl stop nut.target || true ; } && \
        sudo make install && \
        sudo systemctl daemon-reload && \
        sudo systemd-tmpfiles --create && \
        sudo systemctl disable nut.target nut-driver.target \
            nut-monitor nut-server nut-driver-enumerator.path \
            nut-driver-enumerator.service && \
        sudo systemctl enable nut.target nut-driver.target \
            nut-monitor nut-server nut-driver-enumerator.path \
            nut-driver-enumerator.service && \
        { sudo systemctl restart udev || true ; } && \
        sudo systemctl restart nut-driver-enumerator.service \
            nut-monitor nut-server

Note the several attempts to stop old service units — naming did change from 2.7.4 and older releases, through 2.8.0, and up to current codebase. Most of the NUT units are now `WantedBy=nut.target` (which is in turn `WantedBy=multi-user.target` and so bound to system startup). You should only `systemctl enable` those units you need on this system — this allows it to not start the daemons you do not need (e.g. not run `upsd` NUT data server on systems which are only `upsmon secondary` clients).

The `nut-driver-enumerator` units (and corresponding shell script) are part of a new feature introduced in NUT 2.8.0, which automatically discovers `ups.conf` sections and changes to their contents, and manages instances of a `nut-driver@.service` definition.

You may also have to restart (or reload if supported) some system services if your updates impact them, like `udev` for updates USB support (note also PR #1342 regarding the change from `udev.rules` to `udev.hwdb` file with NUT v2.8.0 or later — you may have to remove the older file manually).

##### Iterating with a systemd deployment

If you are regularly building NUT from GitHub "master" branch, or iterating local development branches of your own, you may get away with shorter constructs to just restart the services after installing newly built files (if you know there were no changes to unit file definitions and dependencies), e.g.:

    :; cd /tmp
    :; git clone https://github.com/networkupstools/nut
    :; cd nut
    :; git checkout -b issue-1234 ### your PR branch name, arbitrary
    ### OPTIONALLY fetch known git tags, so semantic versions look better
    :; git fetch --tags --all
    ### Proceed with build
    :; ./autogen.sh
    :; ./configure --enable-inplace-runtime # --maybe-some-other-options
    ### Iterate your code changes (e.g. PR draft), build and install with:
    :; make -j 4 all && make -j 4 check && \
        sudo make install && \
        sudo systemctl daemon-reload && \
        sudo systemd-tmpfiles --create && \
        sudo systemctl restart \
            nut-driver-enumerator.service nut-monitor nut-server

Note that to contribute your work back to upstream NUT codebase, you would need to create a "fork" of https://github.com/networkupstools/nut on GitHub, then `git remote add USERNAME https://github.com/USERNAME/nut`, maybe refresh the workspace index with `git fetch --all`, and finally `git push USERNAME` (possibly follow further instructions from `git` tooling) to create the pull request. For more details, see `docs/developers.txt` in NUT sources.

#### Next steps after an in-place upgrade

You can jump directly to the NUT configuration if you need to revise the settings for your new NUT version, take advantage of new configuration options, etc.

Check the `NEWS.adoc` and `UPGRADING.adoc` files in your checked-out Git workspace to review features that should be present in your new build.

### 5.3. Installing from packages

This chapter describes the specific installation steps when using binary packages that exist on various major systems.

#### Debian, Ubuntu and other derivatives

### Note

NUT is packaged and well maintained in these systems. The official Debian packager used to be part of the NUT Team.

Using your preferred method (apt-get, aptitude, Synaptic, …), install the nut package, and optionally the following:

- nut-cgi, if you need the CGI (HTML) option,
- nut-snmp, if you need the snmp-ups driver,
- nut-xml, for the netxml-ups driver,
- nut-powerman-pdu, to control the PowerMan daemon (PDU management)
- nut-dev, if you need the development files.

Configuration files are located in /etc/nut. nut.conf(5) must be edited to be able to invoke /etc/init.d/nut

### Note

Ubuntu users can access the APT URL installation by clicking on this link.

#### Mandriva

### Note

NUT is packaged and well maintained in these systems. The official Mandriva packager is part of the NUT Team.

Using your preferred method (urpmi, RPMdrake, …), install one of the two below packages:

- nut-server if you have a standalone or netserver installation,
- nut if you have a netclient installation.

Optionally, you can also install the following:

- nut-cgi, if you need the CGI (HTML) option,
- nut-devel, if you need the development files.

#### SUSE / openSUSE

### Note

NUT is packaged and well maintained in these systems. The official SUSE packager is part of the NUT Team.

Install the nut-classic package, and optionally the following:

- nut-drivers-net, if you need the snmp-ups or the netxml-ups drivers,
- nut-cgi, if you need the CGI (HTML) option,
- nut-devel, if you need the development files,

### Note

SUSE and openSUSE users can use the one-click install method to install NUT.

#### Red Hat, Fedora and CentOS

### Note

NUT is packaged and well maintained in these systems. The official Red Hat packager is part of the NUT Team.

Using your preferred method (yum, Add/Remove Software, …), install one of the two below packages:

- nut if you have a standalone or netserver installation,
- nut-client if you have a netclient installation.

Optionally, you can also install the following:

- nut-cgi, if you need the CGI (HTML) option,
- nut-xml, if you need the netxml-ups driver,
- nut-devel, if you need the development files.

#### FreeBSD

You can either install NUT as a binary package or as a port.

##### Binary package

To install NUT as a package execute:

    # pkg install nut

##### Port

The port is located under `sysutils/nut`. Use `make config` to select configuration options, e.g. to build the optional CGI scripts. To install it, use:

    # make install clean

##### USB UPS on FreeBSD

For USB UPS devices the NUT package/port installs devd rules in `/usr/local/etc/devd/nut-usb.conf` to set USB device permissions. devd needs to be restarted for these rules to apply:

    # service devd restart

(Re-)connect the device after restarting devd and check that the USB device has the proper permissions. Check the last entries of the system message buffer. You should find an entry like:

    # dmesg | tail
    [...]
    ugen0.2: <INNO TECH USB to Serial> at usbus0

The device file must be owned by group `uucp` and must be group read-/writable. In the example from above this would be

    # ls -Ll /dev/ugen0.2
    crw-rw----  1 root  uucp  0xa5 Mar 12 10:33 /dev/ugen0.2

If the permissions are not correct, verify that your device is registered in `/usr/local/etc/devd/nut-usb.conf`. The vendor and product id can be found using:

    # usbconfig -u 0 -a 2 dump_device_desc

where `-u` specifies the USB bus number and `-a` specifies the USB device index.

#### Windows

##### Windows binary package

### Note

NUT binary package built for Windows platform was last issued for a much older codebase (using NUT v2.6.5 as a baseline). While the current state of the codebase you are looking at aims to refresh the effort of delivering NUT on Windows, the aim at the moment is to help developers build and modernize it after a decade of blissful slumber, and packages are not being regularly produced yet. Functionality of such builds varies a lot depending on build environment used. This effort is generally tracked at https://github.com/orgs/networkupstools/projects/2/views/1 and help would be welcome!

It should currently be possible to build the codebase in native Windows with MSYS2/MinGW and cross-building from Linux with mingw (preferably in a Debian/Ubuntu container). Refer to Prerequisites for building NUT on different OSes and scripts/Windows/README.adoc file for respective build environment preparation instructions.

Note that to use NUT for Windows, non-system dependency DLL files must be located in same directory as each EXE file that uses them. This can be accomplished for FOSS libraries (copying them from the build environment) by calling `make install-win-bundle DESTDIR=/some/valid/location` easily.

Archives with binaries built by recent iterations of continuous integration jobs should be available for exploration on the respective CI platforms.

Information below may be currently obsolete, but the NUT project wishes it to become actual and factual again :)

NUT binary package built for Windows platform comes in a `.msi` file.

If you are using Windows 95, 98 or Me, you should install Windows Installer 2.0 from Microsoft site.

If you are using Windows 2000 or NT 4.0, you can download it here.

Newer Windows releases should include the Windows Installer natively.

Run `NUT-Installer.msi` and follow the wizard indications.

If you plan to use an UPS which is locally connected to an USB port, you have to install libUSB-win32 on your system. Then you must install your device via libusb’s "Inf Wizard".

### Note

If you intend to build from source, relevant sources may be available at https://github.com/mcuee/libusb-win32 and keep in mind that it is a variant of libusb-0.1. Current NUT supports libusb-1.0 as well, and that project should have Windows support out of the box (but it was not explored for NUT yet).

If you have selected default directory, all configuration files are located in `C:\Program Files\NUT\ups\etc`

##### Building for Windows

For suggestions about setting up the NUT build environment variants for Windows, please see link:docs/config-prereqs.txt and/or link:scripts/Windows/README.adoc files. Note this is rather experimental at this point.

If using USB drivers, such as `usbhid-ups`, `nutdrv_qx` or `blazer_usb`, you may benefit from the Zadig tool to pin the low-level drivers needed for LibUSB and further NUT to interact with the hardware. Otherwise, OS-provided (e.g. "HID Battery") or third-party drivers may attach and "steal" bytes from the data stream needed by LibUSB rendering it invalid.

### Note

For more details, see NUT issue #1690 and the NUT for Windows article on NUT GitHub Wiki.

#### Runtime configuration

You are now ready to configure NUT, and start testing and using it.

You can jump directly to the NUT configuration.

Prev |  | Next
| Home |