Edit

Standalone package based installation

Introduction

This guide will walk you through the process of installing and running Defguard using system packages.

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.

Make sure you understand Defguard's architecture, especially the division into the main components: Core, Proxy, Gateway.

This is a simple guide installing all components on a single server. For production make sure your infrastructure is prepared by following our recommendations.

System Requirements

Before proceeding with the installation, ensure your system meets the following requirements:

  • One of the installed:

    • Debian/Ubuntu

    • Fedora/Red Hat Linux/SUSE

    • FreeBSD

  • 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).

  • Defguard enrollment service (run by proxy) that will enable remote onboarding, enrollment and easy configuration for our Desktop Clients (by adding Defguard instances) with instance URL and one simple token - in this tutorial we use: enroll.defguard.net (this subdomain also points 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.

Installing a database

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:

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.

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

Installing packages

Defguard also have public APT repository, if you want know how to set it up, follow this guide.

Core

You can find the URL to your package from the releases of the Core component on GitHub.

OS distribution
OS architecture
Release artifact naming convention

Debian/Ubuntu

x86

defguard-X.Y.Z-x86_64-unknown-linux-gnu.deb

Fedora/Red Hat Linux/SUSE

x86

defguard-X.Y.Z-x86_64-unknown-linux-gnu.rpm

FreeBSD

x86

defguard-X.Y.Z_x86_64-unknown-freebsd.pkg

Choose the release you want to install, then choose the right package from the list of release's assets, and copy the package URL.

Download the package to your server using wget:

Example:

You can also download directly from the Github release page, but please note that you should know the path where this could be stored after downloading.

Once the package appropriate for your distribution is downloaded, install it using the appropriate system tool:

You can check is core installed properly:

Gateway

You can find the URL to your package from the releases of the Core component on GitHub.

OS discibution
OS architecture
Release artifact naming convention

Debian/Ubuntu

x86

defguard-gateway_X.Y.Z_x86_64-unknown-linux-gnu.deb

Debian/Ubuntu

ARM

defguard-gateway_X.Y.Z_aarch64-unknown-linux-gnu.deb

Fedora/Red Hat Linux/SUSE

x86

defguard-gateway_X.Y.Z_x86_64-unknown-linux-gnu.rpm

FreeBSD

x86

defguard-gateway_X.Y.Z_x86_64-unknown-freebsd.pkg

Choose the release you want to install, then choose the right package from the list of release's assets, and copy the package URL.

Download the package to your server using wget:

Example:

You can also download directly from the Github release page, but please note that you should know the path where this could be stored after downloading.

Once the package appropriate for your distribution is downloaded, install it using the appropriate system tool:

Example:

You can check is core installed properly:

Proxy

You can find the URL to your package from the releases of the Core component on GitHub.

OS discibution
OS architecture
Release artifact naming convention

Debian/Ubuntu

x86

defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.deb

Fedora/Red Hat Linux/SUSE

x86

defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.rpm

Choose the release you want to install, then choose the right package from the list of release's assets, and copy the package URL.

Download the package to your server using wget:

Example:

You can also download directly from the Github release page, but please note that you should know the path where this could be stored after downloading.

Once the package appropriate for your distribution is downloaded, install it using the appropriate system tool:

Example:

You can check is core installed properly:

Running Defguard

Core

To run core service we need to configure /etc/defguard/core.conf.

To generate any secret (which we recommend to be 64 chars), use the following command:

openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64

As previously mentioned, in this tutorial we wil use server domain my-server.defguard.net.

Example /etc/defguard/core.conf:

If you have configured your postgres with different names than in PostgreSQL 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 the Run proxy section. For now DEFGUARD_PROXY_URL is commented.

After changes, you can simply enable and start your Defguard core service:

To see logs, type journalctl command:

Gateway

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

Follow this guide for setting up the location in Defguard Core web interface. You should leave the guide with a token for your new Gateway instance and use it in the following configuration.

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:

Now we can run gateway service with configuration above:

Check the logs of the gateway service:

On the other side, core service should print those informations:

Proxy

To run proxy service (for remote onboarding & enrollment), we can do it by:

Check the logs afterwards. Should look like this:

Reverse proxy

The reverse proxy acts as an intermediary between users and Defguard services, handling HTTPS requests, routing internal gRPC communication, and ensuring encrypted connections between all components.

Follow our additional guide on configuring reverse proxy for for Core and Proxy service. After having the reverse proxy configured and running you can continue with this guide.

Enabling Proxy service in the Core

Now, we can update our Core service configuration in /etc/defguard/core.conf to use the Proxy service by uncommenting DEFGUARD_PROXY_URL

Full /etc/defguard/core.conf:

Reload changes in /etc/defguarc/core.conf

Now you have full working Defguard services 🥳

You can configure your desktop client using the enrollment service and use your VPN.

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.

Upgrading packages

If the new version introduces changes to the default configuration, the existing configuration file will not be overwritten. Instead, a separate file containing the updated default configuration will be created.

FreeBSD/OPNsense

  1. Uninstall the current version.

  2. Install a newer version (as described above).

  3. Restart the service.

PreviousHardware, OS, network and firewall recommendationsNextDefguard APT repository

Last updated

Was this helpful?