Prev |  | Next

### H.4. Optional features

#### CGI client interface

    --with-cgi (default: no)

Build and install the optional CGI programs, HTML files, and sample CGI configuration files. This is not enabled by default, as they are only useful on web servers. See data/htmlcgi/README for additional information on how to set up CGI programs.

    --with-cgi-uri=/cgi-bin/nut

If CGI feature is enabled, the path where NUT programs are expected to be exposed by the web server (e.g. if predictable by packaging integration) can be provided here and built into the `header.html` resource file, so it would be useful out of the box.

#### NUT Scanner tool

    --with-nut-scanner (default: auto)

Build and install the optional nut-scanner(8) tool to discover some types of UPS or ePDU devices on locally or remotely connected media (such as Serial, USB, SNMP, IPMI, NetXML), as well as NUT data servers (by Avahi/mDNS broadcasts or "old" NUT port polling) and simulation device configurations that can be relayed by a local dummy-ups(8) driver instance.

Many of the features depend on third-party libraries that are loosely linked at run-time using libltdl, and due to that, the build, delivery and use of the tool does not depend on all of them being available in the final deployment.

    --with-threading (default: auto)

Currently limited to nut-scanner(8) tool: require/allow build with pthreads and/or semaphore support to parallelize the network and local port scans, and scans of different media types.

Some older systems' implementation of threading may be broken, so while we can detect support, builds using it can fail in practice — so this toggle allows to keep building sequential-only code.

#### NUT Configuration tool

    --with-nutconf (default: auto)

Build and install the optional nutconf(8) tool to create and manipulate NUT configuration files. It also optionally supports device scanning, using the nutscan(3) library (if built), to suggest configuration of devices.

#### Pretty documentation and man pages

    --with-docs=<output-format(s)>  (default: no)
    --with-doc=<output-format(s)>  (default: no)

Build and install NUT documentation file(s). Note: `--with-doc` is a legacy NUT option, and `--with-docs` is an alias that matches the more wide-spread equivalent in different packaging frameworks and projects.

This feature requires AsciiDoc 8.6.3 or newer (see https://asciidoc.org).

The possible documentation type values are:

- `html-single` for single page HTML,
- `html-chunked` for multi-paged HTML,
- `pdf` for a PDF file, and
- `man` for the usual man pages.

Other values understood for this option are listed below:

- If the `--with-doc` argument is passed without a list, or specifies just `=yes` or `=all`, it enables all supported formats with a `=yes` to require them.
- An (explicit!) `--with-doc=auto` argument tries to enable all supported formats with an `=auto` but should not fail the build if something can not be generated.
- A `--with-doc=no` quietly skips generation of all types of documentation, including man pages.
- A `--with-doc=skip` is used to configure some of the `make distcheck*` scenarios to re-use man page files built and distributed by the main build and not waste time on re-generation of those.
- A `--with-doc=dist-auto` allows to use pre-distributed MAN pages if present (should be in "tarball" release archives; should not be among Git-tracked sources; may be left over from earlier builds in same workspace), or build those if we can (the `auto` part). Practically this is implemented in detail only for `--with-doc=man=dist-auto`, as we do not dist HTML and PDF products; it is a placeholder for those to simplify the generic configuration calls.

Multiple documentation format values can be specified, separated with comma. Each such value can be suffixed with `=yes` to require building of this one documentation format (abort configuration if tools are missing), `=auto` to detect and enable if we can build it on this system (and not abort if we can not), and `=no` (or `=skip`) to explicitly skip generation of this document format even if we do have the tools to build it.

If a document format is mentioned in the list without a suffix, then it is treated as a `=yes` requirement.

Verbose output can be enabled using: `ASCIIDOC_VERBOSE=-v make`

Example valid formats of this flag:

- `--with-doc` without an argument, effectively same as `--with-doc=yes`
- `--with-doc=` is a valid empty list, effectively same as `--with-doc=no`
- `--with-doc=auto`
- `--with-doc=pdf,html-chunked`
- `--with-doc=man=no,pdf=auto,html-single`

Additional flags with regard to documentation generation include:

    --enable-docs-man-for-progs-built-only=<yes|no>

Choose to build and install MAN pages only for the NUT programs being built in this run (this is the legacy default selection), or all known MAN pages (including for NUT programs and drivers not being built now). Should not affect the API manual pages (but note they may be impacted by `--with-dev`).

### Note

You want this set to `no` when preparing NUT distribution tarballs.

    --with-docs-man-section-api=<SN>        (default: 3)
    --with-docs-man-section-cfg=<SN>        (default: 5)
    --with-docs-man-section-cmd-sys=<SN>    (default: 8, or 1m on Solaris/illumos)
    --with-docs-man-section-cmd-usr=<SN>    (default: 1)
    --with-docs-man-section-misc=<SN>       (default: 7)

Customize man page section identifiers for operating systems whose standards do not match defaults listed above for Library and API, Configuration Files, System Management Commands and User Commands sections (e.g. Solaris-derived systems might use `--with-docs-man-section-cmd-sys=1m`). This impacts not only file names of the manual pages, but also cross-links in generated documents. Note that use of these flags does not implicitly enable any `--with-docs=...` mode, which should still be specified explicitly.

    --with-docs-man-dir-as-base=(yes/no)    (default: yes, or no Solaris/illumos)

Are platform man directories named by base number (yes) or by full section name (no), e.g. given a `1m` man page section, install the pages into `man1` or `man1m` directory?

    --enable-docs-changelog=<yes|no|skip|auto|{format,list}>

This option was added specifically to allow developer iterations to not waste CPU time rebuilding the huge `ChangeLog*` files whenever their Git index changes. For troubleshooting purposes, this option supports specifying the list of formats (text, adoc, html-single, html-chunked, pdf) with optional suffixes to build (empty/=yes), consider (=auto) or not-build (=no or =skip) specific formats; note that some are prerequisites for others (plain text and prepared adoc are needed to generate HTML and PDF).

    --with-docs-changelog-start=<auto|git-tree-ish>
    --with-docs-changelog-end=<auto|git-tree-ish>

This option was added to allow developers (and CI build agents) to customize the size of `ChangeLog*` files when they are generated. Balancing against the option above to not build `ChangeLog*` files at all, this couple allows quicker builds that exercise all relevant recipe code paths.

Default value for the starting point is `auto`, which applies the legacy default `v2.6.0` either to release/pre-release builds, or when local Git version metadata could not be retrieved, and the most-recent release tag (or `master` as fallback) for usual build iterations.

Default value for the ending point is `HEAD` to represent the current commit at the moment the `ChangeLog` file and its derivatives are (re-)generated.

### Note

The resulting `GITLOG_START_POINT` value may also impact the oldest version considered by maintainer helper script `docs/docinfo.xml.sh` (if it specifies a `v*` tag, otherwise `v2.6.0` is used).

    --with-docs-man-linkmanext-template='https://linux.die.net/man/{0}/{target}'
    --with-docs-man-linkmanext2-template='https://linux.die.net/man/{2}/{target}'
    --enable-docs-man-linkmanext-section-rewrite

NUT manual pages can refer to system-provided programs, files or syscalls using custom-defined `linkmanext` or `linkmanext2` asciidoc macros. They in turn use man page sections, which may be subject to rewrites similar to those applied to NUT pages themselves. The options above should help packagers manage this; defaults are set for Linux standard filesystem layout.

### Note

Avoid characters special for XML or HTML mark-up needed in the template (notably the `&` "ampersand" in HTML URLs with queries), entities like `&amp;` must be used to pass docbook part (not man page generation though) and then it stays in the final document, making the URL invalid. PRs welcome :)

#### Python support

NUT includes a client binding `PyNUT` module, as well as an optional GUI application `NUT-Monitor` (not to be confused with `nut-monitor` service name for `upsmon` as delivered by some OS distribution packages). Both python 2.7 and several versions of python 3.x are supported and regularly tested by NUT CI farm builds; other versions may work or not.

Also some of the source configuration (including activity in `autogen.sh` script and later in certain `Makefile`s during build) relies on presence of `python` (and `perl`) interpreters. If they are not available, e.g. on older operating systems, certain features are skipped — but you may have to `export` special environment variables to signal to `autogen.sh` that this is an expected situation (it would suggest which, for your current NUT version).

### Note

For CI builds (or similar reproducible developer activity) performed with `ci_build.sh`— since this is an area which impacts both `configure` script generation by the helper `autogen.sh` script and subsequently the choices made by the `configure` script itself, settings can be made by exporting the `PYTHON` environment variable which should evaluate to some way to call the correct interpreter (e.g. `python2.7`, `/usr/bin/env python` or `/usr/bin/python3`).

The `configure` script does support equivalent options, whose defaults come from detection of certain program names by current `PATH` setting. Further use of these interpreter names and other paths during NUT build and installation is managed by Makefile variable expansion, as prepared by the `configure` script.

Also note that it is not required to use the same `PYTHON` implementation for `autogen.sh` to do its job, and for the `configure` script option.

As noted above, both python-2.x and python-3.x variants are supported. You can consult the `m4/nut_check_python.m4` file for detection methods used. If both interpreter generations are present, and a particular un-versioned `PYTHON` is not specified or detected, then selected/detected `PYTHON3` is chosen as the ultimate `PYTHON` value.

For majority of uses in the build procedure and products, the generation of Python does not matter and the un-versioned `PYTHON` value is substituted into files as the script shebang, used to find the `site-packages` location, etc.

One exception is generation of NUT-Monitor GUI application, being separated for `NUT-Monitor-py2gtk2`, `NUT-Monitor-py3qt5`, `NUT-Monitor-py3qt6` due to further backend platform technical differences — these build products specifically use `PYTHON2` and `PYTHON3` substitutions. They may also be co-installed on the same system. A dispatcher shell script `NUT-Monitor` is used to launch the preferred (newest) or the only existing implementation.

Please note that by default NUT tries to make use of everything in your build environment, so if both Python generations are detected — the binding module will be delivered into both, and two versions of NUT-Monitor GUI application will be installed. If you want to avoid that behaviour on a build system with both interpreters present, you can explicitly specify to build e.g. `--without-python2 --with-python=/usr/bin/python-3.9`.

Default values are currently prioritized for auto-detection to result in some one Python interpreter version to be chosen even if several were discovered (in order: 3, 2, or not numbered), using `auto-prio=NUM` syntax. If some of these options specify a particular interpreter, none of the `auto-prio` hits are considered.

### Note

Previous default (from NUT v2.8.0 to v2.8.4) was `auto` to allow all up to three hits to be considered as script shebang and as `make install` targets. When using `auto` values, specifying an explicit `--with-python` value does not implicitly mean `--without-python2` nor `--without-python3`, and those would be discovered and configured for, if possible. Conversely, an explicit e.g. `--with-python2` setting does not automatically mean `--without-python` nor `--without-python3`. Since this may come across surprising to some people, the `configure` script would warn in the end if several Python versions were auto-detected one way or another.

A value of `yes` (default if e.g `--with-python` is specified without an argument) means to search for an implementation, and fail if one was not located.

The settings below may be of particular interest to non-distribution packaging efforts with their own dedicated directory trees (like pkgsrc), or where all packages have dedicated sub-trees (like NixOS):

    --with-python=SHEBANG_PATH

Specify a definitive version you want used for majority of the Python code (except version-dependent scripts, see above).

The `SHEBANG_PATH` should be a full program pathname, optionally with one argument, e.g. `/usr/bin/python-3.9` or `/usr/bin/env python2`. Note that packaging distributions generally aim for predictable setups, and disapprove of `/usr/bin/env` in shebangs for packaged scripts.

Defaults for `--with-python` if it was not specified (in order): * `python`, `python3` or `python2` program if present in `PATH` by such name, * or the newest of `PYTHON3` or `PYTHON2` values (specified or detected below).

    --with-python2=SHEBANG_PATH
    --with-python3=SHEBANG_PATH

For version-dependent scripts (see above) or to default the newest Python version if not specified by `--with-python` option or detected otherwise, you can provide the preferred version and implementation of Python 2 or 3 respectively.

Conversely, if neither of these configure options were specified, but some `--with-python` program was specified or detected, and its report says it has Python major version 2 or 3, then the versioned interpreter string would point to that.

    --with-nut_monitor

Install the NUT-Monitor GUI application (depending on Python 2 or 3 version availability), and optional `desktop-file-install` integration).

    --with-pynut

Install the PyNUT module files for general consumption into "site-packages" location of the currently chosen Python interpreter(s): `yes`, `no`, `auto`. or dedicated as the required dependency of NUT-Monitor application (app).

    --with-python-modules-dir=(auto|PATH)
    --with-python2-modules-dir=(auto|PATH)
    --with-python3-modules-dir=(auto|PATH)

Optional, to specify PyNUT(Client) module installation location (for the module-named dir to be created under it), if not bundling with NUT-Monitor UI app. By default the respective interpreter’s site-packages or dist-packages location will be used, so you may have to adjust module search paths for any other values (see `NUT-Monitor` GUI sources for an example).

### Note

Specifically in `NUT-Monitor` scripts, the version-less option gets least priority in search path, but corresponding versioned ones (if not there yet) would be searched first. Any copy of the PyNUT module located near the script (as in NUT source tree) has the highest priority of all. This option may help to make use of that module installed by other means (e.g. as a released PyPI repository package), if you for some reason (like OS packaging policy) choose to build and install NUT itself `--without-pynut`.

### Warning

The module files are installed into a location dedicated to the particular Python version, such as `/usr/lib/python2.7/dist-packages` even if you specify a relaxed or un-versioned interpreter like `python2` (which would be used in scripts for the NUT-Monitor application and possible other consumers of the module).

If the preferred Python version in the deployed system changes later (so the `python2` symlink for this example would point elsewhere) the module import would become not resolvable for such consumers, until it is installed into that other Python’s "site-packages" location.

#### Development files

    --with-dev (default: no)

Build and install the upsclient and nutclient library and header files, to build further projects against NUT (such as wmNUT client and many others).

Also delivers `libnutscan` library and header files, if `--with-nut-scanner` is enabled.

Disabled development file delivery, in particular, disables installation of static libraries.

    --with-dev-libnutconf (yes/no/auto, default: no)

Build and install the nutconf library and header files, to build further projects against NUT (especially those that need to set it up). This is currently not automatically tied into either `--with-dev` nor `--with-nutconf` (note below on `--with-all`), because the tool and library are experimental and the API may yet undergo significant changes in the coming years.

It is more recommended to use the CLI tool as a presumably more stable API for third-party integrations, than the library directly.

This feature may however be enabled or disabled implicitly, using `--with-all(=yes/no/auto)` request, based on a combination of `--with-nutconf` and `--with-dev` options:

- if `--without-all`, default to set `--with-dev-libnutconf=no`; otherwise…
- if either `--without-dev` or `--without-nutconf`, default to set `--with-dev-libnutconf=no`; otherwise…
- if either `--without-dev=auto` and/or `--without-nutconf=auto`, default to set `--with-dev-libnutconf=auto`; otherwise…
- if both `--with-dev` and `--with-nutconf`, default to set `--with-dev-libnutconf=yes`.

Requires C++11 support to be enabled (available in compiler, not neutered by explicit selection of an older standard).

    --enable-ldflags-nut-rpath (yes/no/auto/flags, default: auto)
    --enable-ldflags-nut-rpath-cxx (yes/no/auto/flags, default: auto)

NUT development files include the `*.pc` metadata for `pkg-config` ecosystem and a legacy `libupsclient-config` script, both used to deliver compiler and linker options for third-party programs to build against NUT libraries.

There can be a problem during run-time, when NUT is installed into a location that the system linker does not know to look into, e.g. the default `--prefix` value of `/usr/local/ups`, that the built programs fail to dynamically link with the shared objects of NUT libraries, unless deprecated tricks like the `LD_LIBRARY_PATH` setting are applied.

These options allow NUT to add linker options, which set "RPATH" in consumer binaries, to the announced metadata. As a result, third-party programs or libraries are hard-coded to look for NUT libraries in a certain location, in addition to system locations and similar paths added by other dependencies.

By default (in `auto` mode), the `configure` script queries the compiler for known system library paths (currently supported with GCC and CLANG builds), and checks the NUT `libdir` against that list. If there is a hit, no extra flags are announced; otherwise, the format detected for currently used linker by autoconf libtool macros is added to the announced metadata for builds against NUT. If this causes problems, you can either `--disable-...` these flags or provide the desired string explicitly.

#### Options for developers

    --enable-spellcheck (default: auto)

Activate recipes for documentation source file spelling checks with `aspell` tool. Default behavior depends on availability of the tool, so if present — it would run for `make check` by default, to facilitate quicker acceptance of contributions.

    --enable-check-NIT (default: no)

Add `make check-NIT` to default activity of `make check` to run the NUT Integration Testing suite. This is potentially dangerous (e.g. due to port conflicts when running many such tests in same environment), so not active by default.

    --enable-maintainer-mode (default: no)

Use maintainer mode to keep `Makefile.in` and `Makefile` in sync with ever-changing `Makefile.am` content after Git updates or editing.

    --enable-cppcheck (default: no)

Activate recipes for static analysis with `cppcheck` tools (if available).

    --with-unmapped-data-points (default: no)

Build SNMP and USB-HID subdrivers with entries discovered by the scripts which generated them from data walks, but developers did not rename yet to NUT mappings conforming to `docs/nut-names.txt` standards. Production driver builds must not include any non-standard names.

    --enable-NUT_STRARG-always (default: auto)

Enable the `NUT_STRARG` macro (to handle `NULL` string printing) even if the system libraries seem to safely support this behavior natively? This flag should primarily help against overly zealous static analysis tools in recent compiler generations. The `auto` value enables the flag for certain compiler versions known to complain about some of our use cases — even though those seem to be false positives.

    --enable-configure-debug

Cause the `configure` script run to report some internal values of variables as it goes through making of choices, to help recipe developers troubleshoot it.

    --enable-shared-private-libs (default: no)

Deliver NUT common libraries as shared objects used by different NUT binaries, rather than linking just the used bits into each binary.

This has some potential both for mayhem (so disabled by default) and for significant reduction of installation footprint.

#### I want it all!

    --with-all (no default)

Build and install all of the above (the serial, USB, SNMP, XML/HTTP and PowerMan drivers, the CGI programs and HTML files, and the upsclient library).

You can also use `--with-all=auto` to detect available prerequisites and only build everything that we can build on this system (but not fail due to inability to request a build of something from the full scope).

#### Networking transport security

    --with-ssl (default: auto-detect)
    --with-nss (default: auto-detect)
    --with-openssl (default: auto-detect)

Enable SSL support, using either Mozilla NSS or OpenSSL.

If both are present, and nothing was specified, OpenSSL support will be preferred.

Extended syntax also supports `--with-ssl=nss` or `--with-ssl=openssl`.

### Note

Currently the two implementations differ in supported features.

    --with-ssl-client-validation (default: no)

Enable the `upsd` server-side ability to set up `CERTREQUEST` directive in `upsd.conf`, which lets the server reject clients which do not present a certificate.

### Warning

Until issue #3329 is solved, not all stock NUT clients may even have a way to present some certain certificate.

Read docs/security.txt for instructions on practical setup of SSL support.

#### Networking access security

    --with-wrap (default: auto-detect)

Enable libwrap (tcp-wrappers) support.

Refer to upsd(8) man page for more information.

#### Networking IPv6

    --with-ipv6 (default: auto-detect)

Enable IPv6 support.

#### AVAHI/mDNS

    --with-avahi (default: auto-detect)

Build and install Avahi support, to publish NUT server availability using mDNS protocol. This requires Avahi development files for the Core and Client parts.

#### LibLTDL

    --with-libltdl (default: auto-detect)

Enable libltdl (Libtool dlopen abstraction) support.

This is required to build `nut-scanner` which loads third-party libraries dynamically, based on requested scanning options. This allows to build and package the tool without requiring all possible dependencies to be installed in each run-time environment.

Prev | Up | Next
| Home |