{"id":13587496,"url":"https://github.com/vergoh/vnstat-docker","last_synced_at":"2026-03-12T10:28:11.921Z","repository":{"id":43475817,"uuid":"368270072","full_name":"vergoh/vnstat-docker","owner":"vergoh","description":"vnStat in a container with image output via http","archived":false,"fork":false,"pushed_at":"2025-02-08T18:19:31.000Z","size":107,"stargazers_count":112,"open_issues_count":1,"forks_count":13,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-08T19:22:46.567Z","etag":null,"topics":["container","docker","network-traffic-monitor","vnstat"],"latest_commit_sha":null,"homepage":"https://humdi.net/vnstat/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vergoh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-17T17:32:13.000Z","updated_at":"2025-02-08T18:19:35.000Z","dependencies_parsed_at":"2025-01-01T23:26:27.477Z","dependency_job_id":"28ef5205-384e-44d0-8a87-3b6bdfac1b0c","html_url":"https://github.com/vergoh/vnstat-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vergoh%2Fvnstat-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vergoh%2Fvnstat-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vergoh%2Fvnstat-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vergoh%2Fvnstat-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vergoh","download_url":"https://codeload.github.com/vergoh/vnstat-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247740719,"owners_count":20988259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","docker","network-traffic-monitor","vnstat"],"created_at":"2024-08-01T15:06:14.304Z","updated_at":"2026-03-12T10:28:11.863Z","avatar_url":"https://github.com/vergoh.png","language":"Shell","funding_links":[],"categories":["Shell","置顶","HarmonyOS"],"sub_categories":["05、运维监控体系","Windows Manager"],"readme":"![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/vergoh/vnstat-docker/release.yml?branch=master)\n![Docker Image Size (tag)](https://img.shields.io/docker/image-size/vergoh/vnstat/latest)\n\n# vnStat in a container\n\nvnStat is a network traffic monitor that uses the network\ninterface statistics provided by the kernel as information source. This\nmeans that vnStat won't actually be sniffing any traffic and also ensures\nlight use of system resources regardless of network traffic rate.\n\nBy default, traffic statistics are stored on a five minute level for the last\n48 hours, on a hourly level for the last 4 days, on a daily level for the\nlast 2 full months and on a yearly level forever. The data retention durations\nare fully user configurable. Total seen traffic and a top days listing is also\nprovided.\n\nSee the [official webpage](https://humdi.net/vnstat/) or the\n[GitHub repository](https://github.com/vergoh/vnstat) for additional details\nand output examples. An example of the included image output is also\n[available](https://humdi.net/vnstat/cgidemo/).\n\n## Container content\n\n- vnStat daemon (`vnstatd`) is running as the primary process\n- [lighttpd](https://www.lighttpd.net/) provides vnStat image output (`vnstati`) via http (port 8685 on all interfaces by default)\n  - json and Prometheus compatible metrics endpoints are also available as alternative\n- vnStat command line (`vnstat`)\n\n## Supported tags\n\n- GitHub Container Registry\n  - [`ghcr.io/vergoh/vnstat:latest`](https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile) - [latest released](https://github.com/vergoh/vnstat/releases) vnStat version\n  - [`ghcr.io/vergoh/vnstat:dev`](https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile-dev) - [latest commit](https://github.com/vergoh/vnstat/commits/master) from GitHub repository\n- Docker Hub\n  - [`vergoh/vnstat:latest`](https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile) - [latest released](https://github.com/vergoh/vnstat/releases) vnStat version\n  - [`vergoh/vnstat:dev`](https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile-dev) - [latest commit](https://github.com/vergoh/vnstat/commits/master) from GitHub repository\n\nVersion 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.\n\n## Building the container\n\n```sh\ndocker build -t vergoh/vnstat .\n```\n\n## Running the container\n\n```sh\ndocker run -d \\\n    --restart=unless-stopped \\\n    --network=host \\\n    -e HTTP_PORT=8685 \\\n    -v /etc/localtime:/etc/localtime:ro \\\n    -v /etc/timezone:/etc/timezone:ro \\\n    --name vnstat \\\n    vergoh/vnstat\n```\n\n- `--network=host` is necessary for accessing the network interfaces of the Docker host instead of being limited to monitoring the container specific interface\n- Volumes `/etc/localtime` and `/etc/timezone` are used to configure the container to use the same time zone as the host is using\n  - Alternatively the `TZ` environment variable can be used (`-e TZ=`) with a [supported value](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), localtime and timezone volumes are overridden if used in combination\n- `--privileged` may need to be used **if** the date within the container starts from 1970\n  - The proper solution would be to update libseccomp2 to a more recent version than currently installed\n- The http server binds by default to all interfaces using the port specified with the `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`\n  - See the full list of available environment variables below\n  - Alternatively see the two container solution with unprivileged http server using docker compose explained below\n- Image output is available at `http://localhost:8685/` (using default port)\n- JSON output is available at `http://localhost:8685/json.cgi` (using default port)\n- Prometheus compatible metrics endpoint is available at `http://localhost:8685/metrics` (using default port)\n- Add `-v some_local_directory:/var/lib/vnstat` to map the database directory to the local filesystem if easier access/backups is needed\n\nCommand line interface can be accessed with:\n\n```sh\ndocker exec vnstat vnstat --help\n```\n\n## docker-compose.yml\n\nTwo example docker compose files are provided:\n\n[`docker-compose.yml`](https://github.com/vergoh/vnstat-docker/blob/master/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.\n\n[`docker-compose_isolated_httpd.yml`](https://github.com/vergoh/vnstat-docker/blob/master/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.\n\n## Environment variables\n\nName | Description | Default value\n--- | --- | ---\nHTTP_PORT | Port of the http server, use `0` to disable http server | 8685\nHTTP_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\nHTTP_LOG | Http server log output file, use `/dev/stdout` for output to console and `/dev/null` to disable logging | `/dev/stdout`\nSERVER_NAME | Name of the server in the web page title | Output of `hostname` command\nLARGE_FONTS | Use large fonts in images (0: no, 1: yes) | 0\nCACHE_TIME | Cache created images for given number of minutes (0: disabled) | 1\nDARK_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\nPAGE_REFRESH | Page auto refresh interval in seconds (0: disabled) | 0\nRUN_VNSTATD | Start vnStat daemon (0: no, 1: yes) | 1\nINDEX_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\nINDEX_IMAGE_OUTPUT | [Image output](https://humdi.net/vnstat/man/vnstati.html) to use on index page when the database contains more than one interface (available starting from version 2.13) | `hs`\nINDEX_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*\nINDEX_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*\nEXCLUDE_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*\nTZ | Set time zone ([list of supported values](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)), overrides configuration from possible `/etc/localtime` and `/etc/timezone` volumes | *unset*\nVNSTAT_ prefix | All [vnstat.conf configurations](https://humdi.net/vnstat/man/vnstat.conf.html) 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*\n\n### Deprecated environment variables\n\nName | Description | Default value\n--- | --- | ---\nRATE_UNIT | ~~Used traffic rate unit, 0: bytes, 1: bits.~~ **Deprecated.** Use VNSTAT_RateUnit instead. | 1\nINTERFACE | ~~Default interface for queries, leave empty or unset for automatic selection.~~ **Deprecated.** Use VNSTAT_Interface instead. | *unset*\nINTERFACE_ORDER | ~~Interface order when multiple interfaces are shown, 0: alphabetical by name, 1: alphabetical by alias.~~ **Deprecated.** Use VNSTAT_InterfaceOrder instead. | 0\nQUERY_MODE | ~~Default command line query when none is specified, see [QueryMode in documentation](https://humdi.net/vnstat/man/vnstat.conf.html) for supported values.~~ **Deprecated.** Use VNSTAT_QueryMode instead. | 0\n\n## Usage tips\n\n### Add descriptive interface name\n\n```sh\ndocker exec vnstat vnstat -i eno3 --setalias \"Basement switch\"\n```\n\n### Stop monitoring unnecessary interface\n\n```sh\ndocker exec vnstat vnstat -i br-20f8582bfc70 --remove --force\n```\n\n### Add interface for monitoring\n\n1. Check that the interface is visible on the list of available interfaces:\n\n    ```sh\n    docker exec vnstat vnstat --iflist\n    ```\n\n2. Add the interface\n\n    ```sh\n    docker exec vnstat vnstat -i br-20f8582bfc70 --add\n    ```\n\n3. The daemon will notice the change within 5 minutes and start monitoring the interface\n\n## Troubleshooting\n\n- All images show `no data available` after the container has been started.\n  - The database write interval is 5 minutes so it will take up to 5 minutes for the initial data to become available.\n\n- Is the container running?\n\n    ```sh\n    docker ps\n    ```\n\n- What does the container log?\n\n    ```sh\n    docker logs vnstat\n    ```\n\n- Using a Synology NAS and timezone isn't correct?\n  - Use `/etc/TZ:/etc/localtime:ro` instead of `/etc/localtime:/etc/localtime:ro` or use the `TZ` environment variable.\n\n- Container log shows `Latest database update is in the future (db: 2037-04-03 18:16:49 \u003e now: 1970-01-01 02:00:00)` or something similar with `now` being in 1970.\n  - Use `--privileged` or upgrade libseccomp2 to a much more recent version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvergoh%2Fvnstat-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvergoh%2Fvnstat-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvergoh%2Fvnstat-docker/lists"}