vergoh/vnstat
vnStat in a container with image output via http
1M+
vnStat is a network traffic monitor that uses the network interface statistics provided by the kernel as information source. This means that vnStat won't actually be sniffing any traffic and also ensures light use of system resources regardless of network traffic rate.
By default, traffic statistics are stored on a five minute level for the last 48 hours, on a hourly level for the last 4 days, on a daily level for the last 2 full months and on a yearly level forever. The data retention durations are fully user configurable. Total seen traffic and a top days listing is also provided.
See the official webpage or the GitHub repository for additional details and output examples. An example of the included image output is also available.
vnstatd
) is running as the primary processvnstati
) via http (port 8685 on all interfaces by default)
vnstat
)vergoh/vnstat:latest
- latest released vnStat versionvergoh/vnstat:dev
- latest commit from GitHub repositoryghcr.io/vergoh/vnstat:latest
- latest released vnStat versionghcr.io/vergoh/vnstat:dev
- latest commit from GitHub repositoryVersion specific tags are available starting from 2.7
with the latest release being the same as latest
tag. latest
and dev
are automatically built at least once every month to include possible build time dependency updates.
docker build -t vergoh/vnstat .
docker run -d \
--restart=unless-stopped \
--network=host \
-e HTTP_PORT=8685 \
-v /etc/localtime:/etc/localtime:ro \
-v /etc/timezone:/etc/timezone:ro \
--name vnstat \
vergoh/vnstat
--network=host
is necessary for accessing the network interfaces of the Docker host instead of being limited to monitoring the container specific interface/etc/localtime
and /etc/timezone
are used to configure the container to use the same time zone as the host is using
TZ
environment variable can be used (-e TZ=
) with a supported value, localtime and timezone volumes are overridden if used in combination--privileged
may need to be used if the date within the container starts from 1970
HTTP_PORT
variable. As --network=host
needs to be enabled, the usual Docker port mapping with -p
or --publish
isn't available with this container. Visibility of the http server can be restricted using firewall rules or binding the http server to a specific IP address using the HTTP_BIND
variable. Localhost access can be enforced by setting HTTP_BIND
as 127.0.0.1
http://localhost:8685/
(using default port)http://localhost:8685/json.cgi
(using default port)http://localhost:8685/metrics
(using default port)-v some_local_directory:/var/lib/vnstat
to map the database directory to the local filesystem if easier access/backups is neededCommand line interface can be accessed with:
docker exec vnstat vnstat --help
Two example docker compose files are provided:
docker-compose.yml
is the more simple example with both the vnStat daemon and the httpd running in the same container. While this example works without changes for most users, it results in the httpd also using host networking which may not be a wanted feature for some users.
docker-compose_isolated_httpd.yml
consist of two containers running from the same image. The vnStat daemon is running in the first container (vnstat
) with host networking in order to access all network interfaces but doesn't provide any services or bind to ports. The second container (vnstati
) doesn't use host networking but provides the httpd which accesses the statistics using a shared volume in read-only mode.
Name | Description | Default value |
---|---|---|
HTTP_PORT | Port of the http server, use 0 to disable http server | 8685 |
HTTP_BIND | IP address for the http server to bind, use 127.0.0.1 to bind only to localhost and prevent remote access | * , all addresses |
HTTP_LOG | Http server log output file, use /dev/stdout for output to console and /dev/null to disable logging | /dev/stdout |
SERVER_NAME | Name of the server in the web page title | Output of hostname command |
LARGE_FONTS | Use large fonts in images (0: no, 1: yes) | 0 |
CACHE_TIME | Cache created images for given number of minutes (0: disabled) | 1 |
DARK_MODE | Black background and inverted image colors, 0: disabled, 1: enabled without rx/tx color inversion, 2: enabled for all colors (available starting from version 2.12) | 0 |
PAGE_REFRESH | Page auto refresh interval in seconds (0: disabled) | 0 |
RUN_VNSTATD | Start vnStat daemon (0: no, 1: yes) | 1 |
INDEX_IMAGES_PER_ROW | Number of images to show per row on the index page when the database contains more than one interface (1000: auto fit) (available starting from version 2.13) | 1 |
INDEX_IMAGE_OUTPUT | Image output to use on index page when the database contains more than one interface (available starting from version 2.13) | hs |
INDEX_SHOWN_INTERFACES | Regular expression pattern for selecting which interfaces are shown on the index page when the database contains more than one interface. Leave empty or unset to disable filter. All not shown interfaces will still be monitored. (available starting from version 2.13) | unset |
INDEX_HIDDEN_INTERFACES | Regular expression pattern for selecting which interfaces are hidden from the index page when the database contains more than one interface. Leave empty or unset to disable filter. All hidden interfaces will still be monitored. (available starting from version 2.13) | unset |
EXCLUDE_PATTERN | Extended regular expression pattern for excluding interfaces from getting monitored. For example, ^docker|^veth|^br-|^lxc would exclude interface names starting with docker , veth , br- and lxc . | unset |
TZ | Set time zone (list of supported values), overrides configuration from possible /etc/localtime and /etc/timezone volumes | unset |
VNSTAT_ prefix | All vnstat.conf configurations can be modified using a VNSTAT_ prefixed variable followed with the configuration keyword. For example, changing CRx (color for received data) to 79C999 (pale teal) can be done by defining VNSTAT_CRx=79C999 . Variable name is case sensitive. | unset |
Name | Description | Default value |
---|---|---|
RATE_UNIT | 1 | |
INTERFACE | unset | |
INTERFACE_ORDER | 0 | |
QUERY_MODE | 0 |
docker exec vnstat vnstat -i eno3 --setalias "Basement switch"
docker exec vnstat vnstat -i br-20f8582bfc70 --remove --force
Check that the interface is visible on the list of available interfaces:
docker exec vnstat vnstat --iflist
Add the interface
docker exec vnstat vnstat -i br-20f8582bfc70 --add
The daemon will notice the change within 5 minutes and start monitoring the interface
All images show no data available
after the container has been started.
Is the container running?
docker ps
What does the container log?
docker logs vnstat
Using a Synology NAS and timezone isn't correct?
/etc/TZ:/etc/localtime:ro
instead of /etc/localtime:/etc/localtime:ro
or use the TZ
environment variable.Container log shows Latest database update is in the future (db: 2037-04-03 18:16:49 > now: 1970-01-01 02:00:00)
or something similar with now
being in 1970.
--privileged
or upgrade libseccomp2 to a much more recent version.docker pull vergoh/vnstat