Installing and Configuring BastionGuard WebUI

The BastionGuard package already includes the WebUI. You do not need to copy a separate webui directory manually. After installation, the WebUI is normally available at /usr/share/BastionGuard/webui, while the supplied web-server configuration templates are installed under /usr/share/BastionGuard/data/vhosts/webui.

1. Install the BastionGuard package

Install the BastionGuard package provided for your Linux distribution. Replace the example filename with the actual package filename and version.

Arch Linux or an Arch-based distribution:

sudo pacman -U ./bastionguard-<version>-x86_64.pkg.tar.zst

Debian or Ubuntu:

sudo apt install ./bastionguard_<version>_amd64.deb

Fedora or OpenSuse

sudo apt install ./bastionguard_<version>.x86_64.rpm

Verify that the package installed the WebUI and the virtual-host templates:

test -d /usr/share/BastionGuard/webui && echo "BastionGuard WebUI is installed"
ls -la /usr/share/BastionGuard/data/vhosts/webui

2. Verify the WebUI files

The package should provide the following main locations:

  • /usr/share/BastionGuard/webui — PHP WebUI files;
  • /usr/share/BastionGuard/data/vhosts/webui — Apache, Nginx, Lighttpd, Caddy and PHP-FPM templates;
  • /usr/share/BastionGuard/data/logo.svg — BastionGuard logo;
  • /usr/share/BastionGuard/data/version.bs — application version;
  • /usr/share/BastionGuard/webui/assets/fonts/Cantarell-VF.otf — vendored WebUI font.
ls -la /usr/share/BastionGuard/webui
ls -la /usr/share/BastionGuard/data/vhosts/webui
test -f /usr/share/BastionGuard/webui/assets/fonts/Cantarell-VF.otf && echo "Cantarell font found"

3. Install and configure PHP

The WebUI requires PHP and a web server. PHP-FPM is recommended for Nginx and is also supported by Apache. Enable the PHP database driver that matches the database selected during the first-run setup.

  • pdo_sqlite for SQLite;
  • pdo_mysql for MySQL or MariaDB;
  • pdo_pgsql for PostgreSQL.

Also ensure that the PHP session, JSON, OpenSSL and file-handling extensions required by your distribution are enabled. Package names vary between distributions.

4. Configure the web server

BastionGuard includes ready-to-adapt configuration templates in /usr/share/BastionGuard/data/vhosts/webui. Available templates include:

apache2-fpm-bastionguard-webui.conf
apache2-mod-php-bastionguard-webui.conf
httpd-arch-fpm-bastionguard-webui.conf
nginx-bastionguard-webui.conf
lighttpd-bastionguard-webui.conf
Caddyfile-bastionguard-webui
php-fpm-bastionguard-webui.pool.conf

Copy the template that matches your web stack, review its paths, PHP-FPM socket, listen address, hostname and port, and then enable it in your web server.

Apache HTTP Server on Arch Linux

sudo cp /usr/share/BastionGuard/data/vhosts/webui/httpd-arch-fpm-bastionguard-webui.conf \
  /etc/httpd/conf/extra/bastionguard-webui.conf

sudo nano /etc/httpd/conf/extra/bastionguard-webui.conf

If the file is not already included, add the following line to /etc/httpd/conf/httpd.conf:

Include conf/extra/bastionguard-webui.conf

Apache on Debian or Ubuntu

sudo cp /usr/share/BastionGuard/data/vhosts/webui/apache2-fpm-bastionguard-webui.conf \
  /etc/apache2/sites-available/bastionguard-webui.conf

sudo nano /etc/apache2/sites-available/bastionguard-webui.conf
sudo a2ensite bastionguard-webui.conf

Nginx

sudo cp /usr/share/BastionGuard/data/vhosts/webui/nginx-bastionguard-webui.conf \
  /etc/nginx/conf.d/bastionguard-webui.conf

sudo nano /etc/nginx/conf.d/bastionguard-webui.conf

Some distributions use /etc/nginx/sites-available and /etc/nginx/sites-enabled instead of /etc/nginx/conf.d.

Lighttpd or Caddy

Use lighttpd-bastionguard-webui.conf for Lighttpd or Caddyfile-bastionguard-webui for Caddy. Copy the template into the appropriate configuration directory and adjust the listening address, domain and PHP-FPM endpoint.

5. Install the BastionGuard WebUI helpers

The WebUI uses controlled helper programs for privileged operations, desktop-user configuration files, service management, scans, quarantine actions and the first-run wizard.

Set the desktop Linux username explicitly. This must be the user that owns the BastionGuard desktop profile and runs the systemctl --user services. Do not rely on $USER from a root shell, because it may resolve to root.

DESKTOP_USER="your-desktop-user"

cd /usr/share/BastionGuard/webui
sudo bash scripts/install-webui-helpers.sh "$DESKTOP_USER"

The helper installer creates or refreshes:

  • /usr/local/sbin/bastionguard-webui-admin;
  • /usr/local/sbin/bastionguard-webui-systemctl;
  • /usr/local/sbin/bastionguard-webui-wizard;
  • /etc/sudoers.d/bastionguard-webui;
  • /var/lib/bastionguard-webui, with permissions for the detected PHP-FPM or web-server user.

6. Install optional runtime tools

Install inotify-tools for real-time file monitoring and smbclient for scanning Samba shares.

# Arch Linux
sudo pacman -S inotify-tools smbclient

# Debian or Ubuntu
sudo apt install inotify-tools smbclient

7. Enable the persistent real-time monitor

The root/system monitor can remain active even after the WebUI user logs out. Enable it after installing the helper scripts:

sudo systemctl daemon-reload
sudo systemctl enable --now bastionguard-webui-inotify.service
sudo systemctl status bastionguard-webui-inotify.service

The monitor reads paths saved from the WebUI Scan page. If no paths have been saved, it uses safe fallback locations such as Downloads, public web roots, home directories and temporary directories.

Recommended server monitoring paths:

/tmp
/var/www
/var/www/html
/srv/http
/srv/www
/home
/home/*/public_html
/home/*/www

Useful monitor commands:

DESKTOP_USER="your-desktop-user"

# Start using saved paths or safe defaults
sudo /usr/local/sbin/bastionguard-webui-admin inotify-start-saved "$DESKTOP_USER"

# Stop the monitor
sudo /usr/local/sbin/bastionguard-webui-admin inotify-stop "$DESKTOP_USER"

# Check status
sudo /usr/local/sbin/bastionguard-webui-admin inotify-status "$DESKTOP_USER"

The monitor log is stored in the desktop user profile:

tail -f "$HOME/.local/share/BastionGuard/logs/webui-inotify.log"

8. Restart the web stack

Restart only the services used by your installation:

sudo systemctl restart httpd 2>/dev/null || true
sudo systemctl restart apache2 2>/dev/null || true
sudo systemctl restart nginx 2>/dev/null || true
sudo systemctl restart lighttpd 2>/dev/null || true
sudo systemctl restart caddy 2>/dev/null || true
sudo systemctl restart php-fpm 2>/dev/null || true

9. Complete the first-run WebUI setup

Open the WebUI setup page in a browser using the hostname, IP address and port configured in the web-server virtual host. For example:

http://server-address/setup.php
https://bastionguard.example.com/setup.php

Complete the setup in this order:

  1. Choose SQLite, MySQL/MariaDB or PostgreSQL.
  2. Enter the required database connection details when using MySQL/MariaDB or PostgreSQL.
  3. Create the WebPanel administrator account.
  4. Select Complete setup.
  5. Sign in to the WebUI.
  6. Open Settings → Web Options.
  7. Set the desktop user that owns the BastionGuard configuration and runs the user services.
  8. Run the WebUI first-run wizard and review each environment, service and system step.
  9. Open the Scan page and save the directories that should be monitored in real time.

10. First-run wizard behaviour

The WebPanel wizard is a step-by-step flow covering environment checks, service configuration, system operations and final review.

For safety, the wizard becomes read-only when it detects an active BastionGuard desktop GUI session or an existing ~/.config/BastionGuard configuration for the selected desktop user. In that situation, the WebUI does not overwrite config.json, enable services or execute system setup steps. Use the GTK desktop interface to configure an already-initialized desktop profile.

11. Configuration files used by the WebUI

The WebUI reads and updates the real BastionGuard desktop-user data locations:

  • ~/.config/BastionGuard — main configuration directory;
  • ~/.config/BastionGuard/config.json — wizard and application configuration;
  • ~/.local/share/BastionGuard/banks.json — bank list;
  • ~/.local/share/BastionGuard/webui-inotify.paths — saved real-time monitoring paths;
  • ~/.config/BastionGuard/webui-inotify.conf — monitor configuration marker;
  • /var/lib/bastionguard-webui/alerts.tsv — server-side malware and ransomware alerts;
  • /var/lib/bastionguard-webui/quarantine/.metadata/ — quarantine restore metadata.

12. Configure server alerts

Open Settings → Server Alerts to configure SMTP delivery for malware and ransomware notifications. Administrator email addresses can be used automatically, and extra recipients can be entered one per line or separated by commas.

13. Verify user services

The WebUI can query selected BastionGuard user services through the controlled systemctl helper. Replace www-data with the actual PHP-FPM or web-server account and replace the desktop username.

DESKTOP_USER="your-desktop-user"
sudo -u www-data sudo -n /usr/local/sbin/bastionguard-webui-systemctl \
  user "your-desktop-user" show \
  BastionGuard-ransomware-alert.service \
  ActiveState SubState UnitFileState MainPID

14. Updating BastionGuard

After installing a newer BastionGuard package, reinstall the WebUI helpers because new releases may add helper commands, update sudoers rules or replace the real-time monitor script.

DESKTOP_USER="your-desktop-user"

cd /usr/share/BastionGuard/webui
sudo bash scripts/install-webui-helpers.sh "$DESKTOP_USER"
sudo systemctl daemon-reload
sudo systemctl restart bastionguard-webui-inotify.service 2>/dev/null || true
sudo systemctl restart httpd 2>/dev/null || true
sudo systemctl restart apache2 2>/dev/null || true
sudo systemctl restart nginx 2>/dev/null || true
sudo systemctl restart php-fpm 2>/dev/null || true

15. Uninstall

DESKTOP_USER="your-desktop-user"

cd /usr/share/BastionGuard/webui
sudo bash scripts/install-webui-helpers.sh "$DESKTOP_USER"

16. Security recommendations

  • Publish the WebUI over HTTPS, especially when it is reachable outside the local machine.
  • Restrict access with a firewall, VPN or trusted administrative network.
  • Do not expose setup.php unnecessarily after setup is complete.
  • Use a strong administrator password and keep the underlying BastionGuard package updated.
  • Review the supplied virtual-host template before enabling it.
  • Do not grant the web-server account generic sudo access; use only the installed BastionGuard helper rules.
  • Back up the WebPanel database and the BastionGuard configuration before major upgrades.

17. Troubleshooting

The WebUI opens, but service actions fail

  • Reinstall the helper scripts with the correct desktop username.
  • Check /etc/sudoers.d/bastionguard-webui with visudo -c.
  • Verify which Linux account runs PHP-FPM or the web server.
  • Run the manual bastionguard-webui-systemctl test shown above.

The first-run wizard is read-only

  • Check whether the BastionGuard GTK application is currently running.
  • Check whether ~/.config/BastionGuard already exists for the selected desktop user.
  • Use the GTK desktop interface for an existing desktop configuration.

The persistent monitor does not start

  • Install inotify-tools.
  • Reinstall the WebUI helpers.
  • Run sudo systemctl daemon-reload.
  • Inspect systemctl status bastionguard-webui-inotify.service.
  • Inspect the user log under ~/.local/share/BastionGuard/logs/webui-inotify.log.

PHP cannot connect to the database

  • Enable the correct PDO driver.
  • Verify the database hostname, port, database name, username and password.
  • Confirm that the database user has permission to create and modify the WebPanel tables.
  • Restart PHP-FPM after changing PHP modules or configuration.
Published on:
Last updated on: