Tell me how you are using FW-GUI! File a Usage Report
The FW-GUI project is not affiliated with VyOS in any way. It is a wholly separate project to build a community tool that helps to visually build and manage firewall specific configurations for VyOS firewalls. This project is not owned by VyOS.io, or Sentrium S.L., nor does it seek to appear to be an official project, product or partner of the aforementioned.
FW-GUI is developed and maintained by @ibehren1.
Copyright © 2023-2026 Isaac Behrens. All rights reserved.
The web-based FW-GUI allows the user to visually:
- Create and manage group objects
- Create and manage firewall chains
- Create and manage filters of chains
- Create and manage flowtables
- Support for managing multiple firewall configurations
- Create and compare (diff) snapshots of firewall configurations
- Tag snapshots with a note describing why they were taken, and load or delete them from the Manage Snapshots page
- Loading a snapshot automatically snapshots the working copy first (tagged "auto-snapshot before reloading snapshot"), so nothing is lost
- Push the created policy configurations to the firewall(s) via SSH connectivity from the web interface
- Import/export a JSON file of the fw-gui configuration for backup and to move between instances of the GUI
(FW-GUI only manages configurations under 'set firewall' in the command line syntax.)
- Data Architecture — how FW-GUI stores and moves data: MongoDB config/snapshot model, MongoDB-backed authentication (SQLite before 3.0.0), session store, filesystem layout, backups, and data flow (with diagrams).
- SSH, Password, Key & Cookie Handling — how SSH connectivity, passwords, keys, and cookies are stored, used, and disposed of (with diagrams).
- MongoDB Restore Procedure — how to restore a MongoDB dump into a running
mongodbcontainer (with diagram).
| VyOS Release | FW-GUI Testing | FW-GUI Support (no SLA) |
|---|---|---|
| VyOS 1.3.x Equuleus | - Untested | - No support (do not open issues) |
| VyOS 1.4.x Sagiitta | - Designed for 1.4 and heavily tested in 2024. - No known issues but no longer tested due to VyOS closed release versions. |
- Open GitHub issues for errors. - Best effort support on old build from July 2024. |
| VyOS 1.5.x Circinus (rolling release) |
- Minimal testing but no known issues. | - Open GitHub issues for errors. - Issues may be deprioritized due to unstable daily build status. |
| VyOS 1.5 Stream (latest release) |
- Minimal testing but no known issues. - Current target version for development and testing. |
- Open GitHub issues for errors. - Current quarterly stream release is where testing/fixes will be targeted. |
| Status | ||
|---|---|---|
| Source Code |  |
https://github.com/ibehren1/fw-gui |
| Docker Hub |  |
https://hub.docker.com/repository/docker/ibehren1/fw-gui/general |
| Working Demo |  |
https://fw-gui.com |
Deploy via Docker on a server/VM that will be used to manage multiple VyOS Firewall instances. Use Nginx Proxy Manager (also via Docker) on the same host to provide LetsEncrypt TLS encrytion between client (web browser) and FW-GUI. Recommend adding proxy_read_timeout 30m; as a custom Nginx configuration.
See Deployment section below for configuration commands.
When deployed behind HAProxy (VyOS load-balancing reverse-proxy) timeouts can prevent diffs and commits for firewalls with large configurations. Issue is not observed connecting directly to app when hosted in Docker or behind Nginx proxy.
Resolution: TBD
Connections to the firewall are made using the Napalm-VyOS library via SSH. Napalm for VyOS only allows merging configurations (changes with existing) and does not allow for replacing configurations (new replacing existing). As such, by default, if you remove an item from the config and push, it will not be removed from the firewall as the configs are merged. To work around this, the View Diffs and Commit interface has the option to preface the firewall configuration with a 'delete firewall' command. This causes the configuration to remove all firewall configuration and then add the specified configuration settings so that the net configuration is a replacement of the existing configuration. You will NOT want to use this feature unless you are managing ALL firewall configurations via the GUI.
There is no initial username and password. After starting the application, use the "Register as a new user" link to create your username and password. Once you have registered your user(s), you can disable user registration by updating the environment variable in Docker configuration to DISABLE_REGISTRATION=True. Doing this will remove the link to the registration page and stop any POSTS to the route /user_registration from being processed. This can be reenabled anytime you need to setup users.
Future releases may include administration and user management features.
You can provide an Amazon S3 bucket name and user credentials as environment variables to enable offsite storage of backups in the S3 bucket. Backups are created in the Admin Settings page. Backups are always kept locally and uploaded if the S3 settings are provided. Only Amazon S3 is supported.
Access to the backup files is not provided via the web interface as it contains configurations of all users. Access to the backup is on the Docker host in the FW-GUI volume or via the S3 bucket (if configured).
As of 3.0.0 FW-GUI can take the full backup on its own, once a week, without anyone clicking the button. It is off until you switch it on, and everything about it is configured on the Admin Settings page:
| Setting | Default | Purpose |
|---|---|---|
| Run a full backup automatically every week | off | Whether the schedule runs at all. |
| Day | Sundays | Day of the run. |
| Hour (UTC) | 03:00 | Hour of the run. UTC, so it does not shift with daylight saving. |
| Backups to keep | 4 | How many archives and MongoDB dumps to keep. Four weekly backups, so about a month. 0 never deletes anything. |
There are no environment variables for any of this. The settings are stored in MongoDB, so they survive a restart, a container replacement and a redeploy, and a change takes effect immediately without one. The same page shows the current schedule, the last run and its result, and the next run.
Scheduled runs delete old backups; manual ones never do. This is deliberate: before 3.0.0 nothing in FW-GUI removed a backup or a MongoDB dump, and because every archive re-includes every retained dump, the archives grew without bound. After each scheduled run only the newest N archives and dumps are kept. When you save the settings the page tells you exactly how many old files the next run will remove, so an install that has accumulated years of them is not surprised. Set Backups to keep to 0 to schedule backups without ever deleting anything — but note that nothing then bounds the size of the data directory.
Nothing is ever deleted from S3. Offsite copies exist to survive mistakes made on the host, so the app does not prune them — use an S3 lifecycle rule on the fw-gui/backups/ prefix if you want them expired.
A missed window is caught up once, not once per week missed: an instance that was switched off for a month takes one backup shortly after it starts again, then returns to its normal schedule. Running more than one replica is safe — each claims the run atomically in MongoDB, so exactly one of them backs up.
There is still no automated restore. Retrieving an archive, and restoring a MongoDB dump from it, remains a manual operation on the host or from S3 — see the MongoDB Restore Procedure.
FW-GUI v1.4.0+ uses a separate MongoDB database to store configurations. If you first deployed with a version lower than 1.4.0, you will need to update your deployment to connect to either an external MongoDB database or deploy a second container to host MongoDB.
See below for updated Docker Compose configuration settings.
+ Lines highlighted in green are the additions for v1.4.0+ to add MongoDB.services:
fw-gui:
image: ibehren1/fw-gui:latest
container_name: fw-gui
+ depends_on:
+ - mongodb
environment:
# Change this default to a unique random value before any non-local use.
- APP_SECRET_KEY='This is the secret key.'
- DISABLE_REGISTRATION=<True|False>
- SESSION_TIMEOUT=<number-of-minutes> # Default 120 minutes
+ - MONGODB_URI=mongodb
- BUCKET_NAME=<bucket-name>
- AWS_ACCESS_KEY_ID=<access-key>
- AWS_SECRET_ACCESS_KEY=<secret-access-key>
ports:
- 8080:8080/tcp
restart: unless-stopped
volumes:
- fwgui-data:/opt/fw-gui/data
nginx:
restart: always
image: 'jc21/nginx-proxy-manager:latest'
ports:
- '80:80'
- '81:81'
- '443:443'
environment:
DB_MYSQL_HOST: "db"
DB_MYSQL_PORT: 3306
DB_MYSQL_USER: "npm"
DB_MYSQL_PASSWORD: "npm"
DB_MYSQL_NAME: "npm"
volumes:
- nginx-data:/data
- letsencrypt:/etc/letsencrypt
db:
restart: always
image: 'jc21/mariadb-aria:latest'
environment:
MYSQL_ROOT_PASSWORD: 'npm'
MYSQL_DATABASE: 'npm'
MYSQL_USER: 'npm'
MYSQL_PASSWORD: 'npm'
volumes:
- mysql-data:/var/lib/mysql
+ mongodb:
+ container_name: mongodb
+ image: mongo:7
+ restart: always
+ volumes:
+ - mongo-data:/data/db
+ - mongo-config:/data/configdb
volumes:
fwgui-data:
nginx-data:
mysql-data:
letsencrypt:
+ mongo-data:
+ mongo-config:No longer recommended with additional MongoDB container needed.
services:
fw-gui:
image: ibehren1/fw-gui:latest
container_name: fw-gui
depends_on:
- mongodb
environment:
# Change this default to a unique random value before any non-local use.
- APP_SECRET_KEY='This is the secret key.'
- DISABLE_REGISTRATION=False
- SESSION_TIMEOUT=120
- MONGODB_URI=mongodb
- BUCKET_NAME=
- AWS_ACCESS_KEY_ID=
- AWS_SECRET_ACCESS_KEY=
ports:
- 8080:8080/tcp
restart: unless-stopped
volumes:
- data:/opt/fw-gui/data
mongodb:
container_name: mongodb
image: mongo:7
restart: always
volumes:
- mongo-data:/data/db
- mongo-config:/data/configdb
volumes:
data:
mongo-data:
mongo-config:git clone https://github.com/ibehren1/fw-gui.git
cd fw-gui
helm install fw-gui ./chart/fw-gui-0.1.0.tgz
