NUT Web GUI

Lightweight web interface for Network UPS Tools.

Quickstart

Docker/Podman:

docker run -p 9000:9000 \
  -e UPSD_ADDR=10.0.0.1 \
  -e UPSD_USER=test \
  -e UPSD_PASS=strongpass \
  ghcr.io/superioone/nut_webgui:latest

Container image registries: - Codeberg: codeberg.org/superiorone/nut_webgui:latest - GitHub: ghcr.io/superioone/nut_webgui:latest

Features

• Monitors UPS variables with auto-refresh.
• Supports INSTCMD, SET VAR, and FSD calls from GUI.
• Potato PC friendly. Small footprint on both resource usage and disk size.
• Basic JSON API.
• Supports RISC-V and older ARM devices.

In order to run INSTCMD and FSD, make sure the configured user has the proper privileges in upsd.users. See man(upsd.users).

Examples/How-To's

• Volumes and args
• Docker/Podman compose
• Kubernetes - Basic
• Kubernetes - EndpointSlice
• Custom base path for reverse proxy
• Accessing localhost
• Using NUT with TLS
• Enabling Auth and API Keys
• Connecting multiple NUT servers
• Binary installation
• Events API
• OpenMetrics

CPU architecture support

amd64 v3 and v4 variants require certain CPU feature flags to run. If you are a crackhead min-max enjoyer (like me), you can use nut_webgui:latest-amd64-v3 and nut_webgui:latest-amd64-v4 images. See x86-64 Microarchitecture levels for more details.

Configuration

nut_webgui can be configured via args, environment variables, or config file. All configuration options are merged into single unified config based on their priority.

CLI arguments

CLI arguments hold the highest priority in configuration settings.

• --allow-env: Allow application to load configuration from environment variables.
• --anonymous-metrics: Set anonymous access on /metrics endpoint, ignored when auth is disabled. Default is false.
• --base-path: Override HTTP server base path. Default is /.
• --config-file: config.toml path.
• --default-theme: Web UI default theme.
• --listen: Listen address for the HTTP server. Default is 0.0.0.0.
• --log-level: Log level for the HTTP server. Default is info.
• --port: Port used by the HTTP server. Default is 9000.
• --server-key: Set private server key value. Default is auto-generated value.
• --with-auth: Enable authentication with user.toml file.
• --worker-count: Set HTTP server worker count.

Environment variables

Environment variables have the second-highest priority in configuration settings. Accepts direct values or file paths (automatically reads file contents).

General

Default UPSD

If you only connect to a single NUT server and want to keep configurations simple as possible, connection details can be configured via NUTWG__UPSD__* environment variables.

Container only

The following environment variables are available only to container images and do not apply to binary installations.

TOML config

Config.toml has the least priority, but it's recommended to use the config file as a baseline configuration and use environment variables and command-line arguments to override settings when needed.

version = "1"
log_level = "info"
default_theme = "tokyo-night"

[http_server]
base_path = "/"
listen = "0.0.0.0"
port = 9000
worker_count = 8

[upsd.default]
username = "admin"
password = "where an old man of Aran goes around and around"
address = "localhost"
port = 3493
max_connection = 4
poll_freq = 30
poll_interval = 2
tls_mode = "disable"

[upsd.reactor]
address = "10.0.12.10"
username = "observer"
password = "AbsoluteSecurity"

[auth]
users_file = "/etc/nut_webgui/users.toml"
allow_anonymous_metrics = false

For more detailed config template see ./dist/config.toml.

UniFi NUT Specific Configuration

The current UniFi NUT server supports up to 3 client connections, and when this limit is exceeded, the server restarts itself. To prevent this issue, set the maximum connection limit to 1 using one of the following methods:

• Set the NUTWG__UPSD__MAX_CONNECTION environment variable if you are using a single NUT server
• Configure max_connection in the config.toml file

JSON data API

A simple JSON-based API is available for general-purpose integrations.

OpenAPI 3.0.0 specification files: json | yaml

Events API

Real-time UPS events can read via WebSocket at /events. For more details see Events API.

Probes

nut_webgui has basic probe endpoints to check server health and readiness: - /probes/health - /probes/readiness

If you've multiple NUT server connections, you can also probe the individual connection:

• /probes/health/<namespace>
• /probes/readiness/<namespace>

OpenMetrics

UPS metrics can be scraped from /metrics endpoint. For more details see the OpenMetrics.

Building from source and debugging

Building and Debugging

Custom Build Pipeline