### Configure vnStat init.d Service (Red Hat/CentOS)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Installs and configures the vnStat service for legacy Red Hat/CentOS systems using the init.d script. It copies the init script, enables the service for startup, and then starts it.

```bash
cp -v examples/init.d/redhat/vnstat /etc/init.d/
chkconfig vnstat on
service vnstat start
```

--------------------------------

### Install and Start vnStat Service (systemd) (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Copies the systemd service file to the appropriate directory, enables the vnStat service to start on boot, and then starts the vnStat daemon. This is for modern Ubuntu versions using systemd.

```bash
cp -v examples/systemd/vnstat.service /etc/systemd/system/
systemctl enable vnstat
systemctl start vnstat
```

--------------------------------

### Compile and Install vnStat Binaries

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Compiles the vnStat binaries (vnstat, vnstatd) and optionally the image output binary (vnstati) if libgd is available. This step requires a C compiler and make. The installation command installs the binaries, man pages, and configuration file.

```bash
./configure --prefix=/usr --sysconfdir=/etc && make && make install
```

```bash
./configure --prefix=/usr --sysconfdir=/etc && make
```

```bash
make install
```

--------------------------------

### Install and Start vnStat Service (Upstart) (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Copies the Upstart service configuration file for vnStat and starts the daemon. This is for older Ubuntu versions (14.04 - 15.04) using Upstart.

```bash
cp -v examples/upstart/vnstat.conf /etc/init/
initctl start vnstat
```

--------------------------------

### Configure vnStat Systemd Service (Simple)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Installs and enables a simple systemd service file for vnStat, compatible with older systemd versions. It copies the service file and then enables and starts the vnStat service.

```bash
cp -v examples/systemd/simple/vnstat.service /etc/systemd/system/
systemctl enable vnstat
systemctl start vnstat
```

--------------------------------

### Install and Start vnStat Service (Debian 7 and older)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Debian

Installs the init.d script for vnStat and starts the daemon on older Debian systems. This is the traditional method for managing services before systemd.

```bash
cp -v examples/init.d/debian/vnstat /etc/init.d/
update-rc.d vnstat defaults
/etc/init.d/vnstat start
```

--------------------------------

### Configure vnStat init.d Service (Debian)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Installs and configures the vnStat service for legacy Debian-based systems using the init.d script. It copies the init script and updates the runlevel defaults before starting the service.

```bash
cp -v examples/init.d/debian/vnstat /etc/init.d/
update-rc.d vnstat defaults
service vnstat start
```

--------------------------------

### Install and Enable Service - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Copies the vnstat systemd service file to the system directory, enables the service to start on boot, and starts the vnstat daemon. This ensures vnstat runs automatically and in the background.

```text
cp -v examples/systemd/vnstat.service /etc/systemd/system/
systemctl enable vnstat
systemctl start vnstat

```

--------------------------------

### Install Service and Enable Daemon (CentOS 6 init.d)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-CentOS

Copies the init.d script for vnStat into the system's service directory, configures it to start on boot using chkconfig, and then starts the vnStat service manually.

```shell
cp -v examples/init.d/centos/vnstat /etc/init.d/
chkconfig vnstat on
service vnstat start

```

--------------------------------

### Compile and Install Binaries - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Compiles and installs the vnstat binaries from the extracted source code. The './configure' command sets up the build environment, 'make' compiles the code, and 'make install' places the binaries in their respective system locations.

```text
cd vnstat-2.13
./configure --prefix=/usr --sysconfdir=/etc && make && make install

```

--------------------------------

### Compile and Install vnStat (Shell)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-RHEL

Configures, compiles, and installs the vnStat binaries. The configure script sets up build options, make builds the code, and make install places the binaries.

```shell
cd vnstat-2.13
./configure --prefix=/usr --sysconfdir=/etc && make all && make install

```

--------------------------------

### Verify vnStat Installation and Version

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Checks if the vnStat binaries have been installed correctly by displaying the vnStat version. This helps confirm that the binaries are accessible and the correct version is being used.

```shell
vnstat --version
```

--------------------------------

### Compile and Install vnStat Binaries (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Navigates into the extracted vnStat source directory, configures the build with specified prefixes, compiles the source code, and installs the binaries. This step creates the executable files for vnStat.

```bash
cd vnstat-2.13
./configure --prefix=/usr --sysconfdir=/etc && make && make install
```

--------------------------------

### Enable and start vnStat service using systemctl

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Arch

Enables the vnStat service to start on boot and starts the service immediately. This requires root or admin privileges. No specific inputs or outputs are defined beyond service status.

```bash
systemctl enable vnstat
systemctl start vnstat
```

--------------------------------

### Run vnStat Test Suite

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Executes the test suite for vnStat after the `./configure` script has been run. This requires the Check unit testing framework to be installed. It validates vnStat's functionalities.

```shell
make check
```

--------------------------------

### Start vnStat Daemon Manually (Non-Root)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Starts the vnStat daemon process manually for testing or immediate use after a non-root installation. This command ensures the daemon is running and monitoring network traffic.

```bash
vnstatd --daemon
```

--------------------------------

### Install Development Packages - Zypper

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Installs essential development packages required for compiling software from source on OpenSUSE using the 'zypper' package manager. Includes make, gcc, wget, tar, and SQLite libraries.

```text
zypper install make gcc wget tar sqlite3 sqlite3-devel

```

--------------------------------

### Get User's Home Directory Path

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

A simple command to determine the absolute path of the user's home directory, which is often needed for configuring file paths in vnStat's configuration.

```shell
cd ; pwd
```

--------------------------------

### Install vnStat Binaries as Root

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Installs the compiled vnStat binaries, man pages, and configuration file to system directories. This command requires root privileges. It also handles upgrading existing configuration files.

```bash
make install
```

--------------------------------

### Verify vnStat daemon process

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Arch

Checks if the vnStat daemon process is running. It should return '1' if the daemon is active. A return value of '0' indicates a failure to start. Requires the vnstat package to be installed and service started.

```bash
pgrep -c vnstatd
```

--------------------------------

### Compile and Install vnStat Binaries

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

This command sequence compiles the vnStat, vnstatd, and optionally vnstati binaries. It requires standard build tools like make and a C compiler. The optional vnstati binary is compiled if the libgd2 library is available.

```bash
./configure && make && make install
```

--------------------------------

### Start vnStat Daemon as Root

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Starts the vnStat daemon process, which monitors network interfaces. This command is typically configured to run at system startup. It requires root privileges for accessing system logs and configuration paths.

```bash
/usr/local/sbin/vnstatd --daemon
```

--------------------------------

### Configure vnStat Logging and PID Files

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Updates the vnStat configuration file (~/.vnstatrc) to redirect log and PID files to a location within the user's home directory, ensuring proper operation without root privileges.

```shell
# UseLogging 2
# LogFile "/var/log/vnstat/vnstat.log"
# PidFile "/var/run/vnstat/vnstat.pid"
UseLogging 1
LogFile "/pathtomyhomedir/.vnstat/.log"
PidFile "/pathtomyhomedir/.vnstat/.pid"
```

--------------------------------

### Install Optional Image Dependencies (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Installs optional development packages needed for vnStat to generate image output. If image reports are not required, this step can be skipped.

```bash
apt-get install libgd3 libgd-dev
```

--------------------------------

### Install Core Dependencies (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Installs the essential development packages required to compile vnStat from source. This includes build tools like 'make' and 'gcc', along with necessary libraries like SQLite.

```bash
apt-get update
apt-get install make gcc libc6-dev wget libsqlite3-0 libsqlite3-dev
```

--------------------------------

### Install Optional Image Packages - Zypper

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Installs optional development packages for image output support in vnstat on OpenSUSE. This includes the 'gd' and 'gd-devel' libraries, which are necessary if image-based reporting is desired.

```text
zypper install gd gd-devel

```

--------------------------------

### Starting and Configuring vnStat Daemon (vnstatd)

Source: https://context7.com/vergoh/vnstat/llms.txt

Details on how to start and manage the vnStat daemon (vnstatd) for continuous data collection. Includes options for foreground/background execution, initialization, automatic interface addition, user/group settings, and debug mode.

```bash
# Start daemon in foreground (for testing)
vnstatd --nodaemon

# Start as daemon (background process)
vnstatd --daemon

# Initialize database for all available interfaces
vnstatd --initdb

# Start with automatic interface addition enabled
vnstatd --alwaysadd

# Start without adding any interfaces automatically
vnstatd --noadd

# Run as specific user and group
vnstatd --user vnstat --group vnstat

# Specify custom PID file location
vnstatd --pidfile /var/run/vnstatd.pid

# Enable debug output
vnstatd --debug

# Example systemd service file:
# [Unit]
# Description=vnStat network traffic monitor
# After=network.target
#
# [Service]
# Type=simple
# User=vnstat
# ExecStart=/usr/sbin/vnstatd --nodaemon
# Restart=on-failure
#
# [Install]
# WantedBy=multi-user.target
```

--------------------------------

### Gain Root Permissions and Verify (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

These commands are used to gain root privileges and verify that the user is operating as root. This is a prerequisite for installing system-wide packages and services.

```bash
sudo -s -H
whoami
```

--------------------------------

### Install Development Packages (CentOS 7+ yum)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-CentOS

Installs essential development tools like 'make' and 'gcc', along with 'wget' for downloading, and 'sqlite' libraries required for vnStat's database. These are needed for compiling the source code.

```shell
yum install make gcc wget sqlite sqlite-devel

```

--------------------------------

### Install Optional Image Packages (Yum)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-RHEL

Installs optional packages for vnStat's image output feature, such as gd and gd-devel. This is not strictly necessary for basic functionality.

```shell
yum install make gd gd-devel

```

--------------------------------

### Install Optional Image Packages (CentOS 7+ yum)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-CentOS

Installs the 'gd' library and its development files, which are optional but required if you intend to use vnStat's image output features for graphical statistics.

```shell
yum install gd gd-devel

```

--------------------------------

### Install vnStat Binaries without Root

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Copies vnStat binaries to a user-specified directory and configures the database location and logging paths for non-root installation. This involves copying files and modifying the configuration file.

```bash
cp -v vnstat vnstatd vnstati ~/bin/
cp -v cfg/vnstat.conf ~/.vnstatrc
mkdir ~/.vnstat
```

--------------------------------

### Install vnStat package using pacman

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Arch

Installs the vnStat package for network traffic monitoring. Use the second command to also include vnstati for image output support. Dependencies include pacman.

```bash
pacman -S vnstat
```

```bash
pacman -S vnstat vnstati
```

--------------------------------

### Gain Root Access (Debian)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Debian

These commands are used to switch to the root user for elevated privileges, necessary for system-wide installations and configurations. It involves using the 'su -' command followed by a verification step using 'whoami'.

```text
su -
whoami
```

--------------------------------

### Configure vnStat Database Directory

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL.md

Modifies the vnStat configuration file (~/.vnstatrc) to set a custom directory for storing network statistics data within the user's home directory. This is crucial for non-root installations.

```shell
# DatabaseDir "/var/lib/vnstat"
DatabaseDir "/pathtomyhomedir/.vnstat"
```

--------------------------------

### vnStat Daemon Configuration Options

Source: https://context7.com/vergoh/vnstat/llms.txt

Covers commands and configuration file examples for managing vnStat daemon settings. It includes showing current configuration and specifying a custom configuration file.

```bash
# Show current configuration
vnstat --showconfig

# Use custom configuration file
vnstatd --config /etc/vnstat-custom.conf

# Example configuration file (/etc/vnstat.conf):
# DatabaseDir "/var/lib/vnstat"
# UpdateInterval 20
```

--------------------------------

### Install vnStat Dependencies (Debian 8+)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Debian

Installs the essential development packages required to compile vnStat, including a compiler, make utility, and SQLite development libraries. Optional packages for image output support are also listed.

```bash
apt-get update
apt-get install make gcc libc6-dev wget libsqlite3-0 libsqlite3-dev

# Optional for image output support
apt-get install libgd3 libgd-dev
```

--------------------------------

### Setting Up Traffic Alerts with vnStat

Source: https://context7.com/vergoh/vnstat/llms.txt

Illustrates how to configure traffic alerts based on various conditions like daily, monthly, or percentile limits. It shows examples for different output and exit status configurations, including integration into scripts.

```bash
# Alert if daily traffic exceeds 10 GiB (output=2, exit=3, type=daily, condition=total, limit=10, unit=GiB)
vnstat -i eth0 --alert 2 3 daily total 10 GiB

# Check if monthly transmitted data exceeds 100 GB (exit status only)
vnstat -i eth0 --alert 0 3 monthly tx 100 GB

# Alert on estimated daily total exceeding 5 GiB
vnstat -i eth0 --alert 2 3 daily total_estimate 5 GiB

# Alert if 95th percentile exceeds 100 Mbit/s
vnstat -i eth0 --alert 2 3 95 total 100 Mbit/s

# Example in monitoring script:
# if ! vnstat -i eth0 --alert 0 3 daily total 50 GiB; then
#   echo "Daily traffic limit exceeded!"
#   # Send notification
# fi
```

--------------------------------

### vnstat --alert Example Command

Source: https://github.com/vergoh/vnstat/wiki/Usage-

An example of how to use the vnstat --alert command with specific parameters for monitoring monthly total traffic. This command checks if the total traffic for the 'enp4s0' interface exceeds a 5 GiB monthly limit and outputs the status.

```bash
vnstat -i enp4s0 --alert 1 0 m total 5 GiB
```

--------------------------------

### Install vnStat Dependencies (Debian 7 and older)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Debian

Installs the necessary development packages for compiling vnStat on older Debian versions. This includes build tools and SQLite libraries. Optional packages for image generation are also specified.

```bash
apt-get update
apt-get install make gcc libc6-dev wget libsqlite3-0 libsqlite3-dev

# Optional for image output support
apt-get install libgd2-xpm libgd2-xpm-dev
```

--------------------------------

### Download and Extract vnStat Source (Bash)

Source: https://github.com/vergoh/vnstat/wiki/Install-in-Ubuntu

Fetches the latest vnStat source code archive from the official source and extracts it into the /usr/src directory. This prepares the files for compilation.

```bash
cd /usr/src
wget https://humdi.net/vnstat/vnstat-2.13.tar.gz
tar zxvf vnstat-2.13.tar.gz
```

--------------------------------

### PHP Integration for JSON Output from vnstat

Source: https://context7.com/vergoh/vnstat/llms.txt

This PHP script retrieves network traffic data in JSON format from vnstat. It allows specifying an interface by index via GET parameters and outputs the JSON directly. It also includes an example of how to parse the JSON data using JavaScript.

```php
<?php
$vnstat_cmd = "/usr/bin/vnstat";
$interfaces = explode("\n", trim(shell_exec("$vnstat_cmd --dbiflist 1")));

$iface = "";
if (isset($_GET['interface']) && ctype_digit($_GET['interface'])) {
    $getiface = $_GET['interface'];
    if ($getiface >= 0 && $getiface < count($interfaces)) {
        $iface = " -i ".$interfaces[$getiface];
    }
}

header("Content-Type: application/json");
pasthru($vnstat_cmd." --json". $iface);

// Usage:
// http://server/vnstat-json.php
// http://server/vnstat-json.php?interface=0
// Parse JSON in JavaScript:
// fetch('/vnstat-json.php')
//   .then(response => response.json())
//   .then(data => {
//     console.log(data.interfaces[0].traffic.total.rx);
//   });
?>
```

--------------------------------

### Gain Root Permissions - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

This snippet demonstrates how to switch to the root user in a Linux terminal using the 'su -' command. It's a prerequisite for installing software and managing system services.

```text
su -

```

--------------------------------

### vnstat --alert Output Example

Source: https://github.com/vergoh/vnstat/wiki/Usage-

An example of the text output generated by the vnstat --alert command when monitoring monthly traffic. It displays interface details, a usage bar, and a table with current usage, limit, remaining quota, and estimated usage.

```text
   enp4s0 at 2022-10-09 21:35:00 for month 2022-10

     [===========--------------------------......................]

       monthly |       total      |   percentage   |   avg. rate
     ----------+------------------+----------------+--------------
          used |       926.73 MiB |          18.1% |    1.23 KiB/s
         limit |         5.00 GiB |                |    1.96 KiB/s
     remaining |         4.09 GiB |          81.9% |
     ----------+------------------+----------------+--------------
     estimated |         3.15 GiB |          63.0% |    1.23 KiB/s
```

--------------------------------

### Configure vnStat Logging and PID File (Non-Root)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Updates the vnStat configuration to use user-writable paths for log files and PID files. This is necessary for installations where system directories like /var/log or /var/run are not accessible.

```bash
UseLogging 2
LogFile "/var/log/vnstat/vnstat.log"
PidFile "/var/run/vnstat/vnstat.pid"

    UseLogging 1
    LogFile "/pathtomyhomedir/.vnstat/.log"
    PidFile "/pathtomyhomedir/.vnstat/.pid"
```

--------------------------------

### Get vnStat Data in Oneline Format

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Illustrates how to get vnStat data in a single line, semicolon-separated format using the `--oneline` option. This provides a compact representation of the data, suitable for command-line processing.

```bash
vnstat --oneline
```

--------------------------------

### Verify Daemon Status - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Checks if the vnstat daemon process is running. The 'pgrep -c vnstatd' command counts the number of running vnstatd processes, which should be '1' if the daemon started successfully.

```text
pgrep -c vnstatd

```

--------------------------------

### Bash: vnStat output formatting options

Source: https://context7.com/vergoh/vnstat/llms.txt

Examples showcasing various command-line options for formatting vnStat output. This includes single-line, short formats, locale selection, rate unit adjustment, custom styles, limiting entries, and enabling 95th percentile calculations.

```bash
# One-line output format
vnstat --oneline

# Short output format
vnstat --short

# Use specific locale
vnstat --locale en_US.UTF-8

# Change rate unit display (0=bits, 1=bytes)
vnstat --rateunit 1

# Custom output style (0-4)
vnstat --style 3

# Limit output entries
vnstat -d --limit 10
vnstat -h --limit 24

# 95th percentile calculation
vnstat --95th
```

--------------------------------

### Get vnStat Data in XML Format

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Demonstrates how to obtain vnStat output in XML format using the `--xml` option. This allows for easy parsing and utilization of network traffic data in XML-compatible systems.

```bash
vnstat --xml
```

--------------------------------

### Bash: Generate vnStat XML reports

Source: https://context7.com/vergoh/vnstat/llms.txt

Command-line examples using vnstat to generate XML output for network traffic data. Supports generating XML for all interfaces, specific interfaces, and with limited daily entries. Also shows how to parse the XML output using xmllint.

```bash
# Generate XML output for all data
vnstat --xml

# XML for specific interface
vnstat -i eth0 --xml

# XML with limited daily entries (last 7 days)
vnstat --xml d 7

# Parse XML with xmllint
vnstat --xml | xmllint --xpath "//interface[@name='eth0']/traffic/total/rx/text()" -
```

--------------------------------

### Add vnStat Daemon to Crontab (Non-Root)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Adds a cron job to automatically start the vnStat daemon on system reboot. This command requires editing the user's crontab file and specifying the correct path to the vnstatd binary.

```bash
@reboot ~/bin/vnstatd --daemon
```

--------------------------------

### Configure vnStat Database Directory (Non-Root)

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Modifies the vnStat configuration file to use a user-defined directory for storing database files. This is crucial for installations without root privileges to ensure write permissions.

```bash
;DatabaseDir "/var/lib/vnstat"

    DatabaseDir "/pathtomyhomedir/.vnstat"
```

--------------------------------

### Get vnStat Data in JSON Format

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Shows how to retrieve vnStat output in JSON format using the `--json` option. This is useful for integrating vnStat data into other applications or scripts that can parse JSON.

```bash
vnstat --json
```

--------------------------------

### vnstat Alert with Command Chaining on Quota Reached

Source: https://github.com/vergoh/vnstat/wiki/Usage-

This example demonstrates chaining a command to be executed when the vnstat quota alert is triggered. If the transmitted data on 'eth0' exceeds 2 TiB monthly, the 'systemctl stop nginx' command will be executed.

```bash
vnstat -i eth0 --alert 0 3 m tx 2 TiB || systemctl stop nginx
```

--------------------------------

### Specify Time Range for vnStat Daily Output

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Provides an example of how to specify a custom time range for daily output using the `--begin` and `--end` options. This allows you to query traffic data for a specific week or any custom date range in YYYY-MM-DD HH:MM format.

```bash
vnstat --days --begin $(date --date "Sunday - 6 days" +"%Y-%m-%d") --end $(date --date "Sunday" +"%Y-%m-%d")
```

--------------------------------

### Download and Extract Source - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

Downloads the latest vnstat source code archive using wget and then extracts it using tar. This prepares the source files for compilation. Assumes the current directory is /usr/src.

```text
cd /usr/src
wget https://humdi.net/vnstat/vnstat-2.13.tar.gz
tar zxvf vnstat-2.13.tar.gz

```

--------------------------------

### Compile vnStat Binaries

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Compiles the vnStat and vnstatd binaries. This command assumes the build environment is set up and prerequisites are met. The optional vnstati binary is compiled if libgd2 is available and not explicitly disabled.

```bash
./configure && make
```

--------------------------------

### Real-time Traffic Monitoring with vnStat

Source: https://context7.com/vergoh/vnstat/llms.txt

Explains how to use vnStat for live traffic monitoring, displaying real-time receive (rx) and transmit (tx) rates. It covers setting custom update intervals and monitoring specific interfaces.

```bash
# Show live traffic rate (updates every second)
vnstat -tr

# Live traffic with specific update interval (5 seconds)
vnstat -tr 5

# Live traffic for specific interface
vnstat -i eth0 --traffic
```

--------------------------------

### Select vnStat Output Content Type

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Illustrates how to select different content types for vnStat output, such as 5-minute intervals, hourly, daily, top days, monthly, or yearly data. You can also specify the number of entries to display for each type.

```bash
vnstat -5   # 5 minutes output
vnstat -h   # hours output
vnstat -d   # days output
vnstat -t   # top days output
vnstat -m  # months output
vnstat -y  # year output
vnstat -d 7 # last 7 days
vnstat -h 12 # last 12 hours
vnstat -5 0 # all 5 minute entries
```

--------------------------------

### Query Traffic Statistics with vnStat CLI

Source: https://context7.com/vergoh/vnstat/llms.txt

This section details various commands to query network traffic statistics using the vnStat command-line interface. It covers viewing summaries, specific interfaces, and different time resolutions (daily, hourly, 5-minute, monthly, yearly).

```bash
# View summary of all interfaces
vnstat

# Show traffic for specific interface
vnstat -i eth0

# Display daily traffic for last 30 days
vnstat -d

# Show hourly traffic
vnstat -h

# Display 5-minute resolution data
vnstat -5

# View monthly statistics
vnstat -m

# Show yearly totals
vnstat -y

# Display top traffic days
vnstat -t
```

--------------------------------

### Specify Network Interface with vnStat

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Demonstrates various ways to specify a network interface for vnStat commands. This is useful when you need to monitor a specific interface rather than the default one with the most traffic. Options include short and long flags, as well as direct interface naming.

```bash
vnstat eth1
vnstat -i eth1
vnstat --iface eth1
vnstat --interface eth1
```

--------------------------------

### Generate Hourly Traffic Graph with vnStat

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Demonstrates how to generate an hourly traffic graph using ASCII graphics with the `-hg` or `--hoursgraph` option. This provides a visual representation of traffic for the last 24 hours.

```bash
vnstat -hg
vnstat --hoursgraph
```

--------------------------------

### Generate PNG Traffic Graphs with vnstat

Source: https://context7.com/vergoh/vnstat/llms.txt

These commands demonstrate how to generate various traffic graphs (summary, hourly, daily, monthly, yearly, top 10, 5-minute, horizontal summary, vertical summary) in PNG format using the vnstat command-line tool. Specify the network interface and desired output file.

```bash
# Generate summary image
vnstati -i eth0 -s -o summary.png

# Generate hourly graph
vnstati -i eth0 -h -o hourly.png

# Generate hourly graph (graphical format)
vnstati -i eth0 -hg -o hourly_graph.png

# Generate daily graph (30 days)
vnstati -i eth0 -d -o daily.png

# Generate monthly graph (12 months)
vnstati -i eth0 -m -o monthly.png

# Generate yearly graph
vnstati -i eth0 -y -o yearly.png

# Generate top 10 days graph
vnstati -i eth0 -t -o top10.png

# Generate 5-minute graph
vnstati -i eth0 -5 -o fiveminute.png

# Generate horizontal summary (combines summary and hourly)
vnstati -i eth0 -hs -o horizontal_summary.png

# Generate vertical summary
vnstati -i eth0 -vs -o vertical_summary.png
```

--------------------------------

### Programmatic Access to Traffic Data via JSON

Source: https://context7.com/vergoh/vnstat/llms.txt

Demonstrates how to retrieve vnStat traffic data in JSON format for programmatic access and integration with other systems. It shows options for all data, specific interfaces, and filtering by time ranges.

```bash
# Get all traffic data in JSON format
vnstat --json

# JSON output for specific interface
vnstat -i eth0 --json

# Get JSON with specific time range (daily data, last 7 days)
vnstat --json d 7

# JSON with hourly data
vnstat --json h 24
```

--------------------------------

### vnStat Database Management Commands

Source: https://context7.com/vergoh/vnstat/llms.txt

Provides commands for managing the vnStat SQLite database, including adding, removing, renaming, and setting aliases for network interfaces. It also covers listing monitored interfaces and merging data.

```bash
# Add new interface to monitoring
vnstat --add -i eth1

# Remove interface from database
vnstat --remove -i eth1

# Rename interface in database
vnstat -i eth0 --rename eth1

# Set alias for interface
vnstat -i eth0 --setalias "External Network"

# List all monitored interfaces
vnstat --iflist

# Show database interfaces (mode 1: one per line)
vnstat --dbiflist 1

# Merge data from one interface to another
vnstat --merge eth0 eth1
```

--------------------------------

### Verify Root Access - Shell

Source: https://github.com/vergoh/vnstat/wiki/Install-in-OpenSUSE

This command verifies if the current user has root privileges. It's a simple check to ensure administrative access has been successfully obtained before proceeding with system modifications.

```text
whoami

```

--------------------------------

### Combine Traffic Data from Multiple Interfaces

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Shows how to combine traffic data from multiple network interfaces using the '+' operator. This allows for a consolidated view of traffic across several interfaces in a single vnStat command.

```bash
vnstat eth0+eth1
```

--------------------------------

### Perl: vnStat CGI script for image display

Source: https://context7.com/vergoh/vnstat/llms.txt

A complete Perl CGI script for integrating vnStat with a web server to display network traffic statistics as images. It handles generating summary and hourly graphs for specified interfaces, with caching support, and serves an HTML index page.

```perl
#!/usr/bin/perl -w
use strict;

my $vnstati_cmd = '/usr/bin/vnstati';
my $tmp_dir = '/tmp/vnstatcgi';
my $cachetime = 5;  # minutes
my @interfaces = `$vnstati_cmd --dbiflist 1`;
chomp @interfaces;

mkdir $tmp_dir, 0755 unless -d $tmp_dir;

my $query = $ENV{QUERY_STRING};

# Generate summary image for interface 0
if ($query =~ /^0-s$/) {
    my $file = "$tmp_dir/vnstat_0.png";
    system("$vnstati_cmd -i $interfaces[0] -c $cachetime -s -o $file");

    print "Content-type: image/png\n";
    print "Content-length: ".((stat($file))[7])."\n\n";
    open(my $fh, "<", $file);
    my $data;
    print $data while read($fh, $data, 16384) > 0;
    close($fh);
}
# Generate hourly graph for interface 0
elsif ($query =~ /^0-hg$/) {
    my $file = "$tmp_dir/vnstat_0_hg.png";
    system("$vnstati_cmd -i $interfaces[0] -c $cachetime -hg -o $file");

    print "Content-type: image/png\n";
    print "Content-length: ".((stat($file))[7])."\n\n";
    open(my $fh, "<", $file);
    my $data;
    print $data while read($fh, $data, 16384) > 0;
    close($fh);
}
else {
    # HTML index page
    print "Content-Type: text/html\n\n";
    print "<html><head><title>vnStat</title></head><body>\n";
    print "<h1>Network Traffic Statistics</h1>\n";
    for my $i (0..$#interfaces) {
        print "<h2>$interfaces[$i]</h2>\n";
        print "<img src=\"?${i}-s\" alt=\"summary\"><br>\n";
        print "<img src=\"?${i}-hg\" alt=\"hourly\"><br>\n";
    }
    print "</body></html>\n";
}

# Access via: http://server/vnstat.cgi

```

--------------------------------

### Import vnStat Data for vnStat 1.x

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Import vnStat data from a plain text file into the vnStat database. This command is essential for migrating data from vnStat 1.x versions. Note that vnStat 2.x versions do not support importing data from these text files.

```bash
vnstat --importdb <interface_name>.txt

```

--------------------------------

### vnstat Live Monitoring Style Customization

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Customizes the output style for live monitoring. Using `--style 4` causes a new line to be output every 2 seconds, rather than reusing a single line for updates.

```bash
vnstat -l --style 4
```

--------------------------------

### Real-time Traffic Monitoring with vnStat

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Calculates and displays network traffic for a specified interface over a set duration. Supports human-readable and JSON output formats. No external dependencies are required, only the vnstat binary.

```shell
# Default interface, 5 seconds monitoring
vnstat -tr

# Default interface, 5 seconds monitoring
vnstat -tr 5

# 10 seconds monitoring for eth1
vnstat -tr 10 -i eth1
vnstat -tr 10 eth1

# 2 seconds monitoring, JSON output
vnstat -tr 2 --json
```

--------------------------------

### Customize vnstat PNG Image Output

Source: https://context7.com/vergoh/vnstat/llms.txt

This section details various command-line options for customizing the appearance and content of vnstat-generated PNG graphs. Options include font size, color inversion, custom headers, caching, scaling, and controlling the display of headers and legends.

```bash
# Use large fonts
vnstati -i eth0 -s -o summary.png --large

# Use small fonts (default)
vnstati -i eth0 -s -o summary.png --small

# Dark mode (invert colors)
vnstati -i eth0 -s -o summary.png --invert-colors 2

# Set custom header text
vnstati -i eth0 -s -o summary.png --headertext "Production Server"

# Enable image caching (in minutes)
vnstati -i eth0 -s -o summary.png --cache 5

# Set output to stdout (for CGI scripts)
vnstati -i eth0 -s -o -

# Scale image to 80% of default size
vnstati -i eth0 -s -o summary.png --scale 80

# Remove header from image
vnstati -i eth0 -s -o summary.png --noheader

# Remove legend from image
vnstati -i eth0 -s -o summary.png --nolegend
```

--------------------------------

### Display vnStat Statistics

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Displays the network traffic statistics collected by vnStat. This command is used to view the monitoring results after the daemon has been running and collecting data.

```bash
vnstat
```

--------------------------------

### Merge vnStat Databases using `--merge`

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Merge data from one vnStat database to another. Supports renaming interfaces on the fly. If the interface exists in the destination, it performs an additive merge; otherwise, it copies the data.

```bash
vnstat --merge

```

--------------------------------

### vnstat Live Monitoring in JSON Format

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Outputs live network transfer statistics in JSON format. This is useful for programmatic parsing and analysis. The `--json` flag enables this format, and statistics are typically presented with a sample time of 2 seconds.

```bash
vnstat -l --json
```

--------------------------------

### vnstat Daily Traffic Alert with Email

Source: https://github.com/vergoh/vnstat/wiki/Usage-

A daily traffic report command using vnstat's --alert feature, which checks a 500 GiB monthly limit on the 'eth0' interface and pipes the output to the 'sendmail' command for email delivery. This is suitable for automated daily reports.

```bash
vnstat -i eth0 --alert 1 0 m total 500 GiB | sendmail user@company.com
```

--------------------------------

### vnstat Live Monitoring with Packet/Transfer Mode

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Enables live monitoring with specific display modes. Mode `0` shows packets per second, while mode `1` shows accumulated transfer counters during execution. The default interface is used unless specified.

```bash
vnstat -l 0
vnstat -l 1
```

--------------------------------

### Python: Parse vnStat XML output

Source: https://context7.com/vergoh/vnstat/llms.txt

Python script demonstrating how to parse vnStat's XML output using the `xml.etree.ElementTree` library. It shows how to extract specific data points, such as received bytes for an interface, from the XML structure.

```python
# import xml.etree.ElementTree as ET
# import subprocess
# xml_output = subprocess.check_output(['vnstat', '--xml'])
# root = ET.fromstring(xml_output)
# for interface in root.findall('.//interface'):
#     name = interface.get('name')
#     rx = interface.find('.//total/rx').text
#     print(f"{name}: {rx} bytes received")
```

--------------------------------

### Export vnStat Data for vnStat 1.x

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Export vnStat data for a specific interface to a plain text file. This is primarily used for migrating data from vnStat 1.x versions. The exported file can then be imported on a destination system.

```bash
vnstat --exportdb -i <interface_name> > <interface_name>.txt

```

--------------------------------

### vnstat Live Monitoring (Default)

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Displays current transfer rate for the default network interface in real time. Output is human-readable and updates periodically. Statistics are shown upon interruption if monitoring lasted longer than 10 seconds.

```bash
vnstat -l
vnstat -l -i eth1
vnstat -l eth1
```

--------------------------------

### Run vnStat Docker Container

Source: https://github.com/vergoh/vnstat/blob/master/README.md

This command launches the vnStat Docker container in detached mode. It restarts automatically unless stopped, uses host networking, sets an HTTP port, mounts time configuration, and names the container 'vnstat'.

```text
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
```

--------------------------------

### Cron Job for Daily vnstat Email Report

Source: https://github.com/vergoh/vnstat/wiki/Usage-

A cron job entry that schedules the daily vnstat traffic report with email notification. This command runs at midnight every day, checks the 'eth0' interface's monthly traffic against a 500 GiB limit, and sends the report via email.

```bash
0 0 * * * vnstat -i eth0 --alert 1 0 m total 500 GiB | sendmail user@company.com
```

--------------------------------

### Perl: Export vnStat data for Prometheus

Source: https://context7.com/vergoh/vnstat/llms.txt

This Perl script iterates through different vnStat data resolutions (fiveminute, hour, day, month, year) and formats the received bytes data for Prometheus exposition. It requires access to vnStat data structure and outputs metrics in a Prometheus-compatible format.

```perl
foreach my $resolution ('fiveminute', 'hour', 'day', 'month', 'year') {
    print "\n# HELP vnstat_interface_${resolution}_received_bytes Received bytes for current $resolution\n";
    print "# TYPE vnstat_interface_${resolution}_received_bytes gauge\n";
    foreach my $interface (@{$data->{'interfaces'}}) {
        if (defined $interface->{'traffic'}{$resolution}) {
            my $alias = $interface->{'alias'} || $interface->{'name'};
            print "vnstat_interface_${resolution}_received_bytes{interface=\"$interface->{'name'}\",alias=\"$alias\"} ";
            print "$interface->{'traffic'}{$resolution}[0]{'rx'} ";
            print "$interface->{'updated'}{'timestamp'}000\n";
        }
    }
}
```

--------------------------------

### vnstat Alert Configuration for Quota Reached

Source: https://github.com/vergoh/vnstat/wiki/Usage-

This command configures vnstat to trigger an alert when the monthly transmitted data for the 'eth0' interface exceeds 2 TiB. Output is suppressed (mode 0), and the exit code is set to 3 when the limit is reached, enabling command chaining.

```bash
vnstat -i eth0 --alert 0 3 m tx 2 TiB
```

--------------------------------

### vnstat Live Monitoring with Rate Unit Switching

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Allows switching the rate unit for live monitoring between bytes per second (`-ru` or `--rateunit`) and bits per second. This setting overrides the `RateUnit` configuration option.

```bash
vnstat -l -ru
vnstat -l --rateunit
```

--------------------------------

### Perl CGI Script for JSON Output from vnstat

Source: https://context7.com/vergoh/vnstat/llms.txt

This Perl CGI script provides network traffic data in JSON format. It dynamically selects an interface based on the URL path or uses the first available interface if none is specified. The script outputs JSON data compatible with web applications.

```perl
#!/usr/bin/perl -w
use strict;

my $vnstat_cmd = '/usr/bin/vnstat';
my @interfaces = `$vnstat_cmd --dbiflist 1`;
chomp @interfaces;

my $iface = "";
if (defined $ENV{PATH_INFO}) {
    my @fields = split(/\//, $ENV{PATH_INFO});
    my $interface = $fields[-1];
    for my $i (0..$#interfaces) {
        if ($interfaces[$i] eq $interface) {
            $iface = "-i $interface";
            last;
        }
    }
}

print "Content-Type: application/json\n\n";
exec("$vnstat_cmd --json $iface");

# Usage:
# http://server/vnstat-json.cgi           - All interfaces
# http://server/vnstat-json.cgi/eth0      - Specific interface
# http://server/vnstat-json.cgi?interface=0  - First interface by index
```

--------------------------------

### Bash: Filter vnStat JSON data by date range

Source: https://context7.com/vergoh/vnstat/llms.txt

Demonstrates how to use vnstat with JSON output and date filtering options. This allows users to retrieve network traffic data for specific time periods, including single days, date ranges, and custom date-time specifications.

```bash
# Show data from specific start date
vnstat --json --begin 2025-01-01

# Show data for date range
vnstat --json --begin 2025-01-01 --end 2025-01-31

# Show today's data only
vnstat --json --begin today

# Date with time specification
vnstat --json --begin "2025-01-15 08:00"

# Combine with specific output format (daily data in range)
vnstat -d --begin 2025-01-01 --end 2025-01-31

# JSON output with date filtering
vnstat --json d --begin "2024-12-01" --end "2024-12-31"
```

--------------------------------

### Prometheus Metrics Export from vnstat (Perl)

Source: https://context7.com/vergoh/vnstat/llms.txt

This Perl script generates Prometheus-compatible metrics from vnstat's JSON output. It exports total received and transmitted bytes for each network interface, including interface name and alias, along with the timestamp of the last update.

```perl
#!/usr/bin/perl -w
use strict;
use JSON::PP;

my $vnstat_cmd = '/usr/bin/vnstat';
my $json_data = `$vnstat_cmd --json s 1`;
my $data = decode_json($json_data);

print "Content-Type: text/plain\n\n";
print "# vnStat version: ".$data->{'vnstatversion'}."\n";

# Export total bytes
print "\n# HELP vnstat_interface_total_received_bytes All time total received (rx) bytes\n";
print "# TYPE vnstat_interface_total_received_bytes counter\n";
foreach my $interface (@{$data->{'interfaces'}}) {
    my $alias = $interface->{'alias'} || $interface->{'name'};
    print "vnstat_interface_total_received_bytes{interface=\"$interface->{'name'}\",alias=\"$alias\"} ";
    print "$interface->{'traffic'}{'total'}{'rx'} ";
    print "$interface->{'updated'}{'timestamp'}000\n";
}

print "\n# HELP vnstat_interface_total_transmitted_bytes All time total transmitted (tx) bytes\n";
print "# TYPE vnstat_interface_total_transmitted_bytes counter\n";
foreach my $interface (@{$data->{'interfaces'}}) {
    my $alias = $interface->{'alias'} || $interface->{'name'};
    print "vnstat_interface_total_transmitted_bytes{interface=\"$interface->{'name'}\",alias=\"$alias\"} ";
    print "$interface->{'traffic'}{'total'}{'tx'} ";
    print "$interface->{'updated'}{'timestamp'}000\n";
}

```

--------------------------------

### vnStat Traffic Monitoring - JSON Output

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Demonstrates the JSON output format for real-time traffic monitoring using vnStat. This format is useful for programmatic parsing of traffic data.

```json
{"jsonversion":"1","vnstatversion":"2.9","interface":"eth0","sampletime":2,"rx":{"ratestring":"4.57 KB/s","bytespersecond":4679,"packetspersecond":20,"bytes":9359,"packets":41},"tx":{"ratestring":"3.67 KB/s","bytespersecond":3757,"packetspersecond":18,"bytes":7515,"packets":36}}
```

--------------------------------

### Remove vnStat Interface Monitoring

Source: https://github.com/vergoh/vnstat/blob/master/INSTALL_BSD.md

Stops vnStat from monitoring a specific network interface. This command can be used to manage which interfaces vnStat tracks. It takes the interface name as an argument.

```bash
vnstat --remove -i ethunwanted
```

--------------------------------

### Rename vnStat Interfaces using `--rename`

Source: https://github.com/vergoh/vnstat/wiki/Usage-

Rename network interfaces within the vnStat database. This command should be run when the vnStat daemon is not active. It is useful when interface names change due to system upgrades or configuration changes.

```bash
vnstat --rename

```