https://github.com/superioone/nut_webgui
Web interface for Network UPS Tools
https://github.com/superioone/nut_webgui
management network-ups-tools nut self-hosted ups
Last synced: 5 months ago
JSON representation
Web interface for Network UPS Tools
- Host: GitHub
- URL: https://github.com/superioone/nut_webgui
- Owner: SuperioOne
- License: apache-2.0
- Created: 2024-01-04T02:19:23.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2026-01-13T20:32:45.000Z (5 months ago)
- Last Synced: 2026-01-13T22:26:06.318Z (5 months ago)
- Topics: management, network-ups-tools, nut, self-hosted, ups
- Language: Rust
- Homepage:
- Size: 2.6 MB
- Stars: 286
- Watchers: 1
- Forks: 16
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
Awesome Lists containing this project
README
# NUT Web GUI
Light weight web interface for [Network UPS Tools](https://networkupstools.org/).
## Quickstart
Docker/Podman:
```shell
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
```
## 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 proper privileges given at `upsd.users`. See
> man([upsd.users](https://networkupstools.org/docs/man/upsd.users.html)).
## Examples/How-To's
- [Volumes and args](docs/examples/01_volumes_and_args.md)
- [Docker/Podman compose](docs/examples/02_compose.md)
- [Kubernetes - Basic](docs/examples/03_kubernetes_basic.md)
- [Kubernetes - EndpointSlice](docs/examples/04_kubernetes_endpointslice.md)
- [Custom base path for reverse proxy](docs/examples/05_reverse_proxy_base_path.md)
- [Accessing localhost](docs/examples/06_accessing_localhost.md)
- [Using NUT with TLS](docs/examples/07_nut_and_tls.md)
- [Enabling Auth and API Keys](docs/examples/08_enabling_auth.md)
- [Connecting multiple NUT servers](docs/examples/09_multiple_nut_connection.md)
- [Binary installation](docs/examples/10_binary_installation.md)
## CPU architecture support
| Arch | Test Hardware | Notes |
|----------|------------------------|-----------------------------------------------------------------------------------------------|
| amd64 | AM4 CPU | Works across all amd64 platforms. |
| amd64-v3 | AM4 CPU | Snake oil level optimizations with AVX. It mostly improves response compression, and TLS. |
| amd64-v4 | Intel® SDE | Snake oil level optimizations with AVX-512. It mostly improves response compression, and TLS. |
| arm64 | Raspberry Pi 4 Model B | |
| armv7 | Qemu emulation | Uses software floating-point. |
| armv6 | Qemu emulation | Uses software floating-point. |
| riscv64 | Qemu emulation | |
> 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](https://en.wikipedia.org/wiki/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`: Allows application to load configuration from environment variables.
* `--base-path`: Overrides 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`: Private server key value. Default is randomly auto-generated value.
* `--with-auth`: Enables authentication with `user.toml` file.
### Container image environment variables
Environment variables have the second-highest priority in configuration settings. They can also accept file paths as values. When an environment variable
specifies a file path, the system automatically reads content of that file as a value.
#### General
| Name | Alias (Container Only) | Default | Value | Description |
|---------------------------------|------------------------|-------------------------------|---------------------------------------------|-------------------------------------------------------------|
| `NUTWG__CONFIG_FILE` | `CONFIG_FILE` | `/etc/nut_webgui/config.toml` | File path | Custom `config.toml` file path. |
| `NUTWG__DEFAULT_THEME` | `DEFAULT_THEME` | None | See [config.toml](./dist/config.toml) | Web UI default theme. |
| `NUTWG__LOG_LEVEL` | `LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, `trace` | Log level. |
| `NUTWG__SERVER_KEY` | `SERVER_KEY` | `/etc/nut_webgui/server.key` | File path, UTF-8 string | Server sign key used for signing session tokens. |
| `NUTWG__AUTH__USERS_FILE` | `AUTH_USERS_FILE` | None | File path | Enables authentication with the provided `users.toml` file. |
| `NUTWG__HTTP_SERVER__BASE_PATH` | `BASE_PATH` | `/` | | Overrides HTTP server base path. |
| `NUTWG__HTTP_SERVER__LISTEN` | `LISTEN` | `0.0.0.0` | | HTTP server listen address. |
| `NUTWG__HTTP_SERVER__PORT` | `PORT` | `9000` | 1-65535 | HTTP server listen port. |
| `UPSD_ROOT_CA` | | None | | Path to the Root CA certificate for TLS. |
#### 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.
| Name | Alias (Container Only) | Default | Value | Description |
|-------------------------------|------------------------|-------------|-----------------------------|-------------------------------------------------------------------|
| `NUTWG__UPSD__ADDRESS` | `UPSD_ADDR` | | IPv6, IPv4, hostname | UPS daemon address. |
| `NUTWG__UPSD__MAX_CONNECTION` | | `4` | | Allowed maximum connection for UPSD client. |
| `NUTWG__UPSD__NAME` | | `default` | | Target namespace for the `NUTWG__UPSD__*` environment variables. |
| `NUTWG__UPSD__PASSWORD` | `UPSD_PASS` | None | | UPS daemon password. |
| `NUTWG__UPSD__POLL_FREQ` | `POLL_FREQ` | `30` | | Non-critical ups variables update frequency in seconds. |
| `NUTWG__UPSD__POLL_INTERVAL` | `POLL_INTERVAL` | `2` | | Critical ups variables (`ups.status`) update interval in seconds. |
| `NUTWG__UPSD__PORT` | `UPSD_PORT` | `3493` | 1-65535 | UPS daemon port. |
| `NUTWG__UPSD__TLS_MODE` | `UPSD_TLS` | `disable` | `strict`, `disable`, `skip` | Configures TLS communication between UPSD and client. |
| `NUTWG__UPSD__USERNAME` | `UPSD_USER` | None | | UPS daemon username. |
### 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 or command-line arguments
to override settings when needed.
```toml
version = "1"
log_level = "info"
default_theme = "tokyo-night"
[http_server]
base_path = "/"
listen = "0.0.0.0"
port = 9000
[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"
```
For more detailed config template see [./dist/config.toml](./dist/config.toml).
## JSON data API
A simple JSON-based API is available for integration and automation purposes.
OpenAPI 3.0.0 specification files: [json](docs/api_specs/openapi3_spec.json) | [yaml](docs/api_specs/openapi3_spec.yaml)
## 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/`
- `/probes/readiness/`
## Building from source and debugging
[Building and Debugging](./docs/building_debugging.md)
[Custom Build Pipeline](./docs/custom_build_pipeline.md)