This guide will walk you through the process of installing and running Debian packages (.deb) for core, gateway, proxy services on one server - as a simple example.
For production deployment we would recommend to divide services to multiple servers, e.g.:
Defguard Proxy (used for remote enrollment, onboarding and configuring desktop clients) should be on a DMZ node that is exposed in the Internet
Defguard Gateway should be on your firewall/router
Defguard Core (the main control plain panel) - should be in internal network (intranet) and available only by intranet or VPN itself.
We will cover system requirements, additional dependencies, installation steps, and examples of configuration files and step by step running all services. In this example we will use nginx for a web server (proxy) exposing and securing web based services.
Examples will be made by using Debian 12and Ubuntu based system.
We also provide RPM packages - the procedure is similar to the one for installing DEB packages. If you need help installing RPM packages this guide offers help.
All defguard components are very low resource-consuming. All of them are written in Rust and are single binaries. As minimum setup as follows should be more then enough:
Resource
Minimum requirements
System Requirements
Before proceeding with the installation, ensure your system meets the following requirements:
Debian-based operating system (Debian, Ubuntu, etc.).
Administrative (sudo) privileges.
A server with a public IP address (and you know what that IP address is and to which interface it's assigned) - in this example we use: 185.33.37.51.
You have a domain name and know how to assign IP and manage subdomains, in our example: defguard main url will be my-server.defguard.net (and the subdomain is pointed to 185.33.37.51).
If you have a firewall, we assume you have open port 443 in order to expose both defguard and enrollment service, but also to automatically issue for these domains SSL Certificates. Port 444 (used for internal GRPC communication) should not be exposed public.
System clock is synchronized using Network Time Protocol (NTP). This is important for time-based one-time password (TOTP) codes.
Prequesities
PostgreSQL
Defguard Core uses PostgreSQL database, so if you do not have installed and configured yet, you can do it in this section. For this tutorial we need to create a user with superuser privileges and database.
First of all, install PostgreSQL package:
apt install postgresql
Now you can launch a default user and create a new superuser for your database. We create user, password and database with name defguard, beacuse this is by default in /etc/defguard/core.conf, you can change whatever you want.
# su -c /usr/bin/psql postgres
postgres=# CREATE USER defguard WITH SUPERUSER PASSWORD 'defguard';
postgres=# CREATE DATABASE defguard;
After creating a user and database we can connect our new user to this database. To make it easier to connect now and then, we could try to add auth file
we created .pgpass file that consist of <hostname>:<port>:<database>:<user>:<password>
we connected into the defguard database to verify defguard user can communicate with the database
NGINX
To expose our services in the server we need to configure a reverse proxy server. For this we will use nginx web server with ssl certificates for enabling https protocol.
Navigate to core repository release and choose version of core package that you want to obtain that has debian package and then swap <version> in the following command:
You can also download directly from the Github realse page, but please note that you should know the path where this could be storead after downloading. Once the package is downloaded, install it using dpkg:
Navigate to gateway repository release and choose version of core package that you want to obtain that has debian package and then swap <version> in the following command:
You can also download directly from the Github realse page, but please note that you should know the path where this could be storead after downloading. Once the package is downloaded, install it using dpkg:
Navigate to proxy repository release and choose version of core package that you want to obtain that has debian package and then swap <version> in the following command:
You can also download directly from the Github realse page, but please note that you should know the path where this could be storead after downloading. Once the package is downloaded, install it using dpkg:
Before we run Defguard and configure the reverse proxy, first let's prepare SSL certificates that will be used by the NGINX service. We will generate a certificate for two domains we use in this example: my-service.defguard.net and enroll.defguard.net:
As previously mentioned, in this tutorial we wil use server domain my-server.defguard.net.
Example /etc/defguard/core.conf:
### Core configuration ###
#
# Generate secrets
#
DEFGUARD_AUTH_SECRET=defguard-auth-secret
DEFGUARD_GATEWAY_SECRET=defguard-gateway-secret
DEFGUARD_YUBIBRIDGE_SECRET=defguard-yubibridge-secret
DEFGUARD_SECRET_KEY=9oZqdHRCN0TWIyMhjYOAYwgzVz9IfOqz62PzUvjvyMzqLICGSM3b0pRMdDH300CQ
# Define the URL under which defguard is running:
DEFGUARD_URL=https://my-server.defguard.net
# How long auth session lives in seconds
DEFGUARD_AUTH_SESSION_LIFETIME=604800
# Optional. Generated based on DEFGUARD_URL if not provided.
# DEFGUARD_WEBAUTHN_RP_ID=localhost
DEFGUARD_ADMIN_GROUPNAME=admin
DEFGUARD_DEFAULT_ADMIN_PASSWORD=pass123
# This will be displayed in the network settings when editing/adding a new location:
DEFGUARD_GRPC_URL=https://my-server.defguard.net:444
### Proxy configuration ###
# Proxy is optional - if you would like to use the remote enrollment
# and onboarding service, as well as easy desktop client configuration
# proxy must be enabled.
# For now we leave it uncofigured, will configure it in next step.
# DEFGUARD_PROXY_URL=http://localhost:50051
### LDAP configuration ###
# DEFGUARD_LDAP_URL=ldap://localhost:389
# DEFGUARD_LDAP_SERVICE_PASSWORD=adminpassword
# DEFGUARD_LDAP_USER_SEARCH_BASE="ou=users,dc=example,dc=org"
# DEFGUARD_LDAP_GROUP_SEARCH_BASE="ou=groups,dc=example,dc=org"
# DEFGUARD_LDAP_DEVICE_SEARCH_BASE="ou=devices,dc=example,dc=org"
### DB configuration ###
DEFGUARD_DB_HOST="localhost"
DEFGUARD_DB_PORT=5432
DEFGUARD_DB_NAME="defguard"
DEFGUARD_DB_USER="defguard"
DEFGUARD_DB_PASSWORD="defguard"
# for SQLX CLI
DATABASE_URL="postgresql://defguard:defguard@localhost/defguard"
If you have configured your postgres with different names than inPostgreSQL guide, you can change it in DB configuration part. LDAP configuration is not part of this tutorial, you can also commented those lines.
We will back to this configuration to connect defguard core with proxy in theRun proxysection. For now DEFGUARD_PROXY_URL is commented.
After changes, you can simply enable and start your defguard core service:
If you will use this simple setup and run all services on one server, you can use NGINX access restrictions for securing core and allowing to access the my-server.defguard.net only to selected networks - blocking the direct access from the Internet.
Gateway - the WireGuard VPN service
To run gateway, we should do two things:
setup our first location on https://my-server.defguard.net page to get token and grpc_url for gateway service,
configure /etc/defguard/gateway.toml.
Setup location for gateway
Now, after setting up core service you should go to the website that you set on DEFGUARD_URL. The link should redirect you to login page. To log in type this credentials from /etc/defguard/core.conf
Now we can configure our first location. Depends on what is more convenient fo you, choose configuration from Wireguard file or do it manualy.
After saving configuration for location you should be redirect to Location overview page, where at the top right corner is Edit Locations Settings button, click on it.
In Gateway server setup copy two variables: DEFGUARD_TOKEN and DEFGUARD_GRPC_URL
Create config file
After getting DEFGUARD_TOKEN and DEFGUARD_GRPC_URL variables, we can configure our gateway service. Create config.toml file and swap <your_gateway_token> and <defguard_grpc_url> with your values that you copied.
Template for configure gateway service looks like below:
# This is an example config file for defguard VPN gateway
# To use it fill in actual values for your deployment below
# Required: secret token generated by defguard
# NOTE: must replace default with actual value
token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJEZWZHdWFyZCIsInN1YiI6IkRFRkdVQVJELU5FVFdPUkstMSIsImNsaWVudF9pZCI6IjEiLCJleHAiOjYwMTczODM0MjQsIm5iZiI6MTcyMjQxNjEyOX0.HP-9ArvdXuyeBxRdQ6S_wJb3rBTq73J0sVyfwuPM-vY"
# Required: defguard server gRPC endpoint URL
# NOTE: must replace default with actual value
grpc_url = "https://my-server.defguard.net:444/"
# Optional: gateway name which will be displayed in defguard web UI
name = "Gateway A"
# Required: use userspace WireGuard implementation (e.g. wireguard-go)
userspace = false
# Optional: path to TLS cert file
# grpc_ca = cert.pem
# Required: how often should interface stat updates be sent to defguard server (in seconds)
stats_period = 60
# Required: name of WireGuard interface
ifname = "wg0"
# Optional: write PID to this file
# pidfile = defguard-gateway.pid
# Required: enable logging to syslog
use_syslog = false
# Required: which syslog facility to use
syslog_facility = "LOG_USER"
# Required: which socket to use for logging
syslog_socket = "/var/run/log"
# Optional: Command which will be run before bringing interface up
# Example: Allow all traffic through WireGuard interface:
#pre_up = "/path/to/iptables -A INPUT -i wg0 -j ACCEPT
# example with multiple commands - add them to a shell script
#pre_up = "/path/to/shell /path/to/script"
# Optional: Command which will be run after bringing interface up
# Example: Add a default route after WireGuard interface is up:
#post_up = "/path/to/ip route add default via 192.168.1.1 dev wg0"
# Optional: Command which will be run before bringing interface down
# Example: Remove WireGuard-related firewall rules before interface is taken down:
#pre_down = "/path/to/iptables -D INPUT -i wg0 -j ACCEPT"
# Optional: Command which will be run after bringing interface down
# Example: Remove the default route after WireGuard interface is down:
#post_down = "/pat/to/ip route del default via 192.168.1.1 dev wg0"
# A HTTP port that will expose the REST HTTP gateway health status
# STATUS CODES:
# 200 - Gateway is working and is connected to CORE
# 503 - gateway works but is not connected to CORE
#health_port = 55003
Now we can run gateway service with configuration above:
# systemctl enable defguard-gateway.service
# systemctl start defguard-gateway.service
# journalctl -u defguard-gateway.service | tail -n 50
[2024-07-27T16:37:56Z INFO defguard_gateway::gateway] Starting defguard gateway version 0.7.0 with configuration: Config { token: "***", name: Some("Gateway on server X"), grpc_url: "https://my-server.defguard.net:444/", userspace: false, grpc_ca: None, stats_period: 60, ifname: "wg0", pidfile: None, use_syslog: false, syslog_facility: "LOG_USER", syslog_socket: "/var/run/log", config_path: None, pre_up: None, post_up: None, pre_down: None, post_down: None, health_port: None }
[2024-07-27T16:37:56Z INFO defguard_gateway::gateway] gRPC server connection setup done.
[2024-07-27T16:37:56Z INFO defguard_wireguard_rs::wgapi_linux] Creating interface wg0
[2024-07-27T16:37:56Z INFO defguard_wireguard_rs::wgapi_linux] Configuring interface wg0 with config: InterfaceConfiguration { name: "Szczecin", address: "10.22.33.1/24", port: 50051, peers: [], mtu: None, .. }
[2024-07-27T16:37:56Z WARN netlink_packet_route::link::buffer_tool] Specified IFLA_INET6_STATS NLA attribute holds more(most likely new kernel) data which is unknown to netlink-packet-route crate, expecting 288, got 296
[2024-07-27T16:37:56Z WARN netlink_packet_route::link::buffer_tool] Specified IFLA_INET6_STATS NLA attribute holds more(most likely new kernel) data which is unknown to netlink-packet-route crate, expecting 288, got 296
[2024-07-27T16:37:56Z INFO defguard_gateway::gateway] Reconfigured WireGuard interface Szczecin (address: 10.0.0.1/24)
[2024-07-27T16:37:56Z INFO defguard_gateway::gateway] Stats thread spawned.
[2024-07-27T16:37:56Z INFO defguard_gateway::gateway] Connected to defguard gRPC endpoint: https://my-server.defguard.net:444/
On the other side, core service should print those informations:
2024-07-27T16:37:56.379227Z INFO defguard::grpc: Adding gateway user with to gateway map for network 1
2024-07-27T16:37:56.385951Z INFO defguard::grpc::gateway: Configuration sent to gateway client, network [ID 1] Szczecin.
2024-07-27T16:37:56.388651Z INFO defguard::grpc::gateway: New client connected to updates stream: user, network [ID 1] Szczecin
2024-07-27T16:37:56.388695Z INFO defguard::grpc: Gateway user connected in network 1
2024-07-27T16:37:56.388810Z INFO defguard::grpc::gateway: Starting update stream to gateway: user, network [ID 1] Szczecin
Proxy - enrollment, onboardin and desktop configuration service
# systemctl enable defguard-proxy.service
# systemctl start defguard-proxy.service
# journalctl -u defguard-proxy.service | tail -n 50
2024-07-27T16:53:58.584154Z INFO defguard_proxy::tracing: Tracing initialized
2024-07-27T16:53:58.584233Z INFO defguard_proxy::http: Starting Defguard proxy server
2024-07-27T16:53:58.584371Z INFO defguard_proxy::http: Skipping rate limiter setup
2024-07-27T16:53:58.584438Z INFO defguard_proxy::http: gRPC server is listening on 0.0.0.0:50051
2024-07-27T16:53:58.585125Z INFO defguard_proxy::http: Defguard proxy server initialization complete
2024-07-27T16:53:58.585262Z INFO defguard_proxy::http: API web server is listening on 0.0.0.0:8080
### Core configuration ###
#
# Generate secrets
#
DEFGUARD_AUTH_SECRET=defguard-auth-secret
DEFGUARD_GATEWAY_SECRET=defguard-gateway-secret
DEFGUARD_YUBIBRIDGE_SECRET=defguard-yubibridge-secret
DEFGUARD_SECRET_KEY=9oZqdHRCN0TWIyMhjYOAYwgzVz9IfOqz62PzUvjvyMzqLICGSM3b0pRMdDH300CQ
# Define the URL under which defguard is running:
DEFGUARD_URL=https://my-server.defguard.net
# How long auth session lives in seconds
DEFGUARD_AUTH_SESSION_LIFETIME=604800
# Optional. Generated based on DEFGUARD_URL if not provided.
# DEFGUARD_WEBAUTHN_RP_ID=localhost
DEFGUARD_ADMIN_GROUPNAME=admin
DEFGUARD_DEFAULT_ADMIN_PASSWORD=pass123
# This will be displayed in the network settings when editing/adding a new location:
DEFGUARD_GRPC_URL=https://my-server.defguard.net:444
### Proxy configuration ###
# Proxy is optional - if you would like to use the remote enrollment
# and onboarding service, as well as easy desktop client configuration
# proxy must be enabled.
# PROXY configuration:
DEFGUARD_PROXY_URL=https://enroll.defguard.net:444 # add this line to your config file
### LDAP configuration ###
# DEFGUARD_LDAP_URL=ldap://localhost:389
# DEFGUARD_LDAP_SERVICE_PASSWORD=adminpassword
# DEFGUARD_LDAP_USER_SEARCH_BASE="ou=users,dc=example,dc=org"
# DEFGUARD_LDAP_GROUP_SEARCH_BASE="ou=groups,dc=example,dc=org"
# DEFGUARD_LDAP_DEVICE_SEARCH_BASE="ou=devices,dc=example,dc=org"
### DB configuration ###
DEFGUARD_DB_HOST="localhost"
DEFGUARD_DB_PORT=5432
DEFGUARD_DB_NAME="defguard"
DEFGUARD_DB_USER="defguard"
DEFGUARD_DB_PASSWORD="defguard"
# for SQLX CLI
DATABASE_URL="postgresql://defguard:defguard@localhost/defguard"
If you would like to use the feature in the desktop client to route All traffic through the VPN please configure your firewall to enable Internet access through your VPN - here you can find exaples how to do it.
Securing the setup
After the installation please make sure that only the following ports are open on the server firewall:
HTTPS port for the proxy (and/or the defguard core if you want it to be public)
VPN server port (eg. WireGuard port)
DO NOT EXPOSE PUBLICLY THE gRPC ports of the core gateway and proxy, which are:
444
50051
50055
Also this setup provides only communication encryption between defguard components, if you additionally like for core/proxy and gateway to have authorization - please setup a custom SSL CA.