GUI

The BisonRouter GUI provides a web interface for router configuration and monitoring. The dashboard displays historical traffic, packet, error, and NAT session statistics.

Installation

The following steps are based on the GUI installation guide, with the configuration prompts updated for the current bisonrouter script. Run the shell commands as root.

  1. Install BisonRouter by following the Installation Bison Router DPDK 21 instructions.

  2. Edit /etc/bisonrouter/brouter.conf and add the following line to the startup section:

    sysctl set kni_driver_type "tap"

  3. In the same file, add the kni flag to the vif add command for the interface used to access the GUI. This is usually an uplink VIF.

    Edit /etc/bisonrouter/bisonrouter.env and add all VIFs with the kni flag to br_kni_vifs. Prefix each VIF name with r_. For example, for a VIF named v20:

    br_kni_vifs=(
    "r_v20"
)

    Keep any other KNI VIFs already present in this list.

  4. In /etc/bisonrouter/bisonrouter.env, set br_default_gw to the IP address of the default gateway. For example:

    br_default_gw="192.168.1.2"

    Start BisonRouter with this configuration. If it is already running, restart it to apply the startup and environment changes.

  5. Configure the GUI:

    bisonrouter gui_postinstall

    Enter the IP address or DNS name used to access BisonRouter, then enter the HTTP port. Press Enter at the port prompt to use the default, 80.

    Create an admin account with read-write access:

    bisonrouter gui_add_user admin 'YOUR_ADMIN_PASSWORD' read-write

    Replace YOUR_ADMIN_PASSWORD with the password for this account. Optionally, create an account with read-only access:

    bisonrouter gui_add_user observer 'YOUR_OBSERVER_PASSWORD' read-only

  6. Start the GUI web server:

    service bisonrouter_nginx start

  7. Start the GUI backend:

    service bisonrouter_gui_backend start

  8. Open http://<BisonRouter-IP-or-DNS-name> in a browser and sign in with the admin account and the password set with gui_add_user. If you selected a port other than 80, append it to the address: http://<BisonRouter-IP-or-DNS-name>:<port>.

Dashboard

The dashboard collects router statistics periodically and stores them in InfluxDB. Open Dashboard in the GUI menu to view port traffic, monitored VIF traffic, and NAT map statistics, or to select VIFs for monitoring.

Dashboard installation

Complete the GUI installation first and make sure BisonRouter is running. The installation command uses APT to install InfluxDB 3 Core and requires access to the InfluxData package repository. Run the commands below as root.

  1. Check the dashboard settings in /etc/bisonrouter/bisonrouter.env:

    export br_metrics_influx_url="http://localhost:8181"
export br_metrics_influx_database="bisonrouter"
export br_metrics_influx_token_file="/etc/bisonrouter/br_metrics_collector.token"
export br_metrics_host_id="edge-server-01"

    Note

    Keep the default values of br_metrics_influx_url, br_metrics_influx_database, and br_metrics_influx_token_file shown above. There is no need to change them unless you have a specific reason to use a different InfluxDB endpoint, database name, or token file path.

    Set br_metrics_host_id to an identifier for this router. The collector and GUI backend use these settings to write and read the same statistics. If you change them while the GUI backend is running, reload its environment:

    service bisonrouter_gui_backend restart

  2. Install the dashboard components:

    bisonrouter gui_dashboard_install

    This command installs InfluxDB 3 Core, configures it to listen on 127.0.0.1:8181 inside the BisonRouter network namespace, installs the plugin that aggregates historical data, and starts InfluxDB. It creates an authentication token in the configured token file, preserving an existing nonempty token file. Periodic collection is enabled by the next command.

  3. Start dashboard telemetry:

    bisonrouter gui_dashboard_start

    This command restarts InfluxDB, enables its service at system startup, and installs the metrics collector’s cron job. The collector runs once per minute and creates the required databases and aggregation tasks as data becomes available. Make sure the system cron service is running.

  4. Open Dashboard in the GUI. Allow a few collection cycles for traffic graphs to populate; the first counter sample establishes a baseline. To collect VIF statistics, add interfaces through Dashboard > VIF selection as described below.

To stop dashboard telemetry, run:

bisonrouter gui_dashboard_stop

This command stops InfluxDB, disables its automatic startup, and removes the collector’s cron job. Stored data is preserved, but dashboard queries are unavailable while InfluxDB is stopped. Run bisonrouter gui_dashboard_start to resume collection and viewing. The GUI web server and backend continue running.

Dashboard sections

The Ports, VIF, and NAT maps pages share the same time controls. Select the object to inspect, choose a Data interval, and then select a time range. Click Refresh to fetch the latest available data. Hover over a graph to inspect values, click legend entries to show or hide series, and use the slider below a graph to zoom into a shorter period.

Data intervals and available history
Data interval History retained Time range buttons
1 minute 14 days 1 hour, 24 hours, 7 days, 14 days
5 minutes 30 days 24 hours, 7 days, 14 days, 30 days
1 hour 365 days 7 days, 30 days, 90 days, 1 year

History starts when collection is enabled. Longer intervals summarize collected samples: traffic and session creation/deletion charts show rates over the interval, while NAT state counts are averaged. Coarser intervals become available as the aggregation tasks run.

Ports

Select Dashboard > Ports, then choose a port from the Port list. The page contains two graphs:

  • Traffic shows received (RX) and transmitted (TX) traffic in bits per second.
  • Packets and errors shows RX and TX packet rates, missed packets, transmit errors, receive errors, and No mbuf events (receive buffer allocation failures). Values are displayed as events per second.

The graph subtitle identifies the host, BisonRouter instance, and port. These graphs help identify traffic peaks and periods of packet loss or resource pressure.

Ports dashboard showing Port 1 RX and TX traffic over 24 hours.

Port traffic with a one-minute data interval and a 24-hour time range. The packets and errors graph appears below the traffic graph.

VIF

Select Dashboard > VIF to inspect an individual monitored virtual interface. Choose the interface from the VIF list.

  • Traffic shows RX and TX traffic in bits per second.
  • Packets shows RX and TX packet rates in packets per second.

Only VIFs enabled through VIF selection are collected. If the required interface is missing or has no samples, add it to the monitored list and allow a few collection cycles before refreshing the graphs.

NAT maps

Select Dashboard > NAT maps, then choose a map from the NAT map list. The dashboard supports SNAT, deterministic SNAT, and NAT64 maps.

  • States shows the total connection count and its breakdown into unknown, UDP active, TCP SYN sent, TCP established, TCP FIN wait, TCP close wait, TCP closing, TCP last ACK, TCP closed, ICMP active, DNS, and GRE states or categories. The vertical axis shows connections.
  • Session rates shows created and deleted sessions per second. These rates help identify changes in session turnover even when the total connection count remains steady.

The graph subtitle identifies the host, BisonRouter instance, and map.

NAT64 map 1 dashboard showing total connections and connection states.

NAT64 map connection states with a one-minute data interval. Each legend entry controls the corresponding series.

VIF selection

Select Dashboard > VIF selection to manage the interfaces for which statistics are collected. A read-write GUI account is required to change the monitored list.

  1. Enter the complete, case-sensitive VIF name in Complete VIF name and click Find VIF.
  2. Select the result in Existing VIF. The result shows the VIF name, ID, port, SVID, and CVID so you can identify the interface.
  3. Click the right arrow to add it to Monitored VIFs. Collection starts on subsequent collector runs.
  4. To stop collecting an interface, select it in Monitored VIFs and click the left arrow.

Removing a VIF from this list stops its future collection; it does not delete the router interface.