# Table of Contents - [Kubernetes | 1.4 | defguard](#kubernetes-1-4-defguard) - [Docker images and tags | 1.4 | defguard](#docker-images-and-tags-1-4-defguard) - [AMIs and AWS CloudFormation | 1.4 | defguard](#amis-and-aws-cloudformation-1-4-defguard) - [Overview | 1.4 | defguard](#overview-1-4-defguard) - [Pre-production and development releases | 1.4 | defguard](#pre-production-and-development-releases-1-4-defguard) - [Docker Compose | 1.4 | defguard](#docker-compose-1-4-defguard) - [High Availability and Failover | 1.4 | defguard](#high-availability-and-failover-1-4-defguard) - [Upgrading | 1.4 | defguard](#upgrading-1-4-defguard) - [Gateway | 1.4 | defguard](#gateway-1-4-defguard) - [Securing gRPC communication | 1.4 | defguard](#securing-grpc-communication-1-4-defguard) - [Hardware, OS, network and firewall recommendations | 1.4 | defguard](#hardware-os-network-and-firewall-recommendations-1-4-defguard) - [Deploying to Production | 1.5 | defguard](#deploying-to-production-1-5-defguard) - [Terraform | 1.4 | defguard](#terraform-1-4-defguard) - [Overview | 1.5 | defguard](#overview-1-5-defguard) - [Configuration | 1.4 | defguard](#configuration-1-4-defguard) - [Health check | 1.4 | defguard](#health-check-1-4-defguard) - [Kubernetes | 1.5 | defguard](#kubernetes-1-5-defguard) - [Defguard APT repository | 1.5 | defguard](#defguard-apt-repository-1-5-defguard) - [Configuring HTTPS using AWS Certificate Manager | 1.5 | defguard](#configuring-https-using-aws-certificate-manager-1-5-defguard) - [OpenID RSA key | 1.4 | defguard](#openid-rsa-key-1-4-defguard) - [Docker Compose | 1.5 | defguard](#docker-compose-1-5-defguard) - [Running gateway on MikroTik routers | 1.4 | defguard](#running-gateway-on-mikrotik-routers-1-4-defguard) - [Standalone package based installation | 1.4 | defguard](#standalone-package-based-installation-1-4-defguard) - [Running Gateway on OPNsense firewall | 1.5 | defguard](#running-gateway-on-opnsense-firewall-1-5-defguard) - [Adding a location and getting a Gateway token | 1.5 | defguard](#adding-a-location-and-getting-a-gateway-token-1-5-defguard) - [Hardware, OS, network and firewall recommendations | 1.5 | defguard](#hardware-os-network-and-firewall-recommendations-1-5-defguard) - [Standalone package based installation | 1.5 | defguard](#standalone-package-based-installation-1-5-defguard) - [Running Gateway on MikroTik routers | 1.5 | defguard](#running-gateway-on-mikrotik-routers-1-5-defguard) - [Configuration | 1.5 | defguard](#configuration-1-5-defguard) - [Terraform | 1.5 | defguard](#terraform-1-5-defguard) - [Reverse Proxy configuration using Nginx | 1.5 | defguard](#reverse-proxy-configuration-using-nginx-1-5-defguard) - [Amazon Machine Image (AMI) | 1.5 | defguard](#amazon-machine-image-ami-1-5-defguard) - [Using a userspace wireguard-go implementation | 1.5 | defguard](#using-a-userspace-wireguard-go-implementation-1-5-defguard) - [High Availability and Failover | 1.5 | defguard](#high-availability-and-failover-1-5-defguard) - [Updating and version compatibility | 1.5 | defguard](#updating-and-version-compatibility-1-5-defguard) - [Migration guides | 1.5 | defguard](#migration-guides-1-5-defguard) - [Pre-production and development releases | 1.5 | defguard](#pre-production-and-development-releases-1-5-defguard) - [Securing gRPC communication | 1.5 | defguard](#securing-grpc-communication-1-5-defguard) - [Using RSA instead of HMAC for OpenID key | 1.5 | defguard](#using-rsa-instead-of-hmac-for-openid-key-1-5-defguard) - [Health check | 1.5 | defguard](#health-check-1-5-defguard) - [Overview | 2.0 | defguard](#overview-2-0-defguard) - [Production deployment verification guide | 1.5 | defguard](#production-deployment-verification-guide-1-5-defguard) - [Deploying to Production | 2.0 | defguard](#deploying-to-production-2-0-defguard) - [Hardware, OS, network and firewall recommendations | 2.0 | defguard](#hardware-os-network-and-firewall-recommendations-2-0-defguard) - [Defguard APT repository | 2.0 | defguard](#defguard-apt-repository-2-0-defguard) - [Standalone package based installation | 2.0 | defguard](#standalone-package-based-installation-2-0-defguard) - [Docker Compose | 2.0 | defguard](#docker-compose-2-0-defguard) - [Kubernetes | 2.0 | defguard](#kubernetes-2-0-defguard) - [Running Gateway on OPNsense firewall | 2.0 | defguard](#running-gateway-on-opnsense-firewall-2-0-defguard) - [Terraform | 2.0 | defguard](#terraform-2-0-defguard) - [Configuring HTTPS using AWS Certificate Manager | 2.0 | defguard](#configuring-https-using-aws-certificate-manager-2-0-defguard) - [Adding a location and getting a Gateway token | 2.0 | defguard](#adding-a-location-and-getting-a-gateway-token-2-0-defguard) - [Updating and version compatibility | 2.0 | defguard](#updating-and-version-compatibility-2-0-defguard) - [Using a userspace wireguard-go implementation | 2.0 | defguard](#using-a-userspace-wireguard-go-implementation-2-0-defguard) - [Reverse Proxy configuration using NGINX | 2.0 | defguard](#reverse-proxy-configuration-using-nginx-2-0-defguard) - [Using RSA instead of HMAC for OpenID key | 2.0 | defguard](#using-rsa-instead-of-hmac-for-openid-key-2-0-defguard) - [Pre-production and development releases | 2.0 | defguard](#pre-production-and-development-releases-2-0-defguard) - [Configuration | 2.0 | defguard](#configuration-2-0-defguard) - [Securing gRPC communication | 2.0 | defguard](#securing-grpc-communication-2-0-defguard) - [Running Gateway on MikroTik routers | 2.0 | defguard](#running-gateway-on-mikrotik-routers-2-0-defguard) - [High Availability and Failover | 2.0 | defguard](#high-availability-and-failover-2-0-defguard) - [Health check | 2.0 | defguard](#health-check-2-0-defguard) - [Migration guides | 2.0 | defguard](#migration-guides-2-0-defguard) - [Linux Kernel WireGuard tuning | 2.0 | defguard](#linux-kernel-wireguard-tuning-2-0-defguard) - [Deploying to Production | defguard](#deploying-to-production-defguard) - [Overview | defguard](#overview-defguard) - [Previewing Defguard v2.0-alpha | 2.0 | defguard](#previewing-defguard-v2-0-alpha-2-0-defguard) - [Kubernetes | defguard](#kubernetes-defguard) - [Configuring HTTPS using AWS Certificate Manager | defguard](#configuring-https-using-aws-certificate-manager-defguard) - [Production deployment verification guide | 2.0 | defguard](#production-deployment-verification-guide-2-0-defguard) - [Updating and version compatibility | defguard](#updating-and-version-compatibility-defguard) - [Defguard APT repository | defguard](#defguard-apt-repository-defguard) - [Running Gateway on OPNsense firewall | defguard](#running-gateway-on-opnsense-firewall-defguard) - [High Availability and Failover | defguard](#high-availability-and-failover-defguard) - [Hardware, OS, network and firewall recommendations | defguard](#hardware-os-network-and-firewall-recommendations-defguard) - [Pre-production and development releases | defguard](#pre-production-and-development-releases-defguard) - [Amazon Machine Image (AMI) | 2.0 | defguard](#amazon-machine-image-ami-2-0-defguard) - [Using a userspace wireguard-go implementation | defguard](#using-a-userspace-wireguard-go-implementation-defguard) - [Adding a location and getting a Gateway token | defguard](#adding-a-location-and-getting-a-gateway-token-defguard) - [Securing gRPC communication | defguard](#securing-grpc-communication-defguard) - [Health check | defguard](#health-check-defguard) - [Docker Compose | defguard](#docker-compose-defguard) - [Reverse Proxy configuration using NGINX | defguard](#reverse-proxy-configuration-using-nginx-defguard) - [Deployment automation | defguard](#deployment-automation-defguard) - [Running Gateway on MikroTik routers | defguard](#running-gateway-on-mikrotik-routers-defguard) - [Using RSA instead of HMAC for OpenID key | defguard](#using-rsa-instead-of-hmac-for-openid-key-defguard) - [Linux Kernel WireGuard tuning | defguard](#linux-kernel-wireguard-tuning-defguard) - [Standalone package based installation | defguard](#standalone-package-based-installation-defguard) - [Migration guides | defguard](#migration-guides-defguard) - [Amazon Machine Image (AMI) | defguard](#amazon-machine-image-ami-defguard) - [Configuration | defguard](#configuration-defguard) - [Terraform | defguard](#terraform-defguard) - [Production deployment verification guide | defguard](#production-deployment-verification-guide-defguard) --- # Kubernetes | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/kubernetes#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------- To deploy and use Defguard on your cluster, you'll need: * A [Kubernetes clusterarrow-up-right](https://kubernetes.io/docs/setup/) * Kubernetes CLI [kubectlarrow-up-right](https://kubernetes.io/docs/reference/kubectl/) installed on your machine * Helm binary https://github.com/helm/helm/releases/latest circle-exclamation Our helm charts currently support only **Traefik ingress - which is relevant and affects exposing GRPC services (see below** `ingress.hosts.grpc``**).**` [hashtag](https://docs.defguard.net/1.4/deployment-strategies/kubernetes#deployment) Deployment ---------------------------------------------------------------------------------------------------- We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with Kubernetes configuration, clone it with: Copy git clone https://github.com/DefGuard/deployment.git && cd deployment/charts Then create a namespace for Defguard on your cluster: Copy kubectl create namespace defguard Copy and fill in values file: Copy cp defguard/values.yaml ./ Required values (the rest should work if left as-is): * `ingress.hosts.grpc`: GRPC ingress address - GRPC clients like Defguard **gateway**, yubi-bridge circle-exclamation If you are configuring your gateway or yubi-bridge - please use this GRPC URL for communication. If you have other ingress controller than traefik - you need to configure GRPC ingress manually with corresponding to your setup. * `ingress.hosts.web`: Web ingress address - Defguard web app will be available here. * `publicUrl`: Public URL your Defguard will be available under. Usually the same as ingress.hosts.web, but differs depending on your load balancer and/or reverse-proxy setup. If you want to deploy the enrollment service along with your Defguard instance, you also need to configure values related to the `defguard-proxy`subchart: * `defguard-proxy.enabled`: enable the enrollment service * `proxyUrl`: proxy gRPC endpoint URL (based on `defguard-proxy.ingress.grpc.host`) * `defguard-proxy.publicUrl`: public URL of the enrollment service * `defguard-proxy.ingress.web.host`: enrollment service web ingress address (the enrollment website) * `defguard-proxy.ingress.grpc.host`: enrollment service gRPC ingress address (for communicating with core) And finally, install the Helm chart in the namespace: [PreviousDocker Composechevron-left](https://docs.defguard.net/1.4/deployment-strategies/docker-compose) [NextTerraformchevron-right](https://docs.defguard.net/1.4/deployment-strategies/terraform) * [Prerequisites](https://docs.defguard.net/1.4/deployment-strategies/kubernetes#prerequisites) * [Deployment](https://docs.defguard.net/1.4/deployment-strategies/kubernetes#deployment) sun-brightdesktopmoon Copy helm install --wait=true --namespace defguard defguard defguard -f values.yaml sun-brightdesktopmoon --- # Docker images and tags | 1.4 | defguard All docker images for gateway, core, and proxy have these additional tags: * `latest` - this tag is for the latest production release - aka `vX.Y.Z` from the `main` branch * `pre-release`\- this tag is for the latest pre-production release - aka `vX.Y.Z-alpha/beta/rcX` from the `main` branch * `dev` - this tag is for the latest development release from the `dev` branch. [PreviousStandalone package based installationchevron-left](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation) [NextDocker Composechevron-right](https://docs.defguard.net/1.4/deployment-strategies/docker-compose) sun-brightdesktopmoon sun-brightdesktopmoon --- # AMIs and AWS CloudFormation | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/amis-and-aws-cloudformation#please-check-documentation-v1.5.0) Please check documentation v1.5.0 ------------------------------------------------------------------------------------------------------------------------------------------------------------------- [PreviousTerraformchevron-left](https://docs.defguard.net/1.4/deployment-strategies/terraform) [NextHigh Availability and Failoverchevron-right](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover) Last updated 6 months ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Overview | 1.4 | defguard Welcome to the deployment strategies section of Defguard documentation. This guide covers the different ways you can deploy Defguard in your environment, from quick options using packages or Docker to more advanced setups with Kubernetes or Terraform. Whether you're running a small instance or preparing for a more complex production environment, this section will help you choose the deployment method that best fits your needs. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#components) Components ------------------------------------------------------------------------------------------------------------------ Defguard comes with four main components: * **Core service** - main web UI and database * **Proxy service** - used to safely expose a subset of public functionalities * **VPN gateway server** - retrieves configuration from core and configures VPN interfaces on the gateway server * **Provisioning station** - client application which can be started on any pc to auto-generate PGP keys for YubiKey There is one external component required: PostgreSQL database. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#hardware-requirements) Hardware requirements ---------------------------------------------------------------------------------------------------------------------------------------- All Defguard components are **very low resource-consuming**. All of them are written in [Rustarrow-up-right](https://www.rust-lang.org/) and are single binaries. As minimum setup as follows should be more than enough: Resource Minimum requirements CPU 1 GHz RAM 2 GB (mostly for PostgreSQL) Disk 2 GB Architecture x86\_64, ARM64 [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#quick-start) Quick start -------------------------------------------------------------------------------------------------------------------- The easiest way to run your own Defguard instance is to use Docker and our [one-line install script](https://docs.defguard.net/1.4/getting-started/one-line-install) . Just run the command below in your shell and follow the prompts: To learn more about the script and available options, please see the [documentation](https://docs.defguard.net/1.4/getting-started/one-line-install) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#manual-deployment) Manual deployment -------------------------------------------------------------------------------------------------------------------------------- If you prefer to configure and deploy Defguard manually, see the examples below: * [Docker Compose](https://docs.defguard.net/1.4/deployment-strategies/docker-compose) * [Kubernetes](https://docs.defguard.net/1.4/deployment-strategies/kubernetes) Client services * [Gateway](https://docs.defguard.net/1.4/deployment-strategies/gateway) * [YubiBridge](https://docs.defguard.net/1.4/features/yubikey-provisioning) circle-info On initial startup a new `admin` user will be created with a password which can be configured by the `DEFGUARD_DEFAULT_ADMIN_PASSWORD` environment variable (by default it's `pass123`). Use those credentials to log in and start exploring the system. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#tips) Tips See our [Configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration) document to check all configurable things before you start. And learn about our Architecture [here](https://docs.defguard.net/1.4/in-depth/architecture) to see how it works. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#updates) Updates ------------------------------------------------------------------------------------------------------------ All services within the Defguard architecture can be updated independently, although it's recommended to always use newest version of services and update them all together to avoid situations like Core expecting some not existing feature in Gateway. Check the GitHub repositories for each service to find their newest releases and release notes. * Docker - For Docker and Kubernetes based setup just change docker image version for service you want to update. * Packages(DEB, RPM, etc.) - Currently we don't have any package repository so if you want to update your service installed as package you have to download new version from service repository. **GitHub Repositories:** * [Defguard Corearrow-up-right](https://github.com/DefGuard/defguard/releases) * [Defguard Proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) * [Defguard Gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) * [Defguard YubiBridgearrow-up-right](https://github.com/DefGuard/YubiKey-Provision/releases) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#backup) Backup ---------------------------------------------------------------------------------------------------------- [Core servicearrow-up-right](https://github.com/DefGuard/defguard) is the only service which uses persistent data storage, which is PostgreSQL database. Every SQL migration is applied automatically while bringing up core server and we try our best not to break anything in the process. It's recommended to do database, configuration and Settings(SMTP, Branding) backup before every update in case of some unexpected failure. Example database backup: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#failover-ha-clustering) Failover/HA/Clustering ------------------------------------------------------------------------------------------------------------------------------------------ For now the [Gateway](https://docs.defguard.net/1.4/deployment-strategies/gateway) can be deployed on multiple servers/firewall/routers for failover and HA - even if the connection to the Core will be lost, gateways will operate with their local cache/data and the VPN will be working. Same works the other way around if gateway don't work or is not available other features from Core like OpenID will be working. [PreviousUser SNAT bindingschevron-left](https://docs.defguard.net/1.4/features/user-snat-bindings) [NextHardware, OS, network and firewall recommendationschevron-right](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations) * [Components](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#components) * [Hardware requirements](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#hardware-requirements) * [Quick start](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#quick-start) * [Manual deployment](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#manual-deployment) * [Tips](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#tips) * [Updates](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#updates) * [Backup](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#backup) * [Failover/HA/Clustering](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance#failover-ha-clustering) sun-brightdesktopmoon Copy curl --proto '=https' --tlsv1.2 -sSf -L https://raw.githubusercontent.com/DefGuard/deployment/main/docker-compose/setup.sh -O && bash setup.sh Copy docker exec {container_name} pg_dump -U {user_name} > {backup_file_name} sun-brightdesktopmoon --- # Pre-production and development releases | 1.4 | defguard To test any pre-production or development release: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#one-line-install) One-line install The simplest way to test the latest development or pre-release version is to use one line installation method with the appropriate argument. More on that in [the one-line install documentation](https://docs.defguard.net/1.4/getting-started/one-line-install) . ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) Binaries and packages Each GitHub repository ([corearrow-up-right](https://github.com/DefGuard/defguard/releases) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) , [proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) , and [clientarrow-up-right](https://github.com/DefGuard/client/releases) ) has its **pre-release versions** available on the GitHub release page. This is where you can download binaries or packages with the pre-release, e.g.: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2Fvtlx5G5aTEsJl5PqkRD6%2FScreenshot%25202025-08-01%2520at%252013.38.44.png&width=768&dpr=3&quality=100&sign=a419d94f&sv=2) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#docker-images) Docker images Each Docker image for [corearrow-up-right](https://github.com/DefGuard/defguard/pkgs/container/defguard) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/pkgs/container/gateway) and [proxyarrow-up-right](https://github.com/DefGuard/proxy/pkgs/container/defguard-proxy) has the following tags: * `pre-release` – this tag is for the **latest pre-production release** - which also contains a version in form of `vX.Y.Z-alpha/beta/rcX` from the `main` branch * `dev` – this tag is for the latest development release from the `dev` branch. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#docker-compose) Docker compose Please change the Docker compose file to match the version or tags as stated above. [PreviousUpgradingchevron-left](https://docs.defguard.net/1.4/deployment-strategies/upgrading) [NextGatewaychevron-right](https://docs.defguard.net/1.4/deployment-strategies/gateway) * [One-line install](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#one-line-install) * [Binaries and packages](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) * [Docker images](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases#docker-images) sun-brightdesktopmoon sun-brightdesktopmoon --- # Docker Compose | 1.4 | defguard Here are basic and simple docker-compose configuration files that will enable you to quickly deploy your own instance manually. We also assume in this example, that all services will be deployed on dedicated servers/VMs - separating them physically, thus each compose is for a separate service. circle-check Please not that we also offer docker-compose deployment with [_one-line quick deployment_](https://docs.defguard.net/1.4/getting-started/one-line-install) _,_ but this method is recommended for PoC/quick deployment as **it launches everything on one server and all services in one docker compose**. We use "latest" (latest production images) tags in the examples below, but you can use others - [more info here](https://docs.defguard.net/1.4/deployment-strategies/docker-images-and-tags) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#core) Core -------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the core and database. Configuration is split to the `.env` file (see below): Copy services: core: image: ghcr.io/defguard/defguard:latest restart: always container_name: "defguard" env_file: .env ports: # HTTP port - open on localhost, should be secured by reverse-proxy - "127.0.0.1:8000:8000" # gRPC port for gateway to connect to # open on all interfaces/IPs - whould be secured with custom CA (see .env) - "50055:50055" depends_on: - db volumes: # more info here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key - ./rsakey.pem:/keys/rsakey.pem # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/keys/ca.pem db: image: postgres:17-alpine container_name: "defguard-db" env_file: .env volumes: - db:/var/lib/postgresql/data #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#nginx-reverse-proxy) NGINX reverse-proxy Now that you have core running, here is an example NGINX configuration to provide SSL termination: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#the-configuration) The configuration Here is the `.env` file with all configuration variables: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#proxy) Proxy ---------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the public proxy (enrollment service as well as desktop client configuration service). To secure the gRPC communication, please generate the proxy CA and certificate, [more info here](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#nginx-reverse-proxy-1) NGINX reverse-proxy Now that you have proxy running, here is an example NGINX configuration to provide SSL termination: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#gateway) Gateway -------------------------------------------------------------------------------------------------- For gateway to control the WireGuard kernel as well as network, it's recommended to run in the _host_ network mode as well as there are needed some docker CAPs: [PreviousDocker images and tagschevron-left](https://docs.defguard.net/1.4/deployment-strategies/docker-images-and-tags) [NextKuberneteschevron-right](https://docs.defguard.net/1.4/deployment-strategies/kubernetes) Last updated 5 months ago * [Core](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#core) * [The configuration](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#the-configuration) * [Proxy](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#proxy) * [Gateway](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#gateway) sun-brightdesktopmoon Copy upstream defguard { server 127.0.0.1:8000; } server { listen 443 ssl http2; # your domain server_name defguard.secure-internal.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.error.log; ssl on; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/secure-internal.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/secure-internal.net/privkey.pem; client_max_body_size 20m; location / { proxy_connect_timeout 300; proxy_pass http://defguard; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; } } Copy # please generate each secret with: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-63 DEFGUARD_SECRET_KEY= DEFGUARD_AUTH_SECRET= DEFGUARD_GATEWAY_SECRET= DEFGUARD_YUBIBRIDGE_SECRET= # if you plan to reverse-proxy defguard, please provide a full URL # this URL will be shared in emails, enrollement messages, etc.: DEFGUARD_URL=https://defguard.secure-internal.net # Must be an effective domain of DEFGUARD_URL # Changing DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing # Webauthn credentials. DEFGUARD_WEBAUTHN_RP_ID=defguard.secure-internal.net # accepted: info/debug/warning/error DEFGUARD_LOG_LEVEL=info # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates DEFGUARD_PROXY_GRPC_CA=/keys/ca.pem # gRPC URL of proxy (see proxy config) DEFGUARD_PROXY_URL=https://proxy.host:50051 # more details about RSA key here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key DEFGUARD_OPENID_KEY=rsakey.pem # the URL of your proxy - will be displayed during enrollment, email # messages or desktop client configuration DEFGUARD_ENROLLMENT_URL=https://enrollment.public.net # PostgreSQL database configuration for core DEFGUARD_DB_HOST=db DEFGUARD_DB_PORT=5432 DEFGUARD_DB_USER=defguard # please generate password: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-63 DEFGUARD_DB_PASSWORD= DEFGUARD_DB_NAME=defguard # database configuration for "db" container # must be same as above # database will be initialized with these values (the user/pass set here) POSTGRES_DB=defguard POSTGRES_USER=defguard POSTGRES_PASSWORD=!SAME_AS-GENERATED-DEFGUARD_DB_PASSWORD! Copy proxy: image: ghcr.io/defguard/defguard-proxy:latest restart: unless-stopped ports: # HTTP port - should be secured by reverse proxy - "127.0.0.1:8080:8080" - "50051:50051" environment: # path in the volume to custom proxy cert & key - DEFGUARD_PROXY_GRPC_CERT=ca/proxy.crt - DEFGUARD_PROXY_GRPC_KEY=ca/proxy.key volumes: - ./ca/proxy.crt:ca/proxy.crt - ./ca/proxy.key:ca/proxy.key Copy upstream defguard-proxy { server 127.0.0.1:8080; } server { listen 443 http2; server_name enrollment.public.net; access_log /var/log/nginx/defguard-proxy.log; error_log /var/log/nginx/defguard-proxy.error.log; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/public.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/public.net/privkey.pem; client_max_body_size 20m; location / { proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } Copy services: gateway: image: ghcr.io/defguard/gateway:latest restart: unless-stopped network_mode: "host" environment: - DEFGUARD_GRPC_URL=https://core-ip:50055 - DEFGUARD_GRPC_CA=/ca.pem - DEFGUARD_STATS_PERIOD=30 # to get the token add a VPN location and get the token - DEFGUARD_TOKEN=tokenFromCoreLocation - DEFGUARD_GATEWAY_NAME=willBeVisibleInDefguardAsGWName volumes: # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/ca.pem cap_add: - NET_ADMIN sun-brightdesktopmoon --- # High Availability and Failover | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#gateway-high-availability) Gateway - High Availability -------------------------------------------------------------------------------------------------------------------------------------------------------- We support running multiple gateways for a single VPN instance or location, enabling active-passive configurations. Active-active configurations should also be possible but come with some caveats. Since our gateway uses a vanilla kernel WireGuard®, there are multiple approaches for implementation. circle-info Please also see documentation of [Creating a New VPN location](https://docs.defguard.net/1.4/features/wireguard/create-your-vpn-network) where each [location setting has information regarding high-availability](https://docs.defguard.net/1.4/features/wireguard/create-your-vpn-network#vpn-location-settings) . #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#deploying-multiple-gateways-for-one-location) Deploying multiple gateways for one location To have a multi-gateway setup for a given location, you will need to [deploy the gateway on each one of your servers](https://docs.defguard.net/1.4/deployment-strategies/gateway) under the same location. If you already have a gateway deployed and want to add another one for the location, go to _VPN Overview_ -> Click: _Edit Location Settings (in the top right corner)_, then choose the location you want to add the new gateway to, and follow the deployment instructions: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FbyLyJT1D0BfQ15DN6NlJ%2FScreenshot%25202024-11-12%2520at%252016.55.55.png&width=768&dpr=3&quality=100&sign=9bde2051&sv=2) Each gateway deployed for a given location will receive the same network configuration and will **bind to the defined port** in the location's _Gateway Port._ The only thing left to do is to point your traffic to those gateways, which can be accomplished in several ways: * Floating public IP - if you choose this scenario, please remember that the IP must be the IP specified in the Location _Gateway Address._ In this scenario, the floating IP switches between your gateway servers, directing the traffic to one of the two gateways. * Proxy/load balancing - also remember that the proxy must be configured with the _Gateway Address and Gateway Port._ In this scenario, your clients connect to the proxy/load balancer, which direct the VPN traffic (UDP) to one of your gateway backends_._ #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#active-active-setups) Active-active setups Active-active setups should also be possible but come with some caveats. Here are the currently known issues with such configurations: * Multiple running gateways bound to one location with network traffic distributed between them may produce invalid network usage statistics, making the network usage graphs and displays on the dashboard unreliable. Related issue: [https://github.com/DefGuard/defguard/issues/1022arrow-up-right](https://github.com/DefGuard/defguard/issues/1022) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) Determining if multiple gateways are running All gateways that are successfully connected for the location are displayed under the Location in VPN Overview, here is an example for two gateways: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FDpzaBvwxvJgcML0Dt3xz%2Flocation-overview.png&width=768&dpr=3&quality=100&sign=a0f09b5c&sv=2) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) What is the gateway peers persistence (if core/proxy services fail) 1. For **VPN Locations without MFA** - it's persistent until the system reboot - _even if the gateway will not work_ - as the gateway configures WireGuard "in kernel". 2. For **VPN Locations with MFA**, this depends on the _Peer Disconnect Threshold (seconds)_ setting in the VPN Location settings. This setting specifies that if the peer is inactive for _(defined seconds)_, the gateway should remove it from the configuration. Therefore, if the proxy/core is not operational, MFA authentication will fail, and the peer will not be added if it is disconnected. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#core-proxy-failover) Core / Proxy - Failover ---------------------------------------------------------------------------------------------------------------------------------------------- The core service handles gateway states as well as core connects _**to the proxy**_. Since proxy serves HTTP based protocol communication and should be in the public Internet, it needs to be secure, thus core connects to the proxy. This way **core can be in an Intranet network segment and proxy can be in DMZ, making Core completely cut-off on firewall from the Internet** (you only can have only outgoing firewall rules from Intranet allowing only for core to connect to proxy). So **High Availability for core and proxy** gets complicated, with multiple proxies core needs to manage those connections. We already have most of the code for that ready, but it's not yet production ready. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#how-to-bullet-proof-proxy-and-core-with-failover) How to bullet-proof proxy & core with failover? We recommend to deploy them on a failover solution - like on a kubernetes cluster (even small one - like mini-kube) . This way, Kubernetes manages: healthchecks and does failover. You can have cluster N-nodes and if any VM/node with Core/Proxy goes offline or health checks fail - it's migrated to a new node. [PreviousAMIs and AWS CloudFormationchevron-left](https://docs.defguard.net/1.4/deployment-strategies/amis-and-aws-cloudformation) [NextUpgradingchevron-right](https://docs.defguard.net/1.4/deployment-strategies/upgrading) * [Gateway - High Availability](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#gateway-high-availability) * [Determining if multiple gateways are running](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) * [What is the gateway peers persistence (if core/proxy services fail)](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) * [Core / Proxy - Failover](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#core-proxy-failover) sun-brightdesktopmoon sun-brightdesktopmoon --- # Upgrading | 1.4 | defguard circle-exclamation Before doing any updates please remember to **backup your database.** [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) Any release <= 1.3 -> 1.4 -------------------------------------------------------------------------------------------------------------------------------------------------- 1.4 release introduces changes related to multiple client IP addresses. To ensure compatibility, **all components must be updated** to v1.4 or higher: * **Core** * **Proxy** * **Gateway** * **Desktop Clients** Running outdated versions may result in errors due to incompatible data formats. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core) Core We've made a small update to the LDAP integration to support more complex user nesting within the LDAP tree ([related issuearrow-up-right](https://github.com/DefGuard/defguard/issues/1242) ). If you were already using the integration, you shouldn't notice any changes. However, we **strongly recommend backing up your database before the upgrade and afterwards verifying** the following to ensure everything continues to work as expected: * Your Defguard user list and user devices remain unchanged * All users can still log in without issues If you encounter any problems, please report them on our [GitHubarrow-up-right](https://github.com/DefGuard/defguard/issues) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) Any previous release → 1.4.0-alpha3 --------------------------------------------------------------------------------------------------------------------------------------------------- We've introduced some changes to the LDAP integration. We recommend reading [the above section](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core) before upgrading. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-release-1.3.0) Any previous release → 1.3.0 ------------------------------------------------------------------------------------------------------------------------------------- * The LDAP integration has become an enterprise feature. You will need to purchase the enterprise license if you exceed the free limits. See [License](https://docs.defguard.net/1.4/enterprise/license) for more information regarding the license. * If you used the LDAP integration previously, it will be off by default after upgrading. You will have to manually enable it in the settings in the LDAP tab:\\ ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2F0PEpPFDEkIwy2dAfubFS%2Fimage.png&width=768&dpr=3&quality=100&sign=7bbd7db9&sv=2) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) Any previous 1.3.0 alpha → 1.3.0 alpha 4 ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-1) Core LDAP integration received a major overhaul of how users are mapped to Defguard users when the two-way synchronization is enabled. Now, users are always identified by their leftmost DN value. A new synchronization may cause some of your users to be re-added, which in turn may cause the loss of some of their Defguard specific data (e.g. their devices). This will happen if your leftmost DN component's attribute (referred to as RDN) is not the same as your current username attribute. This issue is only related to the two-way synchronization mechanism and occurs only if you used one of the previous alphas of 1.3.0. Upgrading from any previous release to alpha 4 (skipping the alphas before) should not result in this happening. Before an upgrade, turn off the two-way synchronization. After upgrading, you will have access to a new option, the RDN user attribute: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FvBxwjrtUFsZLtYdvUHuv%2Fimage.png&width=768&dpr=3&quality=100&sign=b9b25b22&sv=2) Set it according to your LDAP server setup. This should be the DN's leftmost component attribute, e.g. in the case of `cn=user1,cn=users,dc=ad,dc=example,dc=com` this would be "cn". This attribute is needed to properly identify users in your LDAP server. The username attribute will be mapped to Defguard usernames. Read [Settings table](https://docs.defguard.net/1.4/features/ldap-and-active-directory-integration/settings-table) for a description of those settings options. After you configured this value, you can re-enable the two-way synchronization. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) Any previous core release -> core 1.1.4 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-2) Core triangle-exclamation In Core 1.1.4, we've made email addresses case insensitive, as this is a standard for many major providers. Because the emails were case sensitive up to this point, you may end up with users with the same email addresses from core's point of view. All email addresses must be unique case-insensitively, meaning that a user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) ` can't coexist with another user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) `. Before upgrading, make sure you don't have any users with the same email addresses given the above. If you do, please change those addresses or remove the users altogether. Remember to check it case-insensitively. If you have users with duplicate email addresses, the migrations will fail, and you won't be able to upgrade. You can use the following SQL query to locate users with duplicate emails in the database: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) 1.0.0 -> 1.1.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#proxy) Proxy There is a new setting: * ENV Variable: DEFGUARD\_PROXY\_URL * command line argument `--url` * /etc/defguard/proxy.toml: `url =` **Which should be set to the same value as in core** `**DEFGUARD_ENROLLMENT_URL**` [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-release-greater-than-1.0.0) Any release -> 1.0.0 --------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-3) Core When upgrading core to 1.0.0 (even to a 1.0.0 pre-release) make sure that your users **have unique email addresses** as we've introduced a constraint requiring email addresses to be unique among users. triangle-exclamation If you have duplicate emails in your database, the migrations during the upgrade process will simply fail. You will need to change a duplicate email address before the upgrade by hand via the Defguard dashboard or by accessing the database. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#desktop-client-real-time-sync) Desktop Client Real Time Sync From 1.0.0 we have introduced [Enterprise featuresarrow-up-right](https://github.com/DefGuard/docs/blob/docs/deployment-strategies/broken-reference/README.md) , and one of them is [automatic and real-time desktop client configuration synchronization](https://docs.defguard.net/1.4/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration) . To enable this on an **already configured desktop client,** one must perform one time instance update, which will generate necessary tokens on the client to perform from now on automatic updates. In details: 1. The admin must generate a new token for the client - [more details here](https://docs.defguard.net/1.4/features/wireguard/remote-desktop-activation) (token can be sent over email or shared in any other secret way). 2. The user must perform the [Instance Update - more details here](https://docs.defguard.net/1.4/using-defguard-for-end-users/desktop-client/instance-configuration#updating-instance) . circle-exclamation Any client that is configured from scratch has this done automatically and no actions needed to be done. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In this release, we have **hardened the security architecture**, and since the Proxy component is open for HTTP commands and is frequently communicating with Core we have reversed the communication and now **Core is connecting to Proxy (Proxy is a gRPC server and Core is the client).** This way if Core is in a secure network segment (like Intranet) and Proxy in a DMZ segment (where Internet traffic is allowed) you don't need to open on your firewall rules for Proxy from DMZ to connect to Intranet (no packet for New Connections from DMZ->Intranet). This change requires a few changes if you are upgrading: #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#proxy-deployment-configuration) Proxy deployment configuration 1. Remove `DEFGUARD_PROXY_UPSTREAM_GRPC_URL` variable - since Proxy does not connect to Defguard Core any more. 2. Proxy is now the server to which Defguard Core connects, so you may want to: 1. Optional: configure non-default Proxy gRPC port with `DEFGUARD_PROXY_GRPC_PORT -` default value is **50051** 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/treafik/...) the port with SSL/TLS. 1. (Optional) If you want to use SSL with Proxy gRPC server without revers-proxy (nginx/etc) configure `DEFGUARD_PROXY_GRPC_CERT` and `DEFGUARD_PROXY_GRPC_KEY` following the [SSL setup guide](https://docs.defguard.net/1.4/deployment-strategies/docker-compose#grpc-ssl-setup) . 3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server **can be reached from Core**. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-deployment-configuration) Core deployment configuration 1. Add `DEFGUARD_PROXY_URL` variable to point to your Proxy gRPC server endpoint, for example `http://proxy:50051` when using Docker Compose - or any gRPC URL you have configured with your reverse proxy. 2. (Optional) If using SSL configure `DEFGUARD_PROXY_GRPC_CA` #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#upgrade-process) Upgrade process 1. Update Core & Proxy images/binaries and restart services. 2. You should see in the logs that Proxy is awaiting a gRPC connection - example docker logs: 1. Core should be attempting to establish a gRPC connection with Proxy (and retrying every 10s if unable to successfully connect), like this: 1. After Defguard connects successfully to proxy, you should see in proxy logs: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) Desktop Client 0.1.x -> 0.2.0 --------------------------------------------------------------------------------------------------------------------------------------------------- With this release we have added Multi-Factor Authentication to the desktop client. Unfortunately desktop client database has change significantly as well as business logic (for example endpoints to proxy for MFA handshake). We have not stored them previously in the database - thus they cannot be recovered/updated automatically. circle-exclamation That unfortunately means you have to remove all your instances before upgrading (or just remove any desktop client configuration files, including the database) and start the enrollment (adding new instance) again after upgrading - just by adding a new device (you can remove the old one). [PreviousHigh Availability and Failoverchevron-left](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover) [NextPre-production and development releaseschevron-right](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases) * [Any release <= 1.3 -> 1.4](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) * [Core](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core) * [Any previous release → 1.4.0-alpha3](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) * [Any previous release → 1.3.0](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-release-1.3.0) * [Any previous 1.3.0 alpha → 1.3.0 alpha 4](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) * [Core](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-1) * [Any previous core release -> core 1.1.4](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) * [Core](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-2) * [1.0.0 -> 1.1.0](https://docs.defguard.net/1.4/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) * [Proxy](https://docs.defguard.net/1.4/deployment-strategies/upgrading#proxy) * [Any release -> 1.0.0](https://docs.defguard.net/1.4/deployment-strategies/upgrading#any-release-greater-than-1.0.0) * [Core](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-3) * [Desktop Client Real Time Sync](https://docs.defguard.net/1.4/deployment-strategies/upgrading#desktop-client-real-time-sync) * [Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x](https://docs.defguard.net/1.4/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) * [Desktop Client 0.1.x -> 0.2.0](https://docs.defguard.net/1.4/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) sun-brightdesktopmoon Copy select id, username, email from "user" where lower(email) in ( select lower(email) from "user" group by lower(email) having count(*) > 1 ) Copy Attaching to defguard_proxy_1 proxy_1 | 2024-01-24T14:05:41.365035Z INFO defguard_proxy::server: Starting Defguard proxy server proxy_1 | 2024-01-24T14:05:41.365069Z DEBUG defguard_proxy::server: Setting up API server proxy_1 | 2024-01-24T14:05:41.365130Z INFO defguard_proxy::server: gRPC server is listening on 0.0.0.0:50051 proxy_1 | 2024-01-24T14:05:41.365333Z INFO defguard_proxy::server: Web server is listening on 0.0.0.0:8080 Copy defguard | 2024-01-24T14:17:47.815294Z INFO defguard::grpc: Connecting to proxy Copy proxy_1 | 2024-01-24T14:17:47.819504Z INFO defguard_proxy: RPC client connected from: 10.123.123.2:35916 sun-brightdesktopmoon --- # Gateway | 1.4 | defguard circle-info If you are looking for [gateway High Availability, go to this document.](https://docs.defguard.net/1.4/deployment-strategies/high-availability-and-failover#gateway-high-availability) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#pre-requirements) Pre-requirements ------------------------------------------------------------------------------------------------------------- circle-exclamation Please remember that **one gateway corresponds to one VPN location.** You can also deploy multiple gateways for one location for High Availability. To deploy the gateway you need to have Defguard core running and know it's [gRPC url](https://docs.defguard.net/1.4/deployment-strategies/configuration#core-configuration) (meaning what is the **host/ip** where the core is running and the **gRPC port** defined in core by DEFGUARD\_GRPC\_PORT configuration variable**)** and a **token.** **Token** can be obtained when you go to _VPN Locations -> Edit location settings (in top right corner) -> Select the desired location_ -> the right panel describes how to deploy the gateway for the location as well as lists the gateway authentication token: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FlBUspJMiHqZR7Oylzqp4%2FScreenshot%25202024-11-12%2520at%252017.28.07.png&width=768&dpr=3&quality=100&sign=5077031c&sv=2) Also, if core has a custom SSL CA to secure gRPC communication, [you need the CA certificate (more here).](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#package-install) Package Install ----------------------------------------------------------------------------------------------------------- 1. On the [release pagearrow-up-right](https://github.com/DefGuard/gateway/releases) find and download a correct software package for your system (currently DEB, RPM and TXZ are available). 2. Install the package using relevant system tools: **Ubuntu/Debian:** **Fedora/Red Hat Linux/SUSE:** **FreeBSD:** 3. Fill in the default configuration file (`/etc/defguard/gateway.toml`) with values corresponding to your Defguard installation (token and gRPC endpoint URL). 4. On systems with [systemdarrow-up-right](https://systemd.io/) , enable and start the **systemd** service: On systems with rc.d (like FreeBSD, NetBSD), start the service. For example, on OPNsense: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#package-upgrade) Package Upgrade ----------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#freebsd-opnsense) FreeBSD/OPNsense 1. Uninstall the current version. 2. Install a newer version (as described above in [Package Install](https://docs.defguard.net/1.4/deployment-strategies/gateway#package-install) ). 3. Restart Defguard Gateway service. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#docker-compose) Docker Compose --------------------------------------------------------------------------------------------------------- To start Defguard Gateway using [Docker Composearrow-up-right](https://docs.docker.com/compose/) : 1. We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with Docker Compose configuration, clone it: 1. Copy and fill in the .env file: 1. Finally, run the service with Docker Compose: If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/1.4/features/network-devices#adding-a-new-network-device) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#opnsense-plugin) OPNsense plugin ----------------------------------------------------------------------------------------------------------- [OPNsense®arrow-up-right](https://opnsense.org/) is an open source, feature rich firewall and routing platform, offering cutting-edge network protection. To start Defguard Gateway as OPNsense plugin: 1. On the [release pagearrow-up-right](https://github.com/DefGuard/gateway/releases) find and download OPNsense package which will be named: `defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg` – this package **includes both Defguard Gateway and OPNsense plugin.** 2. Install the package: 1. Refresh your OPNsense UI by running command below: 1. Go to your OPNsense UI and navigate to **VPN** > **Defguard Gateway**. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2F4Ey4JRUHxe8bUHV53CCX%2FOPNSense%2520Plugin.png&width=768&dpr=3&quality=100&sign=1ec32d61&sv=2) 1. Fill out the form with appropriate values, click **Save**, and then click **Start/Restart.** circle-info You can find detailed description of all fields [here](https://docs.defguard.net/1.4/deployment-strategies/configuration#gateway-configuration) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/1.4/features/wireguard/remote-desktop-activation) . See also: [how to configure Defguard in OPNsense](https://docs.defguard.net/1.4/features/gateway) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#binary-install) Binary Install --------------------------------------------------------------------------------------------------------- 1. Checkout Gateway releases [herearrow-up-right](https://github.com/DefGuard/gateway/releases) and download compatible binary from GitHub page. 2. Decompress and move to bin directory 1. Start gateway `gateway -g -t ` [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway#using-a-userspace-implementation) Using a userspace implementation --------------------------------------------------------------------------------------------------------------------------------------------- Gateway currently supports using `wireguard-go`, a userspace WireGuard implementation. This approach is not recommended on platforms where a native support exists (e.g. Linux). You can enable the userspace implementation by setting the `userspace` config option or a corresponding `DEFGUARD_USERSPACE` environment variable to `true`. Because `wireguard-go` is not bundled by default with Defguard, it must be installed separately. The `wireguard-go` binary/command must be available on the host machine for it to function properly. On Docker, this currently requires building a custom image, as the base gateway images also don't come with `wireguard-go` pre-installed. This can be achieved as follows: Note that when running the Docker container with a userspace implementation on a Linux host, the container requires a `NET_ADMIN` capability and access to `/dev/net/tun`, this can be set in a Docker compose: Or via the command line: [PreviousPre-production and development releaseschevron-left](https://docs.defguard.net/1.4/deployment-strategies/pre-production-and-development-releases) [NextRunning gateway on MikroTik routerschevron-right](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers) * [Pre-requirements](https://docs.defguard.net/1.4/deployment-strategies/gateway#pre-requirements) * [Package Install](https://docs.defguard.net/1.4/deployment-strategies/gateway#package-install) * [Package Upgrade](https://docs.defguard.net/1.4/deployment-strategies/gateway#package-upgrade) * [FreeBSD/OPNsense](https://docs.defguard.net/1.4/deployment-strategies/gateway#freebsd-opnsense) * [Docker Compose](https://docs.defguard.net/1.4/deployment-strategies/gateway#docker-compose) * [OPNsense plugin](https://docs.defguard.net/1.4/deployment-strategies/gateway#opnsense-plugin) * [Binary Install](https://docs.defguard.net/1.4/deployment-strategies/gateway#binary-install) * [Using a userspace implementation](https://docs.defguard.net/1.4/deployment-strategies/gateway#using-a-userspace-implementation) sun-brightdesktopmoon Copy sudo dpkg -i Copy sudo rpm -i Copy pkg add Copy sudo systemctl enable defguard-gateway.service sudo systemctl start defguard-gateway.service Copy sudo /usr/local/etc/rc.d/defguard_gateway start Copy pkg delete defguard-gateway Copy pkg add Copy sudo /usr/local/etc/rc.d/defguard_gateway restart Copy git clone --recursive https://github.com/DefGuard/deployment.git && cd deployment/gateway Copy cp .env.template .env Copy docker compose up Copy pkg add defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg Copy opnsense-patch Copy tar xcf ./gateway.tar.gz sudo chmod +x gateway sudo mv gateway /usr/bin/ Copy FROM golang:1.24.6-alpine AS builder RUN apk add --no-cache git make RUN git clone https://git.zx2c4.com/wireguard-go /src/wireguard-go \ && cd /src/wireguard-go \ && make # Specify the desired Gateway's version here FROM ghcr.io/defguard/gateway:latest COPY --from=builder /src/wireguard-go/wireguard-go /usr/local/bin/wireguard-go RUN chmod +x /usr/local/bin/wireguard-go Copy # Docker compose cap_add: - NET_ADMIN devices: - /dev/net/tun Copy docker run --cap-add=NET_ADMIN --device=/dev/net/tun [...] sun-brightdesktopmoon --- # Securing gRPC communication | 1.4 | defguard Defguard Core has two main communication endpoints: 1. gRPC port for communicating with Defguard Gateways, 2. gRPC port for communicating with Defguard Core. triangle-exclamation It is **critical** that: 1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes. 2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core. 3. If you want an additional layer of security, then you should create a **custom SSL Certificate Authority (CA)**, and provide Core, Proxy and Gateway Certificates from that CA so **any other connections to the gRPC services will not be accepted.** 4. Even if you have secured the network ports/firewall and do not want to create a custom SSL CA, please secure gRPC traffic with SSL and a reverse proxy. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) Custom SSL CA and certificates -------------------------------------------------------------------------------------------------------------------------------------------------------- To secure not only with firewall communication between all Defguard gRPC components, a custom SSL chain of certificates should be used. This way the trust will be ensured on the Transport Layer Security (TLS) level. It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one under which a service is being hosted. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#quick-setup) Quick setup To quickly generate a set of SSL certificates using [OpenSSLarrow-up-right](https://openssl-library.org/) or [LibreSSLarrow-up-right](https://www.libressl.org/) , use the following: * Generate Certificate Authority (CA) certificate and key for domain _example.local_ Copy openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt * Generate private key and Certificate Signing Request (CSR) * Generate certificate by signing the CSR, valid for 365 days circle-info Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly. To display certificate file contents: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-configuration) Defguard configuration #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-core) Defguard Core Using command line arguments Using environment variables #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-proxy) Defguard Proxy Using command line arguments Using environment variables ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-gateway) Defguard Gateway Using command line arguments Using environment variables Using configuration file [hashtag](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) Trusted CA (eg. Let'sEncrypt or others) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Often (like in the standalone package based installation tutorial) gRPC communication can be secured by a reverse proxy (NGINX, Caddy, Traefik, etc.) that handles SSL termination. It's common to use typical trusted CA (that is used for typical HTTPS traffic) like Let'sEncrypt or others. triangle-exclamation While this secures the transport layer and encrypts communication between Defguard components - it does not provide authorization between gRPC components like Custom CA does. Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall. If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for: * Defguard Gateway – in _gateway.toml_ add path to CA certificate file (in PEM format); for example, when using standard Let'sEncrypt installation ([Certbotarrow-up-right](https://certbot.eff.org/) ), you configure the CA path like this: * `grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem"` * Defguard Core – similarily, you need to configure Proxy CA certificate file using **DEFGUARD\_PROXY\_GRPC\_CA** environment variable: * `DEFGUARD_PROXY_GRPC_CA: /etc/letsencrypt/live/domain.name/chain.pem` [PreviousRunning gateway on MikroTik routerschevron-left](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers) [NextOpenID RSA keychevron-right](https://docs.defguard.net/1.4/deployment-strategies/openid-rsa-key) * [Custom SSL CA and certificates](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) * [Quick setup](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#quick-setup) * [Defguard configuration](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-configuration) * [Defguard Gateway](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#defguard-gateway) * [Trusted CA (eg. Let'sEncrypt or others)](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) sun-brightdesktopmoon Copy openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local Copy openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy Copy openssl x509 -noout -text -in core.crt Copy defguard --grpc-cert path/to/core.crt \ --grpc-key path/to/core.key \ --proxy-grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CERT=path/to/core.crt \ DEFGUARD_GRPC_KEY=path/to/core.key \ DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \ defguard Copy defguard-proxy --grpc-cert path/to/proxy.crt \ --grpc-key path/to/proxy.key Copy env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \ DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key defguard-proxy Copy defguard-gateway --grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CA=path/to/ca.crt \ defguard-gateway Copy grpc_ca = "path/to/ca.crt" sun-brightdesktopmoon --- # Hardware, OS, network and firewall recommendations | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) Server & environment requirements ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Defguard can be deployed on multiple servers (physical or virtual) or on a single server (which is not recommended). Recommended setup: 1. **Dedicated server or Virtual Machine for Core (control plane)** - that is in the Intranet network segment, not exposed in the public Internet in any way. Core needs to be accessible from the local (secure) network and VPN (to access Defguard securely). Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location - eg. if Defguard handles 2 VPN locations recommended is min. 2 CPU/vCPU 2. RAM: min. 1GB per location 3. Disk: min 8GB and more (since statistics will be gathered) 2. **Dedicated server or Virtual Machine for Proxy (external and public enrollment service)** - this server/VM needs to be deployed in DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 1GB 3. **Dedicated server or Virtual Machine for Gateway -** this server/VM needs to be deployed in: 1. DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. 2. Has access on Internal network interfaces to all network segments that will be exposed from VPN for users. 3. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 4GB (mostly for logs) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) Operating system and software requirements #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#package-based-installation) Package based installation Package based install requires Debian GNU/Linux min. 13.x or Ubuntu Linux min. 24.04.x #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#docker-based-installation) Docker based installation Docker deployment requires the system to have [official Docker Engine installationarrow-up-right](https://docs.docker.com/engine/install/) (not distribution based packages). [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) Network IP & DNS setup -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) Gateway server - where WireGuard VPN tunnels itself will be launched * **must have a public IP assigned on which the WireGuard port will be exposed in the Internet** * must have all networks on internal interfaces addresses configured, that should be accessible from VPN * **Recommended:** to have a public domain assigned to this IP for VPN server, eg. _vpn.company.com_ ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) Proxy - public web service for enrollment & desktop client configuration * **must have a public IP assigned on which the enrollment domain will be configured and HTTPS server will be exposed** * **must have a public enrollment domain assigned to this IP,** _**eg. enrollment.company.com (or vpn-config.company.com, etc..**_**)** ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) Core & database server * should be internal / private IP addresses accessible only from Intranet and VPN * must have internal domain name assigned in the local network DNS server, eg. _defguard.company.com_ [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) Firewall settings -------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) Gateway 1. Please open the public port you wish the VPN to be working on - eg. 50555 * Please open on the firewall: local network access **from the Gateway server/VM** → **to Defguard Core gRPC port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) Proxy 1. please open the public 443 port on the server (recommended to rewrite port 80 to redirect to 443) 2. please open gRPC port on the internal network - so that the **Defguard Core can connect to this port - more details here:** [**https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service**arrow-up-right](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) Core 1. please open 443 port for web interface accessible only from local/VPN network 2. please open a gRPC port **for the gateway server to connect to this port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) [PreviousOverviewchevron-left](https://docs.defguard.net/1.4/deployment-strategies/setting-up-your-instance) [NextStandalone package based installationchevron-right](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation) Last updated 5 months ago * [Server & environment requirements](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) * [Operating system and software requirements](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) * [Network IP & DNS setup](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) * [Gateway server - where WireGuard VPN tunnels itself will be launched](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) * [Proxy - public web service for enrollment & desktop client configuration](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) * [Core & database server](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) * [Firewall settings](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) * [Gateway](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) * [Proxy](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) * [Core](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) sun-brightdesktopmoon sun-brightdesktopmoon --- # Deploying to Production | 1.5 | defguard 1 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#gain-knowledge) Gain knowledge Before you start your deployment, take a moment to learn about Defguard. The following articles will help you make deployment decisions and understand which features you may want to configure afterward. Make sure to read them carefully. * [Defguard's features](https://docs.defguard.net/1.5/about/features-overview) * [Defguard's architecture](https://docs.defguard.net/1.5/in-depth/architecture) 2 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#choose-your-deployment-strategy) Choose your deployment strategy Decide which deployment approach best fits your infrastructure and security requirements. Choose from different [deployment strategies](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) and their recommended use cases. 3 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#prepare-your-environment) Prepare your environment Make sure your infrastructure meets all [system and network requirements](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) . 4 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#deploy-using-the-chosen-strategy) Deploy using the chosen strategy Deploy your instance using the chosen [strategy](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) . Make sure to follow the right [deployment sequence](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) . 5 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#test-if-everything-works-as-expected) Test if everything works as expected Follow our [guide](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide) to test if your deployment in secure and works as expected. 6 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#configure-features) Configure features Follow detailed descriptions of [Defguard's features](https://docs.defguard.net/1.5/features/overview) . As you follow along, you can adjust the configuration directly within your instance. For a detailed list of all configurable things through environmental variables, options or configuration files follow [this reference](https://docs.defguard.net/1.5/deployment-strategies/configuration) . 7 ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#your-secure-infrastructure-is-ready-for-use) Your secure infrastructure is ready for use Optional but recommended additional steps: * [Securing internal gRPC communication](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * [Configuring backups](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#backup) * [Setting up for high availability and failover](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover) [PreviousOverviewchevron-left](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance) [NextHardware, OS, network and firewall recommendationschevron-right](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) Last updated 3 months ago * [Gain knowledge](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#gain-knowledge) * [Choose your deployment strategy](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#choose-your-deployment-strategy) * [Prepare your environment](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#prepare-your-environment) * [Deploy using the chosen strategy](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#deploy-using-the-chosen-strategy) * [Test if everything works as expected](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#test-if-everything-works-as-expected) * [Configure features](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#configure-features) * [Your secure infrastructure is ready for use](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production#your-secure-infrastructure-is-ready-for-use) sun-brightdesktopmoon sun-brightdesktopmoon --- # Terraform | 1.4 | defguard circle-info Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later. circle-info We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/issues) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#aws) AWS ------------------------------------------------------------------------------------- To deploy Defguard using Terraform on AWS, you can use the Terraform configuration provided in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main) . The terraform configuration includes the necessary resources to setup all components of Defguard. We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture pagearrow-up-right](https://docs.defguard.net/in-depth/architecture) . When configuring the networking, the most important thing is to keep in mind the following rules: * Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection. * Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. * Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN. * All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#using-the-modules) Using the Modules To use the provided Terraform modules in your terraform configuration, you can use the following source: Copy module "" { source = "github.com/DefGuard/deployment//terraform/modules/?ref=" # Rest of the module configuration goes here # ... } Where: * `` is the name you want to give to the module in your configuration. * `` is one of `core`, `proxy`, or `gateway`, depending on which module you want to use. * `` is the commit hash, tag or branch name of the Defguard deployment repository. You can use the `main` branch for the latest stable version. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#configuring-modules) Configuring modules There are three Defguard modules available for deployment: `core`, `proxy` and `gateway`. The modules can be found in the modules [directoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main/terraform/modules) in the Defguard deployment repository. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#common-configuration-options-for-all-modules) Common configuration options for all modules All components have common configuration options that may be configured in their respective blocks in the `main.tf` file: * `instance_type`: The instance type to use. The default is `t3.micro`. You can adjust this based on your performance needs. * `ami`: The base AMI to use for the Defguard instance. We recommend using the Ubuntu Server 24.04 LTS (64-bit) AMI, which is the default in the example configurations. You may change this to a different AMI if needed. Your AMI must meet the requirements defined in [AMI requirements](https://docs.defguard.net/1.4/deployment-strategies/terraform#ami-requirements) . * `package_version`: The version of the Defguard component package to be installed. This must be an existing Defguard debian package released on the Defguard releases page (e.g. Defguard Core packages are available [herearrow-up-right](https://github.com/DefGuard/defguard/releases) ). Example: `1.4.0`, `1.3.2-alpha2`. * `arch`: The architecture of the Defguard Core package to be installed. This can be set to `x86_64` or `aarch64`. The default is `x86_64`. * `log_level`: The log level to use for the Defguard component. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. The default is `info`. Note that setting the log level to `debug` will produce a lot of logs, which may be useful for debugging, but may also fill up your disk space quickly. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#core-module) Core module The core module is responsible for setting up Defguard Core. It accepts the following variables: * `core_url`: The URL at which Defguard web UI will be accessible. * `grpc_port`: The gRPC port for Defguard Core to communicate with gateways. * `http_port`: The HTTP port on which the Defguard Core web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. * `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments. * `default_admin_password`: The default password for the admin user. This should be changed after the first login. * `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module. * `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](https://docs.defguard.net/1.4/deployment-strategies/terraform#vpn-networks-configuration) section for more details on how to configure the VPN networks. * `db_details`: A map containing the database configuration. It must contain the following: * `name`: The name of the PostgreSQL database to be created for Defguard. * `username`: The username for the PostgreSQL database. * `password`: The password for the PostgreSQL database user. * `port`: The port on which the PostgreSQL database will listen. * `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. * `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#proxy-module) Proxy module The proxy module is responsible for setting up the Defguard Proxy. It accepts the following variables: * `url`: The URL at which Defguard Proxy will be accessible. * `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication. * `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#gateway-module) Gateway module The gateway module is responsible for setting up the Defguard VPN gateways. It accepts the following variables: * `core_grpc_port`: The gRPC port of Defguard Core for the internal communication. This must match the `grpc_port` variable in the core module. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core. * `network_id`: The ID of the VPN network. This must match the `id` field in the `vpn_networks` variable in the core module. * `core_address`: The IP address of the Defguard Core instance. This should be core's private address, as it will be used for internal communication between the gateway and core components. See the `basic` example for the configuration of this variable. * `gateway_secret`: The secret used to authenticate the gateway with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the core module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Gateway instance. This is used to ensure that the gateway instance has a private IP address in the same VPC as the core and proxy components. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#vpn-networks-configuration) VPN networks configuration * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. Each network is defined as a map with the following keys: * `id`: The id of the network. Must start with 1 and increment for each new network. This is used to identify the network in the database and allows for applying modifications to the network configuration later. * `name`: The name of the VPN network. This will be used to identify the network in the Defguard web UI and displayed to the users. * `address`: The internal address of the VPN network in the form of `x.x.x.x/x`. This is the address that will be assigned to the VPN clients when they connect to the VPN. It must be a valid CIDR notation. * `port`: The port on which the VPN gateway will listen for incoming VPN connections. Default is `50051`, which is the standard port for WireGuard VPN. You may change this to a different port if needed. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#ami-requirements) AMI requirements If you wish to use a different AMI for the Defguard components, it must meet the following requirements: * Must allow for running systemd services. * Must use the APT package manager. If you are not meeting these requirements, you will need to modify the corresponding `setup.sh` scripts, which are responsible for installing and configuring the Defguard components. The scripts can be found in `terraform/modules//setup.sh`, where `` is one of `core`, `gateway`, or `proxy`. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#examples) Examples The example configurations can be downloaded from the Defguard deployment repository. They are located in the `terraform/examples` directory: (https://github.com/DefGuard/deployment/tree/main/terraform)\[https://github.com/DefGuard/deployment/tree/main/terraform\] If you wish, you can also clone the whole repository using the following command: And then navigate to the `terraform/examples` directory to find the example configurations. To use any of the examples, you can copy or download the `main.tf.example` file and rename it to `main.tf`. Note that the file contains both the module definitions, variables and outputs. This is to make it easier to download the example. You can also split the file into separate files, such as `main.tf`, `variables.tf`, and `outputs.tf`, if you prefer to keep the configuration more organized. To run the examples, use the following commands: or if using OpenTofu: After running these commands, Terraform will create the necessary resources in your AWS account and deploy Defguard. The output will include the public and private addresses for Core, Proxy and gateway components: Note that running the examples will put some sensitive details into your `.tfstate` file, most notably: the database password, gateway secret and the initial admin password. Those details are not ephemeral in the terraform configuration as they must be passed to the Defguard components during their setup. If you want to secure those details, we recommend following the official guidelines on [how to secure your Terraform state filearrow-up-right](https://developer.hashicorp.com/terraform/language/state/sensitive-data) . #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#basic) `basic` The `basic` example can be directly downloaded using the following link: [basic/main.tf.examplearrow-up-right](https://raw.githubusercontent.com/DefGuard/deployment/refs/heads/main/terraform/examples/basic/main.tf.example) . The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following: * Defguard Core instance * Defguard Proxy instance * Defguard Gateway instance * A database instance (RDS) for Defguard Core. * A single VPC for all components. You can use this example as a starting point for your own deployment. To modify the network configuration, edit one of the sections in the `main.tf` file, such as "Core network configuration", "Gateway network configuration", or "Proxy network configuration". For example, to allow SSH access to Defguard Core instance, you can uncomment the following block in the "Core network configuration" section: Note that this will grant SSH access from any IP address, you may want to restrict it further by editing the `cidr_blocks` field. By default, the configuration allows access to Defguard Core web UI only from connected VPN clients, which is the recommended approach: If you want to run Core web UI behind a reverse proxy (e.g. to enable HTTPS), you would need to do the following: 1. Prevent direct access to the services by removing their ingress rules: 1. Add a second public subnet (load balancers require it): 1. Add the load balancer configuration 1. Add load balancer ingress rules to your existing Proxy and Core groups: 1. Finally, you can add the load balancer domain name to the output: This setup will create two load balancers: one internal and one external. Both will act as a reverse proxy, routing the HTTPS traffic matching your domains to the backend servers (Proxy, Core). The next step would be to point your actual domains to the domain names generated by the load balancers in the output (CNAME) and to setup SSL certificates (e.g. via the AWS certificate manager). ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#troubleshooting-and-common-issues) Troubleshooting and common issues #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#checking-status-of-any-component) Checking status of any component You can check the status of any Defguard component by SSHing into the corresponding EC2 instance and running the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the status of the service. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#checking-logs-of-any-component) Checking logs of any component To display the logs of the service, SSH into the corresponding EC2 instance and run the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the logs of the service. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/terraform#checking-setup-logs) Checking setup logs Before any of the components becomes available, a `setup.sh` script is run, which performs its initial setup (package download, configuration). The logs of this script are stored in `/var/log/defguard.log` on a corresponding EC2 instance. You can check this log file to see if there were any issues during the setup. [PreviousKuberneteschevron-left](https://docs.defguard.net/1.4/deployment-strategies/kubernetes) [NextAMIs and AWS CloudFormationchevron-right](https://docs.defguard.net/1.4/deployment-strategies/amis-and-aws-cloudformation) Last updated 5 months ago * [AWS](https://docs.defguard.net/1.4/deployment-strategies/terraform#aws) * [Using the Modules](https://docs.defguard.net/1.4/deployment-strategies/terraform#using-the-modules) * [Configuring modules](https://docs.defguard.net/1.4/deployment-strategies/terraform#configuring-modules) * [Examples](https://docs.defguard.net/1.4/deployment-strategies/terraform#examples) * [Troubleshooting and common issues](https://docs.defguard.net/1.4/deployment-strategies/terraform#troubleshooting-and-common-issues) sun-brightdesktopmoon Copy git clone https://github.com/DefGuard/deployment.git Copy cd deployment/terraform Copy # To initialize all the modules and providers, run: terraform init # To preview the changes that will be made, run: terraform plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: terraform apply -var="aws_access_key=" -var="aws_secret_key=" Copy # To initialize all the modules and providers, run: tofu init # To preview the changes that will be made, run: tofu plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: tofu apply -var="aws_access_key=" -var="aws_secret_key=" Copy Apply complete! Resources: 35 added, 0 changed, 0 destroyed. Outputs: defguard_core_private_address = "10.0.1.x" defguard_core_public_address = "x.x.x.x" defguard_proxy_private_address = "10.0.1.x" defguard_proxy_public_address = "x.x.x.x" defguard_gateway_private_addresses = [\ "10.0.1.226",\ ] defguard_gateway_public_addresses = [\ "x.x.x.x",\ ] Copy ingress { from_port = 22 to_port = 22 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Core security group block [...] ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } # This is in the Proxy security group block [...] ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy vpc_public_subnets = ["10.0.1.0/24", "10.0.4.0/24"] Copy ########################################################################### ###################### Load Balancer Configuration ####################### ########################################################################### # Load balancer security groups resource "aws_security_group" "defguard_alb_sg" { name = "defguard-alb-sg" description = "Access to the Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] description = "HTTPS access from internet" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-alb-sg" } } resource "aws_security_group" "defguard_internal_alb_sg" { name = "defguard-internal-alb-sg" description = "Access to the Internal Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = [local.vpc_cidr] description = "HTTPS access from internal VPC network" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-internal-alb-sg" } } # Public Application Load Balancer resource "aws_lb" "defguard_public_alb" { name = "defguard-public-alb" internal = false load_balancer_type = "application" security_groups = [aws_security_group.defguard_alb_sg.id] subnets = module.vpc.public_subnets enable_deletion_protection = false tags = { Name = "defguard-public-alb" } } # Internal Application Load Balancer resource "aws_lb" "defguard_internal_alb" { name = "defguard-internal-alb" internal = true load_balancer_type = "application" security_groups = [aws_security_group.defguard_internal_alb_sg.id] subnets = module.vpc.private_subnets enable_deletion_protection = false tags = { Name = "defguard-internal-alb" } } # Target Groups resource "aws_lb_target_group" "defguard_core_tg" { name = "defguard-core-tg" port = local.core_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-core-tg" } } resource "aws_lb_target_group" "defguard_proxy_tg" { name = "defguard-proxy-tg" port = local.proxy_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-proxy-tg" } } # Target Group Attachments resource "aws_lb_target_group_attachment" "defguard_core_attachment" { target_group_arn = aws_lb_target_group.defguard_core_tg.arn target_id = module.defguard_core.instance_id port = local.core_http_port } resource "aws_lb_target_group_attachment" "defguard_proxy_attachment" { target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn target_id = module.defguard_proxy.instance_id port = local.proxy_http_port } # Listeners resource "aws_lb_listener" "defguard_public_alb_listener" { load_balancer_arn = aws_lb.defguard_public_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } } resource "aws_lb_listener" "defguard_internal_alb_listener" { load_balancer_arn = aws_lb.defguard_internal_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } } # Listener Rules resource "aws_lb_listener_rule" "defguard_proxy_rule" { listener_arn = aws_lb_listener.defguard_public_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } condition { host_header { values = [replace(local.proxy_url, "https://", "")] } } } resource "aws_lb_listener_rule" "defguard_core_rule" { listener_arn = aws_lb_listener.defguard_internal_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } condition { host_header { values = [replace(local.core_url, "https://", "")] } } } Copy # HTTP access from internal load balancer (Core) ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_internal_alb_sg.id] description = "HTTP access from internal load balancer" } # HTTP access from public load balancer (Proxy) ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_alb_sg.id] description = "HTTP access from public load balancer" } Copy output "defguard_public_alb_dns" { description = "The DNS name of the Public Application Load Balancer" value = aws_lb.defguard_public_alb.dns_name } output "defguard_internal_alb_dns" { description = "The DNS name of the Internal Application Load Balancer" value = aws_lb.defguard_internal_alb.dns_name } Copy sudo systemctl status Copy sudo journalctl -u sun-brightdesktopmoon --- # Overview | 1.5 | defguard Welcome to the deployment strategies section of Defguard documentation. This guide covers the different ways you can deploy Defguard in your environment, from quick options using packages or Docker to more advanced setups with Kubernetes or Terraform. Whether you're running a small instance or preparing for a more complex production environment, this section will help you choose the deployment method that best fits your needs. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#before-you-begin) Before you begin ------------------------------------------------------------------------------------------------------------------------------ 1. Make sure you understand [Defguard's architecture](https://docs.defguard.net/1.5/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. 2. Make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) Initial deployment sequence ---------------------------------------------------------------------------------------------------------------------------------------------------- Before deploying any Gateways, you must first install and configure the Core service. The Core acts as the central control plane - it manages configuration, authentication, and communication with all connected Gateways. Once the Core is running and accessible, log in to the admin interface and navigate to the Gateways section. Create a new Gateway entry to generate a unique registration token. This token will be used during the Gateway deployment process to securely link the Gateway instance with your Core. After obtaining the token, proceed with deploying the Gateway service. During its initial setup, provide the generated token so that the Gateway can authenticate and register itself with the Core. Once registration is complete, the Gateway will appear in the Core dashboard and start receiving configuration updates automatically. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#long-story-short) Long story short: 1 #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#deploy-defguard-core-service) Deploy Defguard Core service. 2 #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#add-a-new-location-in-cores-web-interface-and-obtain-a-token) Add a new location in Core's web interface and obtain a token. More on that [here](https://docs.defguard.net/1.5/deployment-strategies/gateway) . 3 #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#deploy-gateway-configured-with-the-token) Deploy Gateway configured with the token. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) Choose your deployment strategy ------------------------------------------------------------------------------------------------------------------------------------------------------------ Strategy name Difficulty Production readiness Purpose [One-line script](https://docs.defguard.net/1.5/getting-started/one-line-install) 🟢 Easy, single command installation ❌ Doesn't follow the [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) For testing purposes only [Standalone packages](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation) 🟢 Easy, using apt and dpkg ✅ If you followed the [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Docker Compose](https://docs.defguard.net/1.5/deployment-strategies/docker-compose) 🟡 Medium, Docker knowledge required ✅ If you followed the [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Kubernetes](https://docs.defguard.net/1.5/deployment-strategies/kubernetes) 🔴 Advanced, requires a k8s cluster and administrator ✅ If you followed the [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) Large or enterprise deployments [Terraform](https://docs.defguard.net/1.5/deployment-strategies/terraform) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [AMI and AWS CloudFormation](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#configure-to-your-needs) Configure to your needs -------------------------------------------------------------------------------------------------------------------------------------------- See our [configuration documentation](https://docs.defguard.net/1.5/deployment-strategies/configuration) to learn about all the settings you can change in your deployment. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#backup) Backup ---------------------------------------------------------------------------------------------------------- [Core servicearrow-up-right](https://github.com/DefGuard/defguard) is the only service which uses persistent data storage, which is PostgreSQL database. Every SQL migration is applied automatically while bringing up core server and we try our best not to break anything in the process. It's recommended to do database, configuration and Settings(SMTP, Branding) backup before every update in case of some unexpected failure. Example database backup: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#failover-ha-clustering) Failover/HA/Clustering ------------------------------------------------------------------------------------------------------------------------------------------ The [Gateway](https://docs.defguard.net/1.5/deployment-strategies/gateway) can be deployed on multiple servers, firewalls, or routers for failover and high availability (HA). Even if the connection to the Core is lost, gateways continue operating using their local cache and data, ensuring that the VPN remains functional. Conversely, if a gateway becomes unavailable, other Core features (such as OpenID) will continue to work normally. For details on deploying multiple Gateway to [High Availability and Failover](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover) documentation. [PreviousUser SNAT bindingschevron-left](https://docs.defguard.net/1.5/features/user-snat-bindings) [NextDeploying to Productionchevron-right](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production) Last updated 3 months ago * [Before you begin](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#before-you-begin) * [Initial deployment sequence](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) * [Choose your deployment strategy](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) * [Configure to your needs](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#configure-to-your-needs) * [Backup](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#backup) * [Failover/HA/Clustering](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#failover-ha-clustering) sun-brightdesktopmoon Copy docker exec {container_name} pg_dump -U {user_name} > {backup_file_name} sun-brightdesktopmoon --- # Configuration | 1.4 | defguard Here you can find a list of all configurable things through environmental variables, options or configuration files for all Defguard components (each top-level section for a specific component): * [Core config](https://docs.defguard.net/1.4/deployment-strategies/configuration#core) * [Proxy config](https://docs.defguard.net/1.4/deployment-strategies/configuration#proxy-service) * [Gateway config](https://docs.defguard.net/1.4/deployment-strategies/configuration#gateway-configuration) * [YubiBridge config](https://docs.defguard.net/1.4/deployment-strategies/configuration#yubibridge-configuration) circle-info If you are using [one-line installation](https://docs.defguard.net/1.4/getting-started/one-line-install) , everything is generated and configured automatically. [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#core) Core ------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#secrets-configuration) Secrets configuration Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens. circle-info You can generate random strings for secrets with e.g.: `openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64` * `DEFGUARD_AUTH_SECRET`: JWT secret key for encrypting user tokens, default: `DEFGUARD_AUTH_SECRET` * `DEFGUARD_SECRET_KEY`: JWT secret key for encrypting private cookies; must be at least 64 characters long * `DEFGUARD_GATEWAY_SECRET`: JWT secret key for encrypting Gateway tokens, default: `DEFGUARD_GATEWAY_SECRET` * `DEFGUARD_YUBIBRIDGE_SECRET`: JWT secret key for encrypting YubiBridge tokens, default: `DEFGUARD_YUBIBRIDGE_SECRET` * `DEFGUARD_OPENID_KEY`: this is optional if you want to use [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation, if you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) please provide a path to a private key file used for OAuth2/OpenID, [more herearrow-up-right](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) . ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#general-configuration) General configuration * `DEFGUARD_URL`: URL of your server instance, default `http://localhost:8000. This is the address at which the Web UI you use to administer your instance and the REST API endpoints are available (both of those are served by Defguard core on port 8000 by default; port can be configured with DEFGUARD_HTTP_PORT env variable).`This URL is needed to be exact since it's needed for OpenID discovery endpoint to work correctly, so if you have a reverse-proxy, custom domain, please provide an actual URL for Defguard core. * `DEFGUARD_GATEWAY_DISCONNECTION_NOTIFICATION_TIMEOUT`: If gateway is disconnected for this long, send email notification, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_WEBAUTHN_RP_ID` (optional): Relying party ID and relying party origin for WebAuthn used for MFA. By default, it's generated by using a base domain of `DEFGUARD_URL` (for example https://defguard.example.com is converted to defguard.example.com). circle-exclamation `DEFGUARD_WEBAUTHN_RP_ID`must be an effective domain of DEFGUARD\_URL (for example if hosting at `https://idm.example.com`, rp\_id must be `idm.example.com`, `example.com` or `com`). Changing `DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing Webauthn credentials.` * `DEFGUARD_ADMIN_GROUPNAME`: Name of the administrator group, default: `admin` * `DEFGUARD_USERADMIN_GROUPNAME`: Name of the user administrator group, default: `useradmin` * `DEFGUARD_VPN_GROUPNAME`: Name of the vpn group, default: `vpn` * `DEFGUARD_DEFAULT_ADMIN_PASSWORD`: Password for the default `admin` user, default: `pass123` * `DEFGUARD_LOG_LEVEL`: [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_PORT`: Core server port, default: `8000` * `DEFGUARD_LOG_FILE`: Log file path * `DEFGUARD_AUTH_COOKIE_TIMEOUT`: Cookie lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_MFA_CODE_TIMEOUT`: Email code lifetime period, default: `60s` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_SESSION_TIMEOUT`: Session lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#database-configuration) Database configuration Following env variables can be used to setup your database access: * `DEFGUARD_DB_HOST` * `DEFGUARD_DB_PORT` * `DEFGUARD_DB_NAME` * `DEFGUARD_DB_USER` * `DEFGUARD_DB_PASSWORD` ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#auth-cookies-configuration) Auth cookies configuration circle-exclamation If you want to access your Defguard instance without TLS (using an `http://` URL) you MUST enable insecure cookies by setting `DEFGUARD_COOKIE_INSECURE` to `true`. This is of course not recommended in production but can be useful when testing without a full reverse proxy setup. * `DEFGUARD_COOKIE_INSECURE`: set cookies without the `Secure` flag; use only in dev environments when serving Defguard without HTTPS * `DEFGUARD_COOKIE_DOMAIN` (optional): set the domain for auth cookies. By default, it's the domain from `DEFGUARD_URL`. Must be changed to base URL if you want to use [forward auth](https://docs.defguard.net/1.4/features/forward-auth) . ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#stats-cleanup-configuration) Stats cleanup configuration * `DEFGUARD_DISABLE_STATS_PURGE`: disable periodic cleanup of old Wireguard stats * `DEFGUARD_STATS_PURGE_FREQUENCY`: how often should the cleanup process be performed, default `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_STATS_PURGE_THRESHOLD`: age threshold for stats removal, default `30d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#enrollment-configuration) Enrollment configuration * `DEFGUARD_ENROLLMENT_URL`: external URL of the enrollment proxy server, default `http://localhost:8080` - this URL is sent in enrollment emails as well as displayed when configuring the desktop client - thus must be to the actual URL you have configured the proxy Web UI to be accessible at, otherwise the enrollment or desktop client configuration will not work. * `DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT`: how long is the enrollment token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_ENROLLMENT_SESSION_TIMEOUT`: how long in the enrollment session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#password-reset-configuration) Password reset configuration * `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT`: how long is the password reset token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_PASSWORD_RESET_SESSION_TIMEOUT`: how long in the password reset session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#grpc-server-configuration) gRPC server configuration [More on that in this help page.](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_GRPC_PORT`: the port on which the gRPC server should listen, default is `50055`. This port is used by Defguard Gateways to connect to your Core instance. * `DEFGUARD_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_GRPC_KEY`(optional): path to TLS key file * `DEFGUARD_GRPC_URL`: external URL of your instance's gRPC server, default `http://localhost:50055`; used for generating example VPN gateway startup command in Web UI ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#proxy-connection-configuration) Proxy connection configuration * `DEFGUARD_PROXY_URL` (optional): proxy service gRPC endpoint URL * `DEFGUARD_PROXY_GRPC_CA`(optional): path to TLS root certificate file, required if connecting to proxy gRPC service with a custom CA ([More on that in this help page.](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) ) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#proxy-service) Proxy service ------------------------------------------------------------------------------------------------------------- Here are proxy ENV variables. gRPC configuration is described more [on this help page.](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_HTTP_PORT`: port the proxy API server and Web UI will listen on, default `8080` * `DEFGUARD_PROXY_GRPC_PORT`: port the gRPCS server will listen on, default `50051` * `DEFGUARD_PROXY_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_PROXY_GRPC_KEY`(optional): path to TLS key file. [More on that in this help page.](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_URL` - if you wish to use External OIDC enrollment/desktop client configuration, please set this value to the same as `DEFGUARD_ENROLLMENT_URL` in core. This is the address at which the proxy Web UI is available. * `DEFGUARD_PROXY_LOG_LEVEL` : [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_PROXY_RATELIMIT_PERSECOND` - The (average) number of requests per second made without being eventually rate limited * `DEFGUARD_PROXY_RATELIMIT_BURST` - The number of requests allowed to be made in a short amount of time before being rate limited [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#gateway-configuration) Gateway Configuration ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#environmental-variables-arguments) Environmental variables / Arguments If you're using docker image you can pass this value as environmental variables or on binary you can pass them as arguments * `DEFGUARD_GRPC_URL` , `-g ` - Defguard Core gRPC endpoint URL. This is used by the gateway to connect to your Defguard Core instance. If you configured the `DEFGUARD_GRPC_URL` variable on your Core instance before (as described in the [gRPC server configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#grpc-server-configuration) section), use the same value here. Otherwise, provide an URL that will allow the Gateway to reach your Core instance, e.g. `http://localhost:50055` if both Core and Gateway are running on the same host. * `DEFGUARD_TOKEN` ,`-t ` - Token displayed in the Defguard Core web UI after completing the network wizard. It can be copied from the "Authentication Token" section on the Location Settings page. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2F0KYMfW0khouxvP22Hib5%2Fobraz.png&width=768&dpr=3&quality=100&sign=b0c54944&sv=2) * `DEFGUARD_USERSPACE` , `-u` - Use userspace wireguard implementation, useful on systems without native wireguard support * `DEFGUARD_GRPC_CA - path to ca file` more on this topic can be found [on this help page.](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_STATS_PERIOD` ,`-p ` - Defines how often (seconds) should interface statistics be sent to the Defguard server * `DEFGUARD_GATEWAY_NAME`, `--name ` - (optional) human-readable gateway name that will be displayed in Defguard webapp * `-s, --use-syslog` - enable logging to syslog * `RUST_LOG` : Logger log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_MASQUERADE` - controls whether the gateway automatically applies masquerade NAT firewall rule; defaults to `false` * `DEFGUARD_IFNAME` - The network interface that will be created and used for the VPN traffic * `DEFGUARD_FW_PRIORITY` - The NFT forward chain priority, which handles traffic filtering when ACLs are configured. Defaults to 0. Useful if the Defguard's forward chain conflicts with other chains. * `DEFGUARD_DISABLE_FW_MGMT` - disables all firewall management by the gateway; this overrides `DEFGUARD_MASQUERADE` setting; defaults to `false` circle-info `DEFGUARD_DISABLE_FW_MGMT` is meant as a workaround for running in incompatible environments, where our [default firewall integration](https://docs.defguard.net/1.4/features/access-control-list/firewall-internals) is not supported. As a consequence, enabling this option disables [ACL functionality](https://docs.defguard.net/1.4/features/access-control-list) on a given gateway. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#executing-custom-commands-on-vpn-up-down) Executing custom commands on VPN up/down The following env variables or gateway arguments define which commands gateway will run before / after it will bring up / down the VPN. It's usefull for example to use those commands to launch custom firewall commands or scripts that do various operations needed to be done on those occasions. triangle-exclamation Defguard is built with highest security standards in mind, thus the options below **accept only a full path to one command and it's arguments.** If you would like to have **multiple commands run,** you can create a shell script which will define the acceptable and preferred shell you would like to use and then all the commands you like to execute. `PRE_UP` , `--pre-up`, - Command to run before bringing up the interface. If you want to run a shell script, you should pass its path to your shell, for example: `/bin/sh -c /path/to/script` `POST_UP` , `--post-up`, - Command to run after bringing up the interface. `PRE_DOWN` , `--pre-down`, - Command to run before bringing down the interface. `POST_DOWN` , `--post-down`, - Command to run after bringing down the interface. circle-info If logging to syslog please remember to configure your syslog daemon accordingly, so that a dedicated logfile is created or the messages are included in the main system log. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#config-file) Config file Gateway configuration can also be read from a file by using a `--config` CLI option. Example file contents: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#yubibridge-configuration) YubiBridge configuration ----------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#environmental-variables) Environmental variables * `LOG_LEVEL`: Log messages level, default: `INFO`, available levels: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` * `WORKER_ID`: Name of your YubiBridge displayed on Defguard website, default: `YubiBridge` * `DEFGUARD_TOKEN`: - Secret worker token to secure gRPC communication, available on provisioners page * `SMARTCARD_RETRIES`: Number of retries in case provisioning failed, default: `1` * `JOB_INTERVAL`: Defines how often(seconds) YubiBridge checks Defguard for new jobs, default: `2` * `SMARTCARD_RETRY_INTERVAL`: Defines the number of seconds between trying to provision YubiKey again, default `15` ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/configuration#cli-arguments) CLI arguments: * `-h` , `--help`: Display help message * `-g `, `--grpc `: Connect to gRPC server at the given URL * `-i ` , `--id `: WorkerID, default `YubiBridge` * `-d` , `--debug`: Enable debug mode * `-t ` , `--tmpdir `: GnuPG home directory, default: `tmp` * `-p ` , `--provision `: Provision YubiKey with the following data * `-w ` , `--worker-token `: Secret worker token to secure gRPC communication, available on provisioners page * `-c ` , `--command `: Run command after provisioning and pass created keys as arguments [PreviousHealth checkchevron-left](https://docs.defguard.net/1.4/deployment-strategies/health-check) [NextLicensechevron-right](https://docs.defguard.net/1.4/enterprise/license) Last updated 6 months ago * [Core](https://docs.defguard.net/1.4/deployment-strategies/configuration#core) * [Secrets configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#secrets-configuration) * [General configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#general-configuration) * [Database configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#database-configuration) * [Auth cookies configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#auth-cookies-configuration) * [Stats cleanup configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#stats-cleanup-configuration) * [Enrollment configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#enrollment-configuration) * [Password reset configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#password-reset-configuration) * [gRPC server configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#grpc-server-configuration) * [Proxy connection configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#proxy-connection-configuration) * [Proxy service](https://docs.defguard.net/1.4/deployment-strategies/configuration#proxy-service) * [Gateway Configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#gateway-configuration) * [Environmental variables / Arguments](https://docs.defguard.net/1.4/deployment-strategies/configuration#environmental-variables-arguments) * [Config file](https://docs.defguard.net/1.4/deployment-strategies/configuration#config-file) * [YubiBridge configuration](https://docs.defguard.net/1.4/deployment-strategies/configuration#yubibridge-configuration) * [Environmental variables](https://docs.defguard.net/1.4/deployment-strategies/configuration#environmental-variables) * [CLI arguments:](https://docs.defguard.net/1.4/deployment-strategies/configuration#cli-arguments) sun-brightdesktopmoon Copy # 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 = "" # Required: Defguard server gRPC endpoint URL # NOTE: must replace default with actual value grpc_url = "" # Optional: gateway name which will be displayed in Defguard web UI name = "Gateway on server X" # Required: use userspace Wireguard implementation (e.g. wireguard-go) userspace = false # Optional: path to TLS cert file - more in gRPC SSL communication help page # in our documentation. # 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 #pre_up = "/path/to/script.sh" # Optional: Command which will be run after bringing interface up #post_up = "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 = "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 = "ip route del default via 192.168.1.1 dev wg0" sun-brightdesktopmoon --- # Health check | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#core-and-proxy) Core & Proxy ------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#rest-api) Rest API [Corearrow-up-right](https://github.com/defguard/defguard) and [Proxyarrow-up-right](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application server is running. Example request: Copy curl "https://defguard.example.com/api/v1/health" Example response: Copy alive ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#grpc-status-health) gRPC status health #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#proxy-available-from-v0.6.0) Proxy (available from v0.6.0) To verify gRPC services for **Proxy** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. Example request: Copy curl "https://enroll.example.com/api/v1/health-grpc" Possible responses: Copy 200 - Proxy is working and is connected to CORE 503 - Proxy works but is not connected to CORE #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#core-available-from-v1.0.0) Core (available from v1.0.0) To check if core gRCP service is alive, we recommend to use community tools like [grpc\_health\_probearrow-up-right](https://github.com/grpc-ecosystem/grpc-health-probe) . Example request for core: Example response for core: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/health-check#gateway) Gateway ------------------------------------------------------------------------------------------------ You can enable in gateway config ([example configarrow-up-right](https://github.com/DefGuard/gateway/blob/main/example-config.toml) ) a health check port, by adding the following line: In this example, gateway will open an additional HTTP port number 55003 and will return the following HTTP status codes: By default no healthcheck ports are open. [PreviousOpenID RSA keychevron-left](https://docs.defguard.net/1.4/deployment-strategies/openid-rsa-key) [NextConfigurationchevron-right](https://docs.defguard.net/1.4/deployment-strategies/configuration) * [Core & Proxy](https://docs.defguard.net/1.4/deployment-strategies/health-check#core-and-proxy) * [Rest API](https://docs.defguard.net/1.4/deployment-strategies/health-check#rest-api) * [gRPC status health](https://docs.defguard.net/1.4/deployment-strategies/health-check#grpc-status-health) * [Gateway](https://docs.defguard.net/1.4/deployment-strategies/health-check#gateway) sun-brightdesktopmoon Copy ./grpc_health_probe -addr=defguard.example.com:50055 Copy status: SERVING Copy health_port = 55003 Copy 200 - Gateway is working and is connected to CORE Copy 503 - gateway works but is not connected to CORE sun-brightdesktopmoon --- # Kubernetes | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------- To deploy and use Defguard on your cluster, you'll need: * A [Kubernetes clusterarrow-up-right](https://kubernetes.io/docs/setup/) * Kubernetes CLI [kubectlarrow-up-right](https://kubernetes.io/docs/reference/kubectl/) installed on your machine * Helm binary https://github.com/helm/helm/releases/latest circle-exclamation Our helm charts currently support only **Traefik ingress - which is relevant and affects exposing GRPC services (see below** `ingress.hosts.grpc``**).**` [hashtag](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#deployment) Deployment ---------------------------------------------------------------------------------------------------- We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with Kubernetes configuration, clone it with: Copy git clone https://github.com/DefGuard/deployment.git && cd deployment/charts Then create a namespace for Defguard on your cluster: Copy kubectl create namespace defguard Copy and fill in values file: Copy cp defguard/values.yaml ./ Required values (the rest should work if left as-is): * `ingress.hosts.grpc`: GRPC ingress address - GRPC clients like Defguard **gateway**, yubi-bridge circle-exclamation If you are configuring your gateway or yubi-bridge - please use this GRPC URL for communication. If you have other ingress controller than traefik - you need to configure GRPC ingress manually with corresponding to your setup. * `ingress.hosts.web`: Web ingress address - Defguard web app will be available here. * `publicUrl`: Public URL your Defguard will be available under. Usually the same as ingress.hosts.web, but differs depending on your load balancer and/or reverse-proxy setup. And finally, install the Helm chart in the namespace: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#proxy-service) Proxy service If you want to deploy the enrollment service along with your Defguard instance, you also need to configure values related to the `defguard-proxy`subchart: * `defguard-proxy.enabled`: enable the enrollment service * `proxyUrl`: proxy gRPC endpoint URL (based on `defguard-proxy.ingress.grpc.host`) * `defguard-proxy.publicUrl`: public URL of the enrollment service * `defguard-proxy.ingress.web.host`: enrollment service web ingress address (the enrollment website) * `defguard-proxy.ingress.grpc.host`: enrollment service gRPC ingress address (for communicating with core) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#vpn-gateway-service) VPN gateway service If you want to deploy the VPN gateway service along with your Defguard instance, you need to do it in two steps: * first deploy the core service and use the web UI to [setup a VPN location](https://docs.defguard.net/1.5/tutorials/step-by-step-setting-up-a-vpn-server/adding-additional-vpn-locations) * copy the gateway token and proceed to deploying the gateway itself To deploy the gateway service, configure values related to the `defguard-gateway`subchart: * `defguard-gateway.enabled`: enable the VPN gateway service * `defguard-gateway.token`: the gateway token generated in Web UI * `defguard-gateway.grpcUrl`: URL where the core gRPC server is available (based on `defguard.ingress.grpc.host`) [PreviousDocker Composechevron-left](https://docs.defguard.net/1.5/deployment-strategies/docker-compose) [NextTerraformchevron-right](https://docs.defguard.net/1.5/deployment-strategies/terraform) Last updated 4 months ago * [Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#prerequisites) * [Deployment](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#deployment) * [Proxy service](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#proxy-service) * [VPN gateway service](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#vpn-gateway-service) sun-brightdesktopmoon Copy helm install --wait=true --namespace defguard defguard defguard -f values.yaml sun-brightdesktopmoon --- # Defguard APT repository | 1.5 | defguard ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) Distribution Defguard APT repository provides packages for **Debian 12**, **Debian 13**, and **Ubuntu 22.04/24.04 LTS.** Packages are available on the default `trixie` repository distribution. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) Adding Defguard APT repository To add Defguard APT repository, run following commands in your terminal: Copy sudo apt update sudo apt install -y ca-certificates curl #Add official Defguard public GPG key sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://apt.defguard.net/defguard.asc -o /etc/apt/keyrings/defguard.asc sudo chmod a+r /etc/apt/keyrings/defguard.asc #Add APT repository echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Afterward running these commands, you can install and update Defguard via APT. After new release, simply use `sudo apt update` to update repository. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) Using pre-release builds Defguard has two separate components on one APT repository, **release** and **pre-release.** If you want to install packages from pre-release, simply change `release` to `pre-release` in the installation steps described above, or run the following line. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#choosing-distribution) Choosing distribution Most of our packages are located on `trixie` distribution. However, if you are using **Ubuntu 22.04/Debian 12** and want to install **Defguard Client**, you should be using `bookworm` distribution. To do so, replace `trixie` with `bookworm` in installation steps, or run the following command. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) Installing packages Defguard Core: Defguard Proxy: Defguard Gateway: Defguard Client: [PreviousStandalone package based installationchevron-left](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation) [NextDocker Composechevron-right](https://docs.defguard.net/1.5/deployment-strategies/docker-compose) Last updated 3 months ago * [Distribution](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) * [Adding Defguard APT repository](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) * [Using pre-release builds](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) * [Choosing distribution](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#choosing-distribution) * [Installing packages](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) sun-brightdesktopmoon Copy echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie pre-release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Copy echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ bookworm release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Copy sudo apt install defguard Copy sudo apt install defguard-proxy Copy sudo apt install defguard-gateway Copy sudo apt install defguard-client sun-brightdesktopmoon --- # Configuring HTTPS using AWS Certificate Manager | 1.5 | defguard This guide explains how to secure your Defguard deployment with HTTPS by using a public TLS certificate issued by AWS Certificate Manager (ACM). You will request a certificate for the domains used by Defguard Core and Defguard Proxy, validate domain ownership via DNS, and attach the certificate to your CloudFormation stack using its ARN. Once completed, AWS will automatically manage certificate provisioning and renewal, ensuring your Defguard instance is encrypted and trusted without manual certificate handling. Go to AWS console and open the Certificate Manager service page. Request a new certificate (if you don't have one already). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FJNecylJNJEx3RDGWCUGn%252Fimage.png%3Falt%3Dmedia%26token%3D418b78b4-6e45-468c-a5f3-3f9db4f1a7fd&width=768&dpr=3&quality=100&sign=ab7819e&sv=2) A public certificate is enough. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F344qQtdM1aZI9Ek3unzq%252Fimage.png%3Falt%3Dmedia%26token%3D6a21703a-1105-4067-85ae-3839b8ee61cc&width=768&dpr=3&quality=100&sign=9b059a08&sv=2) Specify the domains you will want to use for your Defguard instance (for accessing Defguard Proxy and Defguard Core). Those domains should be the same as those you'll use in `ProxyUrl` and `CoreUrl`. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F0xngEU0Yka5CRdsxJyaL%252Fimage.png%3Falt%3Dmedia%26token%3D720b3b2c-d349-4311-8aca-c2393a0fb9d8&width=768&dpr=3&quality=100&sign=5031f135&sv=2) Next, you will need to validate your domain ownership by adding appropriate CNAME records in your DNS provider. Use the _CNAME name_ and _CNAME value_ values provided in the AWS console and set them in you domain's DNS. After you complete this step, your certificate can be used. Copy the ARN of your certificate and paste it into the `SSLCertificateArn` parameter in the CloudFormation template. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F8aWpQG6bLGZZ8sSs1f7d%252Fimage.png%3Falt%3Dmedia%26token%3D8ec5d114-7e43-49a3-874a-b90be65ccf59&width=768&dpr=3&quality=100&sign=794d0015&sv=2) [PreviousAmazon Machine Image (AMI)chevron-left](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation) [NextAdding a location and getting a Gateway tokenchevron-right](https://docs.defguard.net/1.5/deployment-strategies/gateway) Last updated 2 months ago sun-brightdesktopmoon sun-brightdesktopmoon --- # OpenID RSA key | 1.4 | defguard By default, Defguard uses [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation and the. If you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) , you'll have to configure the Defguard core `DEFGUARD_OPENID_KEY` configuration variable with the path to the RSA private key. You can generate the RSA key with: Copy openssl genpkey -out /path/to/rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096 [PreviousSecuring gRPC communicationchevron-left](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) [NextHealth checkchevron-right](https://docs.defguard.net/1.4/deployment-strategies/health-check) sun-brightdesktopmoon sun-brightdesktopmoon --- # Docker Compose | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#introduction) Introduction ------------------------------------------------------------------------------------------------------------ This document provides a complete example of how to deploy Defguard using Docker Compose, including configuration for all components - Core, Proxy, and Gateway. It covers Docker image tags, environment variables, and reverse-proxy setup examples to help you quickly launch a fully functional Defguard environment. We recommend deploying each Defguard service on a dedicated server or virtual machine to ensure better isolation, performance, and security. In this setup, each Docker Compose file should be used for a single service, keeping the Core, Proxy, and Gateway components physically separated. circle-info Please note that we also offer docker-compose deployment with [_one-line quick deployment_](https://docs.defguard.net/1.5/getting-started/one-line-install) _,_ but this method is recommended for PoC/quick deployment as **it launches everything on one server and all services in one docker compose**. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#docker-images-and-tags) Docker images and tags -------------------------------------------------------------------------------------------------------------------------------- We use `latest` (latest production images) tags in the examples below, but you can use others. All docker images for Core, Gateway, and Proxy have these additional tags: * `latest` - the latest stable production release. * `vX.Y`, `vX.Y.Z`, `vX.Y-alpha1` - fixed tags for specific stable and alpha releases. * `pre-release`\- the latest pre-production release (equivalent to vX.Y-alpha1). * `dev` - the latest development build from the dev branch (experimental). circle-exclamation We recommend always using fixed, stable tags (`vX.Y`, `vX.Y.Z`) for your production deployment. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) Example Docker Compose deployment repository ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with and example Docker Compose configuration. To run your services using this example prepare your .env file by copying the template: Finally, run the service with Docker Compose: Below you'll find a detailed breakdown of configuration for different components: Core, Proxy and Gateway. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) Deploying Core, database and reverse proxy services ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the core and database. Configuration is split to the `.env` file (see below): #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#nginx-reverse-proxy) NGINX reverse-proxy Now that you have core running, here is an example NGINX configuration to provide SSL termination: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#the-configuration) The configuration Here is the `.env` file with all configuration variables: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) Deploying Proxy and reverse proxy service ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the public proxy (enrollment service as well as desktop client configuration service). To secure the gRPC communication, please generate the proxy CA and certificate, [more info here](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#nginx-reverse-proxy-1) NGINX reverse-proxy Now that you have proxy running, here is an example NGINX configuration to provide SSL termination: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-gateway-service) Deploying Gateway service -------------------------------------------------------------------------------------------------------------------------------------- Before deploying a new Gateway service, make sure you have a running Defguard Core instance. On the network level, your Gateway must be able to reach the Core service’s gRPC endpoint. This address is passed as the `DEFGUARD_GRPC_URL` parameter when deploying the Gateway. The Gateway uses it to communicate with Core, fetch its configuration, and publish operational statistics. You’ll also need a Location created in the Defguard Core Admin Panel. Each Location is identified by a unique token, which must be provided to the Gateway as the `DEFGUARD_TOKEN` parameter. The Gateway uses this token to authenticate with Core over the gRPC channel and retrieve the correct configuration for that specific Location. For detailed steps on how to create a Location and obtain its token, see [this section](https://docs.defguard.net/1.5/deployment-strategies/gateway) . For the most basic configuration use the following Docker Compose file: circle-info The Docker Compose configuration runs the Gateway in host network mode and includes the required Docker capabilities. This setup is necessary because the Gateway needs direct access to the host network stack and WireGuard kernel module to create and manage VPN interfaces properly. [PreviousDefguard APT repositorychevron-left](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) [NextKuberneteschevron-right](https://docs.defguard.net/1.5/deployment-strategies/kubernetes) Last updated 3 months ago * [Introduction](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#introduction) * [Docker images and tags](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#docker-images-and-tags) * [Example Docker Compose deployment repository](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) * [Deploying Core, database and reverse proxy services](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) * [Deploying Proxy and reverse proxy service](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) * [Deploying Gateway service](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-gateway-service) sun-brightdesktopmoon Copy cp .env.template .env Copy docker compose up Copy services: core: image: ghcr.io/defguard/defguard:latest restart: always container_name: "defguard" env_file: .env ports: # HTTP port - open on localhost, should be secured by reverse-proxy - "127.0.0.1:8000:8000" # gRPC port for gateway to connect to # open on all interfaces/IPs - whould be secured with custom CA (see .env) - "50055:50055" depends_on: - db volumes: # more info here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key - ./rsakey.pem:/keys/rsakey.pem # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/keys/ca.pem db: image: postgres:17-alpine container_name: "defguard-db" env_file: .env volumes: - db:/var/lib/postgresql/data Copy upstream defguard { server 127.0.0.1:8000; } server { listen 443 ssl http2; # your domain server_name defguard.secure-internal.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.error.log; ssl on; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/secure-internal.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/secure-internal.net/privkey.pem; client_max_body_size 20m; location / { proxy_connect_timeout 300; proxy_pass http://defguard; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; } } Copy # please generate each secret with: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-63 DEFGUARD_SECRET_KEY= DEFGUARD_AUTH_SECRET= DEFGUARD_GATEWAY_SECRET= DEFGUARD_YUBIBRIDGE_SECRET= # if you plan to reverse-proxy defguard, please provide a full URL # this URL will be shared in emails, enrollement messages, etc.: DEFGUARD_URL=https://defguard.secure-internal.net # Must be an effective domain of DEFGUARD_URL # Changing DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing # Webauthn credentials. DEFGUARD_WEBAUTHN_RP_ID=defguard.secure-internal.net # accepted: info/debug/warning/error DEFGUARD_LOG_LEVEL=info # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates DEFGUARD_PROXY_GRPC_CA=/keys/ca.pem # gRPC URL of proxy (see proxy config) DEFGUARD_PROXY_URL=https://proxy.host:50051 # more details about RSA key here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key DEFGUARD_OPENID_KEY=rsakey.pem # the URL of your proxy - will be displayed during enrollment, email # messages or desktop client configuration DEFGUARD_ENROLLMENT_URL=https://enrollment.public.net # PostgreSQL database configuration for core DEFGUARD_DB_HOST=db DEFGUARD_DB_PORT=5432 DEFGUARD_DB_USER=defguard # please generate password: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-63 DEFGUARD_DB_PASSWORD= DEFGUARD_DB_NAME=defguard # database configuration for "db" container # must be same as above # database will be initialized with these values (the user/pass set here) POSTGRES_DB=defguard POSTGRES_USER=defguard POSTGRES_PASSWORD=!SAME_AS-GENERATED-DEFGUARD_DB_PASSWORD! Copy proxy: image: ghcr.io/defguard/defguard-proxy:latest restart: unless-stopped ports: # HTTP port - should be secured by reverse proxy - "127.0.0.1:8080:8080" - "50051:50051" environment: # path in the volume to custom proxy cert & key - DEFGUARD_PROXY_GRPC_CERT=ca/proxy.crt - DEFGUARD_PROXY_GRPC_KEY=ca/proxy.key volumes: - ./ca/proxy.crt:ca/proxy.crt - ./ca/proxy.key:ca/proxy.key Copy upstream defguard-proxy { server 127.0.0.1:8080; } server { listen 443 http2; server_name enrollment.public.net; access_log /var/log/nginx/defguard-proxy.log; error_log /var/log/nginx/defguard-proxy.error.log; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/public.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/public.net/privkey.pem; client_max_body_size 20m; location / { proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } Copy services: gateway: image: ghcr.io/defguard/gateway:latest restart: unless-stopped network_mode: "host" environment: - DEFGUARD_GRPC_URL=https://core-ip:50055 - DEFGUARD_TOKEN=tokenFromCoreLocation cap_add: - NET_ADMIN sun-brightdesktopmoon --- # Running gateway on MikroTik routers | 1.4 | defguard By leveraging the ability of some MikroTik routers to run Docker containers, it is possible to deploy the gateway directly on your router. circle-exclamation Proceed with extra caution when working with your core infrastructure. All official [RouterOS containers warningsarrow-up-right](https://help.mikrotik.com/docs/display/ROS/Container#Container-Disclaimer) still apply. triangle-exclamation Running the gateway on a MikroTik router is not fully supported. Due to custom RouterOS kernel incompatibility this kind of deployment does not support [Access Control List](https://docs.defguard.net/1.4/features/access-control-list) functionality. To run the gateway you must explicitly disable firewall management using the [`DEFGUARD_DISABLE_FW_MGMT` option](https://docs.defguard.net/1.4/deployment-strategies/configuration#gateway-configuration) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------------------------------------- * RouterOS device with ARM or ARM64 architecture (popular home lab choices include RB4011 or RB5009) * `Container` package installed and enabled * Running Defguard core instance with a WireGuard location configured * (optional) Self-signed certificate generated by following [gRPC SSL setup guide](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#setup) Setup --------------------------------------------------------------------------------------------------------------------------- circle-exclamation This guide assumes you do not have other Docker containers deployed on your router yet. If this is not the case adjust accordingly. The same applies if you have some more specific network configuration requirements. circle-info For brevity we'll be using RouterOS terminal commands, but everything can also be accomplished through WinBox GUI. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) Prepare network to install Docker container * First create a bridge interface for Docker containers and assign it an IP address in a dedicated Docker subnet (`172.17.0.0/24` in our example): * Each container must have a dedicated VETH interface; create a `veth1` interface and assign it an IP address in the chosen Docker subnet: * Add the virtual interface to the Docker bridge: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#setup-firewall-rules) Setup firewall rules * Set up NAT for outgoing traffic from containers: * Add port forwarding rule to send UDP traffic from the public WireGuard port to the gateway container: circle-exclamation Container port being forwarded to must match your public WireGuard port. * Add routing for your chosen WireGuard subnet configured in Defguard UI location settings: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#run-gateway-container) Run gateway container * Configure environment variables for the gateway container: * (optional) To use SSL for communication between the gateway and your Defguard instance copy the root certificate to your router's filesystem and add a following mount and environment variable: circle-exclamation Put the root certificate in a directory and mount the whole directory. Trying to mount a specific file can cause unexpected issues. * Add GitHub container registry to config: * Finally, create the actual container: At this point you should see that the gateway is connected in your Defguard instance's web UI. [PreviousGatewaychevron-left](https://docs.defguard.net/1.4/deployment-strategies/gateway) [NextSecuring gRPC communicationchevron-right](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication) * [Prerequisites](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#prerequisites) * [Setup](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#setup) * [Prepare network to install Docker container](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) * [Setup firewall rules](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#setup-firewall-rules) * [Run gateway container](https://docs.defguard.net/1.4/deployment-strategies/gateway/running-gateway-on-mikrotik-routers#run-gateway-container) sun-brightdesktopmoon Copy /interface/bridge/add name=docker /ip/address/add address=172.17.0.1/24 interface=docker Copy /interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1 Copy /interface/bridge/port add bridge=docker interface=veth1 Copy /ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24 Copy /ip/firewall/nat/add chain=dstnat protocol=udp dst-address= dst-port= action=dst-nat to-addresses=172.17.0.2 to-ports= Copy /ip/route/add dst-address= gateway=172.17.0.2 Copy /container/envs/add name=defguard_env key=DEFGUARD_TOKEN value= /container/envs/add name=defguard_env key=DEFGUARD_GRPC_URL value= /container/envs/add name=defguard_env key=DEFGUARD_DISABLE_FW_MGMT value=true Copy /container/mounts/add name=defguard_cert src= dst=/certs /container/envs/add name=defguard_env key=DEFGUARD_GRPC_CA value=/certs/myCA.pem Copy /container/config/set registry-url=https://ghcr.io Copy /container/add remote-image=ghcr.io/defguard/gateway:latest interface=veth1 envlist=defguard_env sun-brightdesktopmoon --- # Standalone package based installation | 1.4 | defguard [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#introduction) Introduction ----------------------------------------------------------------------------------------------------------------------------------- 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**. circle-exclamation 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 12**arrow-up-right](https://www.debian.org/releases/stable/releasenotes) **and Ubuntu based system.** circle-info 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.arrow-up-right](https://phoenixnap.com/kb/how-to-install-rpm-file-centos-linux) Please also remember to [secure the setup after installation](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#securing-the-setup) . ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#hardware-requirements) Hardware Requirements All Defguard components are **very low resource-consuming**. All of them are written in [Rustarrow-up-right](https://www.rust-lang.org/) and are single binaries. As minimum setup as follows should be more then enough: Resource Minimum requirements CPU 1 GHz RAM 2 GB (mostly for PostgreSQL) Disk 2 GB Architecture x86\_64, ARM64 ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#system-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). * Defguard [enrollment servicearrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) (run by proxy) that will enable [remote onboarding, enrollmentarrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) and [easy configuration for our Desktop Clients (by adding Defguard instances)](https://docs.defguard.net/1.4/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#prerequisites) Prerequisites #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#postgresql) PostgreSQL Defguard Core uses [PostgreSQLarrow-up-right](https://www.postgresql.org/) 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 `::::` * we connected into the `defguard` database to verify `defguard` user can communicate with the database #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#nginx) 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. To get started, we need to install: Enable nginx service Disable all default domains: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#installing-packages) Installing packages ------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#core-service) Core service Navigate to [core repository releasearrow-up-right](https://github.com/DefGuard/defguard/releases) and choose version of core package that you want to obtain that has debian package and then swap `` in the following command: Example: 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: Example: You can check is core installed properly: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#gateway-service) Gateway service Navigate to [gateway repository releasearrow-up-right](https://github.com/DefGuard/gateway/releases) and choose version of core package that you want to obtain that has debian package and then swap `` in the following command: Example: 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: Example: You can check is core installed properly: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#proxy-service) Proxy service Navigate to [proxy repository releasearrow-up-right](https://github.com/DefGuard/proxy/releases) and choose version of core package that you want to obtain that has debian package and then swap `` in the following command: Example: 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: Example: You can check is core installed properly: [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#running-defguard) Running Defguard ------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#generating-ssl-certificates-with-letsencrypt) Generating SSL Certificates with Let'sEncrypt 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_: Certbot will generate certificate in fullchain.pem and privkey.pem in path: `/etc/letsencrypt/live/my-server.defguard.net` `/etc/letsencrypt/live/enrolldefguard.net` ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#core-the-control-plain) Core - the control plain To run core service we need to configure `/etc/defguard/core.conf`. circle-info 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**](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#postgresql) **, 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**](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#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: #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#configuring-nginx-reverse-proxy-with-ssl) Configuring NGINX reverse proxy with SSL Now, we are able to create our first nginx config for Defguard core service with _my-server.defguard.net_. Create config file `/etc/nginx/site-available/my-server.defguard.net.conf`, example config file for _my-server.defguard.ent_ should look like this: Link it to `/etc/nginx/site-available/` Restart nginx.service to activate changes: Test your domain on another terminal tab Success! We can move on to the next service. triangle-exclamation If you use this simple setup and run all services on one server, you can use [NGINX access restrictionsarrow-up-right](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-tcp/) for securing core and allowing to access the _my-server.defguard.net_ only to selected networks - blocking the direct access from the Internet. ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#gateway-the-wireguard-vpn-service) 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`. #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#setup-location-for-gateway) 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 these credentials from `/etc/defguard/core.conf` * login: admin * password: `DEFGUARD_DEFAULT_ADMIN_PASSWORD` (by default: pass123) Now we can configure our first location. Depends on what is more convenient for you, choose configuration from Wireguard file or do it manually. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FO2bfNO7VOPNiySbJHzry%2Fchoose_location_setup.png&width=768&dpr=3&quality=100&sign=9c3e4bfa&sv=2) Location wizard ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FN8HJLHjjGZRFZSANpnYL%2Flocation_configuration.png&width=768&dpr=3&quality=100&sign=1478f179&sv=2) Location configuration 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. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FscaAsb2qlA2qoGG29dvd%2Fedit_locations_settings.png&width=768&dpr=3&quality=100&sign=e4bc7858&sv=2) Manual configuration In `Gateway server setup` copy two variables: `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqA26Hk2bOkuJXJg4scJ4%2Fblobs%2FjN6852awzPjMXrDZHDAD%2Fgateway_server_setup.png&width=768&dpr=3&quality=100&sign=6eb34c30&sv=2) Gateway server setup #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#create-config-file) Create config file After getting `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` variables, we can configure our gateway service. Create config.toml file and swap `` and `` with your values that you copied. Template for configure gateway service looks like below: Now we can run gateway service with configuration above: On the other side, core service should print those informations: ### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#proxy-enrollment-onboardin-and-desktop-configuration-service) Proxy - enrollment, onboardin and desktop configuration service To run proxy service (for [remote onboarding & enrollment](https://docs.defguard.net/1.4/using-defguard-for-end-users/enrollment) ), we can do it by: #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#configuring-nginx-reverse-proxy-for-enrollment) Configuring NGiNX reverse proxy for enrollment circle-info Please note that [we already have issued the enrollemnt domain SSL certificate](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#generating-ssl-certificates) . Create config file `/etc/nginx/sites-available/enroll.defguard.net.conf`, example config file for _enroll.defguard.net_ should look like this: Enable configuration and restart nginx: #### [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) Enabling Proxy service in the Core Now, we can update our **core configuration** in `/etc/defguard/core.conf` by uncommenting `DEFGUARD_PROXY_URL` Full `/etc/defguard/core.conf`: Reload changes in `/etc/defguarc/core.conf` circle-check Now you have full working Defguard services 🥳 You can [configure your desktop client using the enrollment](https://docs.defguard.net/1.4/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 itarrow-up-right](https://defguard.gitbook.io/defguard/tutorials/step-by-step-setting-up-a-vpn-server#enabling-to-access-internet-through-your-vpn) . [hashtag](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#securing-the-setup) 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) triangle-exclamation **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](https://docs.defguard.net/1.4/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . [PreviousHardware, OS, network and firewall recommendationschevron-left](https://docs.defguard.net/1.4/deployment-strategies/hardware-os-network-and-firewall-recommendations) [NextDocker images and tagschevron-right](https://docs.defguard.net/1.4/deployment-strategies/docker-images-and-tags) * [Introduction](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#introduction) * [Hardware Requirements](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#hardware-requirements) * [System Requirements](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#system-requirements) * [Prerequisites](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#prerequisites) * [Installing packages](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#installing-packages) * [Core service](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#core-service) * [Gateway service](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#gateway-service) * [Proxy service](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#proxy-service) * [Running Defguard](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#running-defguard) * [Generating SSL Certificates with Let'sEncrypt](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#generating-ssl-certificates-with-letsencrypt) * [Core - the control plain](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#core-the-control-plain) * [Gateway - the WireGuard VPN service](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#gateway-the-wireguard-vpn-service) * [Proxy - enrollment, onboardin and desktop configuration service](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#proxy-enrollment-onboardin-and-desktop-configuration-service) * [Securing the setup](https://docs.defguard.net/1.4/deployment-strategies/standalone-package-based-installation#securing-the-setup) sun-brightdesktopmoon Copy apt install postgresql Copy # su -c /usr/bin/psql postgres postgres=# CREATE USER defguard WITH SUPERUSER PASSWORD 'defguard'; postgres=# CREATE DATABASE defguard; Copy # echo 'localhost:5432:defguard:defguard:defguard' >> ~/.pgpass # chmod 600 ~/.pgpass # psql -d defguard -h localhost -U defguard defguard=# exit Copy apt install nginx certbot Copy systemctl enable nginx.service systemctl start nginx.service Copy unlink /etc/nginx/sites-enabled/default Copy wget https://github.com/DefGuard/defguard/releases/download//defguard--x86_64-unknown-linux-gnu.deb Copy wget https://github.com/DefGuard/defguard/releases/download/v0.11.0/defguard-0.11.0-x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard--x86_64-unknown-linux-gnu.deb Copy dpkg -i defguard-0.11.0-x86_64-unknown-linux-gnu.deb Copy # defguard -V defguard 0.11.0 Copy # wget https://github.com/DefGuard/gateway/releases/download//defguard-gateway__x86_64-unknown-linux-gnu.deb Copy # wget https://github.com/DefGuard/gateway/releases/download/v0.7.0/defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard-gateway__x86_64-unknown-linux-gnu.deb Copy dpkg -i defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # defguard-gateway -V defguard-gateway 0.7.0 Copy wget https://github.com/DefGuard/proxy/releases/download/>/defguard-proxy--x86_64-unknown-linux-gnu.deb Copy wget https://github.com/DefGuard/proxy/releases/download/v0.5.0/defguard-proxy-0.5.0-x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard-proxy--x86_64-unknown-linux-gnu.deb Copy dpkg -i defguard-proxy-0.5.0-x86_64-unknown-linux-gnu.deb Copy # defguard-proxy -V defguard-proxy 0.5.0 Copy certbot certonly --non-interactive --agree-tos --standalone --email [email protected] -d my-server.defguard.net -d enroll.defgurd.net Copy ### 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" Copy systemctl enable defguard.service systemctl start defguard.service Copy # journalctl -u defguard.service | tail -n 50 Jul 29 13:57:15 defguard-testing systemd[1]: Started defguard.service - Defguard core service. Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.738420Z INFO defguard: Starting defguard Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.743079Z INFO defguard::db: Initializing DB pool Jul 29 13:57:16 defguard-testing defguard[2776504]: 2024-07-29T11:57:16.297407Z INFO defguard: Using HMAC OpenID signing key Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.156559Z INFO defguard::db::models::user: Initializing admin user Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.595218Z INFO defguard::db::models::user: New admin user has been created, adding to Admin group... Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.747717Z INFO defguard::db::models::settings: Initializing default settings Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.780563Z INFO defguard: Started web services Copy upstream defguard { server 127.0.0.1:8000; } upstream defguard-grpc { server 127.0.0.1:50055; } server { listen 443 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; client_max_body_size 128M; location / { proxy_pass http://defguard; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } server { listen 444 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard-grpc.log; error_log /var/log/nginx/defguard-grpc.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://defguard-grpc; } } Copy ln -s /etc/nginx/sites-available/my-server.defguard.net.conf /etc/nginx/sites-enabled/my-server.defguard.net.conf Copy systemctl reload nginx.service Copy $ curl https://my-server.defguard.net/api/v1/health alive Copy # 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 Copy # 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/ Copy 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 Copy # 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 Copy upstream defguard-proxy { server 127.0.0.1:8080; } upstream proxy-grpc { server 127.0.0.1:50051; } server { listen 443 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll.log; error_log /var/log/nginx/enroll.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } server { listen 444 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll.log; error_log /var/log/nginx/enroll.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://proxy-grpc; grpc_socket_keepalive on; grpc_read_timeout 3000s; grpc_send_timeout 3000s; grpc_next_upstream_timeout 0; proxy_request_buffering off; proxy_buffering off; proxy_connect_timeout 3000s; proxy_send_timeout 3000s; proxy_read_timeout 3000s; proxy_socket_keepalive on; keepalive_timeout 90s; send_timeout 90s; client_body_timeout 3000s; } } Copy ln -s /etc/nginx/sites-available/enroll.defguard.conf /etc/nginx/sites-enabled/enroll.defguard.conf systemctl restart nginx.service Copy # Proxy connection configuration DEFGUARD_PROXY_URL=https://enroll.defguard.net:444 Copy ### 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" Copy systemctl restart defguard.service sun-brightdesktopmoon --- # Running Gateway on OPNsense firewall | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) OPNsense plugin ---------------------------------------------------------------------------------------------------------------------------------------- [OPNsense®arrow-up-right](https://opnsense.org/) is an open source, feature rich firewall and routing platform, offering cutting-edge network protection. To start Defguard Gateway as OPNsense plugin: 1. On the [release pagearrow-up-right](https://github.com/DefGuard/gateway/releases) find and download OPNsense package which will be named: `defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg` – this package **includes both Defguard Gateway and OPNsense plugin.** 2. Install the package: Copy pkg add defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg 1. Refresh your OPNsense UI by running command below: Copy opnsense-patch 1. Go to your OPNsense UI and navigate to **VPN** > **Defguard Gateway**. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2F3IudZdqcgHS9wglwDhll%2FOPNSense%2520Plugin.png&width=768&dpr=3&quality=100&sign=8e532419&sv=2) 1. Fill out the form with appropriate values, click **Save**, and then click **Start/Restart.** circle-info You can find detailed description of all fields [here](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway-configuration) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/1.5/features/wireguard/remote-desktop-activation) . See also: [how to configure Defguard in OPNsense](https://docs.defguard.net/1.5/features/gateway) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) Binary Install -------------------------------------------------------------------------------------------------------------------------------------- 1. Checkout Gateway releases [herearrow-up-right](https://github.com/DefGuard/gateway/releases) and download compatible binary from GitHub page. 2. Decompress and move to bin directory 1. Start gateway `gateway -g -t ` [PreviousConfigurationchevron-left](https://docs.defguard.net/1.5/deployment-strategies/configuration) [NextRunning Gateway on MikroTik routerschevron-right](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers) Last updated 4 months ago * [OPNsense plugin](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) * [Binary Install](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) sun-brightdesktopmoon Copy tar xcf ./gateway.tar.gz sudo chmod +x gateway sudo mv gateway /usr/bin/ sun-brightdesktopmoon --- # Adding a location and getting a Gateway token | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/gateway#adding-a-location-in-defguard-core) Adding a location in Defguard Core ------------------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation Please remember that **one gateway corresponds to one VPN location.** You can also deploy multiple gateways for one location for High Availability. Go to the address you set on `DEFGUARD_URL` with your browser and sign in using the credentials you set up during Core deployment. Go to the _VPN Overview_ module from the main menu and click the _Edit Locations settings_. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FbsyFbXIUCHdYZFXaXLM1%252FScreenshot%25202025-10-15%2520at%252013.37.33.png%3Falt%3Dmedia%26token%3D5eb3c7e2-f19c-4851-aaf8-4b0b11707f1b&width=768&dpr=3&quality=100&sign=709b2255&sv=2) Adding a new location Then click the _Add new location tab_. ![Adding a new location](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FbOuoAljTgwcTXrCrzW7j%252FScreenshot%25202025-10-15%2520at%252013.37.55.png%3Falt%3Dmedia%26token%3Df1e39443-a51c-4acd-aa17-b4fe826100ce&width=768&dpr=3&quality=100&sign=f69ab2c5&sv=2) Adding a new location Depending on what is more convenient for you, choose configuration from Wireguard file or do it manually. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2F7mbhNEWkeB2NOLegg7XZ%2Fchoose_location_setup.png&width=768&dpr=3&quality=100&sign=7c929887&sv=2) Location wizard ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FgscOUZavxBnTydntdxDM%2Flocation_configuration.png&width=768&dpr=3&quality=100&sign=8178526f&sv=2) Location configuration 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. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FGYViUUDsciTYC4cNQPfe%2Fedit_locations_settings.png&width=768&dpr=3&quality=100&sign=a651e90f&sv=2) Manual configuration In `Gateway server setup` copy two variables: `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FIdldTQ83LvapVowr5Kks%2Fgateway_server_setup.png&width=768&dpr=3&quality=100&sign=6e8cf81f&sv=2) Gateway server setup Also, if core has a custom SSL CA to secure gRPC communication, [you need the CA certificate (more here).](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/gateway#deploy-the-gateway-service) Deploy the Gateway service --------------------------------------------------------------------------------------------------------------------------------- Proceed with deploying your Gateway service using the selected [deployment strategy](https://docs.defguard.net/1.5/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) : * [package based](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#gateway-1) * [Docker Compose](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#deploying-gateway-service) * [Kubernetes](https://docs.defguard.net/1.5/deployment-strategies/kubernetes#vpn-gateway-service) * [Terraform](https://docs.defguard.net/1.5/deployment-strategies/terraform#gateway-module) * [AMIs and AWS CloudFormation](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) You can also check our guides on running Gateway on [OPNsense firewall](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall) or [MikroTik router](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/1.5/features/network-devices#adding-a-new-network-device) . [PreviousConfiguring HTTPS using AWS Certificate Managerchevron-left](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) [NextConfigurationchevron-right](https://docs.defguard.net/1.5/deployment-strategies/configuration) Last updated 4 months ago * [Adding a location in Defguard Core](https://docs.defguard.net/1.5/deployment-strategies/gateway#adding-a-location-in-defguard-core) * [Deploy the Gateway service](https://docs.defguard.net/1.5/deployment-strategies/gateway#deploy-the-gateway-service) sun-brightdesktopmoon sun-brightdesktopmoon --- # Hardware, OS, network and firewall recommendations | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) Server & environment requirements ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Defguard can be deployed on multiple servers (physical or virtual) or on a single server (which is not recommended). Recommended setup reflects the [general system architecture](https://docs.defguard.net/1.5/in-depth/architecture) with components being split into three separate machines: 1. **Dedicated server or Virtual Machine for Core (control plane)** - that is in the Intranet network segment, not exposed in the public Internet in any way. Core needs to be accessible from the local (secure) network and VPN (to access Defguard securely). Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location - eg. if Defguard handles 2 VPN locations recommended is min. 2 CPU/vCPU 2. RAM: min. 1GB per location 3. Disk: min 8GB and more (since statistics will be gathered) 2. **Dedicated server or Virtual Machine for Proxy (external and public enrollment service)** - this server/VM needs to be deployed in DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 1GB 3. **Dedicated server or Virtual Machine for Gateway -** this server/VM needs to be deployed in: 1. DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. 2. Has access on Internal network interfaces to all network segments that will be exposed from VPN for users. 3. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 4GB (mostly for logs) In general the hardware requirements will also have to be adjusted based on the number of active users. The numbers above should serve as a baseline. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) Operating system and software requirements #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#package-based-installation) Package based installation Package based install requires Debian GNU/Linux min. 13.x or Ubuntu Linux min. 24.04.x #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#docker-based-installation) Docker based installation Docker deployment requires the system to have [official Docker Engine installationarrow-up-right](https://docs.docker.com/engine/install/) (not distribution based packages). [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) Network IP & DNS setup -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) Gateway server - where WireGuard VPN tunnels itself will be launched * **The** [**Gateway address**](https://docs.defguard.net/1.5/features/wireguard/create-your-vpn-network) and [**Gateway Port**](https://docs.defguard.net/1.5/features/wireguard/create-your-vpn-network) **must be publicly available from the Internet** circle-exclamation The server on which the Gateway is installed does not need to have the IP address (the same as the Gateway Address) assigned to it - can have internal network address. The Gateway Address is the address specified in the clients’ configuration – therefore, if this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (Gateway Port) must be forwarded (e.g., via NAT) to the Gateway Port on the server where the Gateway is installed.** * must have all networks on internal interfaces addresses configured, that should be accessible from VPN * **Recommended:** to have a public domain assigned to this IP for VPN server, eg. _vpn.company.com_ ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) Proxy - public web service for enrollment & desktop client configuration * **The** [**enrollment URL**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#enrollment-configuration) **(that proxy will be configured under and available for user and clients to reach) needs to be publicly available from the Internet.** circle-exclamation The server on which the Proxy is installed does not need to have the IP address assigned to it which the enrollment URL domain points to - can have internal network address. If this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (eg. if the enrollment URL is https://vpn-config.domain.com, then the port is 443) must be forwarded (e.g., via NAT) to the** [**DEFGUARD\_PROXY\_HTTP\_PORT**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) **on the server where the Proxy is installed.** * **must have a public enrollment domain assigned to this IP,** _**eg. enrollment.company.com (or vpn-config.company.com, etc..**_**)** ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) Core & database server * should be internal / private IP addresses accessible only from Intranet and VPN * must have internal domain name assigned in the local network DNS server, eg. _defguard.company.com_ [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) Firewall settings -------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) Gateway 1. Please open the public port you wish the VPN to be working on - eg. 50555 * Please open on the firewall: local network access **from the Gateway server/VM** → **to Defguard Core gRPC port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) Proxy 1. please open the public 443 port on the server (recommended to rewrite port 80 to redirect to 443) 2. please open gRPC port on the internal network - so that the **Defguard Core can connect to this port - more details here:** [**https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service**arrow-up-right](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) Core 1. please open 443 port for web interface accessible only from local/VPN network 2. please open a gRPC port **for the gateway server to connect to this port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) Backup strategy ---------------------------------------------------------------------------------------------------------------------------------------------------- In a production environment you should use your preferred backup solution to secure the following: * service configuration (.env file, service config files, compose configuration) * database content (prefferably by doing a regular pgdump, not just filesystem-level backup) [PreviousDeploying to Productionchevron-left](https://docs.defguard.net/1.5/deployment-strategies/deploying-to-production) [NextStandalone package based installationchevron-right](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation) Last updated 4 months ago * [Server & environment requirements](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) * [Operating system and software requirements](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) * [Network IP & DNS setup](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) * [Gateway server - where WireGuard VPN tunnels itself will be launched](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) * [Proxy - public web service for enrollment & desktop client configuration](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) * [Core & database server](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) * [Firewall settings](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) * [Gateway](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) * [Core](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) * [Backup strategy](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) sun-brightdesktopmoon sun-brightdesktopmoon --- # Standalone package based installation | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#introduction) 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. circle-info Make sure you understand [Defguard's architecture](https://docs.defguard.net/1.5/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. circle-exclamation This is a simple guide installing all components on a single server. For production make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#system-requirements) 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 servicearrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) (run by proxy) that will enable [remote onboarding, enrollmentarrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) and [easy configuration for our Desktop Clients (by adding Defguard instances)](https://docs.defguard.net/1.5/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#installing-a-database) Installing a database ----------------------------------------------------------------------------------------------------------------------------------------------------- Defguard Core uses [PostgreSQLarrow-up-right](https://www.postgresql.org/) 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 `::::` * we connected into the `defguard` database to verify `defguard` user can communicate with the database [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#installing-packages) Installing packages ------------------------------------------------------------------------------------------------------------------------------------------------- circle-info Defguard also have public APT repository, if you want know how to set it up, follow [this guide](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#core) Core You can find the URL to your package from the releases of the Core component on [GitHubarrow-up-right](https://github.com/DefGuard/defguard/releases) . 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: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#gateway) Gateway You can find the URL to your package from the releases of the Core component on [GitHubarrow-up-right](https://github.com/DefGuard/gateway/releases) . 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: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#proxy) Proxy You can find the URL to your package from the releases of the Core component on [GitHubarrow-up-right](https://github.com/DefGuard/proxy/releases) . 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: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#running-defguard) Running Defguard ------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#core-1) Core To run core service we need to configure `/etc/defguard/core.conf`. circle-info 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**](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#postgresql) **, 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**](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#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: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#gateway-1) 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`. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#setup-location-for-gateway) Setup location for gateway Follow [this guide](https://docs.defguard.net/1.5/deployment-strategies/gateway) 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. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#create-config-file) Create config file After getting `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` variables, we can configure our gateway service. Create config.toml file and swap `` and `` 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: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#proxy-1) Proxy To run proxy service (for [remote onboarding & enrollment](https://docs.defguard.net/1.5/using-defguard-for-end-users/enrollment) ), we can do it by: Check the logs afterwards. Should look like this: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#reverse-proxy) 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](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx) . After having the reverse proxy configured and running you can continue with this guide. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) 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` circle-check Now you have full working Defguard services 🥳 You can [configure your desktop client using the enrollment](https://docs.defguard.net/1.5/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 itarrow-up-right](https://defguard.gitbook.io/defguard/tutorials/step-by-step-setting-up-a-vpn-server#enabling-to-access-internet-through-your-vpn) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#securing-the-setup) 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) triangle-exclamation **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](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#upgrading-packages) Upgrading packages ----------------------------------------------------------------------------------------------------------------------------------------------- circle-info 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. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#freebsd-opnsense) FreeBSD/OPNsense 1. Uninstall the current version. 2. Install a newer version (as described [above](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#installing-packages) ). 3. Restart the service. [PreviousHardware, OS, network and firewall recommendationschevron-left](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) [NextDefguard APT repositorychevron-right](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) Last updated 2 months ago * [Introduction](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#introduction) * [System Requirements](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#system-requirements) * [Installing a database](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#installing-a-database) * [Installing packages](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#installing-packages) * [Core](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#core) * [Gateway](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#gateway) * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#proxy) * [Running Defguard](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#running-defguard) * [Core](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#core-1) * [Gateway](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#gateway-1) * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#proxy-1) * [Reverse proxy](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#reverse-proxy) * [Enabling Proxy service in the Core](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) * [Securing the setup](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#securing-the-setup) * [Upgrading packages](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation#upgrading-packages) sun-brightdesktopmoon Copy apt install postgresql Copy # su -c /usr/bin/psql postgres postgres=# CREATE USER defguard WITH SUPERUSER PASSWORD 'defguard'; postgres=# CREATE DATABASE defguard; Copy # echo 'localhost:5432:defguard:defguard:defguard' >> ~/.pgpass # chmod 600 ~/.pgpass # psql -d defguard -h localhost -U defguard defguard=# exit Copy wget Copy wget https://github.com/DefGuard/defguard/releases/download/v0.11.0/defguard-0.11.0-x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg add /defguard-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard -V defguard 0.11.0 Copy wget Copy # wget https://github.com/DefGuard/gateway/releases/download/v0.7.0/defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg add /defguard-gateway-X.Y.Z_x86_64-unknown-freebsd.pkg Copy sudo dpkg -i defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # defguard-gateway -V defguard-gateway 0.7.0 Copy wget Copy wget https://github.com/DefGuard/proxy/releases/download/v0.5.0/defguard-proxy-0.5.0-x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard-proxy--x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.deb # if you added apt repository sudo apt install defguard-proxy # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg add /defguard-proxy-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard-proxy -V defguard-proxy 0.5.0 Copy ### 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" Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard.service systemctl start defguard.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard start Copy # journalctl -u defguard.service | tail -n 50 Jul 29 13:57:15 defguard-testing systemd[1]: Started defguard.service - Defguard core service. Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.738420Z INFO defguard: Starting defguard Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.743079Z INFO defguard::db: Initializing DB pool Jul 29 13:57:16 defguard-testing defguard[2776504]: 2024-07-29T11:57:16.297407Z INFO defguard: Using HMAC OpenID signing key Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.156559Z INFO defguard::db::models::user: Initializing admin user Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.595218Z INFO defguard::db::models::user: New admin user has been created, adding to Admin group... Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.747717Z INFO defguard::db::models::settings: Initializing default settings Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.780563Z INFO defguard: Started web services Copy # 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-gateway.service systemctl start defguard-gateway.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_gateway start Copy 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/ Copy 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-proxy.service systemctl start defguard-proxy.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_proxy start Copy # 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 Copy # Proxy connection configuration DEFGUARD_PROXY_URL=https://enroll.defguard.net:444 Copy ### 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" Copy systemctl restart defguard.service Copy # Core package pkg delete defguard # or Gateway package pkg delete defguard-gateway # or Proxy package pkg delete defguard-proxy Copy # Core service sudo /usr/local/etc/rc.d/defguard restart # or Gateway service sudo /usr/local/etc/rc.d/defguard_gateway restart # or Proxy service sudo /usr/local/etc/rc.d/defguard_proxy restart sun-brightdesktopmoon --- # Running Gateway on MikroTik routers | 1.5 | defguard By leveraging the ability of some MikroTik routers to run Docker containers, it is possible to deploy the gateway directly on your router. circle-exclamation Proceed with extra caution when working with your core infrastructure. All official [RouterOS containers warningsarrow-up-right](https://help.mikrotik.com/docs/display/ROS/Container#Container-Disclaimer) still apply. triangle-exclamation Running the gateway on a MikroTik router is not fully supported. Due to custom RouterOS kernel incompatibility this kind of deployment does not support [Access Control List](https://docs.defguard.net/1.5/features/access-control-list) functionality. To run the gateway you must explicitly disable firewall management using the [`DEFGUARD_DISABLE_FW_MGMT` option](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway-configuration) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------------------------------------------- * RouterOS device with ARM or ARM64 architecture (popular home lab choices include RB4011 or RB5009) * `Container` package installed and enabled * Running Defguard core instance with a WireGuard location configured * (optional) Self-signed certificate generated by following [gRPC SSL setup guide](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#setup) Setup ------------------------------------------------------------------------------------------------------------------- circle-exclamation This guide assumes you do not have other Docker containers deployed on your router yet. If this is not the case adjust accordingly. The same applies if you have some more specific network configuration requirements. circle-info For brevity we'll be using RouterOS terminal commands, but everything can also be accomplished through WinBox GUI. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) Prepare network to install Docker container * First create a bridge interface for Docker containers and assign it an IP address in a dedicated Docker subnet (`172.17.0.0/24` in our example): * Each container must have a dedicated VETH interface; create a `veth1` interface and assign it an IP address in the chosen Docker subnet: * Add the virtual interface to the Docker bridge: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#setup-firewall-rules) Setup firewall rules * Set up NAT for outgoing traffic from containers: * Add port forwarding rule to send UDP traffic from the public WireGuard port to the gateway container: circle-exclamation Container port being forwarded to must match your public WireGuard port. * Add routing for your chosen WireGuard subnet configured in Defguard UI location settings: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#run-gateway-container) Run gateway container * Configure environment variables for the gateway container: * (optional) To use SSL for communication between the gateway and your Defguard instance copy the root certificate to your router's filesystem and add a following mount and environment variable: circle-exclamation Put the root certificate in a directory and mount the whole directory. Trying to mount a specific file can cause unexpected issues. * Add GitHub container registry to config: * Finally, create the actual container: At this point you should see that the gateway is connected in your Defguard instance's web UI. [PreviousRunning Gateway on OPNsense firewallchevron-left](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall) [NextReverse Proxy configuration using Nginxchevron-right](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx) * [Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#prerequisites) * [Setup](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#setup) * [Prepare network to install Docker container](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) * [Setup firewall rules](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#setup-firewall-rules) * [Run gateway container](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers#run-gateway-container) sun-brightdesktopmoon Copy /interface/bridge/add name=docker /ip/address/add address=172.17.0.1/24 interface=docker Copy /interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1 Copy /interface/bridge/port add bridge=docker interface=veth1 Copy /ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24 Copy /ip/firewall/nat/add chain=dstnat protocol=udp dst-address= dst-port= action=dst-nat to-addresses=172.17.0.2 to-ports= Copy /ip/route/add dst-address= gateway=172.17.0.2 Copy /container/envs/add name=defguard_env key=DEFGUARD_TOKEN value= /container/envs/add name=defguard_env key=DEFGUARD_GRPC_URL value= /container/envs/add name=defguard_env key=DEFGUARD_DISABLE_FW_MGMT value=true Copy /container/mounts/add name=defguard_cert src= dst=/certs /container/envs/add name=defguard_env key=DEFGUARD_GRPC_CA value=/certs/myCA.pem Copy /container/config/set registry-url=https://ghcr.io Copy /container/add remote-image=ghcr.io/defguard/gateway:latest interface=veth1 envlist=defguard_env sun-brightdesktopmoon --- # Configuration | 1.5 | defguard Here you can find a list of all configurable things through environmental variables, options or configuration files for all Defguard components (each top-level section for a specific component): * [Core config](https://docs.defguard.net/1.5/deployment-strategies/configuration#core) * [Proxy config](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) * [Gateway config](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway-configuration) * [YubiBridge config](https://docs.defguard.net/1.5/deployment-strategies/configuration#yubibridge-configuration) circle-info If you are using [one-line installation](https://docs.defguard.net/1.5/getting-started/one-line-install) , everything is generated and configured automatically. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#core) Core ------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#secrets-configuration) Secrets configuration Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens. circle-info You can generate random strings for secrets with e.g.: `openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64` * `DEFGUARD_AUTH_SECRET`: JWT secret key for encrypting user tokens, default: `DEFGUARD_AUTH_SECRET` * `DEFGUARD_SECRET_KEY`: JWT secret key for encrypting private cookies; must be at least 64 characters long * `DEFGUARD_GATEWAY_SECRET`: JWT secret key for encrypting Gateway tokens, default: `DEFGUARD_GATEWAY_SECRET` * `DEFGUARD_YUBIBRIDGE_SECRET`: JWT secret key for encrypting YubiBridge tokens, default: `DEFGUARD_YUBIBRIDGE_SECRET` * `DEFGUARD_OPENID_KEY`: this is optional if you want to use [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation, if you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) please provide a path to a private key file used for OAuth2/OpenID, [more herearrow-up-right](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) . ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#general-configuration) General configuration * `DEFGUARD_URL`: URL of your server instance, default `http://localhost:8000. This is the address at which the Web UI you use to administer your instance and the REST API endpoints are available (both of those are served by Defguard core on port 8000 by default; port can be configured with DEFGUARD_HTTP_PORT env variable).`This URL is needed to be exact since it's needed for OpenID discovery endpoint to work correctly, so if you have a reverse-proxy, custom domain, please provide an actual URL for Defguard core. * `DEFGUARD_GATEWAY_DISCONNECTION_NOTIFICATION_TIMEOUT`: If gateway is disconnected for this long, send email notification, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_WEBAUTHN_RP_ID` (optional): Relying party ID and relying party origin for WebAuthn used for MFA. By default, it's generated by using a base domain of `DEFGUARD_URL` (for example https://defguard.example.com is converted to defguard.example.com). circle-exclamation `DEFGUARD_WEBAUTHN_RP_ID`must be an effective domain of DEFGUARD\_URL (for example if hosting at `https://idm.example.com`, rp\_id must be `idm.example.com`, `example.com` or `com`). Changing `DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing Webauthn credentials.` * `DEFGUARD_ADMIN_GROUPNAME`: Name of the administrator group, default: `admin` * `DEFGUARD_USERADMIN_GROUPNAME`: Name of the user administrator group, default: `useradmin` * `DEFGUARD_VPN_GROUPNAME`: Name of the vpn group, default: `vpn` * `DEFGUARD_DEFAULT_ADMIN_PASSWORD`: Password for the default `admin` user, default: `pass123` * `DEFGUARD_LOG_LEVEL`: [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_PORT`: Core server port, default: `8000` * `DEFGUARD_LOG_FILE`: Log file path * `DEFGUARD_AUTH_COOKIE_TIMEOUT`: Cookie lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_MFA_CODE_TIMEOUT`: Email code lifetime period, default: `60s` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_SESSION_TIMEOUT`: Session lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#database-configuration) Database configuration Following env variables can be used to setup your database access: * `DEFGUARD_DB_HOST` * `DEFGUARD_DB_PORT` * `DEFGUARD_DB_NAME` * `DEFGUARD_DB_USER` * `DEFGUARD_DB_PASSWORD` ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#auth-cookies-configuration) Auth cookies configuration circle-exclamation If you want to access your Defguard instance without TLS (using an `http://` URL) you MUST enable insecure cookies by setting `DEFGUARD_COOKIE_INSECURE` to `true`. This is of course not recommended in production but can be useful when testing without a full reverse proxy setup. * `DEFGUARD_COOKIE_INSECURE`: set cookies without the `Secure` flag; use only in dev environments when serving Defguard without HTTPS * `DEFGUARD_COOKIE_DOMAIN` (optional): set the domain for auth cookies. By default, it's the domain from `DEFGUARD_URL`. Must be changed to base URL if you want to use [forward auth](https://docs.defguard.net/1.5/features/forward-auth) . ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#stats-cleanup-configuration) Stats cleanup configuration * `DEFGUARD_DISABLE_STATS_PURGE`: disable periodic cleanup of old Wireguard stats * `DEFGUARD_STATS_PURGE_FREQUENCY`: how often should the cleanup process be performed, default `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_STATS_PURGE_THRESHOLD`: age threshold for stats removal, default `30d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#enrollment-configuration) Enrollment configuration * `DEFGUARD_ENROLLMENT_URL`: external URL of the enrollment proxy server, default `http://localhost:8080` - this URL is sent in enrollment emails as well as displayed when configuring the desktop client - thus must be to the actual URL you have configured the proxy Web UI to be accessible at, otherwise the enrollment or desktop client configuration will not work. * `DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT`: how long is the enrollment token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_ENROLLMENT_SESSION_TIMEOUT`: how long in the enrollment session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#password-reset-configuration) Password reset configuration * `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT`: how long is the password reset token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_PASSWORD_RESET_SESSION_TIMEOUT`: how long in the password reset session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#grpc-server-configuration) gRPC server configuration [More on that in this help page.](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_GRPC_PORT`: the port on which the gRPC server should listen, default is `50055`. This port is used by Defguard Gateways to connect to your Core instance. * `DEFGUARD_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_GRPC_KEY`(optional): path to TLS key file * `DEFGUARD_GRPC_URL`: external URL of your instance's gRPC server, default `http://localhost:50055`; used for generating example VPN gateway startup command in Web UI ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-connection-configuration) Proxy connection configuration * `DEFGUARD_PROXY_URL` (optional): proxy service gRPC endpoint URL * `DEFGUARD_PROXY_GRPC_CA`(optional): path to TLS root certificate file, required if connecting to proxy gRPC service with a custom CA ([More on that in this help page.](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) ) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) Proxy service ------------------------------------------------------------------------------------------------------------- Here are proxy ENV variables. gRPC configuration is described more [on this help page.](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_HTTP_PORT`: port the proxy API server and Web UI will listen on, default `8080` * `DEFGUARD_PROXY_GRPC_PORT`: port the gRPCS server will listen on, default `50051` * `DEFGUARD_PROXY_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_PROXY_GRPC_KEY`(optional): path to TLS key file. [More on that in this help page.](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_URL` - if you wish to use External OIDC enrollment/desktop client configuration, please set this value to the same as `DEFGUARD_ENROLLMENT_URL` in core. This is the address at which the proxy Web UI is available. * `DEFGUARD_PROXY_LOG_LEVEL` : [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to * `DEFGUARD_PROXY_RATELIMIT_PERSECOND` - The (average) number of requests per second made without being eventually rate limited * `DEFGUARD_PROXY_RATELIMIT_BURST` - The number of requests allowed to be made in a short amount of time before being rate limited [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway-configuration) Gateway Configuration ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#environmental-variables-arguments) Environmental variables / Arguments If you're using docker image you can pass this value as environmental variables or on binary you can pass them as arguments * `DEFGUARD_GRPC_URL` , `-g ` - Defguard Core gRPC endpoint URL. This is used by the gateway to connect to your Defguard Core instance. If you configured the `DEFGUARD_GRPC_URL` variable on your Core instance before (as described in the [gRPC server configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#grpc-server-configuration) section), use the same value here. Otherwise, provide an URL that will allow the Gateway to reach your Core instance, e.g. `http://localhost:50055` if both Core and Gateway are running on the same host. * `DEFGUARD_TOKEN` ,`-t ` - Token displayed in the Defguard Core web UI after completing the network wizard. It can be copied from the "Authentication Token" section on the Location Settings page. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FXClomB27kopdPJ7Pnfct%2Fobraz.png&width=768&dpr=3&quality=100&sign=a68455e3&sv=2) * `DEFGUARD_USERSPACE` , `-u` - Use userspace wireguard implementation, useful on systems without native wireguard support * `DEFGUARD_GRPC_CA - path to ca file` more on this topic can be found [on this help page.](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_STATS_PERIOD` ,`-p ` - Defines how often (seconds) should interface statistics be sent to the Defguard server * `DEFGUARD_GATEWAY_NAME`, `--name ` - (optional) human-readable gateway name that will be displayed in Defguard webapp * `-s, --use-syslog` - enable logging to syslog * `RUST_LOG` : Logger log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_MASQUERADE` - controls whether the gateway automatically applies masquerade NAT firewall rule; defaults to `false` * `DEFGUARD_DISABLE_FW_MGMT` - disables all firewall management by the gateway; this overrides `DEFGUARD_MASQUERADE` setting; defaults to `false` circle-info `DEFGUARD_DISABLE_FW_MGMT` is meant as a workaround for running in incompatible environments, where our [default firewall integration](https://docs.defguard.net/1.5/features/access-control-list/firewall-internals) is not supported. As a consequence, enabling this option disables [ACL functionality](https://docs.defguard.net/1.5/features/access-control-list) on a given gateway. * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_IFNAME` \- The network interface that will be created and used for the VPN traffic * `DEFGUARD_FW_PRIORITY` - The NFT forward chain priority, which handles traffic filtering when ACLs are configured. Defaults to 0. Useful if the Defguard's forward chain conflicts with other chains. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#executing-custom-commands-on-vpn-up-down) Executing custom commands on VPN up/down The following env variables or gateway arguments define which commands gateway will run before / after it will bring up / down the VPN. It's usefull for example to use those commands to launch custom firewall commands or scripts that do various operations needed to be done on those occasions. triangle-exclamation Defguard is built with highest security standards in mind, thus the options below **accept only a full path to one command and it's arguments.** If you would like to have **multiple commands run,** you can create a shell script which will define the acceptable and preferred shell you would like to use and then all the commands you like to execute. `PRE_UP` , `--pre-up`, - Command to run before bringing up the interface. If you want to run a shell script, you should pass its path to your shell, for example: `/bin/sh -c /path/to/script` `POST_UP` , `--post-up`, - Command to run after bringing up the interface. `PRE_DOWN` , `--pre-down`, - Command to run before bringing down the interface. `POST_DOWN` , `--post-down`, - Command to run after bringing down the interface. circle-info If logging to syslog please remember to configure your syslog daemon accordingly, so that a dedicated logfile is created or the messages are included in the main system log. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#config-file) Config file Gateway configuration can also be read from a file by using a `--config` CLI option. Example file contents: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#yubibridge-configuration) YubiBridge configuration ----------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#environmental-variables) Environmental variables * `LOG_LEVEL`: Log messages level, default: `INFO`, available levels: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` * `WORKER_ID`: Name of your YubiBridge displayed on Defguard website, default: `YubiBridge` * `DEFGUARD_TOKEN`: - Secret worker token to secure gRPC communication, available on provisioners page * `SMARTCARD_RETRIES`: Number of retries in case provisioning failed, default: `1` * `JOB_INTERVAL`: Defines how often(seconds) YubiBridge checks Defguard for new jobs, default: `2` * `SMARTCARD_RETRY_INTERVAL`: Defines the number of seconds between trying to provision YubiKey again, default `15` ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#cli-arguments) CLI arguments: * `-h` , `--help`: Display help message * `-g `, `--grpc `: Connect to gRPC server at the given URL * `-i ` , `--id `: WorkerID, default `YubiBridge` * `-d` , `--debug`: Enable debug mode * `-t ` , `--tmpdir `: GnuPG home directory, default: `tmp` * `-p ` , `--provision `: Provision YubiKey with the following data * `-w ` , `--worker-token `: Secret worker token to secure gRPC communication, available on provisioners page * `-c ` , `--command `: Run command after provisioning and pass created keys as arguments [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#troubleshooting-the-configuration) Troubleshooting the configuration ----------------------------------------------------------------------------------------------------------------------------------------------------- Common configuration issues. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway) Gateway `Error: Syslog(Initialization(Io(Os { code: 111, kind: ConnectionRefused, message: "Connection refused" })))` The selected syslog socket may be wrong. See the `syslog_socket` configuration option for the gateway: [Config file](https://docs.defguard.net/1.5/deployment-strategies/configuration#config-file) . Set it to a correct syslog socket on your operating system. The default socket is valid for FreeBSD. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/configuration#core-1) **Core** `Cookie “defguard_session” has been rejected for invalid domain.` (browser console error) This issue most often takes the form of not being able to login without any obvious cause. The login button doesn't redirect and no relevant error message is displayed in the Defguard Core logs. In this case we recommend checking the browser logs (usually right click > inspect should open the developer tools along with the browser console). If you can see the above error, this means that your `DEFGUARD_URL` configuration option doesn't match the URL you use to access the dashboard at the moment. For example, if your login screen is at `http://my.domain.com:8000/auth/login` set `DEFGUARD_URL` to `` http://my.domain.com:8000` `` . [PreviousAdding a location and getting a Gateway tokenchevron-left](https://docs.defguard.net/1.5/deployment-strategies/gateway) [NextRunning Gateway on OPNsense firewallchevron-right](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-opnsense-firewall) Last updated 2 months ago * [Core](https://docs.defguard.net/1.5/deployment-strategies/configuration#core) * [Secrets configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#secrets-configuration) * [General configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#general-configuration) * [Database configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#database-configuration) * [Auth cookies configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#auth-cookies-configuration) * [Stats cleanup configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#stats-cleanup-configuration) * [Enrollment configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#enrollment-configuration) * [Password reset configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#password-reset-configuration) * [gRPC server configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#grpc-server-configuration) * [Proxy connection configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-connection-configuration) * [Proxy service](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) * [Gateway Configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway-configuration) * [Environmental variables / Arguments](https://docs.defguard.net/1.5/deployment-strategies/configuration#environmental-variables-arguments) * [Config file](https://docs.defguard.net/1.5/deployment-strategies/configuration#config-file) * [YubiBridge configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#yubibridge-configuration) * [Environmental variables](https://docs.defguard.net/1.5/deployment-strategies/configuration#environmental-variables) * [CLI arguments:](https://docs.defguard.net/1.5/deployment-strategies/configuration#cli-arguments) * [Troubleshooting the configuration](https://docs.defguard.net/1.5/deployment-strategies/configuration#troubleshooting-the-configuration) * [Gateway](https://docs.defguard.net/1.5/deployment-strategies/configuration#gateway) * [Core](https://docs.defguard.net/1.5/deployment-strategies/configuration#core-1) sun-brightdesktopmoon Copy # 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 = "" # Required: Defguard server gRPC endpoint URL # NOTE: must replace default with actual value grpc_url = "" # Optional: gateway name which will be displayed in Defguard web UI name = "Gateway on server X" # Required: use userspace Wireguard implementation (e.g. wireguard-go) userspace = false # Optional: path to TLS cert file - more in gRPC SSL communication help page # in our documentation. # 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 #pre_up = "/path/to/script.sh" # Optional: Command which will be run after bringing interface up #post_up = "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 = "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 = "ip route del default via 192.168.1.1 dev wg0" sun-brightdesktopmoon --- # Terraform | 1.5 | defguard circle-info Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later. circle-info We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/issues) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#aws) AWS ------------------------------------------------------------------------------------- To deploy Defguard using Terraform on AWS, you can use the Terraform configuration provided in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main) . The terraform configuration includes the necessary resources to setup all components of Defguard. We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture pagearrow-up-right](https://docs.defguard.net/in-depth/architecture) . When configuring the networking, the most important thing is to keep in mind the following rules: * Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection. * Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. * Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN. * All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#using-the-modules) Using the Modules To use the provided Terraform modules in your terraform configuration, you can use the following source: Copy module "" { source = "github.com/DefGuard/deployment//terraform/modules/?ref=" # Rest of the module configuration goes here # ... } Where: * `` is the name you want to give to the module in your configuration. * `` is one of `core`, `proxy`, or `gateway`, depending on which module you want to use. * `` is the commit hash, tag or branch name of the Defguard deployment repository. You can use the `main` branch for the latest stable version. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#configuring-modules) Configuring modules There are three Defguard modules available for deployment: `core`, `proxy` and `gateway`. The modules can be found in the modules [directoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main/terraform/modules) in the Defguard deployment repository. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#common-configuration-options-for-all-modules) Common configuration options for all modules All components have common configuration options that may be configured in their respective blocks in the `main.tf` file: * `instance_type`: The instance type to use. The default is `t3.micro`. You can adjust this based on your performance needs. * `ami`: The base AMI to use for the Defguard instance. We recommend using the Ubuntu Server 24.04 LTS (64-bit) AMI, which is the default in the example configurations. You may change this to a different AMI if needed. Your AMI must meet the requirements defined in [AMI requirements](https://docs.defguard.net/1.5/deployment-strategies/terraform#ami-requirements) . * `package_version`: The version of the Defguard component package to be installed. This must be an existing Defguard debian package released on the Defguard releases page (e.g. Defguard Core packages are available [herearrow-up-right](https://github.com/DefGuard/defguard/releases) ). Example: `1.4.0`, `1.3.2-alpha2`. * `arch`: The architecture of the Defguard Core package to be installed. This can be set to `x86_64` or `aarch64`. The default is `x86_64`. * `log_level`: The log level to use for the Defguard component. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. The default is `info`. Note that setting the log level to `debug` will produce a lot of logs, which may be useful for debugging, but may also fill up your disk space quickly. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#core-module) Core module The core module is responsible for setting up Defguard Core. It accepts the following variables: * `core_url`: The URL at which Defguard web UI will be accessible. * `grpc_port`: The gRPC port for Defguard Core to communicate with gateways. * `http_port`: The HTTP port on which the Defguard Core web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. * `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments. * `default_admin_password`: The default password for the admin user. This should be changed after the first login. * `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module. * `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](https://docs.defguard.net/1.5/deployment-strategies/terraform#vpn-networks-configuration) section for more details on how to configure the VPN networks. * `db_details`: A map containing the database configuration. It must contain the following: * `name`: The name of the PostgreSQL database to be created for Defguard. * `username`: The username for the PostgreSQL database. * `password`: The password for the PostgreSQL database user. * `port`: The port on which the PostgreSQL database will listen. * `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. * `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#proxy-module) Proxy module The proxy module is responsible for setting up the Defguard Proxy. It accepts the following variables: * `url`: The URL at which Defguard Proxy will be accessible. * `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication. * `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#gateway-module) Gateway module The gateway module is responsible for setting up the Defguard VPN gateways. It accepts the following variables: * `core_grpc_port`: The gRPC port of Defguard Core for the internal communication. This must match the `grpc_port` variable in the core module. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core. * `network_id`: The ID of the VPN network. This must match the `id` field in the `vpn_networks` variable in the core module. * `core_address`: The IP address of the Defguard Core instance. This should be core's private address, as it will be used for internal communication between the gateway and core components. See the `basic` example for the configuration of this variable. * `gateway_secret`: The secret used to authenticate the gateway with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the core module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Gateway instance. This is used to ensure that the gateway instance has a private IP address in the same VPC as the core and proxy components. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#vpn-networks-configuration) VPN networks configuration * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. Each network is defined as a map with the following keys: * `id`: The id of the network. Must start with 1 and increment for each new network. This is used to identify the network in the database and allows for applying modifications to the network configuration later. * `name`: The name of the VPN network. This will be used to identify the network in the Defguard web UI and displayed to the users. * `address`: The internal address of the VPN network in the form of `x.x.x.x/x`. This is the address that will be assigned to the VPN clients when they connect to the VPN. It must be a valid CIDR notation. * `port`: The port on which the VPN gateway will listen for incoming VPN connections. Default is `50051`, which is the standard port for WireGuard VPN. You may change this to a different port if needed. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#ami-requirements) AMI requirements If you wish to use a different AMI for the Defguard components, it must meet the following requirements: * Must allow for running systemd services. * Must use the APT package manager. If you are not meeting these requirements, you will need to modify the corresponding `setup.sh` scripts, which are responsible for installing and configuring the Defguard components. The scripts can be found in `terraform/modules//setup.sh`, where `` is one of `core`, `gateway`, or `proxy`. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#examples) Examples The example configurations can be downloaded from the Defguard deployment repository. They are located in the `terraform/examples` directory: (https://github.com/DefGuard/deployment/tree/main/terraform)\[https://github.com/DefGuard/deployment/tree/main/terraform\] If you wish, you can also clone the whole repository using the following command: Copy git clone https://github.com/DefGuard/deployment.git And then navigate to the `terraform/examples` directory to find the example configurations. Copy cd deployment/terraform To use any of the examples, you can copy or download the `main.tf.example` file and rename it to `main.tf`. Note that the file contains both the module definitions, variables and outputs. This is to make it easier to download the example. You can also split the file into separate files, such as `main.tf`, `variables.tf`, and `outputs.tf`, if you prefer to keep the configuration more organized. To run the examples, use the following commands: Copy # To initialize all the modules and providers, run: terraform init # To preview the changes that will be made, run: terraform plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: terraform apply -var="aws_access_key=" -var="aws_secret_key=" or if using OpenTofu: Copy # To initialize all the modules and providers, run: tofu init # To preview the changes that will be made, run: tofu plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: tofu apply -var="aws_access_key=" -var="aws_secret_key=" After running these commands, Terraform will create the necessary resources in your AWS account and deploy Defguard. The output will include the public and private addresses for Core, Proxy and gateway components: Copy Apply complete! Resources: 35 added, 0 changed, 0 destroyed. Outputs: defguard_core_private_address = "10.0.1.x" defguard_core_public_address = "x.x.x.x" defguard_proxy_private_address = "10.0.1.x" defguard_proxy_public_address = "x.x.x.x" defguard_gateway_private_addresses = [\ "10.0.1.226",\ ] defguard_gateway_public_addresses = [\ "x.x.x.x",\ ] Note that running the examples will put some sensitive details into your `.tfstate` file, most notably: the database password, gateway secret and the initial admin password. Those details are not ephemeral in the terraform configuration as they must be passed to the Defguard components during their setup. If you want to secure those details, we recommend following the official guidelines on [how to secure your Terraform state filearrow-up-right](https://developer.hashicorp.com/terraform/language/state/sensitive-data) . #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#basic) `basic` The `basic` example can be directly downloaded using the following link: [basic/main.tf.examplearrow-up-right](https://raw.githubusercontent.com/DefGuard/deployment/refs/heads/main/terraform/examples/basic/main.tf.example) . The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following: * Defguard Core instance * Defguard Proxy instance * Defguard Gateway instance * A database instance (RDS) for Defguard Core. * A single VPC for all components. You can use this example as a starting point for your own deployment. To modify the network configuration, edit one of the sections in the `main.tf` file, such as "Core network configuration", "Gateway network configuration", or "Proxy network configuration". For example, to allow SSH access to Defguard Core instance, you can uncomment the following block in the "Core network configuration" section: Copy ingress { from_port = 22 to_port = 22 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Note that this will grant SSH access from any IP address, you may want to restrict it further by editing the `cidr_blocks` field. By default, the configuration allows access to Defguard Core web UI only from connected VPN clients, which is the recommended approach: Copy ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } If you want to run Core web UI behind a reverse proxy (e.g. to enable HTTPS), you would need to do the following: 1. Prevent direct access to the services by removing their ingress rules: Copy # This is in the Core security group block [...] ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Proxy security group block [...] ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } 1. Add a second public subnet (load balancers require it): Copy vpc_public_subnets = ["10.0.1.0/24", "10.0.4.0/24"] 1. Add the load balancer configuration Copy ########################################################################### ###################### Load Balancer Configuration ####################### ########################################################################### # Load balancer security groups resource "aws_security_group" "defguard_alb_sg" { name = "defguard-alb-sg" description = "Access to the Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] description = "HTTPS access from internet" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-alb-sg" } } resource "aws_security_group" "defguard_internal_alb_sg" { name = "defguard-internal-alb-sg" description = "Access to the Internal Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = [local.vpc_cidr] description = "HTTPS access from internal VPC network" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-internal-alb-sg" } } # Public Application Load Balancer resource "aws_lb" "defguard_public_alb" { name = "defguard-public-alb" internal = false load_balancer_type = "application" security_groups = [aws_security_group.defguard_alb_sg.id] subnets = module.vpc.public_subnets enable_deletion_protection = false tags = { Name = "defguard-public-alb" } } # Internal Application Load Balancer resource "aws_lb" "defguard_internal_alb" { name = "defguard-internal-alb" internal = true load_balancer_type = "application" security_groups = [aws_security_group.defguard_internal_alb_sg.id] subnets = module.vpc.private_subnets enable_deletion_protection = false tags = { Name = "defguard-internal-alb" } } # Target Groups resource "aws_lb_target_group" "defguard_core_tg" { name = "defguard-core-tg" port = local.core_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-core-tg" } } resource "aws_lb_target_group" "defguard_proxy_tg" { name = "defguard-proxy-tg" port = local.proxy_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-proxy-tg" } } # Target Group Attachments resource "aws_lb_target_group_attachment" "defguard_core_attachment" { target_group_arn = aws_lb_target_group.defguard_core_tg.arn target_id = module.defguard_core.instance_id port = local.core_http_port } resource "aws_lb_target_group_attachment" "defguard_proxy_attachment" { target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn target_id = module.defguard_proxy.instance_id port = local.proxy_http_port } # Listeners resource "aws_lb_listener" "defguard_public_alb_listener" { load_balancer_arn = aws_lb.defguard_public_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } } resource "aws_lb_listener" "defguard_internal_alb_listener" { load_balancer_arn = aws_lb.defguard_internal_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } } # Listener Rules resource "aws_lb_listener_rule" "defguard_proxy_rule" { listener_arn = aws_lb_listener.defguard_public_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } condition { host_header { values = [replace(local.proxy_url, "https://", "")] } } } resource "aws_lb_listener_rule" "defguard_core_rule" { listener_arn = aws_lb_listener.defguard_internal_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } condition { host_header { values = [replace(local.core_url, "https://", "")] } } } 1. Add load balancer ingress rules to your existing Proxy and Core groups: Copy # HTTP access from internal load balancer (Core) ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_internal_alb_sg.id] description = "HTTP access from internal load balancer" } # HTTP access from public load balancer (Proxy) ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_alb_sg.id] description = "HTTP access from public load balancer" } 1. Finally, you can add the load balancer domain name to the output: Copy output "defguard_public_alb_dns" { description = "The DNS name of the Public Application Load Balancer" value = aws_lb.defguard_public_alb.dns_name } output "defguard_internal_alb_dns" { description = "The DNS name of the Internal Application Load Balancer" value = aws_lb.defguard_internal_alb.dns_name } This setup will create two load balancers: one internal and one external. Both will act as a reverse proxy, routing the HTTPS traffic matching your domains to the backend servers (Proxy, Core). The next step would be to point your actual domains to the domain names generated by the load balancers in the output (CNAME) and to setup SSL certificates (e.g. via the AWS certificate manager). ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#troubleshooting-and-common-issues) Troubleshooting and common issues All components are deployed as systemd services on the host EC2. Their configuration files can be found at `/etc/defguard`. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#checking-status-of-any-component) Checking status of any component You can check the status of any Defguard component by SSHing into the corresponding EC2 instance and running the following command: Copy sudo systemctl status Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the status of the service. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#checking-logs-of-any-component) Checking logs of any component To display the logs of the service, SSH into the corresponding EC2 instance and run the following command: Copy sudo journalctl -u Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the logs of the service. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/terraform#checking-setup-logs) Checking setup logs Before any of the components becomes available, a `setup.sh` script is run, which performs its initial setup (package download, configuration). The logs of this script are stored in `/var/log/defguard.log` on a corresponding EC2 instance. You can check this log file to see if there were any issues during the setup. [PreviousKuberneteschevron-left](https://docs.defguard.net/1.5/deployment-strategies/kubernetes) [NextAmazon Machine Image (AMI)chevron-right](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation) Last updated 5 months ago --- # Reverse Proxy configuration using Nginx | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#introduction) Introduction ------------------------------------------------------------------------------------------------------------------------------------- This guide explains how to configure [NGINXarrow-up-right](https://nginx.org/) as a reverse proxy for Defguard's components (Core and 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. To provide HTTPS encryption, this guide also uses [Certbotarrow-up-right](https://certbot.eff.org/) , a free, open-source tool from the [Let’s Encryptarrow-up-right](https://letsencrypt.org/) project. Certbot automatically issues and renews SSL/TLS certificates, allowing you to secure your Defguard domains without manual certificate management. circle-info We assume in this guide that you run your Core and Proxy services on separate servers, and you run Certbot and Nginx on each one of them. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#installing-nginx-and-certbot) Installing Nginx and Certbot --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Run the followign command to install Nginx and Certbot. Copy apt install nginx certbot Disable the default Nginx configuration to avoid conflicts: Copy unlink /etc/nginx/sites-enabled/default [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) Obtaining SSL certificates ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Use Certbot to generate SSL certificates. For each service (Core, Proxy), run the following command on the server that your domain’s DNS records resolve to. Ensure that inbound traffic on port 80 is allowed by the firewall and that no other process is using this port. circle-info Certbot verifies domain ownership using the HTTP-01 challenge, where it temporarily serves a validation file over port 80 for the exact domain you are requesting a certificate for. If the request fails with a timeout or connection error, Let’s Encrypt could not reach this temporary server. This usually means the DNS record for that domain does not point to the correct public IP of the machine running Certbot, port 80 is blocked (firewall or Security Group), an IPv6 (AAAA) record is published but not supported on the server, or another service is already using port 80. Ensure the domain’s DNS resolves to this server’s public IP, inbound port 80 is open, and no other service is binding the port before trying again. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificate-for-core-service) Obtaining SSL certificate for Core service Use the following command to generate certificate with Certbot. Replace the example domain for the Core service (my-server.defguard.net) with your own. Copy certbot certonly \ --non-interactive \ --agree-tos \ --standalone \ --email admin@yourdomain.com \ -d my-server.defguard.net Certbot will generate certificate in fullchain.pem and privkey.pem in the following path: Copy /etc/letsencrypt/live/my-server.defguard.net ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificate-for-proxy-service) Obtaining SSL certificate for Proxy service Use the following command to generate certificate with Certbot. Replace the example domain for the Proxy service (enroll.defguard.net) with your own. Copy certbot certonly \ --non-interactive \ --agree-tos \ --standalone \ --email admin@yourdomain.com \ -d enroll.defguard.net Certbot will generate certificate in fullchain.pem and privkey.pem in the following path: Copy /etc/letsencrypt/live/enroll.defguard.net [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#configuring-and-starting-nginx) Configuring and starting Nginx ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#configuring-and-starting-nginx-for-core-service) Configuring and starting Nginx for Core service Create a new configuration file for the Core service: `/etc/nginx/sites-available/my-server.defguard.net.conf` Copy upstream defguard { server 127.0.0.1:8000; } upstream defguard-grpc { server 127.0.0.1:50055; } server { listen 443 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; client_max_body_size 128M; location / { proxy_pass http://defguard; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } server { listen 444 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard-grpc.log; error_log /var/log/nginx/defguard-grpc.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://defguard-grpc; } } Enable the configuration and start Nginx: Copy ln -s /etc/nginx/sites-available/my-server.defguard.net.conf /etc/nginx/sites-enabled/my-server.defguard.net.conf systemctl start nginx.service To verify, run: Copy curl https://my-server.defguard.net/api/v1/health # Expected output: alive circle-info If you use this simple setup and run all services on one server, you can use [NGINX access restrictionsarrow-up-right](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-tcp/) for securing core and allowing to access the _my-server.defguard.net_ only to selected networks - blocking the direct access from the Internet. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#configuring-and-starting-nginx-for-proxy-service) Configuring and starting Nginx for Proxy service The Proxy service exposes APIs for enrollment, remote onboarding, and desktop client configuration. Create its NGINX configuration file: `/etc/nginx/sites-available/enroll.defguard.net.conf` Copy upstream defguard-proxy { server 127.0.0.1:8080; } upstream proxy-grpc { server 127.0.0.1:50051; } server { listen 443 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll.log; error_log /var/log/nginx/enroll.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { proxy_http_version 1.1; proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } } server { listen 444 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll-grpc.log; error_log /var/log/nginx/enroll-grpc.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://proxy-grpc; grpc_socket_keepalive on; grpc_read_timeout 3000s; grpc_send_timeout 3000s; grpc_next_upstream_timeout 0; proxy_request_buffering off; proxy_buffering off; proxy_connect_timeout 3000s; proxy_send_timeout 3000s; proxy_read_timeout 3000s; proxy_socket_keepalive on; keepalive_timeout 90s; send_timeout 90s; client_body_timeout 3000s; } } Enable and restart NGINX: Copy ln -s /etc/nginx/sites-available/enroll.defguard.net.conf /etc/nginx/sites-enabled/enroll.defguard.net.conf systemctl restart nginx.service [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#security-recommendations) Security Recommendations ------------------------------------------------------------------------------------------------------------------------------------------------------------- * Only expose **HTTPS ports (443)** for web access. * Do **not** expose internal **gRPC ports** (444, 50051, 50055) directly to the Internet. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#summary) Summary --------------------------------------------------------------------------------------------------------------------------- After completing the configuration: * Defguard Core is available at `https://my-server.defguard.net` * Enrollment and onboarding services are available at `https://enroll.defguard.net` * Both services are secured with SSL and reverse-proxied through NGINX. [PreviousRunning Gateway on MikroTik routerschevron-left](https://docs.defguard.net/1.5/deployment-strategies/running-gateway-on-mikrotik-routers) [NextHigh Availability and Failoverchevron-right](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover) Last updated 3 months ago --- # Amazon Machine Image (AMI) | 1.5 | defguard This guide explains how to deploy Defguard on AWS using official Amazon Machine Images (AMIs) and a preconfigured CloudFormation template. It walks you through launching all required components - including Core, Gateway, Proxy, and the PostgreSQL database - in a production-ready architecture with minimal manual configuration. You will learn how to subscribe to the AMIs, deploy the stack, attach SSL certificates, configure domains, and gain initial VPN access. The goal is to provide a repeatable, secure deployment method that allows you to get Defguard running quickly while still enabling advanced customization for larger or more complex environments. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#ami-architecture) AMI architecture --------------------------------------------------------------------------------------------------------------------------------- We recommend using the AMIs with our CloudFormation template as it will automatically configure all components. You can import the CloudFormation template from the AWS Marketplace or from our GitHub [deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment) . The template consists of the following main components: * **Defguard Core** * **Defguard Gateway** - The template has only one Gateway instance, but Defguard supports running multiple Gateways if you need more VPN locations. * **Defguard Proxy** * **PostgreSQL Database** We recommend reading the [Architecture documentationarrow-up-right](https://docs.defguard.net/in-depth/architecture) to understand how these components interact. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FIVgFXiWtXEWkmSCeNp10%252Faws_cloudformation_v2.png%3Falt%3Dmedia%26token%3Db3d35ec0-6a54-444b-a6f8-7e5a7fcab1f9&width=768&dpr=3&quality=100&sign=bbdfbe5e&sv=2) Diagram showing how the components are deployed using the template [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#installation-guide) Installation guide ------------------------------------------------------------------------------------------------------------------------------------- circle-info In order to use the CloudFormation template you need to subscribe to the Defguard AMI product. The most straightforward way to obtain the template is to select it during the product delivery after subscribing to the product on the marketplace. After the CloudFormation template is uploaded either manually or via the marketplace, you will be prompted to fill the details of your deployment. This guide will go over the most important settings that need to be filled for a functional deployment. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#prerequisites) Prerequisites * Two domains: one for accessing Defguard Core (the main dashboard) and one for accessing Defguard Proxy (for external enrollment and device configuration) * AWS issued SSL certificates for the two domains. See [this page](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) for more information. * An SSH key added to AWS. This will allow you to access the EC2 instances later on. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#obtaining-the-template) Obtaining the template 1. Subscribe to the product on AWS Marketplace. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FufiAQjzMpOJlEU4VHytw%252FScreenshot%25202025-12-01%2520at%252014.22.10.png%3Falt%3Dmedia%26token%3D4738b07a-f9f6-4b0e-8ba9-3734af4d1182&width=768&dpr=3&quality=100&sign=69df0bb3&sv=2) 2. After subscription succeeds, click the launch your software button: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252Fj1dhDxNU3xrB0zE8ljkq%252Fimage.png%3Falt%3Dmedia%26token%3D9734c4ac-31ed-4f72-8da0-5720e8e12b0a&width=768&dpr=3&quality=100&sign=abea4a56&sv=2) 3. Select the CloudFormation option and click "Launch with CloudFormation" ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FinTMYkUOVwx3LLKsyN8p%252Fimage.png%3Falt%3Dmedia%26token%3D2c8b0594-dc51-4e9c-b588-f2d4e4f4bada&width=768&dpr=3&quality=100&sign=53e97691&sv=2) 4. On the "Create stack" screen click next and proceed to the next section ( [Template parameters](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#template-parameters) ). #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#template-parameters) Template parameters After you are presented with the template configuration screen, make sure to fill out the following parameters: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F7SzZcR3lGNobp7oObK4a%252Fimage.png%3Falt%3Dmedia%26token%3D88e670d7-2ab2-46c2-837b-8f2ac35de3d1&width=768&dpr=3&quality=100&sign=c8d74eea&sv=2) Choose a name for the stack. This can be chosen freely but must be unique across your deployed stacks. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FKMMIhvp4qf3Cr7j0ngWc%252Fimage.png%3Falt%3Dmedia%26token%3Dd05b7279-7193-4abc-8ef2-ed71c67814df&width=768&dpr=3&quality=100&sign=da5abde3&sv=2) The `CoreDefaultAdminPassword` will be the password used for logging to the Defguard Core dashboard for the `admin` user. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FsUTUq1fzjza7E2ql41AO%252Fimage.png%3Falt%3Dmedia%26token%3D2c5f6ee1-8293-4d68-83f3-5d102bb6fceb&width=768&dpr=3&quality=100&sign=c1eeff8&sv=2) The `CoreUrl` is the URL under which your Defguard Core dashboard will be accessible. This should be filled according to the domain you chose before ([Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). For example, if your domain for Defguard Core is `defguard.example.com`, insert `https://defguard.example.com` here. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F3SBNfzoAdlbsxnPfagwx%252Fimage.png%3Falt%3Dmedia%26token%3Dd99eeee5-a1fd-48cd-bb4e-6a35dc43cf02&width=768&dpr=3&quality=100&sign=284458a6&sv=2) This is the database password. Select a relatively strong password here as a very weak password may be rejected by the database system and may result in a deployment failure. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FtSrBN6f4kxVxVSn3bkQW%252Fimage.png%3Falt%3Dmedia%26token%3D36d77d73-5075-4799-92f9-72631f2ba263&width=768&dpr=3&quality=100&sign=1b4b1bc4&sv=2) This is the URL under which the Defguard Proxy will be accessible to users. Fill the field just like the `CoreUrl` field, but this time use the domain you chose for the Defguard Proxy ([Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FOJJyANkuuvYfpeW60n4l%252Fimage.png%3Falt%3Dmedia%26token%3D4b762478-7aac-414f-a515-847db90d71e9&width=768&dpr=3&quality=100&sign=5da799a5&sv=2) Insert here the ARN of the certificate you prepared earlier ([Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). This will auto configure HTTPS for both Defguard Proxy and Core. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FjDn7uzcYRgSPecTAuGKl%252Fimage.png%3Falt%3Dmedia%26token%3D6d79f2ac-26e8-46c9-9337-690f2803f922&width=768&dpr=3&quality=100&sign=21fea5b9&sv=2) Provide here the name of your SSH key. This is required for SSH access to the EC2 instances. Note that manual configuration of firewall access on the SSH port (22) is required after the deployment. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FBDLeg2ZC3VwM9sk9aXrF%252Fimage.png%3Falt%3Dmedia%26token%3De0ab5c15-7b6c-4dd3-a02e-dbb248d01752&width=768&dpr=3&quality=100&sign=1fa36&sv=2) The VPN parameters allow for configuring the details of your VPN network (location). You may want to change the name of the location to better suit your deployment. By default, NAT is enabled on the VPN Gateway instance so connecting clients can automatically reach servers inside your private network (this is required to reach Defguard Core dashboard, for example). If you disable NAT, you will need to configure routing rules yourself. Make sure to also check the rest of the pre-filled parameters, as you may want to change some of them. The full list is available in the [Template parameters](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) section. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#stack-options) Stack options Next, select the behavior on deployment failure: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FNA9nyjJQRO6qgdjtyLhf%252Fimage.png%3Falt%3Dmedia%26token%3D1e08a224-5c17-434c-be69-d5965d3cdc09&width=768&dpr=3&quality=100&sign=9579f9cd&sv=2) We recommend cleaning up everything after failed deployment, to keep a clean state when retrying. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F5FcJsfMRlPrFWNT6hPor%252Fimage.png%3Falt%3Dmedia%26token%3Dbcc3caf5-cc5d-4870-9674-130188092b36&width=768&dpr=3&quality=100&sign=9388bd14&sv=2) The template contains several IAM roles that are used to grant access required for interacting with the AWS SecretManager to pass secrets securely between components during the deployment. The template also consists of a lambda function along with an IAM role which is responsible for creating a token that can be used by an admin to access the VPN for the first time. This needs to be accepted to proceed further. Now wait for the deployment to finish. If all went OK, you should see _CREATE\_COMPLETE_ status. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#outputs) Outputs After the deployment completes, you will receive a set of outputs in the "outputs" tab. This values are required for further configuration. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FLTpp8jic7TAmlMcYPJ76%252Fimage.png%3Falt%3Dmedia%26token%3D145f70d1-b165-4145-b458-a7a3b5471a9b&width=768&dpr=3&quality=100&sign=1a06f3c6&sv=2) #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#setting-up-your-domains) Setting up your domains The template will provision two domains: `InternalProxyALBDNSName` and `PublicProxyALBDNSName` . The public domain points to the Defguard Proxy instance's reverse proxy, and the internal one to Core's. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FyotQa12zLaAVGXzeduWy%252Fimage.png%3Falt%3Dmedia%26token%3D071c6cac-d9ad-4867-9e9f-eac05fcd725f&width=768&dpr=3&quality=100&sign=23baf842&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FUyaG3gQFO6gKiPDraAZc%252Fimage.png%3Falt%3Dmedia%26token%3D1125e705-ffb1-4073-937c-14a955787cfd&width=768&dpr=3&quality=100&sign=da7ad4b2&sv=2) You can use those domains to setup CNAME records in your DNS provider configuration, so the domains you defined in the `ProxyUrl` and `CoreUrl` point to the correct load balancers (reverse proxies) and in result, to the correct components: Your domain CNAME response Target component `` `` Defguard Core (internal) `` `` Defguard Proxy (public) #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#configuring-you-first-device-using-the-desktop-client) Configuring you first device using the desktop client The stack is now fully set up and you can try to access it. The dashboard is not publicly available, so you'll need to configure access to the VPN first. Use the token displayed in the `AdminFirstDeviceToken` CloudFormation output to add your first device. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FbnWIPkfOSDW3h0IpN3PQ%252Fimage.png%3Falt%3Dmedia%26token%3Daf3acebd-82eb-4156-841b-d3fa5e801f58&width=768&dpr=3&quality=100&sign=c280d380&sv=2) Check this [guidearrow-up-right](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) on adding a new instance in the Desktop client, to learn more about the process. As the instance URL, use the URL you defined in your Defguard Proxy instance configuration section of the CloudFormation template (`ProxyUrl`). #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#accessing-the-dashboard) Accessing the dashboard After you use the `AdminFirstDeviceToken` as described in the previous section you will gain access to the VPN network and (by default) the VPC network. To access the Defguard Core dashboard, navigate to the URL you defined in the `CoreUrl` parameter. To login, use the default `admin` username and the password defined in `CoreDefaultAdminPassword`. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#customisation) Customisation --------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) Template parameters #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#general) General * `SshKeyName` (optional): EC2 Key Pair name for SSH access to instances. If not provided, SSH access will not be available. Requires a manual setup of SSH security group rules afterwards. * `StackPrefix` (optional): The prefix that all the deployed components will receive, for example the Defguard core EC2 instance will be named <`StackPrefix>-core-instance`. * `SSLCertificateArn` (optional): The ARN of the AWS issued certificate to use for setting up HTTPS for Core and Proxy. This certificate must be valid for the domains specified in `CoreUrl` and `ProxyUrl`. If left empty, HTTPS won't be configured automatically. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#core-instance) Core Instance * `CoreCookieInsecure` (optional): If set to `true`, Defguard Core will use insecure cookies. This is not recommended for production environments. Set it to `true` if you are using HTTP instead of HTTPS. * `CoreGrpcPort` (optional): The gRPC port, default is `50051`. This is used for communication between Defguard components. * `CoreHttpPort` (optional): The HTTP port on which Defguard Core should listen, default is `8000`. This is where the Defguard web UI will be accessible. * `CoreInstanceType` (optional): The instance type (e.g., `t3.medium`, `m5.large`), default is `t3.micro`. * `CoreLogLevel` (optional): The log level of Defguard Core, default is `info`. You can also set it to `error`, `debug` or `trace`. * `CoreUrl` (required): The URL where Defguard Core will be accessible (e.g., `https://defguard.example.com`). This should be the URL that users will use to access the Defguard web interface. * `CoreDefaultAdminPassword`: The password for the default `admin` user. Used to login to the web dashhboard. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#database) Database * `DbInstanceClass` (optional): The instance class for the PostgreSQL database, default is `db.t3.micro`. * `DbName` (optional): The name of the PostgreSQL database, default is `defguard`. * `DbPassword`: The password for the PostgreSQL database. * `DbPort` (optional): The port on which the PostgreSQL database will listen, default is `5432`. * `DbStorage` (optional): The storage size for the PostgreSQL database, default is `20`. This is the size in GB. * `DbUsername` (optional): The username for the PostgreSQL database, default is `defguard`. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) Gateway Instance * `GatewayInstanceType` (optional): The instance type for the Gateway, default is `t3.micro`. * `GatewayLogLevel` (optional): The log level for the Gateway, default is `info`. You can also set it to `error`, `debug` or `trace`. * `GatewaySecret` (required): The secret used to authenticate the Gateway with Defguard Core. This should be a strong, random string, 64 characters long. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#proxy-instance) Proxy Instance * `ProxyGrpcPort` (optional): The gRPC port for the Proxy, default is `50051`. * `ProxyHttpPort` (optional): The HTTP port for the Proxy, default is `8000`. This is where the Defguard Proxy web UI will be accessible. The proxy UI is used for user enrollment. * `ProxyInstanceType` (optional): The instance type for the Proxy, default is `t3.micro`. * `ProxyLogLevel` (optional): The log level for the Proxy, default is `info`. You can also set it to `error`, `debug` or `trace`. * `ProxyUrl` (required): The URL where the Defguard Proxy will be accessible (e.g., `https://proxy.defguard.example.com`). This should be the URL that users will use to access the Defguard Proxy web UI. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#network-configuration) Network configuration * `VpcCidr` (optional): The CIDR block for the VPC in which Defguard will be deployed, default is `10.0.0.0/16`. * `VpcName` (optional): The name of the VPC, default is `defguard-vpc`. * `PublicSubnet1Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PublicSubnet2Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet1Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet2Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#vpn-network-location-configuration) VPN Network (Location) configuration * `VpnNetworkAddress` (optional): The CIDR address for the VPN network, default is `10.10.10.1/24`. The VPN clients will receive IP addresses from this range. The gateway will have the first address in the range. * `VpnNetworkName` (optional): The name of the VPN network (location). This is displayed both to the clients and in the Defguard web UI, default is `vpn1`. * `VpnNetworkNat` (optional): If set to `true`, the VPN will have masquerading enabled, allowing clients to access other networks through the VPN (e.g., the internet). Default is `true`. * `VpnNetworkPort` (optional): The UDP port on which the VPN will listen for incoming VPN connections, default is `51820`. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#customizing-the-deployment) Customizing the deployment By default, the CloudFormation template will deploy Defguard with the settings according to the recommended architecture, that is: Component Port Access allowed from Core 8000 (HTTP) Gateways Core 50055 (gRPC) Gateways Proxy 50051 (gRPC) Core Proxy 8000 (HTTP) Anywhere Gateway 51820 (UDP) Anywhere You can customize the deployment by modifying the template or doing changes in the AWS Infrastructure Composer. To modify an existing stack deployed from the template, you can use the AWS Console, navigate to the CloudFormation service, select your stack, click on "Update stack" and then choose "Create a change set". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2Fk52OtKW3tSqT8S6k5cba%2Fimage-5.png&width=768&dpr=3&quality=100&sign=478f1b65&sv=2) alt text Next, select how you want to update the stack. If you want to modify the parameters, select "Use existing template". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FOglwrnBEzPUsCEQNBNaV%2Fimage-8.png&width=768&dpr=3&quality=100&sign=6e1a73d5&sv=2) alt text If you want to modify the template itself, the easiest way is to edit it in the Infrastructure Composer: select "Edit in Infrastructure Composer" and click the "Edit in Infrastructure Composer" button. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FhV8M41NvClwpR0W52C8j%2Fimage-9.png&width=768&dpr=3&quality=100&sign=8dfecd4f&sv=2) alt text ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#accessing-the-ec2-instances) Accessing the EC2 instances After deploying the CloudFormation template, the newly created EC2 instances should be visible in the AWS console in your target region: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252F6eD8nIoqLIpkVDpbyC7O%252Fimage3333.png%3Falt%3Dmedia%26token%3D77eada6a-c082-4857-a5ca-b63c2484f30e&width=768&dpr=3&quality=100&sign=2cca7fe6&sv=2) To access the instances, use the key provided in the `SshKeyName` parameter. Note that you will need to allow SSH access to the EC2 instances using their respective AWS security groups. The default user is `admin`. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#upgrading-components) Upgrading components ----------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation It's important to backup your database before performing a backup. Make sure to also check the [Migration guides](https://docs.defguard.net/1.5/deployment-strategies/upgrading) before upgrading to a newer version. All Defguard components are installed from the Defguard APT repository. The upgrade process is as follows: 1. SSH into the given component's EC2 instance 2. Execute the following commands: Copy sudo apt update sudo apt install --only-upgrade The corresponding package names can be found in the [Defguard APT repository documentation](https://docs.defguard.net/1.5/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation#troubleshooting-and-common-issues) Troubleshooting and common issues ------------------------------------------------------------------------------------------------------------------------------------------------------------------- All Defguard components are deployed as systemd services. Their configuration files can be found on the respective host machine under `/etc/defguard`. [PreviousTerraformchevron-left](https://docs.defguard.net/1.5/deployment-strategies/terraform) [NextConfiguring HTTPS using AWS Certificate Managerchevron-right](https://docs.defguard.net/1.5/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) Last updated 2 months ago --- # Using a userspace wireguard-go implementation | 1.5 | defguard Gateway currently supports using `wireguard-go`, a userspace WireGuard implementation. This approach is **not recommended** on platforms where a native support exists (e.g. Linux). You can enable the userspace implementation by setting the `userspace` config option or a corresponding `DEFGUARD_USERSPACE` environment variable to `true`. Because `wireguard-go` is not bundled by default with Defguard, it must be installed separately. The `wireguard-go` binary/command must be available on the host machine for it to function properly. On Docker, this currently requires building a custom image, as the base gateway images also don't come with `wireguard-go` pre-installed. This can be achieved as follows: Copy FROM golang:1.24.6-alpine AS builder RUN apk add --no-cache git make RUN git clone https://git.zx2c4.com/wireguard-go /src/wireguard-go \ && cd /src/wireguard-go \ && make # Specify the desired Gateway's version here FROM ghcr.io/defguard/gateway:latest COPY --from=builder /src/wireguard-go/wireguard-go /usr/local/bin/wireguard-go RUN chmod +x /usr/local/bin/wireguard-go Note that when running the Docker container with a userspace implementation on a Linux host, the container requires a `NET_ADMIN` capability and access to `/dev/net/tun`, this can be set in a Docker compose: Copy # Docker compose cap_add: - NET_ADMIN devices: - /dev/net/tun Or via the command line: Copy docker run --cap-add=NET_ADMIN --device=/dev/net/tun [...] [PreviousMigration guideschevron-left](https://docs.defguard.net/1.5/deployment-strategies/upgrading) [NextPre-production and development releaseschevron-right](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases) Last updated 4 months ago --- # High Availability and Failover | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#gateway-high-availability) Gateway - High Availability -------------------------------------------------------------------------------------------------------------------------------------------------------- We support running multiple gateways for a single VPN instance or location, enabling active-passive configurations. Active-active configurations should also be possible but come with some caveats. Since our gateway uses a vanilla kernel WireGuard®, there are multiple approaches for implementation. circle-info Please also see documentation of [Creating a New VPN location](https://docs.defguard.net/1.5/features/wireguard/create-your-vpn-network) where each [location setting has information regarding high-availability](https://docs.defguard.net/1.5/features/wireguard/create-your-vpn-network#vpn-location-settings) . #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#deploying-multiple-gateways-for-one-location) Deploying multiple gateways for one location To have a multi-gateway setup for a given location, you will need to [deploy the gateway on each one of your servers](https://docs.defguard.net/1.5/deployment-strategies/gateway) under the same location. If you already have a gateway deployed and want to add another one for the location, go to _VPN Overview_ -> Click: _Edit Location Settings (in the top right corner)_, then choose the location you want to add the new gateway to, and follow the deployment instructions: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FRRYVGBnE3OkkkqxNxwj0%2FScreenshot%25202024-11-12%2520at%252016.55.55.png&width=768&dpr=3&quality=100&sign=b2e39557&sv=2) Each gateway deployed for a given location will receive the same network configuration and will **bind to the defined port** in the location's _Gateway Port._ The only thing left to do is to point your traffic to those gateways, which can be accomplished in several ways: * Floating public IP - if you choose this scenario, please remember that the IP must be the IP specified in the Location _Gateway Address._ In this scenario, the floating IP switches between your gateway servers, directing the traffic to one of the two gateways. * Proxy/load balancing - also remember that the proxy must be configured with the _Gateway Address and Gateway Port._ In this scenario, your clients connect to the proxy/load balancer, which direct the VPN traffic (UDP) to one of your gateway backends_._ #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#active-active-setups) Active-active setups Active-active setups should also be possible but come with some caveats. Here are the currently known issues with such configurations: * Multiple running gateways bound to one location with network traffic distributed between them may produce invalid network usage statistics, making the network usage graphs and displays on the dashboard unreliable. Related issue: [https://github.com/DefGuard/defguard/issues/1022arrow-up-right](https://github.com/DefGuard/defguard/issues/1022) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) Determining if multiple gateways are running All gateways that are successfully connected for the location are displayed under the Location in VPN Overview, here is an example for two gateways: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FJrlcfRwIqubgkAHDxFre%2Flocation-overview.png&width=768&dpr=3&quality=100&sign=5841fb07&sv=2) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) What is the gateway peers persistence (if core/proxy services fail) 1. For **VPN Locations without MFA** - it's persistent until the system reboot - _even if the gateway will not work_ - as the gateway configures WireGuard "in kernel". 2. For **VPN Locations with MFA**, this depends on the _Peer Disconnect Threshold (seconds)_ setting in the VPN Location settings. This setting specifies that if the peer is inactive for _(defined seconds)_, the gateway should remove it from the configuration. Therefore, if the proxy/core is not operational, MFA authentication will fail, and the peer will not be added if it is disconnected. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#core-proxy-failover) Core / Proxy - Failover ---------------------------------------------------------------------------------------------------------------------------------------------- The core service handles gateway states as well as core connects _**to the proxy**_. Since proxy serves HTTP based protocol communication and should be in the public Internet, it needs to be secure, thus core connects to the proxy. This way **core can be in an Intranet network segment and proxy can be in DMZ, making Core completely cut-off on firewall from the Internet** (you only can have only outgoing firewall rules from Intranet allowing only for core to connect to proxy). So **High Availability for core and proxy** gets complicated, with multiple proxies core needs to manage those connections. We already have most of the code for that ready, but it's not yet production ready. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#how-to-bullet-proof-proxy-and-core-with-failover) How to bullet-proof proxy & core with failover? We recommend to deploy them on a failover solution - like on a kubernetes cluster (even small one - like mini-kube) . This way, Kubernetes manages: healthchecks and does failover. You can have cluster N-nodes and if any VM/node with Core/Proxy goes offline or health checks fail - it's migrated to a new node. [PreviousReverse Proxy configuration using Nginxchevron-left](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx) [NextUpdating and version compatibilitychevron-right](https://docs.defguard.net/1.5/deployment-strategies/updating-and-version-compatibility) * [Gateway - High Availability](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#gateway-high-availability) * [Determining if multiple gateways are running](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) * [What is the gateway peers persistence (if core/proxy services fail)](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) * [Core / Proxy - Failover](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover#core-proxy-failover) sun-brightdesktopmoon sun-brightdesktopmoon --- # Updating and version compatibility | 1.5 | defguard Each service in the Defguard stack can be updated independently, provided the components remain compatible. When components connect, Defguard automatically performs a version check. If an incompatibility is detected, the connection is refused and it will be clearly reported both in the log files and through a dialog in the core UI: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FcSrZVRythT25fAEBrofO%252Fimage.png%3Falt%3Dmedia%26token%3D9fc3384d-d372-40d1-b2dd-a5308d248982&width=768&dpr=3&quality=100&sign=66d46076&sv=2) circle-exclamation **Note on Multiple Gateways per Location** If you configure more than one gateway for the same location, they will overwrite each other’s incompatibility data. This happens because location is currently used as the identifier for gateways. This limitation will be resolved once full high-availability (HA) support is implemented. It's recommended to always use newest version of services and update them all together to avoid incompatibility. Check the GitHub repositories for each service to find their newest releases and release notes. * Docker - For Docker and Kubernetes based setup just change docker image version for service you want to update. * Packages(DEB, RPM, etc.) - Currently we don't have any package repository so if you want to update your service installed as package you have to download new version from service repository. **GitHub Repositories:** * [Defguard Corearrow-up-right](https://github.com/DefGuard/defguard/releases) * [Defguard Proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) * [Defguard Gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) * [Defguard YubiBridgearrow-up-right](https://github.com/DefGuard/YubiKey-Provision/releases) [PreviousHigh Availability and Failoverchevron-left](https://docs.defguard.net/1.5/deployment-strategies/high-availability-and-failover) [NextMigration guideschevron-right](https://docs.defguard.net/1.5/deployment-strategies/upgrading) Last updated 5 months ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Migration guides | 1.5 | defguard circle-exclamation Before doing any updates please remember to **backup your database.** [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) 1.4.x -> 1.5.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core) Core #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#version-compatibility) Version compatibility This release introduces a version checking system. All the Defguard system components (core, proxy, gateway and clients) are now version-aware and check their compatibility with the components their are communicating with. This might mean that until you upgrade all the components your web UI might indicate that your proxy or gateway is of an unknown version. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#instance-uuid-bug) Instance UUID bug A bug resulting in zeroing the UUID of a given instance has been found and resolved ([PR linkarrow-up-right](https://github.com/DefGuard/defguard/pull/1521) ). This value is used by the desktop client to identify instances. The new client should gracefully handle migration to a new UUID if it has been zeroed out due to the bug mentioned above. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#verify-client-disconnect-threshold-for-your-mfa-locations) Verify client disconnect threshold for your MFA locations In order to ensure that MFA works correctly with the new [mobile clients](https://docs.defguard.net/1.5/using-defguard-for-end-users/mobile-client) please ensure that the [client disconnect threshold](https://docs.defguard.net/1.5/features/wireguard/create-your-vpn-network#client-disconnect-threshold) is set to at least 300s (5 minutes). ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#proxy) Proxy We've introduced a new functionality to Desktop Client - to authenticate [Multi-Factor connections using Mobile Client](https://docs.defguard.net/1.5/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa) . For this feature to work, Proxy (enrollment service) creates a Web-socket that the desktop client connects to while waiting for responses from the mobile client. circle-exclamation If you have a reverse proxy for the enrollment service (which we highly recommend with SSL termination), please **make sure that web-sockets are enabled.** ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client) Desktop client #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#unix-socket-ipc-and-new-user-group-requirement-macos-and-linux) Unix socket IPC and new user group requirement (macOS & Linux) macOS and Linux clients now use Unix sockets for IPC. To securely access this socket the user must belong to a specific group as described in [client documentation](https://docs.defguard.net/1.5/using-defguard-for-end-users/desktop-client) . The change should require no additional steps for macOS users, but Linux users who install the client from official packages will need to log out and back in or reboot after install to refresh group membership. This will not be required on subsequent updates. Linux users who use release binaries will need to manually create the `defguard` group and adjust their group membership. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) Any release <= 1.3 -> 1.4 -------------------------------------------------------------------------------------------------------------------------------------------------- 1.4 release introduces changes related to multiple client IP addresses. To ensure compatibility, **all components must be updated** to v1.4 or higher: * **Core** * **Proxy** * **Gateway** * **Desktop Clients** Running outdated versions may result in errors due to incompatible data formats. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-1) Core We've made a small update to the LDAP integration to support more complex user nesting within the LDAP tree ([related issuearrow-up-right](https://github.com/DefGuard/defguard/issues/1242) ). If you were already using the integration, you shouldn't notice any changes. However, we **strongly recommend backing up your database before the upgrade and afterwards verifying** the following to ensure everything continues to work as expected: * Your Defguard user list and user devices remain unchanged * All users can still log in without issues If you encounter any problems, please report them on our [GitHubarrow-up-right](https://github.com/DefGuard/defguard/issues) . [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) Any previous release → 1.4.0-alpha3 --------------------------------------------------------------------------------------------------------------------------------------------------- We've introduced some changes to the LDAP integration. We recommend reading [the above section](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core) before upgrading. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-release-1.3.0) Any previous release → 1.3.0 ------------------------------------------------------------------------------------------------------------------------------------- * The LDAP integration has become an enterprise feature. You will need to purchase the enterprise license if you exceed the free limits. See [License](https://docs.defguard.net/1.5/enterprise/license) for more information regarding the license. * If you used the LDAP integration previously, it will be off by default after upgrading. You will have to manually enable it in the settings in the LDAP tab:\\ ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FN20K3zCIwtGSj1psXztD%2Fimage.png&width=768&dpr=3&quality=100&sign=f5fb9acb&sv=2) [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) Any previous 1.3.0 alpha → 1.3.0 alpha 4 ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-2) Core LDAP integration received a major overhaul of how users are mapped to Defguard users when the two-way synchronization is enabled. Now, users are always identified by their leftmost DN value. A new synchronization may cause some of your users to be re-added, which in turn may cause the loss of some of their Defguard specific data (e.g. their devices). This will happen if your leftmost DN component's attribute (referred to as RDN) is not the same as your current username attribute. This issue is only related to the two-way synchronization mechanism and occurs only if you used one of the previous alphas of 1.3.0. Upgrading from any previous release to alpha 4 (skipping the alphas before) should not result in this happening. Before an upgrade, turn off the two-way synchronization. After upgrading, you will have access to a new option, the RDN user attribute: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2FSeXryDKJ8yj1tVNrDaeu%2Fimage.png&width=768&dpr=3&quality=100&sign=bc685ebb&sv=2) Set it according to your LDAP server setup. This should be the DN's leftmost component attribute, e.g. in the case of `cn=user1,cn=users,dc=ad,dc=example,dc=com` this would be "cn". This attribute is needed to properly identify users in your LDAP server. The username attribute will be mapped to Defguard usernames. Read [Settings table](https://docs.defguard.net/1.5/features/ldap-and-active-directory-integration/settings-table) for a description of those settings options. After you configured this value, you can re-enable the two-way synchronization. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) Any previous core release -> core 1.1.4 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-3) Core triangle-exclamation In Core 1.1.4, we've made email addresses case insensitive, as this is a standard for many major providers. Because the emails were case sensitive up to this point, you may end up with users with the same email addresses from core's point of view. All email addresses must be unique case-insensitively, meaning that a user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) ` can't coexist with another user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) `. Before upgrading, make sure you don't have any users with the same email addresses given the above. If you do, please change those addresses or remove the users altogether. Remember to check it case-insensitively. If you have users with duplicate email addresses, the migrations will fail, and you won't be able to upgrade. You can use the following SQL query to locate users with duplicate emails in the database: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) 1.0.0 -> 1.1.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#proxy-1) Proxy There is a new setting: * ENV Variable: DEFGUARD\_PROXY\_URL * command line argument `--url` * /etc/defguard/proxy.toml: `url =` **Which should be set to the same value as in core** `**DEFGUARD_ENROLLMENT_URL**` [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-release-greater-than-1.0.0) Any release -> 1.0.0 --------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-4) Core When upgrading core to 1.0.0 (even to a 1.0.0 pre-release) make sure that your users **have unique email addresses** as we've introduced a constraint requiring email addresses to be unique among users. triangle-exclamation If you have duplicate emails in your database, the migrations during the upgrade process will simply fail. You will need to change a duplicate email address before the upgrade by hand via the Defguard dashboard or by accessing the database. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client-real-time-sync) Desktop Client Real Time Sync From 1.0.0 we have introduced [Enterprise featuresarrow-up-right](https://github.com/DefGuard/docs/blob/docs/deployment-strategies/broken-reference/README.md) , and one of them is [automatic and real-time desktop client configuration synchronization](https://docs.defguard.net/1.5/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration) . To enable this on an **already configured desktop client,** one must perform one time instance update, which will generate necessary tokens on the client to perform from now on automatic updates. In details: 1. The admin must generate a new token for the client - [more details here](https://docs.defguard.net/1.5/features/wireguard/remote-desktop-activation) (token can be sent over email or shared in any other secret way). 2. The user must perform the [Instance Update - more details here](https://docs.defguard.net/1.5/using-defguard-for-end-users/desktop-client/instance-configuration#updating-instance) . circle-exclamation Any client that is configured from scratch has this done automatically and no actions needed to be done. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In this release, we have **hardened the security architecture**, and since the Proxy component is open for HTTP commands and is frequently communicating with Core we have reversed the communication and now **Core is connecting to Proxy (Proxy is a gRPC server and Core is the client).** This way if Core is in a secure network segment (like Intranet) and Proxy in a DMZ segment (where Internet traffic is allowed) you don't need to open on your firewall rules for Proxy from DMZ to connect to Intranet (no packet for New Connections from DMZ->Intranet). This change requires a few changes if you are upgrading: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#proxy-deployment-configuration) Proxy deployment configuration 1. Remove `DEFGUARD_PROXY_UPSTREAM_GRPC_URL` variable - since Proxy does not connect to Defguard Core any more. 2. Proxy is now the server to which Defguard Core connects, so you may want to: 1. Optional: configure non-default Proxy gRPC port with `DEFGUARD_PROXY_GRPC_PORT -` default value is **50051** 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/treafik/...) the port with SSL/TLS. 1. (Optional) If you want to use SSL with Proxy gRPC server without revers-proxy (nginx/etc) configure `DEFGUARD_PROXY_GRPC_CERT` and `DEFGUARD_PROXY_GRPC_KEY` following the [SSL setup guide](https://docs.defguard.net/1.5/deployment-strategies/docker-compose#grpc-ssl-setup) . 3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server **can be reached from Core**. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-deployment-configuration) Core deployment configuration 1. Add `DEFGUARD_PROXY_URL` variable to point to your Proxy gRPC server endpoint, for example `http://proxy:50051` when using Docker Compose - or any gRPC URL you have configured with your reverse proxy. 2. (Optional) If using SSL configure `DEFGUARD_PROXY_GRPC_CA` #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#upgrade-process) Upgrade process 1. Update Core & Proxy images/binaries and restart services. 2. You should see in the logs that Proxy is awaiting a gRPC connection - example docker logs: 1. Core should be attempting to establish a gRPC connection with Proxy (and retrying every 10s if unable to successfully connect), like this: 1. After Defguard connects successfully to proxy, you should see in proxy logs: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) Desktop Client 0.1.x -> 0.2.0 --------------------------------------------------------------------------------------------------------------------------------------------------- With this release we have added Multi-Factor Authentication to the desktop client. Unfortunately desktop client database has change significantly as well as business logic (for example endpoints to proxy for MFA handshake). We have not stored them previously in the database - thus they cannot be recovered/updated automatically. circle-exclamation That unfortunately means you have to remove all your instances before upgrading (or just remove any desktop client configuration files, including the database) and start the enrollment (adding new instance) again after upgrading - just by adding a new device (you can remove the old one). [PreviousUpdating and version compatibilitychevron-left](https://docs.defguard.net/1.5/deployment-strategies/updating-and-version-compatibility) [NextUsing a userspace wireguard-go implementationchevron-right](https://docs.defguard.net/1.5/deployment-strategies/using-a-userspace-wireguard-go-implementation) Last updated 3 months ago * [1.4.x -> 1.5.0](https://docs.defguard.net/1.5/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) * [Core](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core) * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/upgrading#proxy) * [Desktop client](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client) * [Any release <= 1.3 -> 1.4](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) * [Core](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-1) * [Any previous release → 1.4.0-alpha3](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) * [Any previous release → 1.3.0](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-release-1.3.0) * [Any previous 1.3.0 alpha → 1.3.0 alpha 4](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) * [Core](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-2) * [Any previous core release -> core 1.1.4](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) * [Core](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-3) * [1.0.0 -> 1.1.0](https://docs.defguard.net/1.5/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/upgrading#proxy-1) * [Any release -> 1.0.0](https://docs.defguard.net/1.5/deployment-strategies/upgrading#any-release-greater-than-1.0.0) * [Core](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-4) * [Desktop Client Real Time Sync](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client-real-time-sync) * [Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x](https://docs.defguard.net/1.5/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) * [Desktop Client 0.1.x -> 0.2.0](https://docs.defguard.net/1.5/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) sun-brightdesktopmoon Copy select id, username, email from "user" where lower(email) in ( select lower(email) from "user" group by lower(email) having count(*) > 1 ) Copy Attaching to defguard_proxy_1 proxy_1 | 2024-01-24T14:05:41.365035Z INFO defguard_proxy::server: Starting Defguard proxy server proxy_1 | 2024-01-24T14:05:41.365069Z DEBUG defguard_proxy::server: Setting up API server proxy_1 | 2024-01-24T14:05:41.365130Z INFO defguard_proxy::server: gRPC server is listening on 0.0.0.0:50051 proxy_1 | 2024-01-24T14:05:41.365333Z INFO defguard_proxy::server: Web server is listening on 0.0.0.0:8080 Copy defguard | 2024-01-24T14:17:47.815294Z INFO defguard::grpc: Connecting to proxy Copy proxy_1 | 2024-01-24T14:17:47.819504Z INFO defguard_proxy: RPC client connected from: 10.123.123.2:35916 sun-brightdesktopmoon --- # Pre-production and development releases | 1.5 | defguard To test any pre-production or development release: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#one-line-install) One-line install The simplest way to test the latest development or pre-release version is to use one line installation method with the appropriate argument. More on that in [the one-line install documentation](https://docs.defguard.net/1.5/getting-started/one-line-install) . ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) Binaries and packages Each GitHub repository ([corearrow-up-right](https://github.com/DefGuard/defguard/releases) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) , [proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) , and [clientarrow-up-right](https://github.com/DefGuard/client/releases) ) has its **pre-release versions** available on the GitHub release page. This is where you can download binaries or packages with the pre-release, e.g.: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FkHPDOBrb5X1TB8O3GsjW%2Fblobs%2F0nq5R7HBS13i2h4ak9xN%2FScreenshot%25202025-08-01%2520at%252013.38.44.png&width=768&dpr=3&quality=100&sign=3fb255e6&sv=2) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#docker-images) Docker images Each Docker image for [corearrow-up-right](https://github.com/DefGuard/defguard/pkgs/container/defguard) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/pkgs/container/gateway) and [proxyarrow-up-right](https://github.com/DefGuard/proxy/pkgs/container/defguard-proxy) has the following tags: * `pre-release` – this tag is for the **latest pre-production release** - which also contains a version in form of `vX.Y.Z-alpha/beta/rcX` from the `main` branch * `dev` – this tag is for the latest development release from the `dev` branch. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#docker-compose) Docker compose Please change the Docker compose file to match the version or tags as stated above. [PreviousUsing a userspace wireguard-go implementationchevron-left](https://docs.defguard.net/1.5/deployment-strategies/using-a-userspace-wireguard-go-implementation) [NextSecuring gRPC communicationchevron-right](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) * [One-line install](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#one-line-install) * [Binaries and packages](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) * [Docker images](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases#docker-images) sun-brightdesktopmoon sun-brightdesktopmoon --- # Securing gRPC communication | 1.5 | defguard Defguard components exchange data over gRPC, which must be properly secured to protect sensitive information and prevent unauthorized access. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#firewall-rules) Firewall rules ------------------------------------------------------------------------------------------------------------------------ Defguard components expose two ports that require firewall-level protection: * Defguard Core exposes a gRPC port for communication with Defguard Gateways. * Defguard Proxy exposes a gRPC port for communication with Defguard Core. Limit access to gRPC ports: * Allow Core’s gRPC port only from Gateway IPs. * Allow Proxy’s gRPC port only from Core’s IP. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#ssl-encryption) SSL encryption ------------------------------------------------------------------------------------------------------------------------ Even if you already use [SSL on a reverse proxy](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) , this only protects external traffic. Internal gRPC connections between Proxy, Core, and Gateways occur behind the proxy and must also be encrypted and authenticated. These connections carry sensitive operational data and should never be left unprotected. You can **choose one** of two approaches: * [Trusted CA certificates](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#trusted-ca-certificates) (encryption only) - use certificates issued by a recognized Certificate Authority (e.g., Let’s Encrypt). This approach provides encrypted traffic. * [Custom internal CA](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-internal-ca) (encryption + authentication) - create your own Certificate Authority and issue certificates for Core, Proxy, and Gateway. This setup enables mutual TLS (mTLS), meaning each component both encrypts and authenticates the connection - ensuring that only trusted Defguard services can communicate with each other. Choose one of these options based on your environment: trusted CA for simplicity, or a custom CA for full Zero Trust mutual authentication. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#trusted-ca-certificates) Trusted CA certificates If you followed our [guide on configuring SSL for reverse proxy](https://docs.defguard.net/1.5/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) your certificates should be located in the following path `/etc/letsencrypt/live/domain.name/`. Use the PEM-formatted CA certificate for configuring Defguard components. circle-exclamation While this secures the transport layer and encrypts communication between Defguard components - it does not provide authorization between gRPC components like [Custom internal CA](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-internal-ca) does. Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#configure-defguard-core) Configure Defguard Core Add path to CA certificate file using command line arguments: or using the service's configuration file: or using environment variable: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#configure-defguard-gateway) Configure Defguard Gateway Add path to CA certificate file using command line arguments: or using the service's configuration file: or using environment variable: ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-internal-ca) Custom internal CA circle-exclamation It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one **under which a service is being hosted**. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#generate-certificates) Generate certificates To quickly generate a set of SSL certificates using [OpenSSLarrow-up-right](https://openssl-library.org/) or [LibreSSLarrow-up-right](https://www.libressl.org/) , use the following: * Generate Certificate Authority (CA) certificate and key for domain _example.local_ * Generate private key and Certificate Signing Request (CSR) * Generate certificate by signing the CSR, valid for 365 days circle-info Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly. To display certificate file contents: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#configure-defguard-core-1) Configure Defguard Core Add paths to certificate files using command line arguments: or using the service's configuration file: or using environment variables: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#configure-defguard-proxy) Configure Defguard Proxy Add paths to certificate files using command line arguments: or using the service's configuration file: or using environment variables: #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#configure-defguard-gateway-1) Configure Defguard Gateway Add paths to certificate files using command line arguments: or using the service's configuration file: or using environment variables: [PreviousPre-production and development releaseschevron-left](https://docs.defguard.net/1.5/deployment-strategies/pre-production-and-development-releases) [NextUsing RSA instead of HMAC for OpenID keychevron-right](https://docs.defguard.net/1.5/deployment-strategies/openid-rsa-key) Last updated 3 months ago * [Firewall rules](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#firewall-rules) * [SSL encryption](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#ssl-encryption) * [Trusted CA certificates](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#trusted-ca-certificates) * [Custom internal CA](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication#custom-internal-ca) sun-brightdesktopmoon Copy defguard --proxy-grpc-ca /etc/letsencrypt/live/domain.name/chain.pem Copy proxy_grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem" Copy env DEFGUARD_PROXY_GRPC_CA=/etc/letsencrypt/live/domain.name/chain.pem \ defguard Copy defguard-gateway --grpc-ca /etc/letsencrypt/live/domain.name/chain.pem Copy grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem" Copy env DEFGUARD_GRPC_CA=/etc/letsencrypt/live/domain.name/chain.pem \ defguard-gateway Copy openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt Copy openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local Copy openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy Copy openssl x509 -noout -text -in core.crt Copy defguard --grpc-cert path/to/core.crt \ --grpc-key path/to/core.key \ --proxy-grpc-ca path/to/ca.crt Copy grpc_cert = "path/to/core.crt" grpc_key = "path/to/core.key" proxy_grpc_ca = "path/to/ca.crt" Copy env DEFGUARD_GRPC_CERT=path/to/core.crt \ DEFGUARD_GRPC_KEY=path/to/core.key \ DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \ defguard Copy defguard-proxy --grpc-cert path/to/proxy.crt \ --grpc-key path/to/proxy.key Copy grpc_cert = "path/to/core.crt" grpc_key = "path/to/core.key" Copy env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \ DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key defguard-proxy Copy defguard-gateway --grpc-ca path/to/ca.crt Copy grpc_ca = "path/to/ca.crt" Copy env DEFGUARD_GRPC_CA=path/to/ca.crt \ defguard-gateway sun-brightdesktopmoon --- # Using RSA instead of HMAC for OpenID key | 1.5 | defguard By default, Defguard uses [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation and the. If you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) , you'll have to configure the Defguard core `DEFGUARD_OPENID_KEY` configuration variable with the path to the RSA private key. You can generate the RSA key with: Copy openssl genpkey -out /path/to/rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096 [PreviousSecuring gRPC communicationchevron-left](https://docs.defguard.net/1.5/deployment-strategies/grpc-ssl-communication) [NextHealth checkchevron-right](https://docs.defguard.net/1.5/deployment-strategies/health-check) sun-brightdesktopmoon sun-brightdesktopmoon --- # Health check | 1.5 | defguard [hashtag](https://docs.defguard.net/1.5/deployment-strategies/health-check#proxy) Proxy -------------------------------------------------------------------------------------------- [Proxyarrow-up-right](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application is running. Example request: Copy curl "https://enroll.example.com/api/v1/health" Response: Copy "alive" - with status code 200 - Proxy is working To verify gRPC services for **Proxy** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. Example request: Copy curl "https://enroll.example.com/api/v1/health-grpc" Response: Copy "alive" with status code 200 - Proxy is working and is connected to CORE "Not connected to Defguard Core" - with status code 503 - Proxy is working but is not connected to CORE [hashtag](https://docs.defguard.net/1.5/deployment-strategies/health-check#core) Core ------------------------------------------------------------------------------------------ To check if [**Core**arrow-up-right](https://github.com/defguard/defguard) is working, you can use endpoint at `GET /api/v1/health` which verify it. Example request: Copy curl "https://defguard.example.com/api/v1/health" Response: To check if core gRPC service is alive, we recommend to use community tools like [grpc\_health\_probearrow-up-right](https://github.com/grpc-ecosystem/grpc-health-probe) . Example request for core: Example response: [hashtag](https://docs.defguard.net/1.5/deployment-strategies/health-check#gateway) Gateway ------------------------------------------------------------------------------------------------ You can enable in gateway config ([example configarrow-up-right](https://github.com/DefGuard/gateway/blob/main/example-config.toml) ) a health check port, by adding the following line: In this example, gateway will open an additional HTTP port number 55003. Now we can use `GET /api/v1/health` endpoint to verify whether gateway is working correctly. Example request: Response: By default, no health check ports are open. [PreviousUsing RSA instead of HMAC for OpenID keychevron-left](https://docs.defguard.net/1.5/deployment-strategies/openid-rsa-key) [NextProduction deployment verification guidechevron-right](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide) Last updated 4 months ago * [Proxy](https://docs.defguard.net/1.5/deployment-strategies/health-check#proxy) * [Core](https://docs.defguard.net/1.5/deployment-strategies/health-check#core) * [Gateway](https://docs.defguard.net/1.5/deployment-strategies/health-check#gateway) sun-brightdesktopmoon Copy "alive" - with status code 200 - Core is working Copy ./grpc_health_probe -addr=defguard.example.com:50055 Copy status: SERVING Copy health_port = 55003 Copy curl "http://gateway.example.com:55003/api/v1/health" Copy "alive" - with status code 200 - Gateway is working and is connected to CORE "Not connected to core" - with status code 503 - Gateway is working but is not connected to CORE sun-brightdesktopmoon --- # Overview | 2.0 | defguard Welcome to the deployment strategies section of Defguard documentation. This guide covers the different ways you can deploy Defguard in your environment, from quick options using packages or Docker to more advanced setups with Kubernetes or Terraform. Whether you're running a small instance or preparing for a more complex production environment, this section will help you choose the deployment method that best fits your needs. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#before-you-begin) Before you begin ------------------------------------------------------------------------------------------------------------------------------ 1. Make sure you understand [Defguard's architecture](https://docs.defguard.net/2.0/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. 2. Make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) Initial deployment sequence ---------------------------------------------------------------------------------------------------------------------------------------------------- Before deploying any Gateways, you must first install and configure the Core service. The Core acts as the central control plane - it manages configuration, authentication, and communication with all connected Gateways. Once the Core is running and accessible, log in to the admin interface and navigate to the Gateways section. Create a new Gateway entry to generate a unique registration token. This token will be used during the Gateway deployment process to securely link the Gateway instance with your Core. After obtaining the token, proceed with deploying the Gateway service. During its initial setup, provide the generated token so that the Gateway can authenticate and register itself with the Core. Once registration is complete, the Gateway will appear in the Core dashboard and start receiving configuration updates automatically. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#long-story-short) Long story short: 1 **Deploy Defguard Core service.** 2 **Add a new location in Core's web interface and obtain a token.** More on that [here](https://docs.defguard.net/2.0/deployment-strategies/gateway) . 3 **Deploy Gateway configured with the token.** [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) Choose your deployment strategy ------------------------------------------------------------------------------------------------------------------------------------------------------------ Strategy name Difficulty Production readiness Purpose [One-line script](https://docs.defguard.net/2.0/getting-started/one-line-install) 🟢 Easy, single command installation ❌ Doesn't follow the [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) For testing purposes only [Standalone packages](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation) 🟢 Easy, using apt and dpkg ✅ If you followed the [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Docker Compose](https://docs.defguard.net/2.0/deployment-strategies/docker-compose) 🟡 Medium, Docker knowledge required ✅ If you followed the [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Kubernetes](https://docs.defguard.net/2.0/deployment-strategies/kubernetes) 🔴 Advanced, requires a k8s cluster and administrator ✅ If you followed the [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) Large or enterprise deployments [Terraform](https://docs.defguard.net/2.0/deployment-strategies/terraform) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [AMI and AWS CloudFormation](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#configure-to-your-needs) Configure to your needs -------------------------------------------------------------------------------------------------------------------------------------------- See our [configuration documentation](https://docs.defguard.net/2.0/deployment-strategies/configuration) to learn about all the settings you can change in your deployment. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#backup) Backup ---------------------------------------------------------------------------------------------------------- [Core servicearrow-up-right](https://github.com/DefGuard/defguard) is the only service which uses persistent data storage, which is PostgreSQL database. Every SQL migration is applied automatically while bringing up core server and we try our best not to break anything in the process. It's recommended to do database, configuration and Settings(SMTP, Branding) backup before every update in case of some unexpected failure. Example database backup: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#failover-ha-clustering) Failover/HA/Clustering ------------------------------------------------------------------------------------------------------------------------------------------ The [Gateway](https://docs.defguard.net/2.0/deployment-strategies/gateway) can be deployed on multiple servers, firewalls, or routers for failover and high availability (HA). Even if the connection to the Core is lost, gateways continue operating using their local cache and data, ensuring that the VPN remains functional. Conversely, if a gateway becomes unavailable, other Core features (such as OpenID) will continue to work normally. For details on deploying multiple Gateway to [High Availability and Failover](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover) documentation. [PreviousGenerating enrollment tokens with Defguard REST APIchevron-left](https://docs.defguard.net/2.0/features/desktop-client-auto-provisioning/generating-enrollment-tokens-with-defguard-rest-api) [NextDeploying to Productionchevron-right](https://docs.defguard.net/2.0/deployment-strategies/deploying-to-production) * [Before you begin](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#before-you-begin) * [Initial deployment sequence](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) * [Choose your deployment strategy](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) * [Configure to your needs](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#configure-to-your-needs) * [Backup](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#backup) * [Failover/HA/Clustering](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#failover-ha-clustering) sun-brightdesktopmoon Copy docker exec {container_name} pg_dump -U {user_name} > {backup_file_name} sun-brightdesktopmoon --- # Production deployment verification guide | 1.5 | defguard This guide helps you verify that your Defguard instance is operational, reachable through the expected network paths, and properly secured. The process will consist of the following steps: 1. Verifying the configuration of your firewall rules. 2. Verifying your DNS resolution. 3. Testing the whole configuration. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------------------------------------- Before proceeding, ensure that you deployed your Defguard environment according to the [recommendations](https://docs.defguard.net/1.5/deployment-strategies/hardware-os-network-and-firewall-recommendations) and that the following components are operational: * 1 server running Defguard Core * Located in an internal network segment (not exposed to the Internet) * Reachable internally under a domain such as defguard.example.com * 1 server running Defguard Proxy * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as proxy.example.com * 1 server running Defguard Gateway * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as vpn.example.com * A workstation with the Defguard Desktop Client installed and configured to test VPN connectivity. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) Verify firewall policies -------------------------------------------------------------------------------------------------------------------------------------------------------------- Confirm that your firewall rules align with Defguard’s secure deployment model. Component Allowed inbound Blocked inbound Notes Core * TCP 443 (from internal/VPN only) * gRPC server port (from Gateway) All public traffic Core should never be directly exposed to the Internet. Proxy * TCP 443 (from public Internet) * gRPC server port (from Core) All other inbound traffic Used for enrollment and client configuration. Gateway * UDP VPN port (from public Internet) All other inbound traffic Only VPN and Core communication should be allowed. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) Verify DNS resolution -------------------------------------------------------------------------------------------------------------------------------------------------------- Proper DNS configuration ensures that each Defguard component resolves to the correct IP address and network zone. Run: Expected results: Domain Expected IP Type Description vpn.example.com Public IP Gateway server reachable from the Internet proxy.example.com Public IP Proxy server for enrollment and configuration defguard.example.com Private/Internal IP Core server, accessible only from internal/VPN network [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-the-environment) Test the environment ------------------------------------------------------------------------------------------------------------------------------------------------------ After you've confirmed the proper network segmentation it's time to test it. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) Testing while disconnected from the VPN Perform the following tests from the workstation where the Defguard Desktop Client is installed. Make sure the client is disconnected before running any commands. In this state: * ❌ You should not be able to reach the Defguard Core server. * ✅ You should be able to reach the Defguard Proxy server. * ✅ You should be able to reach the Defguard Gateway server (UDP port for VPN). #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports) Test: Defguard Core server reachability and ports Check the open ports on your Defguard Core server (replace the example domain with your actual one): Expected output: Interpretation: * The Core server is not reachable when disconnected from the VPN, which is the expected and secure configuration. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-defguard-proxy-server-reachability-and-ports) Test: Defguard Proxy Server Reachability and Ports Check the open ports on your Defguard Proxy server: Expected output: Interpretation: * The host is reachable from the Internet. * Only port 443/tcp is open, as expected for HTTPS access. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-defguard-gateway-server-reachability) Test: Defguard Gateway Server Reachability Check if the Defguard Gateway server is reachable: Expected output: Interpretation: * The host is reachable. * The list of open TCP ports should be empty, as the Gateway primarily uses UDP for VPN connections. * You’ll verify the UDP port functionality in the next step by testing an actual VPN connection. ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) Connecting to the VPN 1. Open the Defguard Desktop Client. 2. Connect to your configured location. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-verify-vpn-connectivity) Test: Verify VPN Connectivity Once connected: 1. Open your browser and navigate to the Defguard Core interface, for example: https://defguard.example.com 2. Sign in using an administrator account. If you can access the web panel, your VPN connection is active and functioning. Then, in the Core UI: * Go to VPN Overview page. You should see your connected device listed there. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F4041812211-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FkHPDOBrb5X1TB8O3GsjW%252Fuploads%252FyWewOYUyfLDWUJloSaPD%252FScreenshot%25202025-10-24%2520at%252011.20.24.png%3Falt%3Dmedia%26token%3D63ffea5d-c4bf-4c99-8683-544adc96692e&width=768&dpr=3&quality=100&sign=198de78e&sv=2) ### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) Testing While Connected to the VPN Perform the following tests again while the Defguard client remains connected. In this state: * ✅ You should be additionally able to reach the Defguard Core server. #### [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports-1) Test: Defguard Core Server Reachability and Ports Check the open ports on your Defguard Core server: Expected output: Interpretation: * The host is reachable via the VPN tunnel. * Port 443/tcp (HTTPS web interface) is open, which confirms proper VPN routing and Core access. [hashtag](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#summary) Summary ---------------------------------------------------------------------------------------------------------------------------- ✅ Firewall policies restrict traffic to approved ports. ✅ DNS records resolve to the expected internal and public addresses. ✅ Core is unreachable from the Internet and reachable only via VPN. ✅ Proxy is publicly reachable only on port 443. ✅ Gateway responds correctly and allows VPN connections. When all verifications and tests pass, your Defguard deployment is operational, properly segmented, and production-ready. [PreviousHealth checkchevron-left](https://docs.defguard.net/1.5/deployment-strategies/health-check) [NextLicensechevron-right](https://docs.defguard.net/1.5/enterprise/license) Last updated 3 months ago * [Prerequisites](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#prerequisites) * [Verify firewall policies](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) * [Verify DNS resolution](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) * [Test the environment](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#test-the-environment) * [Testing while disconnected from the VPN](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) * [Connecting to the VPN](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) * [Testing While Connected to the VPN](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) * [Summary](https://docs.defguard.net/1.5/deployment-strategies/production-deployment-verification-guide#summary) sun-brightdesktopmoon Copy dig +short vpn.example.com dig +short proxy.example.com dig +short defguard.example.com Copy sudo nmap -Pn -sS defguard.example.com Copy Failed to resolve "defguard.example.com". Copy sudo nmap -Pn -sS proxy.example.com Copy Host is up (0.0082s latency). PORT STATE SERVICE 443/tcp open https Copy sudo nmap -Pn -sS vpn.example.com Copy Host is up (0.0082s latency). Copy sudo nmap -Pn -sS defguard.example.com Copy Host is up (0.021s latency). PORT STATE SERVICE 443/tcp open https sun-brightdesktopmoon --- # Deploying to Production | 2.0 | defguard 1 **Gain knowledge** Before you start your deployment, take a moment to learn about Defguard. The following articles will help you make deployment decisions and understand which features you may want to configure afterward. Make sure to read them carefully. * [Defguard's features](https://docs.defguard.net/2.0/about/features-overview) * [Defguard's architecture](https://docs.defguard.net/2.0/in-depth/architecture) 2 **Choose your deployment strategy** Decide which deployment approach best fits your infrastructure and security requirements. Choose from different [deployment strategies](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) and their recommended use cases. 3 **Prepare your environment** Make sure your infrastructure meets all [system and network requirements](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) . 4 **Deploy using the chosen strategy** Deploy your instance using the chosen [strategy](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) . Make sure to follow the right [deployment sequence](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) . 5 **Test if everything works as expected** Follow our [guide](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide) to test if your deployment in secure and works as expected. 6 **Configure features** Follow detailed descriptions of [Defguard's featuresarrow-up-right](https://github.com/DefGuard/docs/blob/v1.6/deployment-strategies/broken-reference/README.md) . As you follow along, you can adjust the configuration directly within your instance. For a detailed list of all configurable things through environmental variables, options or configuration files follow [this reference](https://docs.defguard.net/2.0/deployment-strategies/configuration) . 7 **Your secure infrastructure is ready for use** Optional but recommended additional steps: * [Securing internal gRPC communication](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * [Configuring backups](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#backup) * [Setting up for high availability and failover](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover) [PreviousOverviewchevron-left](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance) [NextHardware, OS, network and firewall recommendationschevron-right](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) sun-brightdesktopmoon sun-brightdesktopmoon --- # Hardware, OS, network and firewall recommendations | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) Server & environment requirements ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Defguard can be deployed on multiple servers (physical or virtual) or on a single server (which is not recommended). Recommended setup reflects the [general system architecture](https://docs.defguard.net/2.0/in-depth/architecture) with components being split into three separate machines: 1. **Dedicated server or Virtual Machine for Core (control plane)** - that is in the Intranet network segment, not exposed in the public Internet in any way. Core needs to be accessible from the local (secure) network and VPN (to access Defguard securely). Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location - eg. if Defguard handles 2 VPN locations recommended is min. 2 CPU/vCPU 2. RAM: min. 1GB per location 3. Disk: min 8GB and more (since statistics will be gathered) 2. **Dedicated server or Virtual Machine for Proxy (external and public enrollment service)** - this server/VM needs to be deployed in DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 1GB 3. **Dedicated server or Virtual Machine for Gateway -** this server/VM needs to be deployed in: 1. DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. 2. Has access on Internal network interfaces to all network segments that will be exposed from VPN for users. 3. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 4GB (mostly for logs) In general the hardware requirements will also have to be adjusted based on the number of active users. The numbers above should serve as a baseline. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) Operating system and software requirements #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#package-based-installation) Package based installation Package based install requires Debian GNU/Linux min. 13.x or Ubuntu Linux min. 24.04.x #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#docker-based-installation) Docker based installation Docker deployment requires the system to have [official Docker Engine installationarrow-up-right](https://docs.docker.com/engine/install/) (not distribution based packages). [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) Network IP & DNS setup -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) Gateway server - where WireGuard VPN tunnels itself will be launched * **The** [**Gateway address**](https://docs.defguard.net/2.0/features/wireguard/create-your-vpn-network) and [**Gateway Port**](https://docs.defguard.net/2.0/features/wireguard/create-your-vpn-network) **must be publicly available from the Internet** circle-exclamation The server on which the Gateway is installed does not need to have the IP address (the same as the Gateway Address) assigned to it - can have internal network address. The Gateway Address is the address specified in the clients’ configuration – therefore, if this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (Gateway Port) must be forwarded (e.g., via NAT) to the Gateway Port on the server where the Gateway is installed.** * must have all networks on internal interfaces addresses configured, that should be accessible from VPN * **Recommended:** to have a public domain assigned to this IP for VPN server, eg. _vpn.company.com_ ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) Proxy - public web service for enrollment & desktop client configuration * **The** [**enrollment URL**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#enrollment-configuration) **(that proxy will be configured under and available for user and clients to reach) needs to be publicly available from the Internet.** circle-exclamation The server on which the Proxy is installed does not need to have the IP address assigned to it which the enrollment URL domain points to - can have internal network address. If this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (eg. if the enrollment URL is https://vpn-config.domain.com, then the port is 443) must be forwarded (e.g., via NAT) to the** [**DEFGUARD\_PROXY\_HTTP\_PORT**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) **on the server where the Proxy is installed.** * **must have a public enrollment domain assigned to this IP,** _**eg. enrollment.company.com (or vpn-config.company.com, etc..**_**)** ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) Core & database server * should be internal / private IP addresses accessible only from Intranet and VPN * must have internal domain name assigned in the local network DNS server, eg. _defguard.company.com_ [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) Firewall settings -------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) Gateway 1. Please open the public port you wish the VPN to be working on - eg. 50555 * Please open on the firewall: local network access **from the Gateway server/VM** → **to Defguard Core gRPC port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) Proxy 1. please open the public 443 port on the server (recommended to rewrite port 80 to redirect to 443) 2. please open gRPC port on the internal network - so that the **Defguard Core can connect to this port - more details here:** [**https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service**arrow-up-right](https://docs.defguard.net/1.5/deployment-strategies/configuration#proxy-service) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) Core 1. please open 443 port for web interface accessible only from local/VPN network 2. please open a gRPC port **for the gateway server to connect to this port - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) Backup strategy ---------------------------------------------------------------------------------------------------------------------------------------------------- In a production environment you should use your preferred backup solution to secure the following: * service configuration (.env file, service config files, compose configuration) * database content (prefferably by doing a regular pgdump, not just filesystem-level backup) [PreviousDeploying to Productionchevron-left](https://docs.defguard.net/2.0/deployment-strategies/deploying-to-production) [NextStandalone package based installationchevron-right](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation) * [Server & environment requirements](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) * [Operating system and software requirements](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) * [Network IP & DNS setup](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) * [Gateway server - where WireGuard VPN tunnels itself will be launched](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) * [Proxy - public web service for enrollment & desktop client configuration](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) * [Core & database server](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) * [Firewall settings](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) * [Gateway](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) * [Core](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) * [Backup strategy](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) sun-brightdesktopmoon sun-brightdesktopmoon --- # Defguard APT repository | 2.0 | defguard ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) Distribution Defguard APT repository provides packages for **Debian 12**, **Debian 13**, and **Ubuntu 22.04/24.04 LTS.** Packages are available on the default `trixie` repository distribution. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) Adding Defguard APT repository To add Defguard APT repository, run following commands in your terminal: Copy sudo apt update sudo apt install -y ca-certificates curl #Add official Defguard public GPG key sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://apt.defguard.net/defguard.asc -o /etc/apt/keyrings/defguard.asc sudo chmod a+r /etc/apt/keyrings/defguard.asc #Add APT repository echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Afterward running these commands, you can install and update Defguard via APT. After new release, simply use `sudo apt update` to update repository. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) Using pre-release builds Defguard has two separate components on one APT repository, **release** and **pre-release.** If you want to install packages from pre-release, simply change `release` to `pre-release` in the installation steps described above, or run the following line. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) Installing packages Defguard Core: Defguard Proxy: Defguard Gateway: Defguard Client: [PreviousStandalone package based installationchevron-left](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation) [NextDocker Composechevron-right](https://docs.defguard.net/2.0/deployment-strategies/docker-compose) * [Distribution](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) * [Adding Defguard APT repository](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) * [Using pre-release builds](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) * [Installing packages](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) sun-brightdesktopmoon Copy echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie pre-release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Copy sudo apt install defguard Copy sudo apt install defguard-proxy Copy sudo apt install defguard-gateway Copy sudo apt install defguard-client sun-brightdesktopmoon --- # Standalone package based installation | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#introduction) 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. circle-info Make sure you understand [Defguard's architecture](https://docs.defguard.net/2.0/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. circle-exclamation This is a simple guide installing all components on a single server. For production make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#system-requirements) 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 servicearrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) (run by proxy) that will enable [remote onboarding, enrollmentarrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) and [easy configuration for our Desktop Clients (by adding Defguard instances)](https://docs.defguard.net/2.0/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 **opened 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 publicly exposed.** * System clock is synchronized using Network Time Protocol (NTP). This is important for time-based one-time password (TOTP) codes. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#installing-a-database) Installing a database ----------------------------------------------------------------------------------------------------------------------------------------------------- Defguard Core uses [PostgreSQLarrow-up-right](https://www.postgresql.org/) 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 `::::` * we connected into the `defguard` database to verify `defguard` user can communicate with the database [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#installing-packages) Installing packages ------------------------------------------------------------------------------------------------------------------------------------------------- circle-info Defguard also have public APT repository, if you want know how to set it up, follow [this guide](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#core) Core You can find the URL to your package from the releases of the Core component on [GitHubarrow-up-right](https://github.com/DefGuard/defguard/releases) . 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 if Defguard Core has been installed properly: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#gateway) Gateway You can find the URL to your package from the releases of Defguard Gateway on [GitHubarrow-up-right](https://github.com/DefGuard/gateway/releases) . 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: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#proxy) Proxy You can find the URL to your package from the releases of Defguard Proxy component on [GitHubarrow-up-right](https://github.com/DefGuard/proxy/releases) . 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: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#running-defguard) Running Defguard ------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#core-1) Core To run core service we need to configure `/etc/defguard/core.conf`. circle-info 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 will use server domain `my-server.defguard.net`. Example `/etc/defguard/core.conf`: **If you have configured PostgreSQL database with different names than in** [**PostgreSQL guide**](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#postgresql) **, 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**](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#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: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#gateway-1) 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`. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#setup-location-for-gateway) Setup location for gateway Follow [this guide](https://docs.defguard.net/2.0/deployment-strategies/gateway) 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. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#create-config-file) Create config file After getting `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` variables, we can configure our gateway service. Create config.toml file and swap `` and `` 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: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#proxy-1) Proxy To run proxy service (for [remote onboarding & enrollment](https://docs.defguard.net/2.0/using-defguard-for-end-users/enrollment) ), we can do it by: Check the logs afterwards. Should look like this: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#reverse-proxy) 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](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx) . After having the reverse proxy configured and running you can continue with this guide. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) 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` circle-check Now you have full working Defguard services 🥳 You can [configure your desktop client using the enrollment](https://docs.defguard.net/2.0/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 itarrow-up-right](https://defguard.gitbook.io/defguard/tutorials/step-by-step-setting-up-a-vpn-server#enabling-to-access-internet-through-your-vpn) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#securing-the-setup) 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) triangle-exclamation **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](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#upgrading-packages) Upgrading packages ----------------------------------------------------------------------------------------------------------------------------------------------- circle-info 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. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#freebsd-opnsense) FreeBSD/OPNsense 1. Uninstall the current version. 2. Install a newer version (as described [above](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#installing-packages) ). 3. Restart the service. [PreviousHardware, OS, network and firewall recommendationschevron-left](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) [NextDefguard APT repositorychevron-right](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) * [Introduction](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#introduction) * [System Requirements](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#system-requirements) * [Installing a database](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#installing-a-database) * [Installing packages](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#installing-packages) * [Core](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#core) * [Gateway](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#gateway) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#proxy) * [Running Defguard](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#running-defguard) * [Core](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#core-1) * [Gateway](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#gateway-1) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#proxy-1) * [Reverse proxy](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#reverse-proxy) * [Enabling Proxy service in the Core](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) * [Securing the setup](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#securing-the-setup) * [Upgrading packages](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#upgrading-packages) sun-brightdesktopmoon Copy apt install postgresql Copy # su -c /usr/bin/psql postgres postgres=# CREATE USER defguard WITH SUPERUSER PASSWORD 'defguard'; postgres=# CREATE DATABASE defguard; Copy # echo 'localhost:5432:defguard:defguard:defguard' >> ~/.pgpass # chmod 600 ~/.pgpass # psql -d defguard -h localhost -U defguard defguard=# exit Copy wget Copy wget https://github.com/DefGuard/defguard/releases/download/v0.11.0/defguard-0.11.0-x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard -V defguard_common 1.6.0 Copy wget Copy # wget https://github.com/DefGuard/gateway/releases/download/v0.7.0/defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-gateway-X.Y.Z_x86_64-unknown-freebsd.pkg Copy sudo dpkg -i defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # defguard-gateway -V defguard-gateway 0.7.0 Copy wget Copy wget https://github.com/DefGuard/proxy/releases/download/v0.5.0/defguard-proxy-0.5.0-x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard-proxy--x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.deb # if you added apt repository sudo apt install defguard-proxy # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-proxy-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard-proxy -V defguard-proxy 0.5.0 Copy ### 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" Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard.service systemctl start defguard.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard start Copy # journalctl -u defguard.service | tail -n 50 Jul 29 13:57:15 defguard-testing systemd[1]: Started defguard.service - Defguard core service. Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.738420Z INFO defguard: Starting defguard Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.743079Z INFO defguard::db: Initializing DB pool Jul 29 13:57:16 defguard-testing defguard[2776504]: 2024-07-29T11:57:16.297407Z INFO defguard: Using HMAC OpenID signing key Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.156559Z INFO defguard::db::models::user: Initializing admin user Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.595218Z INFO defguard::db::models::user: New admin user has been created, adding to Admin group... Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.747717Z INFO defguard::db::models::settings: Initializing default settings Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.780563Z INFO defguard: Started web services Copy # 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-gateway.service systemctl start defguard-gateway.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_gateway start Copy 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/ Copy 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-proxy.service systemctl start defguard-proxy.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_proxy start Copy # 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 Copy # Proxy connection configuration DEFGUARD_PROXY_URL=https://enroll.defguard.net:444 Copy ### 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" Copy systemctl restart defguard.service Copy # Core package pkg delete defguard # or Gateway package pkg delete defguard-gateway # or Proxy package pkg delete defguard-proxy Copy # Core service sudo /usr/local/etc/rc.d/defguard restart # or Gateway service sudo /usr/local/etc/rc.d/defguard_gateway restart # or Proxy service sudo /usr/local/etc/rc.d/defguard_proxy restart sun-brightdesktopmoon --- # Docker Compose | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#introduction) Introduction ------------------------------------------------------------------------------------------------------------ This document provides a complete example of how to deploy Defguard using Docker Compose, including configuration for all components - Core, Proxy, and Gateway. It covers Docker image tags, environment variables, and reverse-proxy setup examples to help you quickly launch a fully functional Defguard environment. We recommend deploying each Defguard service on a dedicated server or virtual machine to ensure better isolation, performance, and security. In this setup, each Docker Compose file should be used for a single service, keeping the Core, Proxy, and Gateway components physically separated. circle-info Please note that we also offer docker-compose deployment with [_one-line quick deployment_](https://docs.defguard.net/2.0/getting-started/one-line-install) _,_ but this method is recommended for PoC/quick deployment as **it launches everything on one server and all services in one docker compose**. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#docker-images-and-tags) Docker images and tags -------------------------------------------------------------------------------------------------------------------------------- We use `latest` (latest production images) tags in the examples below, but you can use others. All docker images for Core, Gateway, and Proxy have these additional tags: * `latest` - the latest stable production release. * `vX.Y`, `vX.Y.Z`, `vX.Y-alpha1` - fixed tags for specific stable and alpha releases. * `pre-release`\- the latest pre-production release (equivalent to vX.Y-alpha1). * `dev` - the latest development build from the dev branch (experimental). circle-exclamation We recommend always using fixed, stable tags (`vX.Y`, `vX.Y.Z`) for your production deployment. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) Example Docker Compose deployment repository ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with and example Docker Compose configuration. To run your services using this example prepare your .env file by copying the template: Finally, run the service with Docker Compose: Below you'll find a detailed breakdown of configuration for different components: Core, Proxy and Gateway. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) Deploying Core, database and reverse proxy services ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the core and database. Configuration is split to the `.env` file (see below): #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#nginx-reverse-proxy) NGINX reverse-proxy Now that you have core running, here is an example NGINX configuration to provide SSL termination: #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#the-configuration) The configuration Here is the `.env` file with all configuration variables: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) Deploying Proxy and reverse proxy service ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here is the docker-compose.yaml for the public proxy (enrollment service as well as desktop client configuration service). To secure the gRPC communication, please generate the proxy CA and certificate, [more info here](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#nginx-reverse-proxy-1) NGINX reverse-proxy Now that you have proxy running, here is an example NGINX configuration to provide SSL termination: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-gateway-service) Deploying Gateway service -------------------------------------------------------------------------------------------------------------------------------------- You'll need a token to deploy the Gateway service. You'll have to set it as DEFGUARD\_TOKEN environment variable. Details on how to obtain the token [here](https://docs.defguard.net/2.0/deployment-strategies/gateway) . For gateway to control the WireGuard kernel as well as network, it's recommended to run in the _host_ network mode as well as there are needed some docker CAPs: [PreviousDefguard APT repositorychevron-left](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) [NextKuberneteschevron-right](https://docs.defguard.net/2.0/deployment-strategies/kubernetes) Last updated 23 days ago * [Introduction](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#introduction) * [Docker images and tags](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#docker-images-and-tags) * [Example Docker Compose deployment repository](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) * [Deploying Core, database and reverse proxy services](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) * [Deploying Proxy and reverse proxy service](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) * [Deploying Gateway service](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-gateway-service) sun-brightdesktopmoon Copy cp .env.template .env Copy docker compose up Copy services: core: image: ghcr.io/defguard/defguard:latest restart: always container_name: "defguard" env_file: .env ports: # HTTP port - open on localhost, should be secured by reverse-proxy - "127.0.0.1:8000:8000" # gRPC port for gateway to connect to # open on all interfaces/IPs - whould be secured with custom CA (see .env) - "50055:50055" depends_on: - db volumes: # more info here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key - ./rsakey.pem:/keys/rsakey.pem # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/keys/ca.pem db: image: postgres:17-alpine container_name: "defguard-db" env_file: .env volumes: - db:/var/lib/postgresql/data volumes: db: Copy upstream defguard { server 127.0.0.1:8000; } server { listen 443 ssl http2; # your domain server_name defguard.secure-internal.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.error.log; ssl on; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/secure-internal.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/secure-internal.net/privkey.pem; client_max_body_size 20m; location / { proxy_connect_timeout 300; proxy_pass http://defguard; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; } } Copy # please generate each secret with: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64 DEFGUARD_SECRET_KEY= DEFGUARD_AUTH_SECRET= DEFGUARD_GATEWAY_SECRET= DEFGUARD_YUBIBRIDGE_SECRET= # if you plan to reverse-proxy defguard, please provide a full URL # this URL will be shared in emails, enrollement messages, etc.: DEFGUARD_URL=https://defguard.secure-internal.net # Must be an effective domain of DEFGUARD_URL # Changing DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing # Webauthn credentials. DEFGUARD_WEBAUTHN_RP_ID=defguard.secure-internal.net # accepted: info/debug/warning/error DEFGUARD_LOG_LEVEL=info # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates DEFGUARD_PROXY_GRPC_CA=/keys/ca.pem # gRPC URL of proxy (see proxy config) DEFGUARD_PROXY_URL=https://proxy.host:50051 # more details about RSA key here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key DEFGUARD_OPENID_KEY=rsakey.pem # the URL of your proxy - will be displayed during enrollment, email # messages or desktop client configuration DEFGUARD_ENROLLMENT_URL=https://enrollment.public.net # PostgreSQL database configuration for core DEFGUARD_DB_HOST=db DEFGUARD_DB_PORT=5432 DEFGUARD_DB_USER=defguard # please generate password: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64 DEFGUARD_DB_PASSWORD= DEFGUARD_DB_NAME=defguard # database configuration for "db" container # must be same as above # database will be initialized with these values (the user/pass set here) POSTGRES_DB=defguard POSTGRES_USER=defguard POSTGRES_PASSWORD=!SAME_AS-GENERATED-DEFGUARD_DB_PASSWORD! Copy proxy: image: ghcr.io/defguard/defguard-proxy:latest restart: unless-stopped ports: # HTTP port - should be secured by reverse proxy - "127.0.0.1:8080:8080" - "50051:50051" environment: # path in the volume to custom proxy cert & key - DEFGUARD_PROXY_GRPC_CERT=ca/proxy.crt - DEFGUARD_PROXY_GRPC_KEY=ca/proxy.key volumes: - ./ca/proxy.crt:ca/proxy.crt - ./ca/proxy.key:ca/proxy.key Copy upstream defguard-proxy { server 127.0.0.1:8080; } server { listen 443 http2; server_name enrollment.public.net; access_log /var/log/nginx/defguard-proxy.log; error_log /var/log/nginx/defguard-proxy.error.log; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/public.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/public.net/privkey.pem; client_max_body_size 20m; location / { proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } Copy services: gateway: image: ghcr.io/defguard/gateway:latest restart: unless-stopped network_mode: "host" environment: - DEFGUARD_GRPC_URL=https://core-ip:50055 - DEFGUARD_GRPC_CA=/ca.pem - DEFGUARD_STATS_PERIOD=30 # to get the token add a VPN location and get the token - DEFGUARD_TOKEN=tokenFromCoreLocation - DEFGUARD_GATEWAY_NAME=willBeVisibleInDefguardAsGWName volumes: # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/ca.pem cap_add: - NET_ADMIN sun-brightdesktopmoon --- # Kubernetes | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------- To deploy and use Defguard on your cluster, you'll need: * A [Kubernetes clusterarrow-up-right](https://kubernetes.io/docs/setup/) * Kubernetes CLI [kubectlarrow-up-right](https://kubernetes.io/docs/reference/kubectl/) installed on your machine * Helm binary https://github.com/helm/helm/releases/latest circle-exclamation Our helm charts currently support only **Traefik ingress - which is relevant and affects exposing GRPC services (see below** `ingress.hosts.grpc``**).**` [hashtag](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#deployment) Deployment ---------------------------------------------------------------------------------------------------- We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with Kubernetes configuration, clone it with: Copy git clone https://github.com/DefGuard/deployment.git && cd deployment/charts Then create a namespace for Defguard on your cluster: Copy kubectl create namespace defguard Copy and fill in values file: Copy cp defguard/values.yaml ./ Required values (the rest should work if left as-is): * `ingress.hosts.grpc`: GRPC ingress address - GRPC clients like Defguard **gateway**, yubi-bridge circle-exclamation If you are configuring your gateway or yubi-bridge - please use this GRPC URL for communication. If you have other ingress controller than traefik - you need to configure GRPC ingress manually with corresponding to your setup. * `ingress.hosts.web`: Web ingress address - Defguard web app will be available here. * `publicUrl`: Public URL your Defguard will be available under. Usually the same as ingress.hosts.web, but differs depending on your load balancer and/or reverse-proxy setup. And finally, install the Helm chart in the namespace: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#proxy-service) Proxy service If you want to deploy the enrollment service along with your Defguard instance, you also need to configure values related to the `defguard-proxy`subchart: * `defguard-proxy.enabled`: enable the enrollment service * `proxyUrl`: proxy gRPC endpoint URL (based on `defguard-proxy.ingress.grpc.host`) * `defguard-proxy.publicUrl`: public URL of the enrollment service * `defguard-proxy.ingress.web.host`: enrollment service web ingress address (the enrollment website) * `defguard-proxy.ingress.grpc.host`: enrollment service gRPC ingress address (for communicating with core) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#vpn-gateway-service) VPN gateway service If you want to deploy the VPN gateway service along with your Defguard instance, you need to do it in two steps: * first deploy the core service and use the web UI to [setup a VPN location](https://docs.defguard.net/2.0/tutorials/step-by-step-setting-up-a-vpn-server/adding-additional-vpn-locations) * copy the gateway token and proceed to deploying the gateway itself To deploy the gateway service, configure values related to the `defguard-gateway`subchart: * `defguard-gateway.enabled`: enable the VPN gateway service * `defguard-gateway.token`: the gateway token generated in Web UI * `defguard-gateway.grpcUrl`: URL where the core gRPC server is available (based on `defguard.ingress.grpc.host`) [PreviousDocker Composechevron-left](https://docs.defguard.net/2.0/deployment-strategies/docker-compose) [NextTerraformchevron-right](https://docs.defguard.net/2.0/deployment-strategies/terraform) * [Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#prerequisites) * [Deployment](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#deployment) * [Proxy service](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#proxy-service) * [VPN gateway service](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#vpn-gateway-service) sun-brightdesktopmoon Copy helm install --wait=true --namespace defguard defguard defguard -f values.yaml sun-brightdesktopmoon --- # Running Gateway on OPNsense firewall | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) OPNsense plugin ---------------------------------------------------------------------------------------------------------------------------------------- [OPNsense®arrow-up-right](https://opnsense.org/) is an open source, feature rich firewall and routing platform, offering cutting-edge network protection. To start Defguard Gateway as OPNsense plugin: 1. On the [release pagearrow-up-right](https://github.com/DefGuard/gateway/releases) find and download OPNsense package which will be named: `defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg` – this package **includes both Defguard Gateway and OPNsense plugin.** 2. Install the package: Copy pkg add defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg 1. Refresh your OPNsense UI by running command below: Copy opnsense-patch 1. Go to your OPNsense UI and navigate to **VPN** > **Defguard Gateway**. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FqvvzrfBmgJqJlutc7awW%2FOPNSense%2520Plugin.png&width=768&dpr=3&quality=100&sign=631849d2&sv=2) 1. Fill out the form with appropriate values, click **Save**, and then click **Start/Restart.** circle-info You can find detailed description of all fields [here](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway-configuration) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/2.0/features/wireguard/remote-desktop-activation) . See also: [how to configure Defguard in OPNsense](https://docs.defguard.net/2.0/features/gateway) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) Binary Install -------------------------------------------------------------------------------------------------------------------------------------- 1. Checkout Gateway releases [herearrow-up-right](https://github.com/DefGuard/gateway/releases) and download compatible binary from GitHub page. 2. Decompress and move to bin directory 1. Start gateway `gateway -g -t ` [PreviousConfigurationchevron-left](https://docs.defguard.net/2.0/deployment-strategies/configuration) [NextRunning Gateway on MikroTik routerschevron-right](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers) * [OPNsense plugin](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) * [Binary Install](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) sun-brightdesktopmoon Copy tar xcf ./gateway.tar.gz sudo chmod +x gateway sudo mv gateway /usr/bin/ sun-brightdesktopmoon --- # Terraform | 2.0 | defguard circle-info Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later. circle-info We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/issues) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#aws) AWS ------------------------------------------------------------------------------------- To deploy Defguard using Terraform on AWS, you can use the Terraform configuration provided in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main) . The terraform configuration includes the necessary resources to setup all components of Defguard. We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture pagearrow-up-right](https://docs.defguard.net/in-depth/architecture) . When configuring the networking, the most important thing is to keep in mind the following rules: * Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection. * Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. * Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN. * All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#using-the-modules) Using the Modules To use the provided Terraform modules in your terraform configuration, you can use the following source: Copy module "" { source = "github.com/DefGuard/deployment//terraform/modules/?ref=" # Rest of the module configuration goes here # ... } Where: * `` is the name you want to give to the module in your configuration. * `` is one of `core`, `proxy`, or `gateway`, depending on which module you want to use. * `` is the commit hash, tag or branch name of the Defguard deployment repository. You can use the `main` branch for the latest stable version. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#configuring-modules) Configuring modules There are three Defguard modules available for deployment: `core`, `proxy` and `gateway`. The modules can be found in the modules [directoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main/terraform/modules) in the Defguard deployment repository. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#common-configuration-options-for-all-modules) Common configuration options for all modules All components have common configuration options that may be configured in their respective blocks in the `main.tf` file: * `instance_type`: The instance type to use. The default is `t3.micro`. You can adjust this based on your performance needs. * `ami`: The base AMI to use for the Defguard instance. We recommend using the Ubuntu Server 24.04 LTS (64-bit) AMI, which is the default in the example configurations. You may change this to a different AMI if needed. Your AMI must meet the requirements defined in [AMI requirements](https://docs.defguard.net/2.0/deployment-strategies/terraform#ami-requirements) . * `package_version`: The version of the Defguard component package to be installed. This must be an existing Defguard debian package released on the Defguard releases page (e.g. Defguard Core packages are available [herearrow-up-right](https://github.com/DefGuard/defguard/releases) ). Example: `1.4.0`, `1.3.2-alpha2`. * `arch`: The architecture of the Defguard Core package to be installed. This can be set to `x86_64` or `aarch64`. The default is `x86_64`. * `log_level`: The log level to use for the Defguard component. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. The default is `info`. Note that setting the log level to `debug` will produce a lot of logs, which may be useful for debugging, but may also fill up your disk space quickly. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#core-module) Core module The core module is responsible for setting up Defguard Core. It accepts the following variables: * `core_url`: The URL at which Defguard web UI will be accessible. * `grpc_port`: The gRPC port for Defguard Core to communicate with gateways. * `http_port`: The HTTP port on which the Defguard Core web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. * `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments. * `default_admin_password`: The default password for the admin user. This should be changed after the first login. * `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module. * `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](https://docs.defguard.net/2.0/deployment-strategies/terraform#vpn-networks-configuration) section for more details on how to configure the VPN networks. * `db_details`: A map containing the database configuration. It must contain the following: * `name`: The name of the PostgreSQL database to be created for Defguard. * `username`: The username for the PostgreSQL database. * `password`: The password for the PostgreSQL database user. * `port`: The port on which the PostgreSQL database will listen. * `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. * `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#proxy-module) Proxy module The proxy module is responsible for setting up the Defguard Proxy. It accepts the following variables: * `url`: The URL at which Defguard Proxy will be accessible. * `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication. * `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#gateway-module) Gateway module The gateway module is responsible for setting up the Defguard VPN gateways. It accepts the following variables: * `core_grpc_port`: The gRPC port of Defguard Core for the internal communication. This must match the `grpc_port` variable in the core module. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core. * `network_id`: The ID of the VPN network. This must match the `id` field in the `vpn_networks` variable in the core module. * `core_address`: The IP address of the Defguard Core instance. This should be core's private address, as it will be used for internal communication between the gateway and core components. See the `basic` example for the configuration of this variable. * `gateway_secret`: The secret used to authenticate the gateway with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the core module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Gateway instance. This is used to ensure that the gateway instance has a private IP address in the same VPC as the core and proxy components. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#vpn-networks-configuration) VPN networks configuration * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. Each network is defined as a map with the following keys: * `id`: The id of the network. Must start with 1 and increment for each new network. This is used to identify the network in the database and allows for applying modifications to the network configuration later. * `name`: The name of the VPN network. This will be used to identify the network in the Defguard web UI and displayed to the users. * `address`: The internal address of the VPN network in the form of `x.x.x.x/x`. This is the address that will be assigned to the VPN clients when they connect to the VPN. It must be a valid CIDR notation. * `port`: The port on which the VPN gateway will listen for incoming VPN connections. Default is `50051`, which is the standard port for WireGuard VPN. You may change this to a different port if needed. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#ami-requirements) AMI requirements If you wish to use a different AMI for the Defguard components, it must meet the following requirements: * Must allow for running systemd services. * Must use the APT package manager. If you are not meeting these requirements, you will need to modify the corresponding `setup.sh` scripts, which are responsible for installing and configuring the Defguard components. The scripts can be found in `terraform/modules//setup.sh`, where `` is one of `core`, `gateway`, or `proxy`. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#examples) Examples The example configurations can be downloaded from the Defguard deployment repository. They are located in the `terraform/examples` directory: (https://github.com/DefGuard/deployment/tree/main/terraform)\[https://github.com/DefGuard/deployment/tree/main/terraform\] If you wish, you can also clone the whole repository using the following command: And then navigate to the `terraform/examples` directory to find the example configurations. To use any of the examples, you can copy or download the `main.tf.example` file and rename it to `main.tf`. Note that the file contains both the module definitions, variables and outputs. This is to make it easier to download the example. You can also split the file into separate files, such as `main.tf`, `variables.tf`, and `outputs.tf`, if you prefer to keep the configuration more organized. To run the examples, use the following commands: or if using OpenTofu: After running these commands, Terraform will create the necessary resources in your AWS account and deploy Defguard. The output will include the public and private addresses for Core, Proxy and gateway components: Note that running the examples will put some sensitive details into your `.tfstate` file, most notably: the database password, gateway secret and the initial admin password. Those details are not ephemeral in the terraform configuration as they must be passed to the Defguard components during their setup. If you want to secure those details, we recommend following the official guidelines on [how to secure your Terraform state filearrow-up-right](https://developer.hashicorp.com/terraform/language/state/sensitive-data) . #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#basic) `basic` The `basic` example can be directly downloaded using the following link: [basic/main.tf.examplearrow-up-right](https://raw.githubusercontent.com/DefGuard/deployment/refs/heads/main/terraform/examples/basic/main.tf.example) . The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following: * Defguard Core instance * Defguard Proxy instance * Defguard Gateway instance * A database instance (RDS) for Defguard Core. * A single VPC for all components. You can use this example as a starting point for your own deployment. To modify the network configuration, edit one of the sections in the `main.tf` file, such as "Core network configuration", "Gateway network configuration", or "Proxy network configuration". For example, to allow SSH access to Defguard Core instance, you can uncomment the following block in the "Core network configuration" section: Note that this will grant SSH access from any IP address, you may want to restrict it further by editing the `cidr_blocks` field. By default, the configuration allows access to Defguard Core web UI only from connected VPN clients, which is the recommended approach: If you want to run Core web UI behind a reverse proxy (e.g. to enable HTTPS), you would need to do the following: 1. Prevent direct access to the services by removing their ingress rules: 1. Add a second public subnet (load balancers require it): 1. Add the load balancer configuration 1. Add load balancer ingress rules to your existing Proxy and Core groups: 1. Finally, you can add the load balancer domain name to the output: This setup will create two load balancers: one internal and one external. Both will act as a reverse proxy, routing the HTTPS traffic matching your domains to the backend servers (Proxy, Core). The next step would be to point your actual domains to the domain names generated by the load balancers in the output (CNAME) and to setup SSL certificates (e.g. via the AWS certificate manager). ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#troubleshooting-and-common-issues) Troubleshooting and common issues All components are deployed as systemd services on the host EC2. Their configuration files can be found at `/etc/defguard`. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#checking-status-of-any-component) Checking status of any component You can check the status of any Defguard component by SSHing into the corresponding EC2 instance and running the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the status of the service. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#checking-logs-of-any-component) Checking logs of any component To display the logs of the service, SSH into the corresponding EC2 instance and run the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the logs of the service. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/terraform#checking-setup-logs) Checking setup logs Before any of the components becomes available, a `setup.sh` script is run, which performs its initial setup (package download, configuration). The logs of this script are stored in `/var/log/defguard.log` on a corresponding EC2 instance. You can check this log file to see if there were any issues during the setup. [PreviousKuberneteschevron-left](https://docs.defguard.net/2.0/deployment-strategies/kubernetes) [NextAmazon Machine Image (AMI)chevron-right](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation) * [AWS](https://docs.defguard.net/2.0/deployment-strategies/terraform#aws) * [Using the Modules](https://docs.defguard.net/2.0/deployment-strategies/terraform#using-the-modules) * [Configuring modules](https://docs.defguard.net/2.0/deployment-strategies/terraform#configuring-modules) * [Examples](https://docs.defguard.net/2.0/deployment-strategies/terraform#examples) * [Troubleshooting and common issues](https://docs.defguard.net/2.0/deployment-strategies/terraform#troubleshooting-and-common-issues) sun-brightdesktopmoon Copy git clone https://github.com/DefGuard/deployment.git Copy cd deployment/terraform Copy # To initialize all the modules and providers, run: terraform init # To preview the changes that will be made, run: terraform plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: terraform apply -var="aws_access_key=" -var="aws_secret_key=" Copy # To initialize all the modules and providers, run: tofu init # To preview the changes that will be made, run: tofu plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: tofu apply -var="aws_access_key=" -var="aws_secret_key=" Copy Apply complete! Resources: 35 added, 0 changed, 0 destroyed. Outputs: defguard_core_private_address = "10.0.1.x" defguard_core_public_address = "x.x.x.x" defguard_proxy_private_address = "10.0.1.x" defguard_proxy_public_address = "x.x.x.x" defguard_gateway_private_addresses = [\ "10.0.1.226",\ ] defguard_gateway_public_addresses = [\ "x.x.x.x",\ ] Copy ingress { from_port = 22 to_port = 22 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Core security group block [...] ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Proxy security group block [...] ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy vpc_public_subnets = ["10.0.1.0/24", "10.0.4.0/24"] Copy ########################################################################### ###################### Load Balancer Configuration ####################### ########################################################################### # Load balancer security groups resource "aws_security_group" "defguard_alb_sg" { name = "defguard-alb-sg" description = "Access to the Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] description = "HTTPS access from internet" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-alb-sg" } } resource "aws_security_group" "defguard_internal_alb_sg" { name = "defguard-internal-alb-sg" description = "Access to the Internal Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = [local.vpc_cidr] description = "HTTPS access from internal VPC network" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-internal-alb-sg" } } # Public Application Load Balancer resource "aws_lb" "defguard_public_alb" { name = "defguard-public-alb" internal = false load_balancer_type = "application" security_groups = [aws_security_group.defguard_alb_sg.id] subnets = module.vpc.public_subnets enable_deletion_protection = false tags = { Name = "defguard-public-alb" } } # Internal Application Load Balancer resource "aws_lb" "defguard_internal_alb" { name = "defguard-internal-alb" internal = true load_balancer_type = "application" security_groups = [aws_security_group.defguard_internal_alb_sg.id] subnets = module.vpc.private_subnets enable_deletion_protection = false tags = { Name = "defguard-internal-alb" } } # Target Groups resource "aws_lb_target_group" "defguard_core_tg" { name = "defguard-core-tg" port = local.core_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-core-tg" } } resource "aws_lb_target_group" "defguard_proxy_tg" { name = "defguard-proxy-tg" port = local.proxy_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-proxy-tg" } } # Target Group Attachments resource "aws_lb_target_group_attachment" "defguard_core_attachment" { target_group_arn = aws_lb_target_group.defguard_core_tg.arn target_id = module.defguard_core.instance_id port = local.core_http_port } resource "aws_lb_target_group_attachment" "defguard_proxy_attachment" { target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn target_id = module.defguard_proxy.instance_id port = local.proxy_http_port } # Listeners resource "aws_lb_listener" "defguard_public_alb_listener" { load_balancer_arn = aws_lb.defguard_public_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } } resource "aws_lb_listener" "defguard_internal_alb_listener" { load_balancer_arn = aws_lb.defguard_internal_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } } # Listener Rules resource "aws_lb_listener_rule" "defguard_proxy_rule" { listener_arn = aws_lb_listener.defguard_public_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } condition { host_header { values = [replace(local.proxy_url, "https://", "")] } } } resource "aws_lb_listener_rule" "defguard_core_rule" { listener_arn = aws_lb_listener.defguard_internal_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } condition { host_header { values = [replace(local.core_url, "https://", "")] } } } Copy # HTTP access from internal load balancer (Core) ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_internal_alb_sg.id] description = "HTTP access from internal load balancer" } # HTTP access from public load balancer (Proxy) ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_alb_sg.id] description = "HTTP access from public load balancer" } Copy output "defguard_public_alb_dns" { description = "The DNS name of the Public Application Load Balancer" value = aws_lb.defguard_public_alb.dns_name } output "defguard_internal_alb_dns" { description = "The DNS name of the Internal Application Load Balancer" value = aws_lb.defguard_internal_alb.dns_name } Copy sudo systemctl status Copy sudo journalctl -u sun-brightdesktopmoon --- # Configuring HTTPS using AWS Certificate Manager | 2.0 | defguard This guide explains how to secure your Defguard deployment with HTTPS by using a public TLS certificate issued by AWS Certificate Manager (ACM). You will request a certificate for the domains used by Defguard Core and Defguard Proxy, validate domain ownership via DNS, and attach the certificate to your CloudFormation stack using its ARN. Once completed, AWS will automatically manage certificate provisioning and renewal, ensuring your Defguard instance is encrypted and trusted without manual certificate handling. Go to AWS console and open the Certificate Manager service page. Request a new certificate (if you don't have one already). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FQoyjbo5fHCIqJBw4Ftua%2Fimage.png&width=768&dpr=3&quality=100&sign=c0711021&sv=2) A public certificate is enough. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FFDrVICaZdA6ax43jq6p4%2Fimage.png&width=768&dpr=3&quality=100&sign=73f6378f&sv=2) Specify the domains you will want to use for your Defguard instance (for accessing Defguard Proxy and Defguard Core). Those domains should be the same as those you'll use in `ProxyUrl` and `CoreUrl`. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FOqG8nfvX2DhWtxwIqhUR%2Fimage.png&width=768&dpr=3&quality=100&sign=88d5db1c&sv=2) Next, you will need to validate your domain ownership by adding appropriate CNAME records in your DNS provider. Use the _CNAME name_ and _CNAME value_ values provided in the AWS console and set them in you domain's DNS. After you complete this step, your certificate can be used. Copy the ARN of your certificate and paste it into the `SSLCertificateArn` parameter in the CloudFormation template. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FZYSmu3hXFG0u2upe9AAh%2Fimage.png&width=768&dpr=3&quality=100&sign=3a76e5c0&sv=2) [PreviousAmazon Machine Image (AMI)chevron-left](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation) [NextAdding a location and getting a Gateway tokenchevron-right](https://docs.defguard.net/2.0/deployment-strategies/gateway) sun-brightdesktopmoon sun-brightdesktopmoon --- # Adding a location and getting a Gateway token | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/gateway#adding-a-location-in-defguard-core) Adding a location in Defguard Core ------------------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation Please remember that **one gateway corresponds to one VPN location.** You can also deploy multiple gateways for one location for High Availability. Go to the address you set on `DEFGUARD_URL` with your browser and sign in using the credentials you set up during Core deployment. Go to the _VPN Overview_ module from the main menu and click the _Edit Locations settings_. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FHSVWzeINmitnw9nyCfyP%2FScreenshot%25202025-10-15%2520at%252013.37.33.png&width=768&dpr=3&quality=100&sign=d1477e24&sv=2) Adding a new location Then click the _Add new location tab_. ![Adding a new location](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FbUm6h25Pkciow4wYOAaM%2FScreenshot%25202025-10-15%2520at%252013.37.55.png&width=768&dpr=3&quality=100&sign=df3dcd1d&sv=2) Adding a new location Depending on what is more convenient for you, choose configuration from Wireguard file or do it manually. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F8e7ZM0kHkuSFQ7rJZ3eT%2Fchoose_location_setup.png&width=768&dpr=3&quality=100&sign=122d2e07&sv=2) Location wizard ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F5QX9owg7VR1jc4w5gjQJ%2Flocation_configuration.png&width=768&dpr=3&quality=100&sign=c35700e6&sv=2) Location configuration 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. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FnMFpXXfBNCORZcbTDvOi%2Fedit_locations_settings.png&width=768&dpr=3&quality=100&sign=45e7f02&sv=2) Manual configuration In `Gateway server setup` copy two variables: `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FKZppLbTnB4EYDxHLzwst%2Fgateway_server_setup.png&width=768&dpr=3&quality=100&sign=9cf3e2e0&sv=2) Gateway server setup Also, if core has a custom SSL CA to secure gRPC communication, [you need the CA certificate (more here).](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/gateway#deploy-the-gateway-service) Deploy the Gateway service --------------------------------------------------------------------------------------------------------------------------------- Proceed with deploying your Gateway service using the selected [deployment strategy](https://docs.defguard.net/2.0/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) : * [package based](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation#gateway-1) * [Docker Compose](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#deploying-gateway-service) * [Kubernetes](https://docs.defguard.net/2.0/deployment-strategies/kubernetes#vpn-gateway-service) * [Terraform](https://docs.defguard.net/2.0/deployment-strategies/terraform#gateway-module) * [AMIs and AWS CloudFormation](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) You can also check our guides on running Gateway on [OPNsense firewall](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall) or [MikroTik router](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/2.0/features/network-devices#adding-a-new-network-device) . [PreviousConfiguring HTTPS using AWS Certificate Managerchevron-left](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) [NextConfigurationchevron-right](https://docs.defguard.net/2.0/deployment-strategies/configuration) * [Adding a location in Defguard Core](https://docs.defguard.net/2.0/deployment-strategies/gateway#adding-a-location-in-defguard-core) * [Deploy the Gateway service](https://docs.defguard.net/2.0/deployment-strategies/gateway#deploy-the-gateway-service) sun-brightdesktopmoon sun-brightdesktopmoon --- # Updating and version compatibility | 2.0 | defguard Each service in the Defguard stack can be updated independently, provided the components remain compatible. When components connect, Defguard automatically performs a version check. If an incompatibility is detected, the connection is refused and it will be clearly reported both in the log files and through a dialog in the core UI: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FuGRqy2UmvL20Kd2QGDKM%2Fimage.png&width=768&dpr=3&quality=100&sign=68961e8b&sv=2) circle-exclamation **Note on Multiple Gateways per Location** If you configure more than one gateway for the same location, they will overwrite each other’s incompatibility data. This happens because location is currently used as the identifier for gateways. This limitation will be resolved once full high-availability (HA) support is implemented. It's recommended to always use newest version of services and update them all together to avoid incompatibility. Check the GitHub repositories for each service to find their newest releases and release notes. * Docker - For Docker and Kubernetes based setup just change docker image version for service you want to update. * Packages(DEB, RPM, etc.) - Currently we don't have any package repository so if you want to update your service installed as package you have to download new version from service repository. **GitHub Repositories:** * [Defguard Corearrow-up-right](https://github.com/DefGuard/defguard/releases) * [Defguard Proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) * [Defguard Gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) * [Defguard YubiBridgearrow-up-right](https://github.com/DefGuard/YubiKey-Provision/releases) [PreviousHigh Availability and Failoverchevron-left](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover) [NextMigration guideschevron-right](https://docs.defguard.net/2.0/deployment-strategies/upgrading) sun-brightdesktopmoon sun-brightdesktopmoon --- # Using a userspace wireguard-go implementation | 2.0 | defguard Gateway currently supports using `wireguard-go`, a userspace WireGuard implementation. This approach is **not recommended** on platforms where a native support exists (e.g. Linux). You can enable the userspace implementation by setting the `userspace` config option or a corresponding `DEFGUARD_USERSPACE` environment variable to `true`. Because `wireguard-go` is not bundled by default with Defguard, it must be installed separately. The `wireguard-go` binary/command must be available on the host machine for it to function properly. On Docker, this currently requires building a custom image, as the base gateway images also don't come with `wireguard-go` pre-installed. This can be achieved as follows: Copy FROM golang:1.24.6-alpine AS builder RUN apk add --no-cache git make RUN git clone https://git.zx2c4.com/wireguard-go /src/wireguard-go \ && cd /src/wireguard-go \ && make # Specify the desired Gateway's version here FROM ghcr.io/defguard/gateway:latest COPY --from=builder /src/wireguard-go/wireguard-go /usr/local/bin/wireguard-go RUN chmod +x /usr/local/bin/wireguard-go Note that when running the Docker container with a userspace implementation on a Linux host, the container requires a `NET_ADMIN` capability and access to `/dev/net/tun`, this can be set in a Docker compose: Copy # Docker compose cap_add: - NET_ADMIN devices: - /dev/net/tun Or via the command line: [PreviousMigration guideschevron-left](https://docs.defguard.net/2.0/deployment-strategies/upgrading) [NextPre-production and development releaseschevron-right](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases) sun-brightdesktopmoon Copy docker run --cap-add=NET_ADMIN --device=/dev/net/tun [...] sun-brightdesktopmoon --- # Reverse Proxy configuration using NGINX | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#introduction) Introduction ------------------------------------------------------------------------------------------------------------------------------------- This guide explains how to configure [NGINXarrow-up-right](https://nginx.org/) as a reverse proxy for Defguard's components (Core and 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. To provide HTTPS encryption, this guide also uses [Certbotarrow-up-right](https://certbot.eff.org/) , a free, open-source tool from the [Let’s Encryptarrow-up-right](https://letsencrypt.org/) project. Certbot automatically issues and renews SSL/TLS certificates, allowing you to secure your Defguard domains without manual certificate management. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#installing-nginx-and-certbot) Installing NGINX and Certbot To install and prepare NGINX with Let’s Encrypt certificates: Copy apt install nginx certbot systemctl enable nginx.service systemctl start nginx.service Disable the default configuration to avoid conflicts: Copy unlink /etc/nginx/sites-enabled/default ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) Obtaining SSL Certificates Before configuring NGINX, issue valid SSL certificates for your domains. In this example we use: * Core: **my-server.defguard.net** * Enrollment (Proxy): **enroll.defguard.net** Generate certificates with Certbot: Copy certbot certonly \ --non-interactive \ --agree-tos \ --standalone \ --email [email protected] \ -d my-server.defguard.net \ -d enroll.defguard.net Certbot will generate certificate in fullchain.pem and privkey.pem in the following paths: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-core-nginx-configuration) Defguard Core NGINX configuration Create a new configuration file for the Core service: `/etc/nginx/sites-available/my-server.defguard.net.conf` Enable the configuration and reload NGINX: To verify, run: circle-info If you use this simple setup and run all services on one server, you can use [NGINX access restrictionsarrow-up-right](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-tcp/) for securing core and allowing to access the _my-server.defguard.net_ only to selected networks - blocking the direct access from the Internet. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-proxy-enrollment-service-nginx-configuration) Defguard Proxy (Enrollment Service) NGINX configuration The Proxy service exposes APIs for enrollment, remote onboarding, and desktop client configuration. Create its NGINX configuration file: `/etc/nginx/sites-available/enroll.defguard.net.conf` Enable and restart NGINX: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#security-recommendations) Security Recommendations * Only expose **HTTPS ports (443)** for web access. * Do **not** expose internal **gRPC ports** (444, 50051, 50055) directly to the Internet. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#summary) Summary After completing the configuration: * Defguard Core is available at `https://my-server.defguard.net` * Enrollment and onboarding services are available at `https://enroll.defguard.net` * Both services are secured with SSL and reverse-proxied through NGINX. [PreviousRunning Gateway on MikroTik routerschevron-left](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers) [NextHigh Availability and Failoverchevron-right](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover) * [Introduction](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#introduction) * [Installing NGINX and Certbot](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#installing-nginx-and-certbot) * [Obtaining SSL Certificates](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) * [Defguard Core NGINX configuration](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-core-nginx-configuration) * [Defguard Proxy (Enrollment Service) NGINX configuration](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-proxy-enrollment-service-nginx-configuration) * [Security Recommendations](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#security-recommendations) * [Summary](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx#summary) sun-brightdesktopmoon Copy /etc/letsencrypt/live/my-server.defguard.net /etc/letsencrypt/live/enroll.defguard.net Copy upstream defguard { server 127.0.0.1:8000; } upstream defguard-grpc { server 127.0.0.1:50055; } server { listen 443 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; client_max_body_size 128M; location / { proxy_pass http://defguard; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } server { listen 444 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard-grpc.log; error_log /var/log/nginx/defguard-grpc.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://defguard-grpc; } } Copy ln -s /etc/nginx/sites-available/my-server.defguard.net.conf /etc/nginx/sites-enabled/my-server.defguard.net.conf systemctl reload nginx.service Copy curl https://my-server.defguard.net/api/v1/health # Expected output: alive Copy upstream defguard-proxy { server 127.0.0.1:8080; } upstream proxy-grpc { server 127.0.0.1:50051; } server { listen 443 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll.log; error_log /var/log/nginx/enroll.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { proxy_http_version 1.1; proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } } server { listen 444 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll-grpc.log; error_log /var/log/nginx/enroll-grpc.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://proxy-grpc; grpc_socket_keepalive on; grpc_read_timeout 3000s; grpc_send_timeout 3000s; grpc_next_upstream_timeout 0; proxy_request_buffering off; proxy_buffering off; proxy_connect_timeout 3000s; proxy_send_timeout 3000s; proxy_read_timeout 3000s; proxy_socket_keepalive on; keepalive_timeout 90s; send_timeout 90s; client_body_timeout 3000s; } } Copy ln -s /etc/nginx/sites-available/enroll.defguard.net.conf /etc/nginx/sites-enabled/enroll.defguard.net.conf systemctl restart nginx.service sun-brightdesktopmoon --- # Using RSA instead of HMAC for OpenID key | 2.0 | defguard By default, Defguard uses [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation and the. If you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) , you'll have to configure the Defguard core `DEFGUARD_OPENID_KEY` configuration variable with the path to the RSA private key. You can generate the RSA key with: Copy openssl genpkey -out /path/to/rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096 [PreviousSecuring gRPC communicationchevron-left](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) [NextHealth checkchevron-right](https://docs.defguard.net/2.0/deployment-strategies/health-check) sun-brightdesktopmoon sun-brightdesktopmoon --- # Pre-production and development releases | 2.0 | defguard To test any pre-production or development release: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#one-line-install) One-line install The simplest way to test the latest development or pre-release version is to use one line installation method with the appropriate argument. More on that in [the one-line install documentation](https://docs.defguard.net/2.0/getting-started/one-line-install) . ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) Binaries and packages Each GitHub repository ([corearrow-up-right](https://github.com/DefGuard/defguard/releases) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) , [proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) , and [clientarrow-up-right](https://github.com/DefGuard/client/releases) ) has its **pre-release versions** available on the GitHub release page. This is where you can download binaries or packages with the pre-release, e.g.: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F1IZXUuDVR4Nut3C6OHWH%2FScreenshot%25202025-08-01%2520at%252013.38.44.png&width=768&dpr=3&quality=100&sign=dc92bedf&sv=2) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#docker-images) Docker images Each Docker image for [corearrow-up-right](https://github.com/DefGuard/defguard/pkgs/container/defguard) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/pkgs/container/gateway) and [proxyarrow-up-right](https://github.com/DefGuard/proxy/pkgs/container/defguard-proxy) has the following tags: * `pre-release` – this tag is for the **latest pre-production release** - which also contains a version in form of `vX.Y.Z-alpha/beta/rcX` from the `main` branch * `dev` – this tag is for the latest development release from the `dev` branch. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#docker-compose) Docker compose Please change the Docker compose file to match the version or tags as stated above. [PreviousUsing a userspace wireguard-go implementationchevron-left](https://docs.defguard.net/2.0/deployment-strategies/using-a-userspace-wireguard-go-implementation) [NextSecuring gRPC communicationchevron-right](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * [One-line install](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#one-line-install) * [Binaries and packages](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) * [Docker images](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases#docker-images) sun-brightdesktopmoon sun-brightdesktopmoon --- # Configuration | 2.0 | defguard Here you can find a list of all configurable things through environmental variables, options or configuration files for all Defguard components (each top-level section for a specific component): * [Core config](https://docs.defguard.net/2.0/deployment-strategies/configuration#core) * [Proxy config](https://docs.defguard.net/2.0/deployment-strategies/configuration#proxy-service) * [Gateway config](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway-configuration) * [YubiBridge config](https://docs.defguard.net/2.0/deployment-strategies/configuration#yubibridge-configuration) circle-info If you are using [one-line installation](https://docs.defguard.net/2.0/getting-started/one-line-install) , everything is generated and configured automatically. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#core) Core ------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#secrets-configuration) Secrets configuration Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens. circle-info You can generate random strings for secrets with e.g.: `openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64` * `DEFGUARD_AUTH_SECRET`: JWT secret key for encrypting user tokens, default: `DEFGUARD_AUTH_SECRET` * `DEFGUARD_SECRET_KEY`: JWT secret key for encrypting private cookies; must be at least 64 characters long * `DEFGUARD_GATEWAY_SECRET`: JWT secret key for encrypting Gateway tokens, default: `DEFGUARD_GATEWAY_SECRET` * `DEFGUARD_YUBIBRIDGE_SECRET`: JWT secret key for encrypting YubiBridge tokens, default: `DEFGUARD_YUBIBRIDGE_SECRET` * `DEFGUARD_OPENID_KEY`: this is optional if you want to use [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation, if you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) please provide a path to a private key file used for OAuth2/OpenID, [more herearrow-up-right](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) . ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#general-configuration) General configuration * `DEFGUARD_URL`: URL of your server instance, default `http://localhost:8000. This is the address at which the Web UI you use to administer your instance and the REST API endpoints are available (both of those are served by Defguard core on port 8000 by default; port can be configured with DEFGUARD_HTTP_PORT env variable).`This URL is needed to be exact since it's needed for OpenID discovery endpoint to work correctly, so if you have a reverse-proxy, custom domain, please provide an actual URL for Defguard core. * `DEFGUARD_GATEWAY_DISCONNECTION_NOTIFICATION_TIMEOUT`: If gateway is disconnected for this long, send email notification, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_WEBAUTHN_RP_ID` (optional): Relying party ID and relying party origin for WebAuthn used for MFA. By default, it's generated by using a base domain of `DEFGUARD_URL` (for example https://defguard.example.com is converted to defguard.example.com). circle-exclamation `DEFGUARD_WEBAUTHN_RP_ID`must be an effective domain of DEFGUARD\_URL (for example if hosting at `https://idm.example.com`, rp\_id must be `idm.example.com`, `example.com` or `com`). Changing `DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing Webauthn credentials.` * `DEFGUARD_ADMIN_GROUPNAME`: Name of the administrator group, default: `admin` * `DEFGUARD_USERADMIN_GROUPNAME`: Name of the user administrator group, default: `useradmin` * `DEFGUARD_VPN_GROUPNAME`: Name of the vpn group, default: `vpn` * `DEFGUARD_DEFAULT_ADMIN_PASSWORD`: Password for the default `admin` user, default: `pass123` * `DEFGUARD_LOG_LEVEL`: [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_PORT`: Core server port, default: `8000` * `DEFGUARD_LOG_FILE`: Log file path * `DEFGUARD_AUTH_COOKIE_TIMEOUT`: Cookie lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_MFA_CODE_TIMEOUT`: Email code lifetime period, default: `60s` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_SESSION_TIMEOUT`: Session lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#database-configuration) Database configuration Following env variables can be used to setup your database access: * `DEFGUARD_DB_HOST` * `DEFGUARD_DB_PORT` * `DEFGUARD_DB_NAME` * `DEFGUARD_DB_USER` * `DEFGUARD_DB_PASSWORD` ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#auth-cookies-configuration) Auth cookies configuration circle-exclamation If you want to access your Defguard instance without TLS (using an `http://` URL) you MUST enable insecure cookies by setting `DEFGUARD_COOKIE_INSECURE` to `true`. This is of course not recommended in production but can be useful when testing without a full reverse proxy setup. * `DEFGUARD_COOKIE_INSECURE`: set cookies without the `Secure` flag; use only in dev environments when serving Defguard without HTTPS * `DEFGUARD_COOKIE_DOMAIN` (optional): set the domain for auth cookies. By default, it's the domain from `DEFGUARD_URL`. Must be changed to base URL if you want to use [forward auth](https://docs.defguard.net/2.0/features/forward-auth) . ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#stats-cleanup-configuration) Stats cleanup configuration * `DEFGUARD_DISABLE_STATS_PURGE`: disable periodic cleanup of old Wireguard stats * `DEFGUARD_STATS_PURGE_FREQUENCY`: how often should the cleanup process be performed, default `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_STATS_PURGE_THRESHOLD`: age threshold for stats removal, default `30d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#enrollment-configuration) Enrollment configuration * `DEFGUARD_ENROLLMENT_URL`: external URL of the enrollment proxy server, default `http://localhost:8080` - this URL is sent in enrollment emails as well as displayed when configuring the desktop client - thus must be to the actual URL you have configured the proxy Web UI to be accessible at, otherwise the enrollment or desktop client configuration will not work. * `DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT`: how long is the enrollment token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_ENROLLMENT_SESSION_TIMEOUT`: how long in the enrollment session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#password-reset-configuration) Password reset configuration * `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT`: how long is the password reset token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_PASSWORD_RESET_SESSION_TIMEOUT`: how long in the password reset session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#grpc-server-configuration) gRPC server configuration [More on that in this help page.](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_GRPC_PORT`: the port on which the gRPC server should listen, default is `50055`. This port is used by Defguard Gateways to connect to your Core instance. * `DEFGUARD_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_GRPC_KEY`(optional): path to TLS key file * `DEFGUARD_GRPC_URL`: external URL of your instance's gRPC server, default `http://localhost:50055`; used for generating example VPN gateway startup command in Web UI ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#proxy-connection-configuration) Proxy connection configuration * `DEFGUARD_PROXY_URL` (optional): proxy service gRPC endpoint URL * `DEFGUARD_PROXY_GRPC_CA`(optional): path to TLS root certificate file, required if connecting to proxy gRPC service with a custom CA ([More on that in this help page.](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) ) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#proxy-service) Proxy service ------------------------------------------------------------------------------------------------------------- Here are proxy ENV variables. gRPC configuration is described more [on this help page.](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_HTTP_PORT`: port the proxy API server and Web UI will listen on, default `8080` * `DEFGUARD_PROXY_GRPC_PORT`: port the gRPCS server will listen on, default `50051` * `DEFGUARD_PROXY_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_PROXY_GRPC_KEY`(optional): path to TLS key file. [More on that in this help page.](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_URL` - if you wish to use External OIDC enrollment/desktop client configuration, please set this value to the same as `DEFGUARD_ENROLLMENT_URL` in core. This is the address at which the proxy Web UI is available. * `DEFGUARD_PROXY_LOG_LEVEL` : [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to * `DEFGUARD_PROXY_RATELIMIT_PERSECOND` - The (average) number of requests per second made without being eventually rate limited * `DEFGUARD_PROXY_RATELIMIT_BURST` - The number of requests allowed to be made in a short amount of time before being rate limited [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway-configuration) Gateway Configuration ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#environmental-variables-arguments) Environmental variables / Arguments If you're using docker image you can pass this value as environmental variables or on binary you can pass them as arguments * `DEFGUARD_GRPC_URL` , `-g ` - Defguard Core gRPC endpoint URL. This is used by the gateway to connect to your Defguard Core instance. If you configured the `DEFGUARD_GRPC_URL` variable on your Core instance before (as described in the [gRPC server configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#grpc-server-configuration) section), use the same value here. Otherwise, provide an URL that will allow the Gateway to reach your Core instance, e.g. `http://localhost:50055` if both Core and Gateway are running on the same host. * `DEFGUARD_TOKEN` ,`-t ` - Token displayed in the Defguard Core web UI after completing the network wizard. It can be copied from the "Authentication Token" section on the Location Settings page. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FwMAlfRmVuW6I574VZ81e%2Fobraz.png&width=768&dpr=3&quality=100&sign=3d29e572&sv=2) * `DEFGUARD_USERSPACE` , `-u` - Use userspace wireguard implementation, useful on systems without native wireguard support * `DEFGUARD_GRPC_CA - path to ca file` more on this topic can be found [on this help page.](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_STATS_PERIOD` ,`-p ` - Defines how often (seconds) should interface statistics be sent to the Defguard server * `DEFGUARD_GATEWAY_NAME`, `--name ` - (optional) human-readable gateway name that will be displayed in Defguard webapp * `-s, --use-syslog` - enable logging to syslog * `RUST_LOG` : Logger log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_MASQUERADE` - controls whether the gateway automatically applies masquerade NAT firewall rule; defaults to `false` * `DEFGUARD_DISABLE_FW_MGMT` - disables all firewall management by the gateway; this overrides `DEFGUARD_MASQUERADE` setting; defaults to `false` circle-info `DEFGUARD_DISABLE_FW_MGMT` is meant as a workaround for running in incompatible environments, where our [default firewall integration](https://docs.defguard.net/2.0/features/access-control-list/firewall-internals) is not supported. As a consequence, enabling this option disables [ACL functionality](https://docs.defguard.net/2.0/features/access-control-list) on a given gateway. * `DEFGUARD_IFNAME` - The network interface that will be created and used for the VPN traffic * `DEFGUARD_FW_PRIORITY` - The NFT forward chain priority, which handles traffic filtering when ACLs are configured. Defaults to 0. Useful if the Defguard's forward chain conflicts with other chains. * `HEALTH_PORT` - (optional) If a port number is provided an [HTTP healthcheck server](https://docs.defguard.net/2.0/deployment-strategies/health-check#gateway) will be started * `DEFGUARD_HTTP_BIND_ADDRESS` - (optional) the IP address that the HTTP healthcheck server should bind to #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#executing-custom-commands-on-vpn-up-down) Executing custom commands on VPN up/down The following env variables or gateway arguments define which commands gateway will run before / after it will bring up / down the VPN. It's usefull for example to use those commands to launch custom firewall commands or scripts that do various operations needed to be done on those occasions. triangle-exclamation Defguard is built with highest security standards in mind, thus the options below **accept only a full path to one command and it's arguments.** If you would like to have **multiple commands run,** you can create a shell script which will define the acceptable and preferred shell you would like to use and then all the commands you like to execute. `PRE_UP` , `--pre-up`, - Command to run before bringing up the interface. If you want to run a shell script, you should pass its path to your shell, for example: `/bin/sh -c /path/to/script` `POST_UP` , `--post-up`, - Command to run after bringing up the interface. `PRE_DOWN` , `--pre-down`, - Command to run before bringing down the interface. `POST_DOWN` , `--post-down`, - Command to run after bringing down the interface. circle-info If logging to syslog please remember to configure your syslog daemon accordingly, so that a dedicated logfile is created or the messages are included in the main system log. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#config-file) Config file Gateway configuration can also be read from a file by using a `--config` CLI option. Example file contents: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#yubibridge-configuration) YubiBridge configuration ----------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#environmental-variables) Environmental variables * `LOG_LEVEL`: Log messages level, default: `INFO`, available levels: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` * `WORKER_ID`: Name of your YubiBridge displayed on Defguard website, default: `YubiBridge` * `DEFGUARD_TOKEN`: - Secret worker token to secure gRPC communication, available on provisioners page * `SMARTCARD_RETRIES`: Number of retries in case provisioning failed, default: `1` * `JOB_INTERVAL`: Defines how often(seconds) YubiBridge checks Defguard for new jobs, default: `2` * `SMARTCARD_RETRY_INTERVAL`: Defines the number of seconds between trying to provision YubiKey again, default `15` ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#cli-arguments) CLI arguments: * `-h` , `--help`: Display help message * `-g `, `--grpc `: Connect to gRPC server at the given URL * `-i ` , `--id `: WorkerID, default `YubiBridge` * `-d` , `--debug`: Enable debug mode * `-t ` , `--tmpdir `: GnuPG home directory, default: `tmp` * `-p ` , `--provision `: Provision YubiKey with the following data * `-w ` , `--worker-token `: Secret worker token to secure gRPC communication, available on provisioners page * `-c ` , `--command `: Run command after provisioning and pass created keys as arguments ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#troubleshooting-the-configuration) Troubleshooting the configuration Common configuration issues. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway) Gateway `Error: Syslog(Initialization(Io(Os { code: 111, kind: ConnectionRefused, message: "Connection refused" })))` The selected syslog socket may be wrong. See the `syslog_socket` configuration option for the gateway: [Config file](https://docs.defguard.net/2.0/deployment-strategies/configuration#config-file) . Set it to a correct syslog socket on your operating system. The default socket is valid for FreeBSD. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/configuration#core-1) Core `Cookie “defguard_session” has been rejected for invalid domain.` (browser console error) This issue most often takes the form of not being able to login without any obvious cause. The login button doesn't redirect and no relevant error message is displayed in the Defguard Core logs. In this case we recommend checking the browser logs (usually right click > inspect should open the developer tools along with the browser console). If you can see the above error, this means that your `DEFGUARD_URL` configuration option doesn't match the URL you use to access the dashboard at the moment. For example, if your login screen is at `http://my.domain.com:8000/auth/login` set `DEFGUARD_URL` to `` http://my.domain.com:8000` `` . [PreviousAdding a location and getting a Gateway tokenchevron-left](https://docs.defguard.net/2.0/deployment-strategies/gateway) [NextRunning Gateway on OPNsense firewallchevron-right](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall) * [Core](https://docs.defguard.net/2.0/deployment-strategies/configuration#core) * [Secrets configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#secrets-configuration) * [General configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#general-configuration) * [Database configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#database-configuration) * [Auth cookies configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#auth-cookies-configuration) * [Stats cleanup configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#stats-cleanup-configuration) * [Enrollment configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#enrollment-configuration) * [Password reset configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#password-reset-configuration) * [gRPC server configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#grpc-server-configuration) * [Proxy connection configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#proxy-connection-configuration) * [Proxy service](https://docs.defguard.net/2.0/deployment-strategies/configuration#proxy-service) * [Gateway Configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway-configuration) * [Environmental variables / Arguments](https://docs.defguard.net/2.0/deployment-strategies/configuration#environmental-variables-arguments) * [Config file](https://docs.defguard.net/2.0/deployment-strategies/configuration#config-file) * [YubiBridge configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#yubibridge-configuration) * [Environmental variables](https://docs.defguard.net/2.0/deployment-strategies/configuration#environmental-variables) * [CLI arguments:](https://docs.defguard.net/2.0/deployment-strategies/configuration#cli-arguments) * [Troubleshooting the configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#troubleshooting-the-configuration) sun-brightdesktopmoon Copy # 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 = "" # Required: Defguard server gRPC endpoint URL # NOTE: must replace default with actual value grpc_url = "" # Optional: gateway name which will be displayed in Defguard web UI name = "Gateway on server X" # Required: use userspace Wireguard implementation (e.g. wireguard-go) userspace = false # Optional: path to TLS cert file - more in gRPC SSL communication help page # in our documentation. # 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 #pre_up = "/path/to/script.sh" # Optional: Command which will be run after bringing interface up #post_up = "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 = "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 = "ip route del default via 192.168.1.1 dev wg0" sun-brightdesktopmoon --- # Securing gRPC communication | 2.0 | defguard Defguard Core has two main communication endpoints: 1. gRPC port for communicating with Defguard Gateways, 2. gRPC port for communicating with Defguard Core. triangle-exclamation It is **critical** that: 1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes. 2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core. 3. If you want an additional layer of security, then you should create a **custom SSL Certificate Authority (CA)**, and provide Core, Proxy and Gateway Certificates from that CA so **any other connections to the gRPC services will not be accepted.** 4. Even if you have secured the network ports/firewall and do not want to create a custom SSL CA, please secure gRPC traffic with SSL and a reverse proxy. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) Custom SSL CA and certificates -------------------------------------------------------------------------------------------------------------------------------------------------------- To secure not only with firewall communication between all Defguard gRPC components, a custom SSL chain of certificates should be used. This way the trust will be ensured on the Transport Layer Security (TLS) level. It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one under which a service is being hosted. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#quick-setup) Quick setup To quickly generate a set of SSL certificates using [OpenSSLarrow-up-right](https://openssl-library.org/) or [LibreSSLarrow-up-right](https://www.libressl.org/) , use the following: * Generate Certificate Authority (CA) certificate and key for domain _example.local_ Copy openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt * Generate private key and Certificate Signing Request (CSR) * Generate certificate by signing the CSR, valid for 365 days circle-info Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly. To display certificate file contents: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-configuration) Defguard configuration #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-core) Defguard Core Using command line arguments Using environment variables #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-proxy) Defguard Proxy Using command line arguments Using environment variables ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-gateway) Defguard Gateway Using command line arguments Using environment variables Using configuration file [hashtag](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) Trusted CA (eg. Let'sEncrypt or others) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Often (like in the standalone package based installation tutorial) gRPC communication can be secured by a reverse proxy (NGINX, Caddy, Traefik, etc.) that handles SSL termination. It's common to use typical trusted CA (that is used for typical HTTPS traffic) like Let'sEncrypt or others. triangle-exclamation While this secures the transport layer and encrypts communication between Defguard components - it does not provide authorization between gRPC components like Custom CA does. Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall. If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for: * Defguard Gateway – in _gateway.toml_ add path to CA certificate file (in PEM format); for example, when using standard Let'sEncrypt installation ([Certbotarrow-up-right](https://certbot.eff.org/) ), you configure the CA path like this: * `grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem"` * Defguard Core – similarily, you need to configure Proxy CA certificate file using **DEFGUARD\_PROXY\_GRPC\_CA** environment variable: * `DEFGUARD_PROXY_GRPC_CA: /etc/letsencrypt/live/domain.name/chain.pem` [PreviousPre-production and development releaseschevron-left](https://docs.defguard.net/2.0/deployment-strategies/pre-production-and-development-releases) [NextUsing RSA instead of HMAC for OpenID keychevron-right](https://docs.defguard.net/2.0/deployment-strategies/openid-rsa-key) * [Custom SSL CA and certificates](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) * [Quick setup](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#quick-setup) * [Defguard configuration](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-configuration) * [Defguard Gateway](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#defguard-gateway) * [Trusted CA (eg. Let'sEncrypt or others)](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) sun-brightdesktopmoon Copy openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local Copy openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy Copy openssl x509 -noout -text -in core.crt Copy defguard --grpc-cert path/to/core.crt \ --grpc-key path/to/core.key \ --proxy-grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CERT=path/to/core.crt \ DEFGUARD_GRPC_KEY=path/to/core.key \ DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \ defguard Copy defguard-proxy --grpc-cert path/to/proxy.crt \ --grpc-key path/to/proxy.key Copy env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \ DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key defguard-proxy Copy defguard-gateway --grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CA=path/to/ca.crt \ defguard-gateway Copy grpc_ca = "path/to/ca.crt" sun-brightdesktopmoon --- # Running Gateway on MikroTik routers | 2.0 | defguard By leveraging the ability of some MikroTik routers to run Docker containers, it is possible to deploy the gateway directly on your router. circle-exclamation Proceed with extra caution when working with your core infrastructure. All official [RouterOS containers warningsarrow-up-right](https://help.mikrotik.com/docs/display/ROS/Container#Container-Disclaimer) still apply. triangle-exclamation Running the gateway on a MikroTik router is not fully supported. Due to custom RouterOS kernel incompatibility this kind of deployment does not support [Access Control List](https://docs.defguard.net/2.0/features/access-control-list) functionality. To run the gateway you must explicitly disable firewall management using the [`DEFGUARD_DISABLE_FW_MGMT` option](https://docs.defguard.net/2.0/deployment-strategies/configuration#gateway-configuration) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------------------------------------------- * RouterOS device with ARM or ARM64 architecture (popular home lab choices include RB4011 or RB5009) * `Container` package installed and enabled * Running Defguard core instance with a WireGuard location configured * (optional) Self-signed certificate generated by following [gRPC SSL setup guide](https://docs.defguard.net/2.0/deployment-strategies/grpc-ssl-communication) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#setup) Setup ------------------------------------------------------------------------------------------------------------------- circle-exclamation This guide assumes you do not have other Docker containers deployed on your router yet. If this is not the case adjust accordingly. The same applies if you have some more specific network configuration requirements. circle-info For brevity we'll be using RouterOS terminal commands, but everything can also be accomplished through WinBox GUI. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) Prepare network to install Docker container * First create a bridge interface for Docker containers and assign it an IP address in a dedicated Docker subnet (`172.17.0.0/24` in our example): * Each container must have a dedicated VETH interface; create a `veth1` interface and assign it an IP address in the chosen Docker subnet: * Add the virtual interface to the Docker bridge: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#setup-firewall-rules) Setup firewall rules * Set up NAT for outgoing traffic from containers: * Add port forwarding rule to send UDP traffic from the public WireGuard port to the gateway container: circle-exclamation Container port being forwarded to must match your public WireGuard port. * Add routing for your chosen WireGuard subnet configured in Defguard UI location settings: ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#run-gateway-container) Run gateway container * Configure environment variables for the gateway container: * (optional) To use SSL for communication between the gateway and your Defguard instance copy the root certificate to your router's filesystem and add a following mount and environment variable: circle-exclamation Put the root certificate in a directory and mount the whole directory. Trying to mount a specific file can cause unexpected issues. * Add GitHub container registry to config: * Finally, create the actual container: At this point you should see that the gateway is connected in your Defguard instance's web UI. [PreviousRunning Gateway on OPNsense firewallchevron-left](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-opnsense-firewall) [NextReverse Proxy configuration using NGINXchevron-right](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx) * [Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#prerequisites) * [Setup](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#setup) * [Prepare network to install Docker container](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#prepare-network-to-install-docker-container) * [Setup firewall rules](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#setup-firewall-rules) * [Run gateway container](https://docs.defguard.net/2.0/deployment-strategies/running-gateway-on-mikrotik-routers#run-gateway-container) sun-brightdesktopmoon Copy /interface/bridge/add name=docker /ip/address/add address=172.17.0.1/24 interface=docker Copy /interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1 Copy /interface/bridge/port add bridge=docker interface=veth1 Copy /ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24 Copy /ip/firewall/nat/add chain=dstnat protocol=udp dst-address= dst-port= action=dst-nat to-addresses=172.17.0.2 to-ports= Copy /ip/route/add dst-address= gateway=172.17.0.2 Copy /container/envs/add name=defguard_env key=DEFGUARD_TOKEN value= /container/envs/add name=defguard_env key=DEFGUARD_GRPC_URL value= /container/envs/add name=defguard_env key=DEFGUARD_DISABLE_FW_MGMT value=true Copy /container/mounts/add name=defguard_cert src= dst=/certs /container/envs/add name=defguard_env key=DEFGUARD_GRPC_CA value=/certs/myCA.pem Copy /container/config/set registry-url=https://ghcr.io Copy /container/add remote-image=ghcr.io/defguard/gateway:latest interface=veth1 envlist=defguard_env sun-brightdesktopmoon --- # High Availability and Failover | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#gateway-high-availability) Gateway - High Availability -------------------------------------------------------------------------------------------------------------------------------------------------------- We support running multiple gateways for a single VPN instance or location, enabling active-passive configurations. Active-active configurations should also be possible but come with some caveats. Since our gateway uses a vanilla kernel WireGuard®, there are multiple approaches for implementation. circle-info Please also see documentation of [Creating a New VPN location](https://docs.defguard.net/2.0/features/wireguard/create-your-vpn-network) where each [location setting has information regarding high-availability](https://docs.defguard.net/2.0/features/wireguard/create-your-vpn-network#vpn-location-settings) . #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#deploying-multiple-gateways-for-one-location) Deploying multiple gateways for one location To have a multi-gateway setup for a given location, you will need to [deploy the gateway on each one of your servers](https://docs.defguard.net/2.0/deployment-strategies/gateway) under the same location. If you already have a gateway deployed and want to add another one for the location, go to _VPN Overview_ -> Click: _Edit Location Settings (in the top right corner)_, then choose the location you want to add the new gateway to, and follow the deployment instructions: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F8zYuZXZDKhAXAmMhmK06%2FScreenshot%25202024-11-12%2520at%252016.55.55.png&width=768&dpr=3&quality=100&sign=5a19b4de&sv=2) Each gateway deployed for a given location will receive the same network configuration and will **bind to the defined port** in the location's _Gateway Port._ The only thing left to do is to point your traffic to those gateways, which can be accomplished in several ways: * Floating public IP - if you choose this scenario, please remember that the IP must be the IP specified in the Location _Gateway Address._ In this scenario, the floating IP switches between your gateway servers, directing the traffic to one of the two gateways. * Proxy/load balancing - also remember that the proxy must be configured with the _Gateway Address and Gateway Port._ In this scenario, your clients connect to the proxy/load balancer, which direct the VPN traffic (UDP) to one of your gateway backends_._ #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#active-active-setups) Active-active setups Active-active setups should also be possible but come with some caveats. Here are the currently known issues with such configurations: * Multiple running gateways bound to one location with network traffic distributed between them may produce invalid network usage statistics, making the network usage graphs and displays on the dashboard unreliable. Related issue: [https://github.com/DefGuard/defguard/issues/1022arrow-up-right](https://github.com/DefGuard/defguard/issues/1022) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) Determining if multiple gateways are running All gateways that are successfully connected for the location are displayed under the Location in VPN Overview, here is an example for two gateways: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fku9jjp3UpWhUKm2ByOM8%2Flocation-overview.png&width=768&dpr=3&quality=100&sign=8943e12e&sv=2) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) What is the gateway peers persistence (if core/proxy services fail) 1. For **VPN Locations without MFA** - it's persistent until the system reboot - _even if the gateway will not work_ - as the gateway configures WireGuard "in kernel". 2. For **VPN Locations with MFA**, this depends on the _Peer Disconnect Threshold (seconds)_ setting in the VPN Location settings. This setting specifies that if the peer is inactive for _(defined seconds)_, the gateway should remove it from the configuration. Therefore, if the proxy/core is not operational, MFA authentication will fail, and the peer will not be added if it is disconnected. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#core-proxy-failover) Core / Proxy - Failover ---------------------------------------------------------------------------------------------------------------------------------------------- The core service handles gateway states as well as core connects _**to the proxy**_. Since proxy serves HTTP based protocol communication and should be in the public Internet, it needs to be secure, thus core connects to the proxy. This way **core can be in an Intranet network segment and proxy can be in DMZ, making Core completely cut-off on firewall from the Internet** (you only can have only outgoing firewall rules from Intranet allowing only for core to connect to proxy). So **High Availability for core and proxy** gets complicated, with multiple proxies core needs to manage those connections. We already have most of the code for that ready, but it's not yet production ready. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#how-to-bullet-proof-proxy-and-core-with-failover) How to bullet-proof proxy & core with failover? We recommend to deploy them on a failover solution - like on a kubernetes cluster (even small one - like mini-kube) . This way, Kubernetes manages: healthchecks and does failover. You can have cluster N-nodes and if any VM/node with Core/Proxy goes offline or health checks fail - it's migrated to a new node. [PreviousReverse Proxy configuration using NGINXchevron-left](https://docs.defguard.net/2.0/deployment-strategies/reverse-proxy-configuration-using-nginx) [NextUpdating and version compatibilitychevron-right](https://docs.defguard.net/2.0/deployment-strategies/updating-and-version-compatibility) * [Gateway - High Availability](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#gateway-high-availability) * [Determining if multiple gateways are running](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) * [What is the gateway peers persistence (if core/proxy services fail)](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) * [Core / Proxy - Failover](https://docs.defguard.net/2.0/deployment-strategies/high-availability-and-failover#core-proxy-failover) sun-brightdesktopmoon sun-brightdesktopmoon --- # Health check | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/health-check#proxy) Proxy -------------------------------------------------------------------------------------------- [Proxyarrow-up-right](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application is running. Example request: Copy curl "https://enroll.example.com/api/v1/health" Response: Copy "alive" - with status code 200 - Proxy is working To verify gRPC services for **Proxy** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. Example request: Copy curl "https://enroll.example.com/api/v1/health-grpc" Response: Copy "alive" with status code 200 - Proxy is working and is connected to CORE "Not connected to Defguard Core" - with status code 503 - Proxy is working but is not connected to CORE [hashtag](https://docs.defguard.net/2.0/deployment-strategies/health-check#core) Core ------------------------------------------------------------------------------------------ To check if [**Core**arrow-up-right](https://github.com/defguard/defguard) is working, you can use endpoint at `GET /api/v1/health` which verify it. Example request: Copy curl "https://defguard.example.com/api/v1/health" Response: To check if core gRPC service is alive, we recommend to use community tools like [grpc\_health\_probearrow-up-right](https://github.com/grpc-ecosystem/grpc-health-probe) . Example request for core: Example response: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/health-check#gateway) Gateway ------------------------------------------------------------------------------------------------ You can enable in gateway config ([example configarrow-up-right](https://github.com/DefGuard/gateway/blob/main/example-config.toml) ) a health check port, by adding the following line: In this example, gateway will open an additional HTTP port number 55003. Now we can use `GET /api/v1/health` endpoint to verify whether gateway is working correctly. If running in Docker you can also enable it by setting the `HEALTH_PORT` [environment variable](https://docs.defguard.net/2.0/deployment-strategies/configuration#environmental-variables-arguments) . By default the HTTP server will listen on all interfaces, but if you prefer to bind only a specific IP you can set it by using the `http_bind_address` config option (or `DEFGUARD_HTTP_BIND_ADDRESS` environment variable). For example: Example request: Response: By default, no health check ports are open. [PreviousUsing RSA instead of HMAC for OpenID keychevron-left](https://docs.defguard.net/2.0/deployment-strategies/openid-rsa-key) [NextProduction deployment verification guidechevron-right](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/health-check#proxy) * [Core](https://docs.defguard.net/2.0/deployment-strategies/health-check#core) * [Gateway](https://docs.defguard.net/2.0/deployment-strategies/health-check#gateway) sun-brightdesktopmoon Copy "alive" - with status code 200 - Core is working Copy ./grpc_health_probe -addr=defguard.example.com:50055 Copy status: SERVING Copy health_port = 55003 Copy http_bind_address = 10.0.10.20 Copy curl "http://gateway.example.com:55003/api/v1/health" Copy "alive" - with status code 200 - Gateway is working and is connected to CORE "Not connected to core" - with status code 503 - Gateway is working but is not connected to CORE sun-brightdesktopmoon --- # Migration guides | 2.0 | defguard circle-exclamation Before doing any updates please remember to **backup your database.** [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.5.x-greater-than-1.6.0) 1.5.x -> 1.6.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core) Core #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#service-locations) Service locations A new feature has been introduced: [Service locations](https://docs.defguard.net/2.0/features/service-locations) . This feature requires both Defguard Core and Proxy to be updated to the 1.6.0 version. Updating only one of those components will prevent this feature from working properly. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy) Proxy #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#service-locations-1) Service locations As mentioned in the Core migration section, this feature requires both Defguard Core and Proxy to be updated to the 1.6.0 version. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client) Desktop client #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#service-locations-2) Service locations The [Service locations](https://docs.defguard.net/2.0/features/service-locations) feature currently only works on the Windows Desktop Client. Locations in the service location mode won't be sent to clients that don't support them (either are older than 1.6.0 or are on a different platform than Windows). To work properly, this feature requires the Desktop Client to be in version 1.6. Service locations won't show up or work in older clients. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#force-all-traffic) Force all traffic 1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](https://docs.defguard.net/2.0/features/wireguard/behavior-customization#client-traffic-policy-selection) . However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#macos-client-changes) macOS Client changes Desktop Client is now distributed in App Store and uses native VPN management. For these reasons, the user settings have moved from `~/Library/Application Support/net.defguard` to `~/Library/Containers/net.defguard/Data/Library/Application Support/net.defguard`. In order to preserve settings from v1.5.x, use one of the following guides to transfer the data: **Using Finder** 1. In Finder, select the menu **Go**, press and hold _Alt_ key, then select **Library**, as depicted below. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F29J4PQ1FnrDJiUXT4jO7%2Ffinder-go-library.png&width=768&dpr=3&quality=100&sign=d19c4947&sv=2) 1. Move or copy the contents of _Application Support_ > _net.defguard_ to _Containers_ > _net.defguard_ > _Data_ > _Library_ > _Application Support_ > _net.defguard_ **Using Terminal** Open Terminal.app and execute #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#windows-client-changes) Windows Client changes The Windows Desktop Client installer has changed. The installer is now provided in an `.msi` format. Installing the new 1.6.0 Client from the `.msi` will leave the previous Client version still installed. This can also cause old VPN connections to still be active until a next system restart is performed. To resolve this, before upgrading, we recommend first uninstalling the old Client. This will leave your configuration intact and it should carry over to the new Client after its installation, without the need to configure everything again. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#mobile-client) Mobile client **Force all traffic** 1.6 introduces the ability to "Force all traffic" as a [Client traffic policyarrow-up-right](https://app.gitbook.com/o/Z3mGSAbEj9iLdZ7cNFlL/s/e86iamwJVSYnIRsyVEAV/features/wireguard/behavior-customization#client-traffic-policy-selection) . However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) 1.4.x -> 1.5.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-1) Core #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#version-compatibility) Version compatibility This release introduces a version checking system. All the Defguard system components (core, proxy, gateway and clients) are now version-aware and check their compatibility with the components their are communicating with. This might mean that until you upgrade all the components your web UI might indicate that your proxy or gateway is of an unknown version. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#instance-uuid-bug) Instance UUID bug A bug resulting in zeroing the UUID of a given instance has been found and resolved ([PR linkarrow-up-right](https://github.com/DefGuard/defguard/pull/1521) ). This value is used by the desktop client to identify instances. The new client should gracefully handle migration to a new UUID if it has been zeroed out due to the bug mentioned above. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#verify-client-disconnect-threshold-for-your-mfa-locations) Verify client disconnect threshold for your MFA locations In order to ensure that MFA works correctly with the new [mobile clients](https://docs.defguard.net/2.0/using-defguard-for-end-users/mobile-client) please ensure that the [client disconnect threshold](https://docs.defguard.net/2.0/features/wireguard/create-your-vpn-network#client-disconnect-threshold) is set to at least 300s (5 minutes). ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy-1) Proxy We've introduced a new functionality to Desktop Client - to authenticate [Multi-Factor connections using Mobile Client](https://docs.defguard.net/2.0/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa) . For this feature to work, Proxy (enrollment service) creates a Web-socket that the desktop client connects to while waiting for responses from the mobile client. circle-exclamation If you have a reverse proxy for the enrollment service (which we highly recommend with SSL termination), please **make sure that web-sockets are enabled.** ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-1) Desktop client #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#unix-socket-ipc-and-new-user-group-requirement-macos-and-linux) Unix socket IPC and new user group requirement (macOS & Linux) macOS and Linux clients now use Unix sockets for IPC. To securely access this socket the user must belong to a specific group as described in [client documentation](https://docs.defguard.net/2.0/using-defguard-for-end-users/desktop-client) . The change should require no additional steps for macOS users, but Linux users who install the client from official packages will need to log out and back in or reboot after install to refresh group membership. This will not be required on subsequent updates. Linux users who use release binaries will need to manually create the `defguard` group and adjust their group membership. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) Any release <= 1.3 -> 1.4 -------------------------------------------------------------------------------------------------------------------------------------------------- 1.4 release introduces changes related to multiple client IP addresses. To ensure compatibility, **all components must be updated** to v1.4 or higher: * **Core** * **Proxy** * **Gateway** * **Desktop Clients** Running outdated versions may result in errors due to incompatible data formats. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-2) Core We've made a small update to the LDAP integration to support more complex user nesting within the LDAP tree ([related issuearrow-up-right](https://github.com/DefGuard/defguard/issues/1242) ). If you were already using the integration, you shouldn't notice any changes. However, we **strongly recommend backing up your database before the upgrade and afterwards verifying** the following to ensure everything continues to work as expected: * Your Defguard user list and user devices remain unchanged * All users can still log in without issues If you encounter any problems, please report them on our [GitHubarrow-up-right](https://github.com/DefGuard/defguard/issues) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) Any previous release → 1.4.0-alpha3 --------------------------------------------------------------------------------------------------------------------------------------------------- We've introduced some changes to the LDAP integration. We recommend reading [the above section](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core) before upgrading. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-release-1.3.0) Any previous release → 1.3.0 ------------------------------------------------------------------------------------------------------------------------------------- * The LDAP integration has become an enterprise feature. You will need to purchase the enterprise license if you exceed the free limits. See [Purchasing and using the license](https://docs.defguard.net/2.0/enterprise/license) for more information regarding the license. * If you used the LDAP integration previously, it will be off by default after upgrading. You will have to manually enable it in the settings in the LDAP tab:\\ ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FAIjyFXAAccd2CcridSsw%2Fimage.png&width=768&dpr=3&quality=100&sign=172cab2d&sv=2) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) Any previous 1.3.0 alpha → 1.3.0 alpha 4 ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-3) Core LDAP integration received a major overhaul of how users are mapped to Defguard users when the two-way synchronization is enabled. Now, users are always identified by their leftmost DN value. A new synchronization may cause some of your users to be re-added, which in turn may cause the loss of some of their Defguard specific data (e.g. their devices). This will happen if your leftmost DN component's attribute (referred to as RDN) is not the same as your current username attribute. This issue is only related to the two-way synchronization mechanism and occurs only if you used one of the previous alphas of 1.3.0. Upgrading from any previous release to alpha 4 (skipping the alphas before) should not result in this happening. Before an upgrade, turn off the two-way synchronization. After upgrading, you will have access to a new option, the RDN user attribute: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fylx6JUxpg0ewYtdDVobp%2Fimage.png&width=768&dpr=3&quality=100&sign=533b5c03&sv=2) Set it according to your LDAP server setup. This should be the DN's leftmost component attribute, e.g. in the case of `cn=user1,cn=users,dc=ad,dc=example,dc=com` this would be "cn". This attribute is needed to properly identify users in your LDAP server. The username attribute will be mapped to Defguard usernames. Read [Settings table](https://docs.defguard.net/2.0/features/ldap-and-active-directory-integration/settings-table) for a description of those settings options. After you configured this value, you can re-enable the two-way synchronization. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) Any previous core release -> core 1.1.4 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-4) Core triangle-exclamation In Core 1.1.4, we've made email addresses case insensitive, as this is a standard for many major providers. Because the emails were case sensitive up to this point, you may end up with users with the same email addresses from core's point of view. All email addresses must be unique case-insensitively, meaning that a user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) ` can't coexist with another user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) `. Before upgrading, make sure you don't have any users with the same email addresses given the above. If you do, please change those addresses or remove the users altogether. Remember to check it case-insensitively. If you have users with duplicate email addresses, the migrations will fail, and you won't be able to upgrade. You can use the following SQL query to locate users with duplicate emails in the database: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) 1.0.0 -> 1.1.0 ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy-2) Proxy There is a new setting: * ENV Variable: DEFGUARD\_PROXY\_URL * command line argument `--url` * /etc/defguard/proxy.toml: `url =` **Which should be set to the same value as in core** `**DEFGUARD_ENROLLMENT_URL**` [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-release-greater-than-1.0.0) Any release -> 1.0.0 --------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-5) Core When upgrading core to 1.0.0 (even to a 1.0.0 pre-release) make sure that your users **have unique email addresses** as we've introduced a constraint requiring email addresses to be unique among users. triangle-exclamation If you have duplicate emails in your database, the migrations during the upgrade process will simply fail. You will need to change a duplicate email address before the upgrade by hand via the Defguard dashboard or by accessing the database. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-real-time-sync) Desktop Client Real Time Sync From 1.0.0 we have introduced [Enterprise featuresarrow-up-right](https://github.com/DefGuard/docs/blob/docs/deployment-strategies/broken-reference/README.md) , and one of them is [automatic and real-time desktop client configuration synchronization](https://docs.defguard.net/2.0/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration) . To enable this on an **already configured desktop client,** one must perform one time instance update, which will generate necessary tokens on the client to perform from now on automatic updates. In details: 1. The admin must generate a new token for the client - [more details here](https://docs.defguard.net/2.0/features/wireguard/remote-desktop-activation) (token can be sent over email or shared in any other secret way). 2. The user must perform the [Instance Update - more details here](https://docs.defguard.net/2.0/using-defguard-for-end-users/desktop-client/instance-configuration#updating-instance) . circle-exclamation Any client that is configured from scratch has this done automatically and no actions needed to be done. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In this release, we have **hardened the security architecture**, and since the Proxy component is open for HTTP commands and is frequently communicating with Core we have reversed the communication and now **Core is connecting to Proxy (Proxy is a gRPC server and Core is the client).** This way if Core is in a secure network segment (like Intranet) and Proxy in a DMZ segment (where Internet traffic is allowed) you don't need to open on your firewall rules for Proxy from DMZ to connect to Intranet (no packet for New Connections from DMZ->Intranet). This change requires a few changes if you are upgrading: #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy-deployment-configuration) Proxy deployment configuration 1. Remove `DEFGUARD_PROXY_UPSTREAM_GRPC_URL` variable - since Proxy does not connect to Defguard Core any more. 2. Proxy is now the server to which Defguard Core connects, so you may want to: 1. Optional: configure non-default Proxy gRPC port with `DEFGUARD_PROXY_GRPC_PORT -` default value is **50051** 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/treafik/...) the port with SSL/TLS. 1. (Optional) If you want to use SSL with Proxy gRPC server without revers-proxy (nginx/etc) configure `DEFGUARD_PROXY_GRPC_CERT` and `DEFGUARD_PROXY_GRPC_KEY` following the [SSL setup guide](https://docs.defguard.net/2.0/deployment-strategies/docker-compose#grpc-ssl-setup) . 3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server **can be reached from Core**. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-deployment-configuration) Core deployment configuration 1. Add `DEFGUARD_PROXY_URL` variable to point to your Proxy gRPC server endpoint, for example `http://proxy:50051` when using Docker Compose - or any gRPC URL you have configured with your reverse proxy. 2. (Optional) If using SSL configure `DEFGUARD_PROXY_GRPC_CA` #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#upgrade-process) Upgrade process 1. Update Core & Proxy images/binaries and restart services. 2. You should see in the logs that Proxy is awaiting a gRPC connection - example docker logs: 1. Core should be attempting to establish a gRPC connection with Proxy (and retrying every 10s if unable to successfully connect), like this: 1. After Defguard connects successfully to proxy, you should see in proxy logs: [hashtag](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) Desktop Client 0.1.x -> 0.2.0 --------------------------------------------------------------------------------------------------------------------------------------------------- With this release we have added Multi-Factor Authentication to the desktop client. Unfortunately desktop client database has change significantly as well as business logic (for example endpoints to proxy for MFA handshake). We have not stored them previously in the database - thus they cannot be recovered/updated automatically. circle-exclamation That unfortunately means you have to remove all your instances before upgrading (or just remove any desktop client configuration files, including the database) and start the enrollment (adding new instance) again after upgrading - just by adding a new device (you can remove the old one). [PreviousUpdating and version compatibilitychevron-left](https://docs.defguard.net/2.0/deployment-strategies/updating-and-version-compatibility) [NextUsing a userspace wireguard-go implementationchevron-right](https://docs.defguard.net/2.0/deployment-strategies/using-a-userspace-wireguard-go-implementation) * [1.5.x -> 1.6.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.5.x-greater-than-1.6.0) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy) * [Desktop client](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client) * [Mobile client](https://docs.defguard.net/2.0/deployment-strategies/upgrading#mobile-client) * [1.4.x -> 1.5.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-1) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy-1) * [Desktop client](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-1) * [Any release <= 1.3 -> 1.4](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-2) * [Any previous release → 1.4.0-alpha3](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) * [Any previous release → 1.3.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-release-1.3.0) * [Any previous 1.3.0 alpha → 1.3.0 alpha 4](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-3) * [Any previous core release -> core 1.1.4](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-4) * [1.0.0 -> 1.1.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) * [Proxy](https://docs.defguard.net/2.0/deployment-strategies/upgrading#proxy-2) * [Any release -> 1.0.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#any-release-greater-than-1.0.0) * [Core](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-5) * [Desktop Client Real Time Sync](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-real-time-sync) * [Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x](https://docs.defguard.net/2.0/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) * [Desktop Client 0.1.x -> 0.2.0](https://docs.defguard.net/2.0/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) sun-brightdesktopmoon Copy rm -r ~/Library/Containers/net.defguard/Data/Library/Application\ Support/net.defguard mv ~/Library/Application\ Support/net.defguard ~/Library/Containers/net.defguard/Data/Library/Application\ Support/ Copy select id, username, email from "user" where lower(email) in ( select lower(email) from "user" group by lower(email) having count(*) > 1 ) Copy Attaching to defguard_proxy_1 proxy_1 | 2024-01-24T14:05:41.365035Z INFO defguard_proxy::server: Starting Defguard proxy server proxy_1 | 2024-01-24T14:05:41.365069Z DEBUG defguard_proxy::server: Setting up API server proxy_1 | 2024-01-24T14:05:41.365130Z INFO defguard_proxy::server: gRPC server is listening on 0.0.0.0:50051 proxy_1 | 2024-01-24T14:05:41.365333Z INFO defguard_proxy::server: Web server is listening on 0.0.0.0:8080 Copy defguard | 2024-01-24T14:17:47.815294Z INFO defguard::grpc: Connecting to proxy Copy proxy_1 | 2024-01-24T14:17:47.819504Z INFO defguard_proxy: RPC client connected from: 10.123.123.2:35916 sun-brightdesktopmoon --- # Linux Kernel WireGuard tuning | 2.0 | defguard [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#introduction) Introduction --------------------------------------------------------------------------------------------------------------------------- WireGuard is widely praised for its lean codebase and efficiency. However, the default Linux kernel settings are often tuned for general-purpose computing, not for acting as a high-speed router handling encrypted UDP traffic at scale. Here are some tuning parameters to achieve maximum performance (low latency), stability across changing networks (roaming), and high concurrency, we must tune three distinct layers. circle-info Kernel **sysctl** settings optimize how the Linux kernel schedules packets and manages memory buffers. Add the following to `/etc/sysctl.d/99-wireguard-tuning.conf`. or `/etc/sysctl.conf` [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#kernel-tuning) Kernel tuning ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#congestion-control-and-queuing-latency-and-throughput) Congestion Control & Queuing (Latency & Throughput) To reduce bufferbloat (latency spikes under load) and maximize throughput, we replace the default CUBIC algorithm with BBR (Bottleneck Bandwidth and Round-trip propagation time), which is less sensitive to packet loss and more aggressively seeks the optimal congestion window. Copy # Use BBR congestion control net.core.default_qdisc = fq net.ipv4.tcp_congestion_control = bbr ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#memory-and-buffers-throughput) Memory & Buffers (Throughput) WireGuard uses UDP for data transport. By default, Linux kernel UDP buffer sizes are often too small for high-speed transfers (1 Gbps+), causing packets to be dropped in the kernel before WireGuard can process them. Copy # Increase default and max receive/send window sizes (approx 16MB) net.core.rmem_max = 16777216 net.core.wmem_max = 16777216 net.core.rmem_default = 262144 net.core.wmem_default = 262144 net.ipv4.udp_mem = 4096 87380 16777216 ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#packet-processing-and-forwarding-efficiency) Packet Processing & Forwarding (Efficiency) These settings allow the kernel to process packets faster and handle bursts of traffic without dropping them. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#packet-buffering) Packet buffering In Linux, network cards (NICs) use **NAPI** (New API) polling to handle incoming packets. When an interrupt fires, the kernel disables further interrupts and polls the NIC, processing packets in batches. `net.core.netdev_budget` limits how many packets the kernel may process in a single SoftIRQ cycle before yielding the CPU and it's default is: 300 packets. * Too low value - Under heavy load (e.g., 100+ streaming users), the kernel yields too early, packets back up in the NIC buffer, and drops occur. * Too high value - The networking stack can monopolize a CPU core, starving userspace processes and increasing overall latency. For high-performance VPN servers, we increase `netdev_budget` to favor network throughput and tune the companion setting `netdev_budget_usecs` to cap CPU time per polling cycle. Below you wil find some recommended values for multiple scenarios. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#home-small-office) Home/Small Office Meaning around ~20 users: The default 300 is fine and changing it won't be noticeable. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#id-50-vpn-users-and-above) 50 VPN users and above #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#high-throughput-10gbps) High throughput ≥ 10Gbps You may need values as high as `netdev_budget = 1200`, assuming you have a powerful CPU with Receive Packet Steering (RPS) enabled. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#multiple-connection-concurrency-egress-via-vpn) Multiple connection concurrency (egress via VPN) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- WireGuard is stateless, but the Linux firewall tracking (used for Masquerade or DNAT when configuring connection tracking and egress through VPN) is stateful. Here is a formula how to optimize netfliter parameters based on the following assumptions that one connected device is a UDP stream (VPN) and multiple TCP streams that the user/device "uses" for browsing/apps "exiting" via VPN: circle-exclamation **Assumptation**: 1 active user generates ~50-100 simultaneous connections Parameter (Sysctl) Description 10 Devices(Home/SOHO) 100 Devices(SMB/Office) 1,000 Devices(Enterprise/ISP) 10,000 Devices(Data Center) `net.netfilter.nf_conntrack_max` CRITICAL. Max concurrent connections tracked. 65536 131072 524288 5242880 `net.core.somaxconn` Max pending connections in queue. 4096 4096 16384 65535 `net.core.netdev_max_backlog` Max packets queued if kernel is busy. 1000 5000 16384 65535 `net.core.netdev_budget` Max packets processed in one CPU cycle. 300 600 600 1200 `net.core.rmem_max` (Bytes) Max OS receive buffer size (UDP). 16 MB 16 MB 32 MB 128 MB `net.core.wmem_max` (Bytes) Max OS send buffer size (UDP). 16 MB 16 MB 32 MB 128 MB `fs.file-max` System-wide file descriptor limit. Default 100000 1000000 5000000 **Required System RAM** Minimum RAM needed for state tables. 512 MB 1 GB 4 GB 32 GB+ [PreviousProduction deployment verification guidechevron-left](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide) [NextPreviewing Defguard v2.0-alphachevron-right](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha) Last updated 21 days ago * [Introduction](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#introduction) * [Kernel tuning](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#kernel-tuning) * [Congestion Control & Queuing (Latency & Throughput)](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#congestion-control-and-queuing-latency-and-throughput) * [Memory & Buffers (Throughput)](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#memory-and-buffers-throughput) * [Packet Processing & Forwarding (Efficiency)](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#packet-processing-and-forwarding-efficiency) * [Packet buffering](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#packet-buffering) * [50 VPN users and above](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#id-50-vpn-users-and-above) * [Multiple connection concurrency (egress via VPN)](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning#multiple-connection-concurrency-egress-via-vpn) sun-brightdesktopmoon Copy # Enable IP Forwarding (Required for VPN) net.ipv4.ip_forward = 1 # Increase the maximum length of the processor input queue # (Prevents drops during traffic bursts) net.core.netdev_max_backlog = 5000 # Increase the maximum number of connections waiting for acceptance net.core.somaxconn = 8192 Copy # --- NAPI Polling Budget Tuning --- # Increase packet budget (Default: 300). # Allow the CPU to process up to 600 packets in one cycle. # Beneficial for high PPS (packets per second) environments. net.core.netdev_budget = 600 # Increase the time budget (Default: 2000us or 2ms). # Allow the NAPI cycle to run for up to 4ms before yielding. # Prevents the loop from aborting prematurely during heavy traffic bursts. net.core.netdev_budget_usecs = 4000 sun-brightdesktopmoon --- # Deploying to Production | defguard 1 **Gain knowledge** Before you start your deployment, take a moment to learn about Defguard. The following articles will help you make deployment decisions and understand which features you may want to configure afterward. Make sure to read them carefully. * [Defguard's features](https://docs.defguard.net/about/features-overview) * [Defguard's architecture](https://docs.defguard.net/in-depth/architecture) 2 **Choose your deployment strategy** Decide which deployment approach best fits your infrastructure and security requirements. Choose from different [deployment strategies](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) and their recommended use cases. 3 **Prepare your environment** Make sure your infrastructure meets all [system and network requirements](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) . 4 **Deploy using the chosen strategy** Deploy your instance using the chosen [strategy](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) . Make sure to follow the right [deployment sequence](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) . 5 **Test if everything works as expected** Follow our [guide](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide) to test if your deployment in secure and works as expected. 6 **Configure features** Follow detailed descriptions of [Defguard's featuresarrow-up-right](https://github.com/DefGuard/docs/blob/v1.6/deployment-strategies/broken-reference/README.md) . As you follow along, you can adjust the configuration directly within your instance. For a detailed list of all configurable things through environmental variables, options or configuration files follow [this reference](https://docs.defguard.net/deployment-strategies/configuration) . 7 **Your secure infrastructure is ready for use** Optional but recommended additional steps: * [Securing internal gRPC communication](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * [Configuring backups](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#backup) * [Setting up for high availability and failover](https://docs.defguard.net/deployment-strategies/high-availability-and-failover) [PreviousOverviewchevron-left](https://docs.defguard.net/deployment-strategies/setting-up-your-instance) [NextHardware, OS, network and firewall recommendationschevron-right](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) Last updated 12 days ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Overview | defguard Welcome to the deployment strategies section of Defguard documentation. This guide covers the different ways you can deploy Defguard in your environment, from quick options using packages or Docker to more advanced setups with Kubernetes or Terraform. Whether you're running a small instance or preparing for a more complex production environment, this section will help you choose the deployment method that best fits your needs. [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#before-you-begin) Before you begin -------------------------------------------------------------------------------------------------------------------------- 1. Make sure you understand [Defguard's architecture](https://docs.defguard.net/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. 2. Make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) Initial deployment sequence ------------------------------------------------------------------------------------------------------------------------------------------------ Before deploying any Gateways, you must first install and configure the Core service. The Core acts as the central control plane - it manages configuration, authentication, and communication with all connected Gateways. Once the Core is running and accessible, log in to the admin interface and navigate to the Gateways section. Create a new Gateway entry to generate a unique registration token. This token will be used during the Gateway deployment process to securely link the Gateway instance with your Core. After obtaining the token, proceed with deploying the Gateway service. During its initial setup, provide the generated token so that the Gateway can authenticate and register itself with the Core. Once registration is complete, the Gateway will appear in the Core dashboard and start receiving configuration updates automatically. #### [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#long-story-short) Long story short: 1 **Deploy Defguard Core service.** 2 **Add a new location in Core's web interface and obtain a token.** More on that [here](https://docs.defguard.net/deployment-strategies/gateway) . 3 **Deploy Gateway configured with the token.** [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) Choose your deployment strategy -------------------------------------------------------------------------------------------------------------------------------------------------------- Strategy name Difficulty Production readiness Purpose [One-line script](https://docs.defguard.net/getting-started/one-line-install) 🟢 Easy, single command installation ❌ Doesn't follow the [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) For testing purposes only [Standalone packages](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation) 🟢 Easy, using apt and dpkg ✅ If you followed the [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Docker Compose](https://docs.defguard.net/deployment-strategies/docker-compose) 🟡 Medium, Docker knowledge required ✅ If you followed the [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) Small to medium deployment [Kubernetes](https://docs.defguard.net/deployment-strategies/kubernetes) 🔴 Advanced, requires a k8s cluster and administrator ✅ If you followed the [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) Large or enterprise deployments [Terraform](https://docs.defguard.net/deployment-strategies/terraform) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [AMI and AWS CloudFormation](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation) 🔴 Advanced, requires an AWS account and knowledge ✅ Large or enterprise deployments [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#configure-to-your-needs) Configure to your needs ---------------------------------------------------------------------------------------------------------------------------------------- See our [configuration documentation](https://docs.defguard.net/deployment-strategies/configuration) to learn about all the settings you can change in your deployment. [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#backup) Backup ------------------------------------------------------------------------------------------------------ [Core servicearrow-up-right](https://github.com/DefGuard/defguard) is the only service which uses persistent data storage, which is PostgreSQL database. Every SQL migration is applied automatically while bringing up core server and we try our best not to break anything in the process. It's recommended to do database, configuration and Settings(SMTP, Branding) backup before every update in case of some unexpected failure. Example database backup: [hashtag](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#failover-ha-clustering) Failover/HA/Clustering -------------------------------------------------------------------------------------------------------------------------------------- The [Gateway](https://docs.defguard.net/deployment-strategies/gateway) can be deployed on multiple servers, firewalls, or routers for failover and high availability (HA). Even if the connection to the Core is lost, gateways continue operating using their local cache and data, ensuring that the VPN remains functional. Conversely, if a gateway becomes unavailable, other Core features (such as OpenID) will continue to work normally. For details on deploying multiple Gateway to [High Availability and Failover](https://docs.defguard.net/deployment-strategies/high-availability-and-failover) documentation. [PreviousGenerating enrollment tokens with Defguard REST APIchevron-left](https://docs.defguard.net/features/desktop-client-auto-provisioning/generating-enrollment-tokens-with-defguard-rest-api) [NextDeploying to Productionchevron-right](https://docs.defguard.net/deployment-strategies/deploying-to-production) Last updated 8 days ago * [Before you begin](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#before-you-begin) * [Initial deployment sequence](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#initial-deployment-sequence) * [Choose your deployment strategy](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) * [Configure to your needs](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#configure-to-your-needs) * [Backup](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#backup) * [Failover/HA/Clustering](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#failover-ha-clustering) sun-brightdesktopmoon Copy docker exec {container_name} pg_dump -U {user_name} > {backup_file_name} sun-brightdesktopmoon --- # Previewing Defguard v2.0-alpha | 2.0 | defguard This tutorial will help you test the new major update to Defguard - version 2.0. For the list of changes made in this version, go to our release blog post or release notes. triangle-exclamation This is an early alpha! Do not migrate from your previous production versions to this one! This release is only for setting up new, test instances. It's meant to preview the upcoming v2.0 and gather feedback. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#starting-defguard-2.0) Starting Defguard 2.0 ---------------------------------------------------------------------------------------------------------------------------------------------- We've prepared a convenient docker compose config file that allows you to easily set up the whole Defguard stack and test the new UI and functionalities. To start the Defguard v2.0 stack, do the following: Copy git clone https://github.com/DefGuard/deployment.git defguard-deployment cd defguard-deployment/docker-compose2.0 docker compose up -d This will start 8 docker containers: * db - PostgreSQL database * core - Defguard Core component (main control plane) * edge1, edge2, edge-lb - two Defguard Edge (formerly Proxy) components with a NGINX-based load balancer (user enrolment and client app configuration) * gateway1, gateway2, gateway-lb - two Defguard Gateway components with an Envoy-based load balancer (VPN gateways) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#initial-configuration) Initial configuration ---------------------------------------------------------------------------------------------------------------------------------------------- Notice that the Docker Compose file contains only minimal configuration parameters. This is one of the major changes in the new version. All configuration that was previously stored in environment variables or configuration files is now stored in the database and initialized using a convenient **setup wizard**. To begin the initial configuration, just visit this address http://localhost:8000/ after you started the stack with Docker Compose. Defguard will detect that this is a fresh instance and will welcome you with the setup wizard. The setup process contains several major steps: * Creating admin user account * Creating a custom CA for securing inter-component communication * Setting up Edge component to securely expose selected functionality to the internet while keeping the Core component isolated * Creating an initial VPN Location (logical VPN site) * Creating a VPN Gateway for the initial VPN Location (actual VPN server) For the stable version of 2.0 (or in following alpha) we'll also add a **migration wizard** that will help you to upgrade from previous Defguard version to the latest one with ease. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#example-setup) Example setup 1 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#go-to-the-core-component-ui) Go to the Core Component UI Visit [http://localhost:8000arrow-up-right](http://localhost:8000/) after starting the stack using Docker Compose. See the Initial Setup Wizard is being triggered automatically. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252F96JfaO3xwocSIvgo7QVG%252FScreenshot%25202026-02-08%2520at%252022.29.27.png%3Falt%3Dmedia%26token%3D6c3f81c5-9101-4677-b1e6-9d8e1a5682a3&width=768&dpr=3&quality=100&sign=e2cc6351&sv=2) 2 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#create-admin-user-account) Create admin user account ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FSImjmwlZvkxVVoyNxMn4%252FScreenshot%25202026-02-08%2520at%252022.29.56.png%3Falt%3Dmedia%26token%3D5ff92a02-b042-4a63-971a-065a63c20f80&width=768&dpr=3&quality=100&sign=92429d6c&sv=2) 3 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#provide-general-configuration) Provide general configuration You can set `http://localhost:8080` as the _Public Edge Component URL_ if you'll only test the setup using the Defguard Desktop Application on the same machine. If you're planning to also test the setup using the Defguard Mobile Application connected to the same local network, setting it to the IP address you got in the network is a better idea. I got mine by executing this command on my MacOS: and set it to `http://192.168.83.132:8080`. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FdLfdchmZx5LYkySDNCvS%252FScreenshot%25202026-02-08%2520at%252022.30.27.png%3Falt%3Dmedia%26token%3Ded2fa2ab-e89d-401f-876f-005a9bb5e612&width=768&dpr=3&quality=100&sign=4fe11f68&sv=2) 4 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#create-custom-certificate-authority) Create custom Certificate Authority Previously Defguard administrators had to configure this manually and often skipped the process. We wanted to make this step much easier because we know it's crutial for the system's security. Now Defguard handles both creating the custom CA and using it to generate certificates for Edge and Gateway component while adopting them. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FBG3qzgNmIWM9H48q3vvP%252FScreenshot%25202026-02-08%2520at%252022.30.42.png%3Falt%3Dmedia%26token%3D9858f84e-614f-48b8-b6b0-0bb9a845bbe7&width=768&dpr=3&quality=100&sign=3a6beda7&sv=2) 5 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#create-and-adopt-first-edge-component) Create and adopt first Edge Component If you've started the all the services from the provided Docker Compose configuration, the Edge Component service is already started and waiting to be adopted in Defguard Core. Use the Docker service name as the _IP or Domain_ while configuring the component. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FS4eVjWYjfSxmxPc45E92%252FScreenshot%25202026-02-08%2520at%252023.07.31.png%3Falt%3Dmedia%26token%3D00ddc833-3397-43a3-85c8-49af1a46ebad&width=768&dpr=3&quality=100&sign=4be5cdaa&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FLjVOvWly5btPHDUG3k83%252FScreenshot%25202026-02-08%2520at%252023.07.33.png%3Falt%3Dmedia%26token%3Db2bcab40-8a9f-4443-8358-8fdf7617766c&width=768&dpr=3&quality=100&sign=43b473f9&sv=2) 6 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#create-first-location) Create first Location Here, same as with Edge Component, set the Gateway address to the IP you got in your local network. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252Fr2ocBQ0p7T9uBXGAOMKn%252FScreenshot%25202026-02-08%2520at%252023.08.14.png%3Falt%3Dmedia%26token%3De3e44af0-6c5d-4f77-8333-fc46d4c34249&width=768&dpr=3&quality=100&sign=79937128&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FlKWs2rrmsz69qSrMbXN9%252FScreenshot%25202026-02-08%2520at%252023.08.38.png%3Falt%3Dmedia%26token%3Df434b776-20ac-41b6-bbc3-8ac734a3f3f4&width=768&dpr=3&quality=100&sign=e366ad01&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252Fip2ychtqHacY3DPAsxhk%252FScreenshot%25202026-02-08%2520at%252023.08.41.png%3Falt%3Dmedia%26token%3D308e3e14-896d-43cb-b2c9-bdc2f1a46d3c&width=768&dpr=3&quality=100&sign=f3abe486&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252Ff6zrfsBEhQHaGvmDbnvX%252FScreenshot%25202026-02-08%2520at%252023.08.49.png%3Falt%3Dmedia%26token%3D1d50f2a1-9493-4fd1-af19-047c0a6d3626&width=768&dpr=3&quality=100&sign=7ec0c80f&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FWqO9dcOhxFDeO3ayPaWs%252FScreenshot%25202026-02-08%2520at%252023.08.53.png%3Falt%3Dmedia%26token%3Dc634e7fd-9aab-4d9c-b19a-3ff760e810a1&width=768&dpr=3&quality=100&sign=96c49c35&sv=2) Now, if we want to set up gateway for our new location, make sure you clicked the "Run the gateway activation wizard once the location is created" checkbox. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252Fudi3dKujSZfmFei7DEO5%252FScreenshot%25202026-02-08%2520at%252023.09.05.png%3Falt%3Dmedia%26token%3Dd184a502-71de-4358-8029-3205c272aa7a&width=768&dpr=3&quality=100&sign=84b5cf37&sv=2) 7 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#create-first-gateway-for-the-newly-created-location) Create first Gateway for the newly created Location If you've started the all the services from the provided Docker Compose configuration, the Gateway Component service is already started and waiting to be adopted in Defguard Core. Use the Docker service name as the _IP or Domain_ while configuring the component. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FRk2cb9RvEYatorupkZCR%252FScreenshot%25202026-02-08%2520at%252023.09.22.png%3Falt%3Dmedia%26token%3Dc59d293c-db7a-4531-967c-53fa30c402f9&width=768&dpr=3&quality=100&sign=7474cd66&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FJSE7P7Trzg72jctYPPf8%252FScreenshot%25202026-02-08%2520at%252023.09.24.png%3Falt%3Dmedia%26token%3Da1bf90eb-8933-4bde-9bb5-fab6026c7607&width=768&dpr=3&quality=100&sign=31062cac&sv=2) 8 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#inspect-the-newly-create-edge-component-location-and-gateway-component) Inspect the newly create Edge Component, Location and Gateway Component ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FArrhWKkW4TVl3lygYFm2%252FScreenshot%25202026-02-08%2520at%252023.09.42.png%3Falt%3Dmedia%26token%3Dcfa68511-7f48-4b18-98ae-8d403e8a8ffc&width=768&dpr=3&quality=100&sign=d44764dc&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FlOzhbmsC09fSX25j6aCN%252FScreenshot%25202026-02-08%2520at%252023.09.37.png%3Falt%3Dmedia%26token%3Deae61942-31bb-4f67-bb84-341158e9a6f6&width=768&dpr=3&quality=100&sign=d9ee05da&sv=2) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#enjoy-fully-redesigned-interface) Enjoy fully redesigned interface -------------------------------------------------------------------------------------------------------------------------------------------------------------------- After finishing the initial setup, Defguard is fully operational. You can manage your instance using the fully redesigned UI/UX. You can also enrol users and connect to the newly crated Location. You'll notice changes in every part of the interface, but some areas changed in a very significant way. Check those modules for sure: * VPN overview - strictly a dashboard for the administrator, previously mixed with system configuration, which was confusing. Also, we've significantly refactored our statistics module to make sure the dashboard is responsive even for large deployments. * Dedicated Locations page - previously hidden somewhere in the VPN overview page, mixed with dashboard, now a clear Location listing and management. * Firewall (formerly ACL) - new nomenclature (Aliases, Destinations, Rules), brand-new Alias, Destination, and Rule form. The Rule form, despite realising a complex task of creating a firewall rule, is intuitive and guides the user through the process. * Settings - since all the settings are now stored in the database, they can be managed with the UI. All system parameter got divided into logical sections, with broad descriptions, making it much easier to configure your system. * Edge Components (formerly Proxy) page - brand-new page for managing Edge Components (exposing selected Core functionality to the internet while keeping the Core isolated). [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-the-setup-configured-using-the-wizard) Test the setup configured using the wizard ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now the only thing left to do is to test the setup. You can test the following scenario: 1. Create a new user. 2. Sign in as the user. 3. Add TOTP MFA method in the user's profile. 4. Enrol as the new user using the Desktop or Mobile app. 5. Connect to the created Location. 6. See a new session visible in the VPN overview. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#high-availability-of-edge-and-gateway-components) High Availability of Edge and Gateway components ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- circle-info This feature will be available only in the Enterprise plan after v2.0 reaches stable version. Another major feature of v2.0 is High Availability in active-active mode for the Edge and Gateway components. You can now add multiple Gateways to your Locations. Users will still connect to a single Gateway (using sticky sessions), but in the event of a Gateway failure, their VPN connection will remain active and be handled by another Gateway. You can also add multiple Edge components to ensure that enrollment, configuration updates, and MFA session initiation are fast and fail-safe. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#example-setup-1) Example setup 1 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#add-another-edge-component) Add another Edge Component If you've started the all the services from the provided Docker Compose configuration, the additional Edge Compoent service is already started and waiting to be adopted in Defguard Core. Both Edge Components are behind a basic NGINX-based load balancer. Use the Docker service name as the _IP or Domain_ while configuring the component. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FwVL3F58H5e4IlkSwp8lO%252FScreenshot%25202026-02-08%2520at%252023.37.27.png%3Falt%3Dmedia%26token%3D10850e4c-8c95-45d5-b9a2-81b184273896&width=768&dpr=3&quality=100&sign=3a586e42&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252F5KF5z5HvTI7fJxC0Udph%252FScreenshot%25202026-02-08%2520at%252023.38.28.png%3Falt%3Dmedia%26token%3Dcdd80434-f635-4f9c-8605-cbcad747def9&width=768&dpr=3&quality=100&sign=5e0b5686&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FtXqmaYov85gfCxg4sMLk%252FScreenshot%25202026-02-08%2520at%252023.38.31.png%3Falt%3Dmedia%26token%3D2f13c490-b49c-40dc-bd65-f601bc866041&width=768&dpr=3&quality=100&sign=abca7dc5&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FAm068XjoMxJlXxamPjOR%252FScreenshot%25202026-02-08%2520at%252023.38.39.png%3Falt%3Dmedia%26token%3D84e2101f-a174-4067-9b5c-be35bd6a4546&width=768&dpr=3&quality=100&sign=79e5948e&sv=2) 2 #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#add-another-gateway-component-to-your-location) Add another Gateway Component to your Location If you've started the all the services from the provided Docker Compose configuration, the additional Gateway Component service is already started and waiting to be adopted in Defguard Core. Both Gateway Components are behind a basic Envoy-based load balancer. Use the Docker service name as the _IP or Domain_ while configuring the component. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FqB8GR1IgV8JKz8Bw3g2r%252FScreenshot%25202026-02-08%2520at%252023.40.06.png%3Falt%3Dmedia%26token%3D0e4fd807-054b-4e99-8ff8-8f4eca670138&width=768&dpr=3&quality=100&sign=3799d6a8&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FqbVVp8VNP6WOFv1H5ljo%252FScreenshot%25202026-02-08%2520at%252023.41.04.png%3Falt%3Dmedia%26token%3D7a505c85-08af-4f83-8370-8419cb72d288&width=768&dpr=3&quality=100&sign=8e5ace14&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252FYxkzXm1nYylsCujxX8aw%252FScreenshot%25202026-02-08%2520at%252023.41.07.png%3Falt%3Dmedia%26token%3Dc17ffc7d-7200-4f19-aafe-2d3a47f66520&width=768&dpr=3&quality=100&sign=183112ef&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F2426002228-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FqPYuWxfmxFk6sz1LLLwd%252Fuploads%252F03J3A9BsNLPbTXbtZsOv%252FScreenshot%25202026-02-08%2520at%252023.42.14.png%3Falt%3Dmedia%26token%3D20dff74f-3f7c-4b08-a8da-e4ec4c2bd8a1&width=768&dpr=3&quality=100&sign=c911f769&sv=2) [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-the-high-availability-and-failover) Test the High Availability and Failover ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-ha-for-edge-components) Test HA for Edge Components 1. Display logs of both Edge Components using `docker compose logs -f edge1 edge2` 2. Trigger enrolment or MFA VPN connection using the Defguard Desktop or Mobile Application. 3. Notice traffic being directed to both Edge Components using round robin strategy on the NGINX load balancer. 4. Stop one of the Edge Components using `docker compose stop edge1` 5. Notice the enrolment process or MFA VPN connections working as expected on the Edge Components that's left. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-ha-for-gateway-components) Test HA for Gateway Components 1. Display logs of both Gateway Components using `docker compose logs -f gateway1 gateway2` 2. Ping the VPN gateway using `ping 10.10.10.1`. Since the VPN connection is not active yet it should fail. Keep it running through the test. 3. Connect to the VPN Location. 4. Notice that the ping now succeeds. 5. Now play with stoping on of the gateways `docker compose stop gateway1` or `docker compose stop gateway2` . Make sure you don't stop both of them. 6. Notice that the VPN connection is alive the whole time (ping still succeeds). [PreviousLinux Kernel WireGuard tuningchevron-left](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning) [NextPurchasing and using the licensechevron-right](https://docs.defguard.net/2.0/enterprise/license) Last updated 8 days ago * [Starting Defguard 2.0](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#starting-defguard-2.0) * [Initial configuration](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#initial-configuration) * [Example setup](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#example-setup) * [Enjoy fully redesigned interface](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#enjoy-fully-redesigned-interface) * [Test the setup configured using the wizard](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-the-setup-configured-using-the-wizard) * [High Availability of Edge and Gateway components](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#high-availability-of-edge-and-gateway-components) * [Example setup](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#example-setup-1) * [Test the High Availability and Failover](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-the-high-availability-and-failover) * [Test HA for Edge Components](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-ha-for-edge-components) * [Test HA for Gateway Components](https://docs.defguard.net/2.0/deployment-strategies/previewing-defguard-v2.0-alpha#test-ha-for-gateway-components) sun-brightdesktopmoon Copy ipconfig getifaddr en0 192.168.83.132 Copy ipconfig getifaddr en0 192.168.83.132 sun-brightdesktopmoon --- # Kubernetes | defguard [hashtag](https://docs.defguard.net/deployment-strategies/kubernetes#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------ To deploy and use Defguard on your cluster, you'll need: * A [Kubernetes clusterarrow-up-right](https://kubernetes.io/docs/setup/) * Kubernetes CLI [kubectlarrow-up-right](https://kubernetes.io/docs/reference/kubectl/) installed on your machine * Helm binary https://github.com/helm/helm/releases/latest circle-exclamation Our helm charts currently support only **Traefik ingress - which is relevant and affects exposing GRPC services (see below** `ingress.hosts.grpc``**).**` [hashtag](https://docs.defguard.net/deployment-strategies/kubernetes#deployment) Deployment ------------------------------------------------------------------------------------------------ We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with Kubernetes configuration, clone it with: Copy git clone https://github.com/DefGuard/deployment.git && cd deployment/charts Then create a namespace for Defguard on your cluster: Copy kubectl create namespace defguard Copy and fill in values file: Copy cp defguard/values.yaml ./ Required values (the rest should work if left as-is): * `ingress.hosts.grpc`: GRPC ingress address - GRPC clients like Defguard **gateway**, yubi-bridge circle-exclamation If you are configuring your gateway or yubi-bridge - please use this GRPC URL for communication. If you have other ingress controller than traefik - you need to configure GRPC ingress manually with corresponding to your setup. * `ingress.hosts.web`: Web ingress address - Defguard web app will be available here. * `publicUrl`: Public URL your Defguard will be available under. Usually the same as ingress.hosts.web, but differs depending on your load balancer and/or reverse-proxy setup. And finally, install the Helm chart in the namespace: ### [hashtag](https://docs.defguard.net/deployment-strategies/kubernetes#proxy-service) Proxy service If you want to deploy the enrollment service along with your Defguard instance, you also need to configure values related to the `defguard-proxy`subchart: * `defguard-proxy.enabled`: enable the enrollment service * `proxyUrl`: proxy gRPC endpoint URL (based on `defguard-proxy.ingress.grpc.host`) * `defguard-proxy.publicUrl`: public URL of the enrollment service * `defguard-proxy.ingress.web.host`: enrollment service web ingress address (the enrollment website) * `defguard-proxy.ingress.grpc.host`: enrollment service gRPC ingress address (for communicating with core) ### [hashtag](https://docs.defguard.net/deployment-strategies/kubernetes#vpn-gateway-service) VPN gateway service If you want to deploy the VPN gateway service along with your Defguard instance, you need to do it in two steps: * first deploy the core service and use the web UI to [setup a VPN location](https://docs.defguard.net/tutorials/step-by-step-setting-up-a-vpn-server/adding-additional-vpn-locations) * copy the gateway token and proceed to deploying the gateway itself To deploy the gateway service, configure values related to the `defguard-gateway`subchart: * `defguard-gateway.enabled`: enable the VPN gateway service * `defguard-gateway.token`: the gateway token generated in Web UI * `defguard-gateway.grpcUrl`: URL where the core gRPC server is available (based on `defguard.ingress.grpc.host`) [PreviousDocker Composechevron-left](https://docs.defguard.net/deployment-strategies/docker-compose) [NextTerraformchevron-right](https://docs.defguard.net/deployment-strategies/terraform) * [Prerequisites](https://docs.defguard.net/deployment-strategies/kubernetes#prerequisites) * [Deployment](https://docs.defguard.net/deployment-strategies/kubernetes#deployment) * [Proxy service](https://docs.defguard.net/deployment-strategies/kubernetes#proxy-service) * [VPN gateway service](https://docs.defguard.net/deployment-strategies/kubernetes#vpn-gateway-service) sun-brightdesktopmoon Copy helm install --wait=true --namespace defguard defguard defguard -f values.yaml sun-brightdesktopmoon --- # Configuring HTTPS using AWS Certificate Manager | defguard This guide explains how to secure your Defguard deployment with HTTPS by using a public TLS certificate issued by AWS Certificate Manager (ACM). You will request a certificate for the domains used by Defguard Core and Defguard Proxy, validate domain ownership via DNS, and attach the certificate to your CloudFormation stack using its ARN. Once completed, AWS will automatically manage certificate provisioning and renewal, ensuring your Defguard instance is encrypted and trusted without manual certificate handling. Go to AWS console and open the Certificate Manager service page. Request a new certificate (if you don't have one already). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-c08368433162426a44574d1250e52b30f7a17d91%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=9c7ec6fd&sv=2) A public certificate is enough. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-027adaf6e6bb2042dd3e45f5a5a250a15e1cc043%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=bf8dc528&sv=2) Specify the domains you will want to use for your Defguard instance (for accessing Defguard Proxy and Defguard Core). Those domains should be the same as those you'll use in `ProxyUrl` and `CoreUrl`. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-02bd340d90728970759fea995fdca92333406009%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=7dc9e5d2&sv=2) Next, you will need to validate your domain ownership by adding appropriate CNAME records in your DNS provider. Use the _CNAME name_ and _CNAME value_ values provided in the AWS console and set them in you domain's DNS. After you complete this step, your certificate can be used. Copy the ARN of your certificate and paste it into the `SSLCertificateArn` parameter in the CloudFormation template. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-faf29fa22568e93c5dd2473a912b4b85848dbe91%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=48489d3a&sv=2) [PreviousAmazon Machine Image (AMI)chevron-left](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation) [NextAdding a location and getting a Gateway tokenchevron-right](https://docs.defguard.net/deployment-strategies/gateway) Last updated 2 months ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Production deployment verification guide | 2.0 | defguard This guide helps you verify that your Defguard instance is operational, reachable through the expected network paths, and properly secured. The process will consist of the following steps: 1. Verifying the configuration of your firewall rules. 2. Verifying your DNS resolution. 3. Testing the whole configuration. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------------------------------------- Before proceeding, ensure that you deployed your Defguard environment according to the [recommendations](https://docs.defguard.net/2.0/deployment-strategies/hardware-os-network-and-firewall-recommendations) and that the following components are operational: * 1 server running Defguard Core * Located in an internal network segment (not exposed to the Internet) * Reachable internally under a domain such as defguard.example.com * 1 server running Defguard Proxy * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as proxy.example.com * 1 server running Defguard Gateway * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as vpn.example.com * A workstation with the Defguard Desktop Client installed and configured to test VPN connectivity. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) Verify firewall policies -------------------------------------------------------------------------------------------------------------------------------------------------------------- Confirm that your firewall rules align with Defguard’s secure deployment model. Component Allowed inbound Blocked inbound Notes Core * TCP 443 (from internal/VPN only) * gRPC server port (from Gateway) All public traffic Core should never be directly exposed to the Internet. Proxy * TCP 443 (from public Internet) * gRPC server port (from Core) All other inbound traffic Used for enrollment and client configuration. Gateway * UDP VPN port (from public Internet) All other inbound traffic Only VPN and Core communication should be allowed. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) Verify DNS resolution -------------------------------------------------------------------------------------------------------------------------------------------------------- Proper DNS configuration ensures that each Defguard component resolves to the correct IP address and network zone. Run: Expected results: Domain Expected IP Type Description vpn.example.com Public IP Gateway server reachable from the Internet proxy.example.com Public IP Proxy server for enrollment and configuration defguard.example.com Private/Internal IP Core server, accessible only from internal/VPN network [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-the-environment) Test the environment ------------------------------------------------------------------------------------------------------------------------------------------------------ After you've confirmed the proper network segmentation it's time to test it. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) Testing while disconnected from the VPN Perform the following tests from the workstation where the Defguard Desktop Client is installed. Make sure the client is disconnected before running any commands. In this state: * ❌ You should not be able to reach the Defguard Core server. * ✅ You should be able to reach the Defguard Proxy server. * ✅ You should be able to reach the Defguard Gateway server (UDP port for VPN). #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports) Test: Defguard Core server reachability and ports Check the open ports on your Defguard Core server (replace the example domain with your actual one): Expected output: Interpretation: * The Core server is not reachable when disconnected from the VPN, which is the expected and secure configuration. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-defguard-proxy-server-reachability-and-ports) Test: Defguard Proxy Server Reachability and Ports Check the open ports on your Defguard Proxy server: Expected output: Interpretation: * The host is reachable from the Internet. * Only port 443/tcp is open, as expected for HTTPS access. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-defguard-gateway-server-reachability) Test: Defguard Gateway Server Reachability Check if the Defguard Gateway server is reachable: Expected output: Interpretation: * The host is reachable. * The list of open TCP ports should be empty, as the Gateway primarily uses UDP for VPN connections. * You’ll verify the UDP port functionality in the next step by testing an actual VPN connection. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) Connecting to the VPN 1. Open the Defguard Desktop Client. 2. Connect to your configured location. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-verify-vpn-connectivity) Test: Verify VPN Connectivity Once connected: 1. Open your browser and navigate to the Defguard Core interface, for example: https://defguard.example.com 2. Sign in using an administrator account. If you can access the web panel, your VPN connection is active and functioning. Then, in the Core UI: * Go to VPN Overview page. You should see your connected device listed there. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FsHmlyMe7R3CBIrHoNTlW%2FScreenshot%25202025-10-24%2520at%252011.20.24.png&width=768&dpr=3&quality=100&sign=fce00a24&sv=2) ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) Testing While Connected to the VPN Perform the following tests again while the Defguard client remains connected. In this state: * ✅ You should be additionally able to reach the Defguard Core server. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports-1) Test: Defguard Core Server Reachability and Ports Check the open ports on your Defguard Core server: Expected output: Interpretation: * The host is reachable via the VPN tunnel. * Port 443/tcp (HTTPS web interface) is open, which confirms proper VPN routing and Core access. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#summary) Summary ---------------------------------------------------------------------------------------------------------------------------- ✅ Firewall policies restrict traffic to approved ports. ✅ DNS records resolve to the expected internal and public addresses. ✅ Core is unreachable from the Internet and reachable only via VPN. ✅ Proxy is publicly reachable only on port 443. ✅ Gateway responds correctly and allows VPN connections. When all verifications and tests pass, your Defguard deployment is operational, properly segmented, and production-ready. [PreviousHealth checkchevron-left](https://docs.defguard.net/2.0/deployment-strategies/health-check) [NextLinux Kernel WireGuard tuningchevron-right](https://docs.defguard.net/2.0/deployment-strategies/linux-kernel-wireguard-tuning) * [Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#prerequisites) * [Verify firewall policies](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) * [Verify DNS resolution](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) * [Test the environment](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#test-the-environment) * [Testing while disconnected from the VPN](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) * [Connecting to the VPN](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) * [Testing While Connected to the VPN](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) * [Summary](https://docs.defguard.net/2.0/deployment-strategies/production-deployment-verification-guide#summary) sun-brightdesktopmoon Copy dig +short vpn.example.com dig +short proxy.example.com dig +short defguard.example.com Copy sudo nmap -Pn -sS defguard.example.com Copy Failed to resolve "defguard.example.com". Copy sudo nmap -Pn -sS proxy.example.com Copy Host is up (0.0082s latency). PORT STATE SERVICE 443/tcp open https Copy sudo nmap -Pn -sS vpn.example.com Copy Host is up (0.0082s latency). Copy sudo nmap -Pn -sS defguard.example.com Copy Host is up (0.021s latency). PORT STATE SERVICE 443/tcp open https sun-brightdesktopmoon --- # Updating and version compatibility | defguard Each service in the Defguard stack can be updated independently, provided the components remain compatible. When components connect, Defguard automatically performs a version check. If an incompatibility is detected, the connection is refused and it will be clearly reported both in the log files and through a dialog in the core UI: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-f9141d5355db7093e438e0ec2208ce0867451ce8%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=a01a6512&sv=2) circle-exclamation **Note on Multiple Gateways per Location** If you configure more than one gateway for the same location, they will overwrite each other’s incompatibility data. This happens because location is currently used as the identifier for gateways. This limitation will be resolved once full high-availability (HA) support is implemented. It's recommended to always use newest version of services and update them all together to avoid incompatibility. Check the GitHub repositories for each service to find their newest releases and release notes. * Docker - For Docker and Kubernetes based setup just change docker image version for service you want to update. * Packages(DEB, RPM, etc.) - Currently we don't have any package repository so if you want to update your service installed as package you have to download new version from service repository. **GitHub Repositories:** * [Defguard Corearrow-up-right](https://github.com/DefGuard/defguard/releases) * [Defguard Proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) * [Defguard Gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) * [Defguard YubiBridgearrow-up-right](https://github.com/DefGuard/YubiKey-Provision/releases) [PreviousHigh Availability and Failoverchevron-left](https://docs.defguard.net/deployment-strategies/high-availability-and-failover) [NextMigration guideschevron-right](https://docs.defguard.net/deployment-strategies/upgrading) sun-brightdesktopmoon sun-brightdesktopmoon --- # Defguard APT repository | defguard ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) Distribution Defguard APT repository provides packages for **Debian 12**, **Debian 13**, and **Ubuntu 22.04/24.04 LTS.** Packages are available on the default `trixie` repository distribution. ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) Adding Defguard APT repository To add Defguard APT repository, run following commands in your terminal: Copy sudo apt update sudo apt install -y ca-certificates curl #Add official Defguard public GPG key sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://apt.defguard.net/defguard.asc -o /etc/apt/keyrings/defguard.asc sudo chmod a+r /etc/apt/keyrings/defguard.asc #Add APT repository echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Afterward running these commands, you can install and update Defguard via APT. After new release, simply use `sudo apt update` to update repository. ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) Using pre-release builds Defguard has two separate components on one APT repository, **release** and **pre-release.** If you want to install packages from pre-release, simply change `release` to `pre-release` in the installation steps described above, or run the following line. ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) Installing packages Defguard Core: Defguard Proxy: Defguard Gateway: Defguard Client: [PreviousStandalone package based installationchevron-left](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation) [NextDocker Composechevron-right](https://docs.defguard.net/deployment-strategies/docker-compose) Last updated 3 months ago * [Distribution](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#distribution) * [Adding Defguard APT repository](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#adding-defguard-apt-repository) * [Using pre-release builds](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#using-pre-release-builds) * [Installing packages](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository#installing-packages) sun-brightdesktopmoon Copy echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/defguard.asc] https://apt.defguard.net/ trixie pre-release " | \ sudo tee /etc/apt/sources.list.d/defguard.list > /dev/null sudo apt update Copy sudo apt install defguard Copy sudo apt install defguard-proxy Copy sudo apt install defguard-gateway Copy sudo apt install defguard-client sun-brightdesktopmoon --- # Running Gateway on OPNsense firewall | defguard [hashtag](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) OPNsense plugin ------------------------------------------------------------------------------------------------------------------------------------ [OPNsense®arrow-up-right](https://opnsense.org/) is an open source, feature rich firewall and routing platform, offering cutting-edge network protection. To start Defguard Gateway as OPNsense plugin: 1. On the [release pagearrow-up-right](https://github.com/DefGuard/gateway/releases) find and download OPNsense package which will be named: `defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg` – this package **includes both Defguard Gateway and OPNsense plugin.** 2. Install the package: Copy pkg add defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg 1. Refresh your OPNsense UI by running command below: Copy opnsense-patch 1. Go to your OPNsense UI and navigate to **VPN** > **Defguard Gateway**. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-9a2f89076d509383361d32a0ad6f6461ce490d0b%252FOPNSense%2520Plugin.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c673c877&sv=2) 1. Fill out the form with appropriate values, click **Save**, and then click **Start/Restart.** circle-info You can find detailed description of all fields [here](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/features/wireguard/remote-desktop-activation) . See also: [how to configure Defguard in OPNsense](https://docs.defguard.net/features/gateway) [hashtag](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) Binary Install ---------------------------------------------------------------------------------------------------------------------------------- 1. Checkout Gateway releases [herearrow-up-right](https://github.com/DefGuard/gateway/releases) and download compatible binary from GitHub page. 2. Decompress and move to bin directory 1. Start gateway `gateway -g -t ` [PreviousConfigurationchevron-left](https://docs.defguard.net/deployment-strategies/configuration) [NextRunning Gateway on MikroTik routerschevron-right](https://docs.defguard.net/deployment-strategies/running-gateway-on-mikrotik-routers) * [OPNsense plugin](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall#opnsense-plugin) * [Binary Install](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall#binary-install) sun-brightdesktopmoon Copy tar xcf ./gateway.tar.gz sudo chmod +x gateway sudo mv gateway /usr/bin/ sun-brightdesktopmoon --- # High Availability and Failover | defguard [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#gateway-high-availability) Gateway - High Availability ---------------------------------------------------------------------------------------------------------------------------------------------------- We support running multiple gateways for a single VPN instance or location, enabling active-passive configurations. Active-active configurations should also be possible but come with some caveats. Since our gateway uses a vanilla kernel WireGuard®, there are multiple approaches for implementation. circle-info Please also see documentation of [Creating a New VPN location](https://docs.defguard.net/features/wireguard/create-your-vpn-network) where each [location setting has information regarding high-availability](https://docs.defguard.net/features/wireguard/create-your-vpn-network#vpn-location-settings) . ### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#deploying-multiple-gateways-for-one-location) Deploying multiple gateways for one location To have a multi-gateway setup for a given location, you will need to [deploy the gateway on each one of your servers](https://docs.defguard.net/deployment-strategies/gateway) under the same location. If you already have a gateway deployed and want to add another one for the location, go to _VPN Overview_ -> Click: _Edit Location Settings (in the top right corner)_, then choose the location you want to add the new gateway to, and follow the deployment instructions: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-a52035b58d7c7e99edb2fdaea6254c99d6eb32ec%252FScreenshot%25202024-11-12%2520at%252016.55.55.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=b50d132&sv=2) Each gateway deployed for a given location will receive the same network configuration and will **bind to the defined port** in the location's _Gateway Port._ The only thing left to do is to point your traffic to those gateways, which can be accomplished in several ways: * Floating public IP - if you choose this scenario, please remember that the IP must be the IP specified in the Location _Gateway Address._ In this scenario, the floating IP switches between your gateway servers, directing the traffic to one of the two gateways. * Proxy/load balancing - also remember that the proxy must be configured with the _Gateway Address and Gateway Port._ In this scenario, your clients connect to the proxy/load balancer, which direct the VPN traffic (UDP) to one of your gateway backends_._ #### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#determining-if-multiple-gateways-are-running) Determining if multiple gateways are running All gateways that are successfully connected for the location are displayed under the Location in VPN Overview, here is an example for two gateways: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-c62c5f4b58d47821fe8090a8e47a632a2474fe4e%252Flocation-overview.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c3058819&sv=2) ### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#known-issues) Known issues #### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#session-recovery-in-active-passive-setups) **Session recovery in active-passive setups** In active-passive deployments using floating IPs (e.g., VRRP), client sessions are not fully recovered when traffic fails over to a secondary gateway and later fails back to the primary one. After failback, clients may still appear as connected in the UI and continue reporting activity, but VPN traffic may stop flowing. In such cases, manual client reconnection is required to restore connectivity. Related issue: [https://github.com/DefGuard/defguard/issues/1909arrow-up-right](https://github.com/DefGuard/defguard/issues/1909) . ### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#active-active-setups) Active-active setups Active-active setups should also be possible but come with some caveats. Here are the currently known issues with such configurations: * Multiple running gateways bound to one location with network traffic distributed between them may produce invalid network usage statistics, making the network usage graphs and displays on the dashboard unreliable. This also causes MFA on VPN locations to not work properly. Related issue: [https://github.com/DefGuard/defguard/issues/1022arrow-up-right](https://github.com/DefGuard/defguard/issues/1022) ### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) What is the gateway peers persistence (if core/proxy services fail) 1. For **VPN Locations without MFA** - it's persistent until the system reboot - _even if the gateway will not work_ - as the gateway configures WireGuard "in kernel". 2. For **VPN Locations with MFA**, this depends on the _Peer Disconnect Threshold (seconds)_ setting in the VPN Location settings. This setting specifies that if the peer is inactive for _(defined seconds)_, the gateway should remove it from the configuration. Therefore, if the proxy/core is not operational, MFA authentication will fail, and the peer will not be added if it is disconnected. [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#core-proxy-failover) Core / Proxy - Failover ------------------------------------------------------------------------------------------------------------------------------------------ The core service handles gateway states as well as core connects _**to the proxy**_. Since proxy serves HTTP based protocol communication and should be in the public Internet, it needs to be secure, thus core connects to the proxy. This way **core can be in an Intranet network segment and proxy can be in DMZ, making Core completely cut-off on firewall from the Internet** (you only can have only outgoing firewall rules from Intranet allowing only for core to connect to proxy). So **High Availability for core and proxy** gets complicated, with multiple proxies core needs to manage those connections. We already have most of the code for that ready, but it's not yet production ready. #### [hashtag](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#how-to-bullet-proof-proxy-and-core-with-failover) How to bullet-proof proxy & core with failover? We recommend to deploy them on a failover solution - like on a kubernetes cluster (even small one - like mini-kube) . This way, Kubernetes manages: healthchecks and does failover. You can have cluster N-nodes and if any VM/node with Core/Proxy goes offline or health checks fail - it's migrated to a new node. [PreviousReverse Proxy configuration using NGINXchevron-left](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx) [NextUpdating and version compatibilitychevron-right](https://docs.defguard.net/deployment-strategies/updating-and-version-compatibility) Last updated 14 days ago * [Gateway - High Availability](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#gateway-high-availability) * [Deploying multiple gateways for one location](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#deploying-multiple-gateways-for-one-location) * [Known issues](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#known-issues) * [Active-active setups](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#active-active-setups) * [What is the gateway peers persistence (if core/proxy services fail)](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#what-is-the-gateway-peers-persistence-if-core-proxy-services-fail) * [Core / Proxy - Failover](https://docs.defguard.net/deployment-strategies/high-availability-and-failover#core-proxy-failover) sun-brightdesktopmoon sun-brightdesktopmoon --- # Hardware, OS, network and firewall recommendations | defguard [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) Server & environment requirements -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Defguard can be deployed on multiple servers (physical or virtual) or on a single server (which is not recommended). Recommended setup reflects the [general system architecture](https://docs.defguard.net/in-depth/architecture) with components being split into three separate machines: 1. **Dedicated server or Virtual Machine for Core (control plane)** - that is in the Intranet network segment, not exposed in the public Internet in any way. Core needs to be accessible from the local (secure) network and VPN (to access Defguard securely). Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location - eg. if Defguard handles 2 VPN locations recommended is min. 2 CPU/vCPU 2. RAM: min. 1GB per location 3. Disk: min 8GB and more (since statistics will be gathered) 2. **Dedicated server or Virtual Machine for Proxy (external and public enrollment service)** - this server/VM needs to be deployed in DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 1GB 3. **Dedicated server or Virtual Machine for Gateway -** this server/VM needs to be deployed in: 1. DMZ/public/external systems network segment - as this service will be exposed and must be available publicly from the Internet. 2. Has access on Internal network interfaces to all network segments that will be exposed from VPN for users. 3. Recommended hardware parameters: 1. CPU: min. 1 CPU/vCPU per location 2. RAM: min. 1GB 3. Disk: min 4GB (mostly for logs) In general the hardware requirements will also have to be adjusted based on the number of active users. The numbers above should serve as a baseline. ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) Operating system and software requirements #### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#package-based-installation) Package based installation Package based install requires Debian GNU/Linux min. 13.x or Ubuntu Linux min. 24.04.x #### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#docker-based-installation) Docker based installation Docker deployment requires the system to have [official Docker Engine installationarrow-up-right](https://docs.docker.com/engine/install/) (not distribution based packages). [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) Network IP & DNS setup ---------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) Gateway server - where WireGuard VPN tunnels itself will be launched * **The** [**Gateway address**](https://docs.defguard.net/features/wireguard/create-your-vpn-network#gateway-address) and [**Gateway Port**](https://docs.defguard.net/features/wireguard/create-your-vpn-network#gateway-port) **must be publicly available from the Internet** circle-exclamation The server on which the Gateway is installed does not need to have the IP address (the same as the Gateway Address) assigned to it - can have internal network address. The Gateway Address is the address specified in the clients’ configuration – therefore, if this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (Gateway Port) must be forwarded (e.g., via NAT) to the Gateway Port on the server where the Gateway is installed.** * must have all networks on internal interfaces addresses configured, that should be accessible from VPN * **Recommended:** to have a public domain assigned to this IP for VPN server, eg. _vpn.company.com_ ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) Proxy - public web service for enrollment & desktop client configuration * **The** [**enrollment URL**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#enrollment-configuration) **(that proxy will be configured under and available for user and clients to reach) needs to be publicly available from the Internet.** circle-exclamation The server on which the Proxy is installed does not need to have the IP address assigned to it which the enrollment URL domain points to - can have internal network address. If this address is assigned for example to a Firewall or Load Balancer rather than the server hosting the Gateway, **the port from this address (eg. if the enrollment URL is https://vpn-config.domain.com, then the port is 443) must be forwarded (e.g., via NAT) to the** [**DEFGUARD\_PROXY\_HTTP\_PORT**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) **on the server where the Proxy is installed.** * **must have a public enrollment domain assigned to this IP,** _**eg. enrollment.company.com (or vpn-config.company.com, etc..**_**)** ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) Core & database server * should be internal / private IP addresses accessible only from Intranet and VPN * must have internal domain name assigned in the local network DNS server, eg. _defguard.company.com_ [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) Firewall settings ---------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) Gateway 1. Please open the public port you wish the VPN to be working on - eg. 50555 ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) Proxy 1. Please open the public 443 port on the server (recommended to rewrite port 80 to redirect to 443) 2. Please open gRPC port on the internal network - so that the **Defguard Core can connect to this port - more details here:** [**https://docs.defguard.net/deployment-strategies/configuration#proxy-service**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) ### [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) Core 1. Please open 443 port for web interface accessible only from local/VPN network 2. Please open a gRPC port **for the Gateway server to connect to this port via a local network - more info here:** [**https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration**arrow-up-right](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) [hashtag](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) Backup strategy ------------------------------------------------------------------------------------------------------------------------------------------------ In a production environment you should use your preferred backup solution to secure the following: * service configuration (.env file, service config files, compose configuration) * database content (prefferably by doing a regular pgdump, not just filesystem-level backup) [PreviousDeploying to Productionchevron-left](https://docs.defguard.net/deployment-strategies/deploying-to-production) [NextStandalone package based installationchevron-right](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation) Last updated 1 day ago * [Server & environment requirements](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#server-and-environment-requirements) * [Operating system and software requirements](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#operating-system-and-software-requirements) * [Network IP & DNS setup](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#network-ip-and-dns-setup) * [Gateway server - where WireGuard VPN tunnels itself will be launched](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway-server-where-wireguard-vpn-tunnels-itself-will-be-launched) * [Proxy - public web service for enrollment & desktop client configuration](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy-public-web-service-for-enrollment-and-desktop-client-configuration) * [Core & database server](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#core-and-database-server) * [Firewall settings](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#firewall-settings) * [Gateway](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#gateway) * [Proxy](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#proxy) * [Core](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#core) * [Backup strategy](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations#backup-strategy) sun-brightdesktopmoon sun-brightdesktopmoon --- # Pre-production and development releases | defguard To test any pre-production or development release: ### [hashtag](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#one-line-install) One-line install The simplest way to test the latest development or pre-release version is to use one line installation method with the appropriate argument. More on that in [the one-line install documentation](https://docs.defguard.net/getting-started/one-line-install) . ### [hashtag](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) Binaries and packages Each GitHub repository ([corearrow-up-right](https://github.com/DefGuard/defguard/releases) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/releases) , [proxyarrow-up-right](https://github.com/DefGuard/proxy/releases) , and [clientarrow-up-right](https://github.com/DefGuard/client/releases) ) has its **pre-release versions** available on the GitHub release page. This is where you can download binaries or packages with the pre-release, e.g.: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-2b46ffcbc83d44de543cf0fcfd8ffda8b9c628ce%252FScreenshot%25202025-08-01%2520at%252013.38.44.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c3c9832d&sv=2) ### [hashtag](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#docker-images) Docker images Each Docker image for [corearrow-up-right](https://github.com/DefGuard/defguard/pkgs/container/defguard) , [gatewayarrow-up-right](https://github.com/DefGuard/gateway/pkgs/container/gateway) and [proxyarrow-up-right](https://github.com/DefGuard/proxy/pkgs/container/defguard-proxy) has the following tags: * `pre-release` – this tag is for the **latest pre-production release** - which also contains a version in form of `vX.Y.Z-alpha/beta/rcX` from the `main` branch * `dev` – this tag is for the latest development release from the `dev` branch. #### [hashtag](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#docker-compose) Docker compose Please change the Docker compose file to match the version or tags as stated above. [PreviousUsing a userspace wireguard-go implementationchevron-left](https://docs.defguard.net/deployment-strategies/using-a-userspace-wireguard-go-implementation) [NextSecuring gRPC communicationchevron-right](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * [One-line install](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#one-line-install) * [Binaries and packages](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#binaries-and-packages) * [Docker images](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases#docker-images) sun-brightdesktopmoon sun-brightdesktopmoon --- # Amazon Machine Image (AMI) | 2.0 | defguard This guide explains how to deploy Defguard on AWS using official Amazon Machine Images (AMIs) and a preconfigured CloudFormation template. It walks you through launching all required components - including Core, Gateway, Proxy, and the PostgreSQL database - in a production-ready architecture with minimal manual configuration. You will learn how to subscribe to the AMIs, deploy the stack, attach SSL certificates, configure domains, and gain initial VPN access. The goal is to provide a repeatable, secure deployment method that allows you to get Defguard running quickly while still enabling advanced customization for larger or more complex environments. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#ami-architecture) AMI architecture --------------------------------------------------------------------------------------------------------------------------------- We recommend using the AMIs with our CloudFormation template as it will automatically configure all components. You can import the CloudFormation template from the AWS Marketplace or from our GitHub [deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment) . The template consists of the following main components: * **Defguard Core** * **Defguard Gateway** - The template has only one Gateway instance, but Defguard supports running multiple Gateways if you need more VPN locations. * **Defguard Proxy** * **PostgreSQL Database** We recommend reading the [Architecture documentationarrow-up-right](https://docs.defguard.net/in-depth/architecture) to understand how these components interact. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F8r4VC6yesJvRhbcGfeWD%2Faws_cloudformation_v2.png&width=768&dpr=3&quality=100&sign=74f9326&sv=2) Diagram showing how the components are deployed using the template [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#installation-guide) Installation guide ------------------------------------------------------------------------------------------------------------------------------------- circle-info In order to use the CloudFormation template you need to subscribe to the Defguard AMI product. The most straightforward way to obtain the template is to select it during the product delivery after subscribing to the product on the marketplace. After the CloudFormation template is uploaded either manually or via the marketplace, you will be prompted to fill the details of your deployment. This guide will go over the most important settings that need to be filled for a functional deployment. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#prerequisites) Prerequisites * Two domains: one for accessing Defguard Core (the main dashboard) and one for accessing Defguard Proxy (for external enrollment and device configuration) * AWS issued SSL certificates for the two domains. See [this page](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) for more information. * An SSH key added to AWS. This will allow you to access the EC2 instances later on. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#obtaining-the-template) Obtaining the template 1. Subscribe to the product on AWS Marketplace. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F8JVMBrZdQyMFBchAaF3T%2FScreenshot%25202025-12-01%2520at%252014.22.10.png&width=768&dpr=3&quality=100&sign=3b14952e&sv=2) 2. After subscription succeeds, click the launch your software button: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fp7IUmTetBduKoIwcfZAj%2Fimage.png&width=768&dpr=3&quality=100&sign=3d3eb840&sv=2) 3. Select the CloudFormation option and click "Launch with CloudFormation" ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FgLsc00QHZdZY3GlbfIql%2Fimage.png&width=768&dpr=3&quality=100&sign=584d585&sv=2) 4. On the "Create stack" screen click next and proceed to the next section ( [Template parameters](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#template-parameters) ). #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#template-parameters) Template parameters After you are presented with the template configuration screen, make sure to fill out the following parameters: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F46fa9bKOgoaKFEYpacx1%2Fimage.png&width=768&dpr=3&quality=100&sign=df57b6bd&sv=2) Choose a name for the stack. This can be chosen freely but must be unique across your deployed stacks. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FGuqTrTGXAqGa9jN76EPk%2Fimage.png&width=768&dpr=3&quality=100&sign=b70a049e&sv=2) The `CoreDefaultAdminPassword` will be the password used for logging to the Defguard Core dashboard for the `admin` user. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FYwiauN1Zg1ypQFuSPwjg%2Fimage.png&width=768&dpr=3&quality=100&sign=c388c282&sv=2) The `CoreUrl` is the URL under which your Defguard Core dashboard will be accessible. This should be filled according to the domain you chose before ([Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). For example, if your domain for Defguard Core is `defguard.example.com`, insert `https://defguard.example.com` here. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FaQy504wax5AwkFwBoyvV%2Fimage.png&width=768&dpr=3&quality=100&sign=c77fd005&sv=2) This is the database password. Select a relatively strong password here as a very weak password may be rejected by the database system and may result in a deployment failure. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FR1sUkBiMhk6oU08h2UZR%2Fimage.png&width=768&dpr=3&quality=100&sign=67559b48&sv=2) This is the URL under which the Defguard Proxy will be accessible to users. Fill the field just like the `CoreUrl` field, but this time use the domain you chose for the Defguard Proxy ([Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fsps7zwfp1faoesN1TSyQ%2Fimage.png&width=768&dpr=3&quality=100&sign=821eb9d3&sv=2) Insert here the ARN of the certificate you prepared earlier ([Prerequisites](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). This will auto configure HTTPS for both Defguard Proxy and Core. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FY8A6WpnlWiCm6N8Vwmn2%2Fimage.png&width=768&dpr=3&quality=100&sign=9fc33bdb&sv=2) Provide here the name of your SSH key. This is required for SSH access to the EC2 instances. Note that manual configuration of firewall access on the SSH port (22) is required after the deployment. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fbta4g2vViks8zPKs8OWY%2Fimage.png&width=768&dpr=3&quality=100&sign=141b1a54&sv=2) The VPN parameters allow for configuring the details of your VPN network (location). You may want to change the name of the location to better suit your deployment. By default, NAT is enabled on the VPN Gateway instance so connecting clients can automatically reach servers inside your private network (this is required to reach Defguard Core dashboard, for example). If you disable NAT, you will need to configure routing rules yourself. Make sure to also check the rest of the pre-filled parameters, as you may want to change some of them. The full list is available in the [Template parameters](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) section. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#stack-options) Stack options Next, select the behavior on deployment failure: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FGEPzYQKpqOuAWw7S2J61%2Fimage.png&width=768&dpr=3&quality=100&sign=f296f920&sv=2) We recommend cleaning up everything after failed deployment, to keep a clean state when retrying. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FR6eZr34qyql6F8JfOKc6%2Fimage.png&width=768&dpr=3&quality=100&sign=44560ad2&sv=2) The template contains several IAM roles that are used to grant access required for interacting with the AWS SecretManager to pass secrets securely between components during the deployment. The template also consists of a lambda function along with an IAM role which is responsible for creating a token that can be used by an admin to access the VPN for the first time. This needs to be accepted to proceed further. Now wait for the deployment to finish. If all went OK, you should see _CREATE\_COMPLETE_ status. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#outputs) Outputs After the deployment completes, you will receive a set of outputs in the "outputs" tab. This values are required for further configuration. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fq3wf719h8Jhc8sGi6tTE%2Fimage.png&width=768&dpr=3&quality=100&sign=21e75851&sv=2) #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#setting-up-your-domains) Setting up your domains The template will provision two domains: `InternalProxyALBDNSName` and `PublicProxyALBDNSName` . The public domain points to the Defguard Proxy instance's reverse proxy, and the internal one to Core's. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fk1QtrBzNj1elUnk2eXRh%2Fimage.png&width=768&dpr=3&quality=100&sign=bf7c15e8&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2Fwgu4HeuxVCl3Kad6VH3F%2Fimage.png&width=768&dpr=3&quality=100&sign=40ab06b2&sv=2) You can use those domains to setup CNAME records in your DNS provider configuration, so the domains you defined in the `ProxyUrl` and `CoreUrl` point to the correct load balancers (reverse proxies) and in result, to the correct components: Your domain CNAME response Target component `` `` Defguard Core (internal) `` `` Defguard Proxy (public) #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#configuring-you-first-device-using-the-desktop-client) Configuring you first device using the desktop client The stack is now fully set up and you can try to access it. The dashboard is not publicly available, so you'll need to configure access to the VPN first. Use the token displayed in the `AdminFirstDeviceToken` CloudFormation output to add your first device. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FfOX3IS3ys67H8DMg9XZZ%2Fimage.png&width=768&dpr=3&quality=100&sign=983e8907&sv=2) Check this [guidearrow-up-right](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) on adding a new instance in the Desktop client, to learn more about the process. As the instance URL, use the URL you defined in your Defguard Proxy instance configuration section of the CloudFormation template (`ProxyUrl`). #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#accessing-the-dashboard) Accessing the dashboard After you use the `AdminFirstDeviceToken` as described in the previous section you will gain access to the VPN network and (by default) the VPC network. To access the Defguard Core dashboard, navigate to the URL you defined in the `CoreUrl` parameter. To login, use the default `admin` username and the password defined in `CoreDefaultAdminPassword`. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#customisation) Customisation --------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) Template parameters #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#general) General * `SshKeyName` (optional): EC2 Key Pair name for SSH access to instances. If not provided, SSH access will not be available. Requires a manual setup of SSH security group rules afterwards. * `StackPrefix` (optional): The prefix that all the deployed components will receive, for example the Defguard core EC2 instance will be named <`StackPrefix>-core-instance`. * `SSLCertificateArn` (optional): The ARN of the AWS issued certificate to use for setting up HTTPS for Core and Proxy. This certificate must be valid for the domains specified in `CoreUrl` and `ProxyUrl`. If left empty, HTTPS won't be configured automatically. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#core-instance) Core Instance * `CoreCookieInsecure` (optional): If set to `true`, Defguard Core will use insecure cookies. This is not recommended for production environments. Set it to `true` if you are using HTTP instead of HTTPS. * `CoreGrpcPort` (optional): The gRPC port, default is `50051`. This is used for communication between Defguard components. * `CoreHttpPort` (optional): The HTTP port on which Defguard Core should listen, default is `8000`. This is where the Defguard web UI will be accessible. * `CoreInstanceType` (optional): The instance type (e.g., `t3.medium`, `m5.large`), default is `t3.micro`. * `CoreLogLevel` (optional): The log level of Defguard Core, default is `info`. You can also set it to `error`, `debug` or `trace`. * `CoreUrl` (required): The URL where Defguard Core will be accessible (e.g., `https://defguard.example.com`). This should be the URL that users will use to access the Defguard web interface. * `CoreDefaultAdminPassword`: The password for the default `admin` user. Used to login to the web dashhboard. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#database) Database * `DbInstanceClass` (optional): The instance class for the PostgreSQL database, default is `db.t3.micro`. * `DbName` (optional): The name of the PostgreSQL database, default is `defguard`. * `DbPassword`: The password for the PostgreSQL database. * `DbPort` (optional): The port on which the PostgreSQL database will listen, default is `5432`. * `DbStorage` (optional): The storage size for the PostgreSQL database, default is `20`. This is the size in GB. * `DbUsername` (optional): The username for the PostgreSQL database, default is `defguard`. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) Gateway Instance * `GatewayInstanceType` (optional): The instance type for the Gateway, default is `t3.micro`. * `GatewayLogLevel` (optional): The log level for the Gateway, default is `info`. You can also set it to `error`, `debug` or `trace`. * `GatewaySecret` (required): The secret used to authenticate the Gateway with Defguard Core. This should be a strong, random string, 64 characters long. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#proxy-instance) Proxy Instance * `ProxyGrpcPort` (optional): The gRPC port for the Proxy, default is `50051`. * `ProxyHttpPort` (optional): The HTTP port for the Proxy, default is `8000`. This is where the Defguard Proxy web UI will be accessible. The proxy UI is used for user enrollment. * `ProxyInstanceType` (optional): The instance type for the Proxy, default is `t3.micro`. * `ProxyLogLevel` (optional): The log level for the Proxy, default is `info`. You can also set it to `error`, `debug` or `trace`. * `ProxyUrl` (required): The URL where the Defguard Proxy will be accessible (e.g., `https://proxy.defguard.example.com`). This should be the URL that users will use to access the Defguard Proxy web UI. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#network-configuration) Network configuration * `VpcCidr` (optional): The CIDR block for the VPC in which Defguard will be deployed, default is `10.0.0.0/16`. * `VpcName` (optional): The name of the VPC, default is `defguard-vpc`. * `PublicSubnet1Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PublicSubnet2Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet1Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet2Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. #### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#vpn-network-location-configuration) VPN Network (Location) configuration * `VpnNetworkAddress` (optional): The CIDR address for the VPN network, default is `10.10.10.1/24`. The VPN clients will receive IP addresses from this range. The gateway will have the first address in the range. * `VpnNetworkName` (optional): The name of the VPN network (location). This is displayed both to the clients and in the Defguard web UI, default is `vpn1`. * `VpnNetworkNat` (optional): If set to `true`, the VPN will have masquerading enabled, allowing clients to access other networks through the VPN (e.g., the internet). Default is `true`. * `VpnNetworkPort` (optional): The UDP port on which the VPN will listen for incoming VPN connections, default is `51820`. ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#customizing-the-deployment) Customizing the deployment By default, the CloudFormation template will deploy Defguard with the settings according to the recommended architecture, that is: Component Port Access allowed from Core 8000 (HTTP) Gateways Core 50055 (gRPC) Gateways Proxy 50051 (gRPC) Core Proxy 8000 (HTTP) Anywhere Gateway 51820 (UDP) Anywhere You can customize the deployment by modifying the template or doing changes in the AWS Infrastructure Composer. To modify an existing stack deployed from the template, you can use the AWS Console, navigate to the CloudFormation service, select your stack, click on "Update stack" and then choose "Create a change set". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FCqiq7sMIuCFEqGrT0qol%2Fimage-5.png&width=768&dpr=3&quality=100&sign=31c4a8d1&sv=2) alt text Next, select how you want to update the stack. If you want to modify the parameters, select "Use existing template". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FexljBGfBj5zn35TKiqYJ%2Fimage-8.png&width=768&dpr=3&quality=100&sign=54859084&sv=2) alt text If you want to modify the template itself, the easiest way is to edit it in the Infrastructure Composer: select "Edit in Infrastructure Composer" and click the "Edit in Infrastructure Composer" button. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2FTOyK7padkuKNgGNSxWTy%2Fimage-9.png&width=768&dpr=3&quality=100&sign=4546eb59&sv=2) alt text ### [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#accessing-the-ec2-instances) Accessing the EC2 instances After deploying the CloudFormation template, the newly created EC2 instances should be visible in the AWS console in your target region: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FqPYuWxfmxFk6sz1LLLwd%2Fblobs%2F0U74vnR1rJ8203D7PzQG%2Fimage3333.png&width=768&dpr=3&quality=100&sign=8a8f9dcb&sv=2) To access the instances, use the key provided in the `SshKeyName` parameter. Note that you will need to allow SSH access to the EC2 instances using their respective AWS security groups. The default user is `admin`. [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#upgrading-components) Upgrading components ----------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation It's important to backup your database before performing a backup. Make sure to also check the [Migration guides](https://docs.defguard.net/2.0/deployment-strategies/upgrading) before upgrading to a newer version. All Defguard components are installed from the Defguard APT repository. The upgrade process is as follows: 1. SSH into the given component's EC2 instance 2. Execute the following commands: The corresponding package names can be found in the [Defguard APT repository documentation](https://docs.defguard.net/2.0/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . [hashtag](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#troubleshooting-and-common-issues) Troubleshooting and common issues ------------------------------------------------------------------------------------------------------------------------------------------------------------------- All Defguard components are deployed as systemd services. Their configuration files can be found on the respective host machine under `/etc/defguard`. [PreviousTerraformchevron-left](https://docs.defguard.net/2.0/deployment-strategies/terraform) [NextConfiguring HTTPS using AWS Certificate Managerchevron-right](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) * [AMI architecture](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#ami-architecture) * [Installation guide](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#installation-guide) * [Customisation](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#customisation) * [Template parameters](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) * [Customizing the deployment](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#customizing-the-deployment) * [Accessing the EC2 instances](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#accessing-the-ec2-instances) * [Upgrading components](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#upgrading-components) * [Troubleshooting and common issues](https://docs.defguard.net/2.0/deployment-strategies/amis-and-aws-cloudformation#troubleshooting-and-common-issues) sun-brightdesktopmoon Copy sudo apt update sudo apt install --only-upgrade sun-brightdesktopmoon --- # Using a userspace wireguard-go implementation | defguard Gateway currently supports using `wireguard-go`, a userspace WireGuard implementation. This approach is **not recommended** on platforms where a native support exists (e.g. Linux). You can enable the userspace implementation by setting the `userspace` config option or a corresponding `DEFGUARD_USERSPACE` environment variable to `true`. Because `wireguard-go` is not bundled by default with Defguard, it must be installed separately. The `wireguard-go` binary/command must be available on the host machine for it to function properly. On Docker, this currently requires building a custom image, as the base gateway images also don't come with `wireguard-go` pre-installed. This can be achieved as follows: Copy FROM golang:1.24.6-alpine AS builder RUN apk add --no-cache git make RUN git clone https://git.zx2c4.com/wireguard-go /src/wireguard-go \ && cd /src/wireguard-go \ && make # Specify the desired Gateway's version here FROM ghcr.io/defguard/gateway:latest COPY --from=builder /src/wireguard-go/wireguard-go /usr/local/bin/wireguard-go RUN chmod +x /usr/local/bin/wireguard-go Note that when running the Docker container with a userspace implementation on a Linux host, the container requires a `NET_ADMIN` capability and access to `/dev/net/tun`, this can be set in a Docker compose: Copy # Docker compose cap_add: - NET_ADMIN devices: - /dev/net/tun Or via the command line: [PreviousMigration guideschevron-left](https://docs.defguard.net/deployment-strategies/upgrading) [NextPre-production and development releaseschevron-right](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases) sun-brightdesktopmoon Copy docker run --cap-add=NET_ADMIN --device=/dev/net/tun [...] sun-brightdesktopmoon --- # Adding a location and getting a Gateway token | defguard [hashtag](https://docs.defguard.net/deployment-strategies/gateway#adding-a-location-in-defguard-core) Adding a location in Defguard Core --------------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation Please remember that **one gateway corresponds to one VPN location.** You can also deploy multiple gateways for one location for High Availability. Go to the address you set on `DEFGUARD_URL` with your browser and sign in using the credentials you set up during Core deployment. Go to the _VPN Overview_ module from the main menu and click the _Edit Locations settings_. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-9c14a4fcfd7e5c0e51ef4cb62d80c81f1ec2b635%252FScreenshot%25202025-10-15%2520at%252013.37.33.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=f969bdc&sv=2) Adding a new location Then click the _Add new location tab_. ![Adding a new location](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-d13a16e067acba452265f323aa247b694cfa6088%252FScreenshot%25202025-10-15%2520at%252013.37.55.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=e2c7b890&sv=2) Adding a new location Depending on what is more convenient for you, choose configuration from Wireguard file or do it manually. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-1bcd600655d9a635a6e2dc5029cab5ddff9fe298%252Fchoose_location_setup.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=a6adb359&sv=2) Location wizard ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-5c3096775d6fe257cb29c06890b93d09ad9f2640%252Flocation_configuration.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=275a1d5e&sv=2) Location configuration 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. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-703da6d817495ce11709ec01a15465522f52e112%252Fedit_locations_settings.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=e5628065&sv=2) Manual configuration In `Gateway server setup` copy two variables: `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-52ced7f70b6a9a2833b601b19ca4eaf6e2ab8c73%252Fgateway_server_setup.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=39110997&sv=2) Gateway server setup Also, if core has a custom SSL CA to secure gRPC communication, [you need the CA certificate (more here).](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) [hashtag](https://docs.defguard.net/deployment-strategies/gateway#deploy-the-gateway-service) Deploy the Gateway service ----------------------------------------------------------------------------------------------------------------------------- Proceed with deploying your Gateway service using the selected [deployment strategy](https://docs.defguard.net/deployment-strategies/setting-up-your-instance#choose-your-deployment-strategy) : * [package based](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#gateway-1) * [Docker Compose](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-gateway-service) * [Kubernetes](https://docs.defguard.net/deployment-strategies/kubernetes#vpn-gateway-service) * [Terraform](https://docs.defguard.net/deployment-strategies/terraform#gateway-module) * [AMIs and AWS CloudFormation](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) You can also check our guides on running Gateway on [OPNsense firewall](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall) or [MikroTik router](https://docs.defguard.net/deployment-strategies/running-gateway-on-mikrotik-routers) . If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](https://docs.defguard.net/features/network-devices#adding-a-new-network-device) . [PreviousConfiguring HTTPS using AWS Certificate Managerchevron-left](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) [NextConfigurationchevron-right](https://docs.defguard.net/deployment-strategies/configuration) * [Adding a location in Defguard Core](https://docs.defguard.net/deployment-strategies/gateway#adding-a-location-in-defguard-core) * [Deploy the Gateway service](https://docs.defguard.net/deployment-strategies/gateway#deploy-the-gateway-service) sun-brightdesktopmoon sun-brightdesktopmoon --- # Securing gRPC communication | defguard Defguard Core has two main communication endpoints: 1. gRPC port for communicating with Defguard Gateways, 2. gRPC port for communicating with Defguard Core. triangle-exclamation It is **critical** that: 1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes. 2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core. 3. If you want an additional layer of security, then you should create a **custom SSL Certificate Authority (CA)**, and provide Core, Proxy and Gateway Certificates from that CA so **any other connections to the gRPC services will not be accepted.** 4. Even if you have secured the network ports/firewall and do not want to create a custom SSL CA, please secure gRPC traffic with SSL and a reverse proxy. [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) Custom SSL CA and certificates ---------------------------------------------------------------------------------------------------------------------------------------------------- To secure not only with firewall communication between all Defguard gRPC components, a custom SSL chain of certificates should be used. This way the trust will be ensured on the Transport Layer Security (TLS) level. It is important to embed a correct domain name into the certificate as _X509v3 Subject Alternative Name_. The domain name must match the one under which a service is being hosted. ### [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#quick-setup) Quick setup To quickly generate a set of SSL certificates using [OpenSSLarrow-up-right](https://openssl-library.org/) or [LibreSSLarrow-up-right](https://www.libressl.org/) , use the following: * Generate Certificate Authority (CA) certificate and key for domain _example.local_ Copy openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt * Generate private key and Certificate Signing Request (CSR) * Generate certificate by signing the CSR, valid for 365 days circle-info Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly. To display certificate file contents: ### [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-configuration) Defguard configuration #### [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-core) Defguard Core Using command line arguments Using environment variables #### [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-proxy) Defguard Proxy Using command line arguments Using environment variables ### [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-gateway) Defguard Gateway Using command line arguments Using environment variables Using configuration file [hashtag](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) Trusted CA (eg. Let'sEncrypt or others) ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Often (like in the standalone package based installation tutorial) gRPC communication can be secured by a reverse proxy (NGINX, Caddy, Traefik, etc.) that handles SSL termination. It's common to use typical trusted CA (that is used for typical HTTPS traffic) like Let'sEncrypt or others. triangle-exclamation While this secures the transport layer and encrypts communication between Defguard components - it does not provide authorization between gRPC components like Custom CA does. Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall. If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for: * Defguard Gateway – in _gateway.toml_ add path to CA certificate file (in PEM format); for example, when using standard Let'sEncrypt installation ([Certbotarrow-up-right](https://certbot.eff.org/) ), you configure the CA path like this: * `grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem"` * Defguard Core – similarily, you need to configure Proxy CA certificate file using **DEFGUARD\_PROXY\_GRPC\_CA** environment variable: * `DEFGUARD_PROXY_GRPC_CA: /etc/letsencrypt/live/domain.name/chain.pem` [PreviousPre-production and development releaseschevron-left](https://docs.defguard.net/deployment-strategies/pre-production-and-development-releases) [NextUsing RSA instead of HMAC for OpenID keychevron-right](https://docs.defguard.net/deployment-strategies/openid-rsa-key) * [Custom SSL CA and certificates](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) * [Quick setup](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#quick-setup) * [Defguard configuration](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-configuration) * [Defguard Gateway](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#defguard-gateway) * [Trusted CA (eg. Let'sEncrypt or others)](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#trusted-ca-eg.-letsencrypt-or-others) sun-brightdesktopmoon Copy openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local Copy openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy Copy openssl x509 -noout -text -in core.crt Copy defguard --grpc-cert path/to/core.crt \ --grpc-key path/to/core.key \ --proxy-grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CERT=path/to/core.crt \ DEFGUARD_GRPC_KEY=path/to/core.key \ DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \ defguard Copy defguard-proxy --grpc-cert path/to/proxy.crt \ --grpc-key path/to/proxy.key Copy env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \ DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key defguard-proxy Copy defguard-gateway --grpc-ca path/to/ca.crt Copy env DEFGUARD_GRPC_CA=path/to/ca.crt \ defguard-gateway Copy grpc_ca = "path/to/ca.crt" sun-brightdesktopmoon --- # Health check | defguard [hashtag](https://docs.defguard.net/deployment-strategies/health-check#proxy) Proxy ---------------------------------------------------------------------------------------- [Proxyarrow-up-right](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application is running. Example request: Copy curl "https://enroll.example.com/api/v1/health" Response: Copy "alive" - with status code 200 - Proxy is working To verify gRPC services for **Proxy** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. Example request: Copy curl "https://enroll.example.com/api/v1/health-grpc" Response: Copy "alive" with status code 200 - Proxy is working and is connected to CORE "Not connected to Defguard Core" - with status code 503 - Proxy is working but is not connected to CORE [hashtag](https://docs.defguard.net/deployment-strategies/health-check#core) Core -------------------------------------------------------------------------------------- To check if [**Core**arrow-up-right](https://github.com/defguard/defguard) is working, you can use endpoint at `GET /api/v1/health` which verify it. Example request: Copy curl "https://defguard.example.com/api/v1/health" Response: To check if core gRPC service is alive, we recommend to use community tools like [grpc\_health\_probearrow-up-right](https://github.com/grpc-ecosystem/grpc-health-probe) . Example request for core: Example response: [hashtag](https://docs.defguard.net/deployment-strategies/health-check#gateway) Gateway -------------------------------------------------------------------------------------------- You can enable in gateway config ([example configarrow-up-right](https://github.com/DefGuard/gateway/blob/main/example-config.toml) ) a health check port, by adding the following line: In this example, gateway will open an additional HTTP port number 55003. Now we can use `GET /health` endpoint to verify whether gateway is working correctly. If running in Docker you can also enable it by setting the `HEALTH_PORT` [environment variable](https://docs.defguard.net/deployment-strategies/configuration#environmental-variables-arguments) . By default the HTTP server will listen on all interfaces, but if you prefer to bind only a specific IP you can set it by using the `http_bind_address` config option (or `DEFGUARD_HTTP_BIND_ADDRESS` environment variable). For example: Example request: Response: By default, no health check ports are open. [PreviousUsing RSA instead of HMAC for OpenID keychevron-left](https://docs.defguard.net/deployment-strategies/openid-rsa-key) [NextProduction deployment verification guidechevron-right](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide) Last updated 14 days ago * [Proxy](https://docs.defguard.net/deployment-strategies/health-check#proxy) * [Core](https://docs.defguard.net/deployment-strategies/health-check#core) * [Gateway](https://docs.defguard.net/deployment-strategies/health-check#gateway) sun-brightdesktopmoon Copy "alive" - with status code 200 - Core is working Copy ./grpc_health_probe -addr=defguard.example.com:50055 Copy status: SERVING Copy health_port = 55003 Copy http_bind_address = 10.0.10.20 Copy curl "http://gateway.example.com:55003/health" Copy "alive" - with status code 200 - Gateway is working and is connected to CORE "Not connected to core" - with status code 503 - Gateway is working but is not connected to CORE sun-brightdesktopmoon --- # Docker Compose | defguard [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#introduction) Introduction -------------------------------------------------------------------------------------------------------- This document provides a complete example of how to deploy Defguard using Docker Compose, including configuration for all components - Core, Proxy, and Gateway. It covers Docker image tags, environment variables, and reverse-proxy setup examples to help you quickly launch a fully functional Defguard environment. We recommend deploying each Defguard service on a dedicated server or virtual machine to ensure better isolation, performance, and security. In this setup, each Docker Compose file should be used for a single service, keeping the Core, Proxy, and Gateway components physically separated. circle-info Please note that we also offer docker-compose deployment with [_one-line quick deployment_](https://docs.defguard.net/getting-started/one-line-install) _,_ but this method is recommended for PoC/quick deployment as **it launches everything on one server and all services in one docker compose**. [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#docker-images-and-tags) Docker images and tags ---------------------------------------------------------------------------------------------------------------------------- We use `latest` (latest production images) tags in the examples below, but you can use others. All docker images for Core, Gateway, and Proxy have these additional tags: * `latest` - the latest stable production release. * `vX.Y`, `vX.Y.Z`, `vX.Y-alpha1` - fixed tags for specific stable and alpha releases. * `pre-release`\- the latest pre-production release (equivalent to vX.Y-alpha1). * `dev` - the latest development build from the dev branch (experimental). circle-exclamation We recommend always using fixed, stable tags (`vX.Y`, `vX.Y.Z`) for your production deployment. [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) Example Docker Compose deployment repository ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ We prepared a [git repositoryarrow-up-right](https://github.com/DefGuard/deployment) with and example Docker Compose configuration. To run your services using this example prepare your .env file by copying the template: Finally, run the service with Docker Compose: Below you'll find a detailed breakdown of configuration for different components: Core, Proxy and Gateway. [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) Deploying Core, database and reverse proxy services ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here is the **docker-compose.yaml** for the core and database. Configuration is split to the `.env` file (see below): #### [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#nginx-reverse-proxy) NGINX reverse-proxy Now that you have Defguard Core running, here is an example NGINX configuration to provide SSL termination: #### [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#the-configuration) The configuration Here is the `.env` file with all configuration variables: [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) Deploying Proxy and reverse proxy service ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Here is the **docker-compose.yaml** for Defguard Proxy (enrollment service and desktop client configuration service). To secure the gRPC communication, please generate the proxy CA and certificate, [more info here](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . #### [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#nginx-reverse-proxy-1) NGINX reverse-proxy Now that you have Defguard Proxy running, here is an example NGINX configuration to provide SSL termination: [hashtag](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-gateway-service) Deploying Gateway service ---------------------------------------------------------------------------------------------------------------------------------- You'll need a token to deploy Defguard Gateway. You'll have to set it as DEFGUARD\_TOKEN environment variable. Details on how to obtain the token [here](https://docs.defguard.net/deployment-strategies/gateway) . For Gateway to control the WireGuard kernel as well as network, it's recommended to run in the _host_ network mode as well as there are needed some Docker CAPs: [PreviousDefguard APT repositorychevron-left](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) [NextKuberneteschevron-right](https://docs.defguard.net/deployment-strategies/kubernetes) Last updated 9 days ago * [Introduction](https://docs.defguard.net/deployment-strategies/docker-compose#introduction) * [Docker images and tags](https://docs.defguard.net/deployment-strategies/docker-compose#docker-images-and-tags) * [Example Docker Compose deployment repository](https://docs.defguard.net/deployment-strategies/docker-compose#example-docker-compose-deployment-repository) * [Deploying Core, database and reverse proxy services](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-core-database-and-reverse-proxy-services) * [Deploying Proxy and reverse proxy service](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-proxy-and-reverse-proxy-service) * [Deploying Gateway service](https://docs.defguard.net/deployment-strategies/docker-compose#deploying-gateway-service) sun-brightdesktopmoon Copy cp .env.template .env Copy docker compose up Copy services: core: image: ghcr.io/defguard/defguard:latest restart: always container_name: "defguard" env_file: .env ports: # HTTP port - open on localhost, should be secured by reverse-proxy - "127.0.0.1:8000:8000" # gRPC port for gateway to connect to # open on all interfaces/IPs - whould be secured with custom CA (see .env) - "50055:50055" depends_on: - db volumes: # more info here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key - ./rsakey.pem:/keys/rsakey.pem # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/keys/ca.pem db: image: postgres:17-alpine container_name: "defguard-db" env_file: .env volumes: - db:/var/lib/postgresql/data volumes: db: Copy upstream defguard { server 127.0.0.1:8000; } server { listen 443 ssl http2; # your domain server_name defguard.secure-internal.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.error.log; ssl on; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/secure-internal.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/secure-internal.net/privkey.pem; client_max_body_size 20m; location / { proxy_connect_timeout 300; proxy_pass http://defguard; proxy_set_header Connection "upgrade"; proxy_set_header Upgrade $http_upgrade; proxy_set_header X-Forwarded-for $remote_addr; } } Copy # please generate each secret with: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64 DEFGUARD_SECRET_KEY= DEFGUARD_AUTH_SECRET= DEFGUARD_GATEWAY_SECRET= DEFGUARD_YUBIBRIDGE_SECRET= # if you plan to reverse-proxy defguard, please provide a full URL # this URL will be shared in emails, enrollement messages, etc.: DEFGUARD_URL=https://defguard.secure-internal.net # Must be an effective domain of DEFGUARD_URL # Changing DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing # Webauthn credentials. DEFGUARD_WEBAUTHN_RP_ID=defguard.secure-internal.net # accepted: info/debug/warning/error DEFGUARD_LOG_LEVEL=info # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates DEFGUARD_PROXY_GRPC_CA=/keys/ca.pem # gRPC URL of proxy (see proxy config) DEFGUARD_PROXY_URL=https://proxy.host:50051 # more details about RSA key here: # https://docs.defguard.net/deployment-strategies/openid-rsa-key DEFGUARD_OPENID_KEY=rsakey.pem # the URL of your proxy - will be displayed during enrollment, email # messages or desktop client configuration DEFGUARD_ENROLLMENT_URL=https://enrollment.public.net # PostgreSQL database configuration for core DEFGUARD_DB_HOST=db DEFGUARD_DB_PORT=5432 DEFGUARD_DB_USER=defguard # please generate password: # openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64 DEFGUARD_DB_PASSWORD= DEFGUARD_DB_NAME=defguard # database configuration for "db" container # must be same as above # database will be initialized with these values (the user/pass set here) POSTGRES_DB=defguard POSTGRES_USER=defguard POSTGRES_PASSWORD=!SAME_AS-GENERATED-DEFGUARD_DB_PASSWORD! Copy services: proxy: image: ghcr.io/defguard/defguard-proxy:latest restart: unless-stopped ports: # HTTP port - should be secured by reverse proxy - "127.0.0.1:8080:8080" - "50051:50051" environment: # path in the volume to custom proxy cert & key - DEFGUARD_PROXY_GRPC_CERT=ca/proxy.crt - DEFGUARD_PROXY_GRPC_KEY=ca/proxy.key volumes: - ./ca/proxy.crt:ca/proxy.crt - ./ca/proxy.key:ca/proxy.key Copy upstream defguard-proxy { server 127.0.0.1:8080; } server { listen 443 http2; server_name enrollment.public.net; access_log /var/log/nginx/defguard-proxy.log; error_log /var/log/nginx/defguard-proxy.error.log; # we assume you already have Let'sEncrypt SSL certificates # for your domain ssl_certificate /etc/letsencrypt/live/public.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/public.net/privkey.pem; client_max_body_size 20m; location / { proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } Copy services: gateway: image: ghcr.io/defguard/gateway:latest restart: unless-stopped network_mode: "host" environment: - DEFGUARD_GRPC_URL=https://core-ip:50055 - DEFGUARD_GRPC_CA=/ca.pem - DEFGUARD_STATS_PERIOD=30 # to get the token add a VPN location and get the token - DEFGUARD_TOKEN=tokenFromCoreLocation - DEFGUARD_GATEWAY_NAME=willBeVisibleInDefguardAsGWName volumes: # more info about custom CA here: # https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates - ./ca.pem:/ca.pem cap_add: - NET_ADMIN sun-brightdesktopmoon --- # Reverse Proxy configuration using NGINX | defguard [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#introduction) Introduction --------------------------------------------------------------------------------------------------------------------------------- This guide explains how to configure [NGINXarrow-up-right](https://nginx.org/) as a reverse proxy for Defguard's components (Core and 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. To provide HTTPS encryption, this guide also uses [Certbotarrow-up-right](https://certbot.eff.org/) , a free, open-source tool from the [Let’s Encryptarrow-up-right](https://letsencrypt.org/) project. Certbot automatically issues and renews SSL/TLS certificates, allowing you to secure your Defguard domains without manual certificate management. ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#installing-nginx-and-certbot) Installing NGINX and Certbot To install and prepare NGINX with Let’s Encrypt certificates: Copy apt install nginx certbot systemctl enable nginx.service systemctl start nginx.service Disable the default configuration to avoid conflicts: Copy unlink /etc/nginx/sites-enabled/default ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) Obtaining SSL Certificates Before configuring NGINX, issue valid SSL certificates for your domains. In this example we use: * Core: **my-server.defguard.net** * Enrollment (Proxy): **enroll.defguard.net** Generate certificates with Certbot: Copy certbot certonly \ --non-interactive \ --agree-tos \ --standalone \ --email [email protected] \ -d my-server.defguard.net \ -d enroll.defguard.net Certbot will generate certificate in fullchain.pem and privkey.pem in the following paths: ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-core-nginx-configuration) Defguard Core NGINX configuration Create a new configuration file for the Core service: `/etc/nginx/sites-available/my-server.defguard.net.conf` Enable the configuration and reload NGINX: To verify, run: circle-info If you use this simple setup and run all services on one server, you can use [NGINX access restrictionsarrow-up-right](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-tcp/) for securing core and allowing to access the _my-server.defguard.net_ only to selected networks - blocking the direct access from the Internet. ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-proxy-enrollment-service-nginx-configuration) Defguard Proxy (Enrollment Service) NGINX configuration The Proxy service exposes APIs for enrollment, remote onboarding, and desktop client configuration. Create its NGINX configuration file: `/etc/nginx/sites-available/enroll.defguard.net.conf` Enable and restart NGINX: ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#security-recommendations) Security Recommendations * Only expose **HTTPS ports (443)** for web access. * Do **not** expose internal **gRPC ports** (444, 50051, 50055) directly to the Internet. ### [hashtag](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#summary) Summary After completing the configuration: * Defguard Core is available at `https://my-server.defguard.net` * Enrollment and onboarding services are available at `https://enroll.defguard.net` * Both services are secured with SSL and reverse-proxied through NGINX. [PreviousRunning Gateway on MikroTik routerschevron-left](https://docs.defguard.net/deployment-strategies/running-gateway-on-mikrotik-routers) [NextHigh Availability and Failoverchevron-right](https://docs.defguard.net/deployment-strategies/high-availability-and-failover) * [Introduction](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#introduction) * [Installing NGINX and Certbot](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#installing-nginx-and-certbot) * [Obtaining SSL Certificates](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#obtaining-ssl-certificates) * [Defguard Core NGINX configuration](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-core-nginx-configuration) * [Defguard Proxy (Enrollment Service) NGINX configuration](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#defguard-proxy-enrollment-service-nginx-configuration) * [Security Recommendations](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#security-recommendations) * [Summary](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx#summary) sun-brightdesktopmoon Copy /etc/letsencrypt/live/my-server.defguard.net /etc/letsencrypt/live/enroll.defguard.net Copy upstream defguard { server 127.0.0.1:8000; } upstream defguard-grpc { server 127.0.0.1:50055; } server { listen 443 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard.log; error_log /var/log/nginx/defguard.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; client_max_body_size 128M; location / { proxy_pass http://defguard; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } server { listen 444 ssl http2; server_name my-server.defguard.net; access_log /var/log/nginx/defguard-grpc.log; error_log /var/log/nginx/defguard-grpc.e.log; ssl_certificate /etc/letsencrypt/live/my-server.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-server.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://defguard-grpc; } } Copy ln -s /etc/nginx/sites-available/my-server.defguard.net.conf /etc/nginx/sites-enabled/my-server.defguard.net.conf systemctl reload nginx.service Copy curl https://my-server.defguard.net/api/v1/health # Expected output: alive Copy upstream defguard-proxy { server 127.0.0.1:8080; } upstream proxy-grpc { server 127.0.0.1:50051; } server { listen 443 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll.log; error_log /var/log/nginx/enroll.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { proxy_http_version 1.1; proxy_pass http://defguard-proxy; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } } server { listen 444 ssl http2; server_name enroll.defguard.net; access_log /var/log/nginx/enroll-grpc.log; error_log /var/log/nginx/enroll-grpc.e.log; ssl_certificate /etc/letsencrypt/live/enroll.defguard.net/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/enroll.defguard.net/privkey.pem; client_max_body_size 200m; location / { grpc_pass grpc://proxy-grpc; grpc_socket_keepalive on; grpc_read_timeout 3000s; grpc_send_timeout 3000s; grpc_next_upstream_timeout 0; proxy_request_buffering off; proxy_buffering off; proxy_connect_timeout 3000s; proxy_send_timeout 3000s; proxy_read_timeout 3000s; proxy_socket_keepalive on; keepalive_timeout 90s; send_timeout 90s; client_body_timeout 3000s; } } Copy ln -s /etc/nginx/sites-available/enroll.defguard.net.conf /etc/nginx/sites-enabled/enroll.defguard.net.conf systemctl restart nginx.service sun-brightdesktopmoon --- # Deployment automation | defguard This guide will focus on ways of automating some aspects of the deployment of the Defguard components. ### [hashtag](https://docs.defguard.net/deployment-strategies/deployment-automation#gateway-secret) Gateway secret The Gateway secret is one of the [Core's configuration values](https://docs.defguard.net/deployment-strategies/configuration#secrets-configuration) and is used to generate [Gateway authentication tokens](https://docs.defguard.net/deployment-strategies/gateway) . This value must be often generated automatically and then passed to components to achieve a fully automated process. The easiest way of generating the `DEFGUARD_GATEWAY_SECRET` would be using the following bash command: Copy openssl rand -base64 64 | tr -d "=+/" | tr -d '\n' | cut -c1-"64" ### [hashtag](https://docs.defguard.net/deployment-strategies/deployment-automation#first-location-creation) First location creation You can programmatically add a first network (location) by invoking the following command (using the Defguard binary): Copy defguard --secret-key "" init-vpn-location \ --name \ --address \ --endpoint \ --port \ --id 1 \ --allowed-ips \ --allowed-ips 2>&1 \ | grep -Eo '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' For example: Copy defguard --secret-key "" init-vpn-location \ --name network-name \ --address 10.10.10.1/24 \ --endpoint 127.0.0.1 \ --port 50051 \ --id 1 \ --allowed-ips 10.10.10.1/24 \ --allowed-ips 10.10.11.1/24 2>&1 \ | grep -Eo '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' The grep at the end is used to extract the Gateway token (JWT) that the command returns. The token should be [passed to the Gateway](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) in order to authenticate to Core. The Defguard binary location is dependent on the deployment method, an absolute path may be required here, e.g. `/usr/bin/defguard`. If the command doesn't produce an output, try running it without the grep, to check for any errors. Please note that the above command requires all your Defguard Core environment variables to be present (especially ones related to the database connection) during invocation. Your database also needs to be reachable. If your invocation environment doesn't have access to the Core's configuration variables, you should load them, for example: Replace `/etc/defguard/core.conf` with the location of your Defguard Core environment variables. ### [hashtag](https://docs.defguard.net/deployment-strategies/deployment-automation#gateway-token) Gateway token If for some reason you can't rely on the token that's output by the `init-vpn-location` command described in the [previous section](https://docs.defguard.net/deployment-strategies/deployment-automation#first-location-creation) , you can generate the token independently using scripts. To generate a Gateway authentication token, the Core's `DEFGUARD_GATEWAY_SECRET` value must be available to the script. Thus, your deployment process must generate the `DEFGUARD_GATEWAY_SECRET` before generating the token, and share the value of the secret, to the script that generates the token. The following example script can be used to generate Gateway's authentication token: The above script requires the environment variable `DEFGUARD_GATEWAY_SECRET` to be set. Example execution: The output token can be then used for [configuring the Gateway](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) . [PreviousLinux Kernel WireGuard tuningchevron-left](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning) [NextPurchasing and using the licensechevron-right](https://docs.defguard.net/enterprise/license) Last updated 12 days ago * [Gateway secret](https://docs.defguard.net/deployment-strategies/deployment-automation#gateway-secret) * [First location creation](https://docs.defguard.net/deployment-strategies/deployment-automation#first-location-creation) * [Gateway token](https://docs.defguard.net/deployment-strategies/deployment-automation#gateway-token) sun-brightdesktopmoon Copy source /etc/defguard/core.conf && defguard --secret-key ... Copy #!/bin/bash base64url_encode() { echo -n "$1" | openssl base64 -e -A | tr '+/' '-_' | tr -d '=' } # The ID of the DefGuard network for which the gateway token is generated, # if your deployment creates only one (first) network, this should be "1". NETWORK_ID="1" ISSUER="DefGuard" HEADER='{"alg":"HS256","typ":"JWT"}' NOW=$(date +%s) EXPIRATION=$(($NOW + 315360000)) PAYLOAD=$(cat < dst-port= action=dst-nat to-addresses=172.17.0.2 to-ports= Copy /ip/route/add dst-address= gateway=172.17.0.2 Copy /container/envs/add name=defguard_env key=DEFGUARD_TOKEN value= /container/envs/add name=defguard_env key=DEFGUARD_GRPC_URL value= /container/envs/add name=defguard_env key=DEFGUARD_DISABLE_FW_MGMT value=true Copy /container/mounts/add name=defguard_cert src= dst=/certs /container/envs/add name=defguard_env key=DEFGUARD_GRPC_CA value=/certs/myCA.pem Copy /container/config/set registry-url=https://ghcr.io Copy /container/add remote-image=ghcr.io/defguard/gateway:latest interface=veth1 envlist=defguard_env sun-brightdesktopmoon --- # Using RSA instead of HMAC for OpenID key | defguard By default, Defguard uses [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation and the. If you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) , you'll have to configure the Defguard core `DEFGUARD_OPENID_KEY` configuration variable with the path to the RSA private key. You can generate the RSA key with: Copy openssl genpkey -out /path/to/rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096 [PreviousSecuring gRPC communicationchevron-left](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) [NextHealth checkchevron-right](https://docs.defguard.net/deployment-strategies/health-check) sun-brightdesktopmoon sun-brightdesktopmoon --- # Linux Kernel WireGuard tuning | defguard [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#introduction) Introduction ----------------------------------------------------------------------------------------------------------------------- WireGuard is widely praised for its lean codebase and efficiency. However, the default Linux kernel settings are often tuned for general-purpose computing, not for acting as a high-speed router handling encrypted UDP traffic at scale. Here are some tuning parameters to achieve maximum performance (low latency), stability across changing networks (roaming), and high concurrency, we must tune three distinct layers. circle-info Kernel **sysctl** settings optimize how the Linux kernel schedules packets and manages memory buffers. Add the following to `/etc/sysctl.d/99-wireguard-tuning.conf`. or `/etc/sysctl.conf` [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#kernel-tuning) Kernel tuning ------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#congestion-control-and-queuing-latency-and-throughput) Congestion Control & Queuing (Latency & Throughput) To reduce bufferbloat (latency spikes under load) and maximize throughput, we replace the default CUBIC algorithm with BBR (Bottleneck Bandwidth and Round-trip propagation time), which is less sensitive to packet loss and more aggressively seeks the optimal congestion window. Copy # Use BBR congestion control net.core.default_qdisc = fq net.ipv4.tcp_congestion_control = bbr ### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#memory-and-buffers-throughput) Memory & Buffers (Throughput) WireGuard uses UDP for data transport. By default, Linux kernel UDP buffer sizes are often too small for high-speed transfers (1 Gbps+), causing packets to be dropped in the kernel before WireGuard can process them. Copy # Increase default and max receive/send window sizes (approx 16MB) net.core.rmem_max = 16777216 net.core.wmem_max = 16777216 net.core.rmem_default = 262144 net.core.wmem_default = 262144 net.ipv4.udp_mem = 4096 87380 16777216 ### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#packet-processing-and-forwarding-efficiency) Packet Processing & Forwarding (Efficiency) These settings allow the kernel to process packets faster and handle bursts of traffic without dropping them. ### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#packet-buffering) Packet buffering In Linux, network cards (NICs) use **NAPI** (New API) polling to handle incoming packets. When an interrupt fires, the kernel disables further interrupts and polls the NIC, processing packets in batches. `net.core.netdev_budget` limits how many packets the kernel may process in a single SoftIRQ cycle before yielding the CPU and it's default is: 300 packets. * Too low value - Under heavy load (e.g., 100+ streaming users), the kernel yields too early, packets back up in the NIC buffer, and drops occur. * Too high value - The networking stack can monopolize a CPU core, starving userspace processes and increasing overall latency. For high-performance VPN servers, we increase `netdev_budget` to favor network throughput and tune the companion setting `netdev_budget_usecs` to cap CPU time per polling cycle. Below you wil find some recommended values for multiple scenarios. #### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#home-small-office) Home/Small Office Meaning around ~20 users: The default 300 is fine and changing it won't be noticeable. ### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#id-50-vpn-users-and-above) 50 VPN users and above #### [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#high-throughput-10gbps) High throughput ≥ 10Gbps You may need values as high as `netdev_budget = 1200`, assuming you have a powerful CPU with Receive Packet Steering (RPS) enabled. [hashtag](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#multiple-connection-concurrency-egress-via-vpn) Multiple connection concurrency (egress via VPN) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- WireGuard is stateless, but the Linux firewall tracking (used for Masquerade or DNAT when configuring connection tracking and egress through VPN) is stateful. Here is a formula how to optimize netfliter parameters based on the following assumptions that one connected device is a UDP stream (VPN) and multiple TCP streams that the user/device "uses" for browsing/apps "exiting" via VPN: circle-exclamation **Assumptation**: 1 active user generates ~50-100 simultaneous connections Parameter (Sysctl) Description 10 Devices(Home/SOHO) 100 Devices(SMB/Office) 1,000 Devices(Enterprise/ISP) 10,000 Devices(Data Center) `net.netfilter.nf_conntrack_max` CRITICAL. Max concurrent connections tracked. 65536 131072 524288 5242880 `net.core.somaxconn` Max pending connections in queue. 4096 4096 16384 65535 `net.core.netdev_max_backlog` Max packets queued if kernel is busy. 1000 5000 16384 65535 `net.core.netdev_budget` Max packets processed in one CPU cycle. 300 600 600 1200 `net.core.rmem_max` (Bytes) Max OS receive buffer size (UDP). 16 MB 16 MB 32 MB 128 MB `net.core.wmem_max` (Bytes) Max OS send buffer size (UDP). 16 MB 16 MB 32 MB 128 MB `fs.file-max` System-wide file descriptor limit. Default 100000 1000000 5000000 **Required System RAM** Minimum RAM needed for state tables. 512 MB 1 GB 4 GB 32 GB+ [PreviousProduction deployment verification guidechevron-left](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide) [NextDeployment automationchevron-right](https://docs.defguard.net/deployment-strategies/deployment-automation) Last updated 21 days ago * [Introduction](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#introduction) * [Kernel tuning](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#kernel-tuning) * [Congestion Control & Queuing (Latency & Throughput)](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#congestion-control-and-queuing-latency-and-throughput) * [Memory & Buffers (Throughput)](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#memory-and-buffers-throughput) * [Packet Processing & Forwarding (Efficiency)](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#packet-processing-and-forwarding-efficiency) * [Packet buffering](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#packet-buffering) * [50 VPN users and above](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#id-50-vpn-users-and-above) * [Multiple connection concurrency (egress via VPN)](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning#multiple-connection-concurrency-egress-via-vpn) sun-brightdesktopmoon Copy # Enable IP Forwarding (Required for VPN) net.ipv4.ip_forward = 1 # Increase the maximum length of the processor input queue # (Prevents drops during traffic bursts) net.core.netdev_max_backlog = 5000 # Increase the maximum number of connections waiting for acceptance net.core.somaxconn = 8192 Copy # --- NAPI Polling Budget Tuning --- # Increase packet budget (Default: 300). # Allow the CPU to process up to 600 packets in one cycle. # Beneficial for high PPS (packets per second) environments. net.core.netdev_budget = 600 # Increase the time budget (Default: 2000us or 2ms). # Allow the NAPI cycle to run for up to 4ms before yielding. # Prevents the loop from aborting prematurely during heavy traffic bursts. net.core.netdev_budget_usecs = 4000 sun-brightdesktopmoon --- # Standalone package based installation | defguard [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#introduction) 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. circle-info Make sure you understand [Defguard's architecture](https://docs.defguard.net/in-depth/architecture) , especially the division into the main components: Core, Proxy, Gateway. circle-exclamation This is a simple guide installing all components on a single server. For production make sure your infrastructure is prepared by following our [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) . [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#system-requirements) 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 servicearrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) (run by proxy) that will enable [remote onboarding, enrollmentarrow-up-right](https://defguard.gitbook.io/defguard/help/enrollment) and [easy configuration for our Desktop Clients (by adding Defguard instances)](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 **opened 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 publicly exposed.** * System clock is synchronized using Network Time Protocol (NTP). This is important for time-based one-time password (TOTP) codes. [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#installing-a-database) Installing a database ------------------------------------------------------------------------------------------------------------------------------------------------- Defguard Core uses [PostgreSQLarrow-up-right](https://www.postgresql.org/) 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 `::::` * we connected into the `defguard` database to verify `defguard` user can communicate with the database [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#installing-packages) Installing packages --------------------------------------------------------------------------------------------------------------------------------------------- circle-info Defguard also have public APT repository, if you want know how to set it up, follow [this guide](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#core) Core You can find the URL to your package from the releases of the Core component on [GitHubarrow-up-right](https://github.com/DefGuard/defguard/releases) . 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 if Defguard Core has been installed properly: ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#gateway) Gateway You can find the URL to your package from the releases of Defguard Gateway on [GitHubarrow-up-right](https://github.com/DefGuard/gateway/releases) . 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: ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#proxy) Proxy You can find the URL to your package from the releases of Defguard Proxy component on [GitHubarrow-up-right](https://github.com/DefGuard/proxy/releases) . 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: [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#running-defguard) Running Defguard --------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#core-1) Core To run core service we need to configure `/etc/defguard/core.conf`. circle-info 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 will use server domain `my-server.defguard.net`. Example `/etc/defguard/core.conf`: **If you have configured PostgreSQL database with different names than in** [**PostgreSQL guide**](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#postgresql) **, 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**](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#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: ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#gateway-1) 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`. #### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#setup-location-for-gateway) Setup location for gateway Follow [this guide](https://docs.defguard.net/deployment-strategies/gateway) 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. #### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#create-config-file) Create config file After getting `DEFGUARD_TOKEN` and `DEFGUARD_GRPC_URL` variables, we can configure our gateway service. Create config.toml file and swap `` and `` 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: ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#proxy-1) Proxy To run proxy service (for [remote onboarding & enrollment](https://docs.defguard.net/using-defguard-for-end-users/enrollment) ), we can do it by: Check the logs afterwards. Should look like this: ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#reverse-proxy) 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](https://docs.defguard.net/deployment-strategies/reverse-proxy-configuration-using-nginx) . After having the reverse proxy configured and running you can continue with this guide. ### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) 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` circle-check Now you have full working Defguard services 🥳 You can [configure your desktop client using the enrollment](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) 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 itarrow-up-right](https://defguard.gitbook.io/defguard/tutorials/step-by-step-setting-up-a-vpn-server#enabling-to-access-internet-through-your-vpn) . [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#securing-the-setup) 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) triangle-exclamation **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](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication#custom-ssl-ca-and-certificates) . [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#upgrading-packages) Upgrading packages ------------------------------------------------------------------------------------------------------------------------------------------- circle-info 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. #### [hashtag](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#freebsd-opnsense) FreeBSD/OPNsense 1. Uninstall the current version. 2. Install a newer version (as described [above](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#installing-packages) ). 3. Restart the service. [PreviousHardware, OS, network and firewall recommendationschevron-left](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) [NextDefguard APT repositorychevron-right](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) Last updated 2 months ago * [Introduction](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#introduction) * [System Requirements](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#system-requirements) * [Installing a database](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#installing-a-database) * [Installing packages](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#installing-packages) * [Core](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#core) * [Gateway](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#gateway) * [Proxy](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#proxy) * [Running Defguard](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#running-defguard) * [Core](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#core-1) * [Gateway](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#gateway-1) * [Proxy](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#proxy-1) * [Reverse proxy](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#reverse-proxy) * [Enabling Proxy service in the Core](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#enabling-proxy-service-in-the-core) * [Securing the setup](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#securing-the-setup) * [Upgrading packages](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation#upgrading-packages) sun-brightdesktopmoon Copy apt install postgresql Copy # su -c /usr/bin/psql postgres postgres=# CREATE USER defguard WITH SUPERUSER PASSWORD 'defguard'; postgres=# CREATE DATABASE defguard; Copy # echo 'localhost:5432:defguard:defguard:defguard' >> ~/.pgpass # chmod 600 ~/.pgpass # psql -d defguard -h localhost -U defguard defguard=# exit Copy wget Copy wget https://github.com/DefGuard/defguard/releases/download/v0.11.0/defguard-0.11.0-x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard -V defguard_common 1.6.0 Copy wget Copy # wget https://github.com/DefGuard/gateway/releases/download/v0.7.0/defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.deb # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-gateway-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-gateway-X.Y.Z_x86_64-unknown-freebsd.pkg Copy sudo dpkg -i defguard-gateway_0.7.0_x86_64-unknown-linux-gnu.deb Copy # defguard-gateway -V defguard-gateway 0.7.0 Copy wget Copy wget https://github.com/DefGuard/proxy/releases/download/v0.5.0/defguard-proxy-0.5.0-x86_64-unknown-linux-gnu.deb Copy dpkg -i /defguard-proxy--x86_64-unknown-linux-gnu.deb Copy # on Debian/Ubuntu sudo dpkg -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.deb # if you added apt repository sudo apt install defguard-proxy # on Fedora/Red Hat Linux/SUSE sudo rpm -i /defguard-proxy-X.Y.Z-x86_64-unknown-linux-gnu.rpm # FreeBSD pkg install openssl pkg add /defguard-proxy-X.Y.Z_x86_64-unknown-freebsd.pkg Copy # defguard-proxy -V defguard-proxy 0.5.0 Copy ### 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" Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard.service systemctl start defguard.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard start Copy # journalctl -u defguard.service | tail -n 50 Jul 29 13:57:15 defguard-testing systemd[1]: Started defguard.service - Defguard core service. Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.738420Z INFO defguard: Starting defguard Jul 29 13:57:15 defguard-testing defguard[2776504]: 2024-07-29T11:57:15.743079Z INFO defguard::db: Initializing DB pool Jul 29 13:57:16 defguard-testing defguard[2776504]: 2024-07-29T11:57:16.297407Z INFO defguard: Using HMAC OpenID signing key Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.156559Z INFO defguard::db::models::user: Initializing admin user Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.595218Z INFO defguard::db::models::user: New admin user has been created, adding to Admin group... Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.747717Z INFO defguard::db::models::settings: Initializing default settings Jul 29 13:57:19 defguard-testing defguard[2776504]: 2024-07-29T11:57:19.780563Z INFO defguard: Started web services Copy # 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-gateway.service systemctl start defguard-gateway.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_gateway start Copy 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/ Copy 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 Copy # on systems with systemd (like Debian, Ubuntu, Fedora/Red Hat Linux/SUSE) systemctl enable defguard-proxy.service systemctl start defguard-proxy.service # on systems with rc.d (like FreeBSD, NetBSD) sudo /usr/local/etc/rc.d/defguard_proxy start Copy # 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 Copy # Proxy connection configuration DEFGUARD_PROXY_URL=https://enroll.defguard.net:444 Copy ### 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" Copy systemctl restart defguard.service Copy # Core package pkg delete defguard # or Gateway package pkg delete defguard-gateway # or Proxy package pkg delete defguard-proxy Copy # Core service sudo /usr/local/etc/rc.d/defguard restart # or Gateway service sudo /usr/local/etc/rc.d/defguard_gateway restart # or Proxy service sudo /usr/local/etc/rc.d/defguard_proxy restart sun-brightdesktopmoon --- # Migration guides | defguard circle-exclamation Before doing any updates please remember to **backup your database.** [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#id-1.5.x-greater-than-1.6.0) 1.5.x -> 1.6.0 -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core) Core #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#service-locations) Service locations A new feature has been introduced: [Service locations](https://docs.defguard.net/features/service-locations) . This feature requires both Defguard Core and Proxy to be updated to the 1.6.0 version. Updating only one of those components will prevent this feature from working properly. ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#proxy) Proxy #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#service-locations-1) Service locations As mentioned in the Core migration section, this feature requires both Defguard Core and Proxy to be updated to the 1.6.0 version. ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client) Desktop client #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#service-locations-2) Service locations The [Service locations](https://docs.defguard.net/features/service-locations) feature currently only works on the Windows Desktop Client. Locations in the service location mode won't be sent to clients that don't support them (either are older than 1.6.0 or are on a different platform than Windows). To work properly, this feature requires the Desktop Client to be in version 1.6. Service locations won't show up or work in older clients. #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#force-all-traffic) Force all traffic 1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](https://docs.defguard.net/features/wireguard/behavior-customization#client-traffic-policy-selection) . However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#macos-client-changes) macOS Client changes Desktop Client is now distributed in App Store and uses native VPN management. For these reasons, the user settings have moved from `~/Library/Application Support/net.defguard` to `~/Library/Containers/net.defguard/Data/Library/Application Support/net.defguard`. In order to preserve settings from v1.5.x, use one of the following guides to transfer the data: **Using Finder** 1. In Finder, select the menu **Go**, press and hold _Alt_ key, then select **Library**, as depicted below. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-50a4c5c2fe2b9179ed57b5a1c81ef718dd11c864%252Ffinder-go-library.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c090d2a8&sv=2) 1. Move or copy the contents of _Application Support_ > _net.defguard_ to _Containers_ > _net.defguard_ > _Data_ > _Library_ > _Application Support_ > _net.defguard_ **Using Terminal** Open Terminal.app and execute #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#windows-client-changes) Windows Client changes The Windows Desktop Client installer has changed. The installer is now provided in an `.msi` format. Installing the new 1.6.0 Client from the `.msi` will leave the previous Client version still installed. This can also cause old VPN connections to still be active until a next system restart is performed. To resolve this, before upgrading, we recommend first uninstalling the old Client. This will leave your configuration intact and it should carry over to the new Client after its installation, without the need to configure everything again. ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#mobile-client) Mobile client **Force all traffic** 1.6 introduces the ability to "Force all traffic" as a [Client traffic policyarrow-up-right](https://app.gitbook.com/o/Z3mGSAbEj9iLdZ7cNFlL/s/e86iamwJVSYnIRsyVEAV/features/wireguard/behavior-customization#client-traffic-policy-selection) . However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) 1.4.x -> 1.5.0 -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-1) Core #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#version-compatibility) Version compatibility This release introduces a version checking system. All the Defguard system components (core, proxy, gateway and clients) are now version-aware and check their compatibility with the components their are communicating with. This might mean that until you upgrade all the components your web UI might indicate that your proxy or gateway is of an unknown version. #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#instance-uuid-bug) Instance UUID bug A bug resulting in zeroing the UUID of a given instance has been found and resolved ([PR linkarrow-up-right](https://github.com/DefGuard/defguard/pull/1521) ). This value is used by the desktop client to identify instances. The new client should gracefully handle migration to a new UUID if it has been zeroed out due to the bug mentioned above. #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#verify-client-disconnect-threshold-for-your-mfa-locations) Verify client disconnect threshold for your MFA locations In order to ensure that MFA works correctly with the new [mobile clients](https://docs.defguard.net/using-defguard-for-end-users/mobile-client) please ensure that the [client disconnect threshold](https://docs.defguard.net/features/wireguard/create-your-vpn-network#client-disconnect-threshold) is set to at least 300s (5 minutes). ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#proxy-1) Proxy We've introduced a new functionality to Desktop Client - to authenticate [Multi-Factor connections using Mobile Client](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa) . For this feature to work, Proxy (enrollment service) creates a Web-socket that the desktop client connects to while waiting for responses from the mobile client. circle-exclamation If you have a reverse proxy for the enrollment service (which we highly recommend with SSL termination), please **make sure that web-sockets are enabled.** ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-1) Desktop client #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#unix-socket-ipc-and-new-user-group-requirement-macos-and-linux) Unix socket IPC and new user group requirement (macOS & Linux) macOS and Linux clients now use Unix sockets for IPC. To securely access this socket the user must belong to a specific group as described in [client documentation](https://docs.defguard.net/using-defguard-for-end-users/desktop-client) . The change should require no additional steps for macOS users, but Linux users who install the client from official packages will need to log out and back in or reboot after install to refresh group membership. This will not be required on subsequent updates. Linux users who use release binaries will need to manually create the `defguard` group and adjust their group membership. [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) Any release <= 1.3 -> 1.4 ---------------------------------------------------------------------------------------------------------------------------------------------- 1.4 release introduces changes related to multiple client IP addresses. To ensure compatibility, **all components must be updated** to v1.4 or higher: * **Core** * **Proxy** * **Gateway** * **Desktop Clients** Running outdated versions may result in errors due to incompatible data formats. ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-2) Core We've made a small update to the LDAP integration to support more complex user nesting within the LDAP tree ([related issuearrow-up-right](https://github.com/DefGuard/defguard/issues/1242) ). If you were already using the integration, you shouldn't notice any changes. However, we **strongly recommend backing up your database before the upgrade and afterwards verifying** the following to ensure everything continues to work as expected: * Your Defguard user list and user devices remain unchanged * All users can still log in without issues If you encounter any problems, please report them on our [GitHubarrow-up-right](https://github.com/DefGuard/defguard/issues) . [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) Any previous release → 1.4.0-alpha3 ----------------------------------------------------------------------------------------------------------------------------------------------- We've introduced some changes to the LDAP integration. We recommend reading [the above section](https://docs.defguard.net/deployment-strategies/upgrading#core) before upgrading. [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-release-1.3.0) Any previous release → 1.3.0 --------------------------------------------------------------------------------------------------------------------------------- * The LDAP integration has become an enterprise feature. You will need to purchase the enterprise license if you exceed the free limits. See [Purchasing and using the license](https://docs.defguard.net/enterprise/license) for more information regarding the license. * If you used the LDAP integration previously, it will be off by default after upgrading. You will have to manually enable it in the settings in the LDAP tab:\\ ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-5f4070edec7e75f1fed21dfe30999dee72601b7d%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=3f2b9ac4&sv=2) [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) Any previous 1.3.0 alpha → 1.3.0 alpha 4 --------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-3) Core LDAP integration received a major overhaul of how users are mapped to Defguard users when the two-way synchronization is enabled. Now, users are always identified by their leftmost DN value. A new synchronization may cause some of your users to be re-added, which in turn may cause the loss of some of their Defguard specific data (e.g. their devices). This will happen if your leftmost DN component's attribute (referred to as RDN) is not the same as your current username attribute. This issue is only related to the two-way synchronization mechanism and occurs only if you used one of the previous alphas of 1.3.0. Upgrading from any previous release to alpha 4 (skipping the alphas before) should not result in this happening. Before an upgrade, turn off the two-way synchronization. After upgrading, you will have access to a new option, the RDN user attribute: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-039cf1a173824bd50af1f1f4355a170084d15aab%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=67d5eae8&sv=2) Set it according to your LDAP server setup. This should be the DN's leftmost component attribute, e.g. in the case of `cn=user1,cn=users,dc=ad,dc=example,dc=com` this would be "cn". This attribute is needed to properly identify users in your LDAP server. The username attribute will be mapped to Defguard usernames. Read [Settings table](https://docs.defguard.net/features/ldap-and-active-directory-integration/settings-table) for a description of those settings options. After you configured this value, you can re-enable the two-way synchronization. [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) Any previous core release -> core 1.1.4 ------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-4) Core triangle-exclamation In Core 1.1.4, we've made email addresses case insensitive, as this is a standard for many major providers. Because the emails were case sensitive up to this point, you may end up with users with the same email addresses from core's point of view. All email addresses must be unique case-insensitively, meaning that a user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) ` can't coexist with another user with an address `[[email protected]](https://docs.defguard.net/cdn-cgi/l/email-protection) `. Before upgrading, make sure you don't have any users with the same email addresses given the above. If you do, please change those addresses or remove the users altogether. Remember to check it case-insensitively. If you have users with duplicate email addresses, the migrations will fail, and you won't be able to upgrade. You can use the following SQL query to locate users with duplicate emails in the database: [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) 1.0.0 -> 1.1.0 -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#proxy-2) Proxy There is a new setting: * ENV Variable: DEFGUARD\_PROXY\_URL * command line argument `--url` * /etc/defguard/proxy.toml: `url =` **Which should be set to the same value as in core** `**DEFGUARD_ENROLLMENT_URL**` [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#any-release-greater-than-1.0.0) Any release -> 1.0.0 ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-5) Core When upgrading core to 1.0.0 (even to a 1.0.0 pre-release) make sure that your users **have unique email addresses** as we've introduced a constraint requiring email addresses to be unique among users. triangle-exclamation If you have duplicate emails in your database, the migrations during the upgrade process will simply fail. You will need to change a duplicate email address before the upgrade by hand via the Defguard dashboard or by accessing the database. ### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-real-time-sync) Desktop Client Real Time Sync From 1.0.0 we have introduced [Enterprise featuresarrow-up-right](https://github.com/DefGuard/docs/blob/docs/deployment-strategies/broken-reference/README.md) , and one of them is [automatic and real-time desktop client configuration synchronization](https://docs.defguard.net/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration) . To enable this on an **already configured desktop client,** one must perform one time instance update, which will generate necessary tokens on the client to perform from now on automatic updates. In details: 1. The admin must generate a new token for the client - [more details here](https://docs.defguard.net/features/wireguard/remote-desktop-activation) (token can be sent over email or shared in any other secret way). 2. The user must perform the [Instance Update - more details here](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#updating-instance) . circle-exclamation Any client that is configured from scratch has this done automatically and no actions needed to be done. [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In this release, we have **hardened the security architecture**, and since the Proxy component is open for HTTP commands and is frequently communicating with Core we have reversed the communication and now **Core is connecting to Proxy (Proxy is a gRPC server and Core is the client).** This way if Core is in a secure network segment (like Intranet) and Proxy in a DMZ segment (where Internet traffic is allowed) you don't need to open on your firewall rules for Proxy from DMZ to connect to Intranet (no packet for New Connections from DMZ->Intranet). This change requires a few changes if you are upgrading: #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#proxy-deployment-configuration) Proxy deployment configuration 1. Remove `DEFGUARD_PROXY_UPSTREAM_GRPC_URL` variable - since Proxy does not connect to Defguard Core any more. 2. Proxy is now the server to which Defguard Core connects, so you may want to: 1. Optional: configure non-default Proxy gRPC port with `DEFGUARD_PROXY_GRPC_PORT -` default value is **50051** 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/treafik/...) the port with SSL/TLS. 1. (Optional) If you want to use SSL with Proxy gRPC server without revers-proxy (nginx/etc) configure `DEFGUARD_PROXY_GRPC_CERT` and `DEFGUARD_PROXY_GRPC_KEY` following the [SSL setup guide](https://docs.defguard.net/deployment-strategies/docker-compose#grpc-ssl-setup) . 3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server **can be reached from Core**. #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#core-deployment-configuration) Core deployment configuration 1. Add `DEFGUARD_PROXY_URL` variable to point to your Proxy gRPC server endpoint, for example `http://proxy:50051` when using Docker Compose - or any gRPC URL you have configured with your reverse proxy. 2. (Optional) If using SSL configure `DEFGUARD_PROXY_GRPC_CA` #### [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#upgrade-process) Upgrade process 1. Update Core & Proxy images/binaries and restart services. 2. You should see in the logs that Proxy is awaiting a gRPC connection - example docker logs: 1. Core should be attempting to establish a gRPC connection with Proxy (and retrying every 10s if unable to successfully connect), like this: 1. After Defguard connects successfully to proxy, you should see in proxy logs: [hashtag](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) Desktop Client 0.1.x -> 0.2.0 ----------------------------------------------------------------------------------------------------------------------------------------------- With this release we have added Multi-Factor Authentication to the desktop client. Unfortunately desktop client database has change significantly as well as business logic (for example endpoints to proxy for MFA handshake). We have not stored them previously in the database - thus they cannot be recovered/updated automatically. circle-exclamation That unfortunately means you have to remove all your instances before upgrading (or just remove any desktop client configuration files, including the database) and start the enrollment (adding new instance) again after upgrading - just by adding a new device (you can remove the old one). [PreviousUpdating and version compatibilitychevron-left](https://docs.defguard.net/deployment-strategies/updating-and-version-compatibility) [NextUsing a userspace wireguard-go implementationchevron-right](https://docs.defguard.net/deployment-strategies/using-a-userspace-wireguard-go-implementation) Last updated 2 months ago * [1.5.x -> 1.6.0](https://docs.defguard.net/deployment-strategies/upgrading#id-1.5.x-greater-than-1.6.0) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core) * [Proxy](https://docs.defguard.net/deployment-strategies/upgrading#proxy) * [Desktop client](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client) * [Mobile client](https://docs.defguard.net/deployment-strategies/upgrading#mobile-client) * [1.4.x -> 1.5.0](https://docs.defguard.net/deployment-strategies/upgrading#id-1.4.x-greater-than-1.5.0) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core-1) * [Proxy](https://docs.defguard.net/deployment-strategies/upgrading#proxy-1) * [Desktop client](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-1) * [Any release <= 1.3 -> 1.4](https://docs.defguard.net/deployment-strategies/upgrading#any-release-less-than-1.3-greater-than-1.4) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core-2) * [Any previous release → 1.4.0-alpha3](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-release-1.4.0-alpha3) * [Any previous release → 1.3.0](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-release-1.3.0) * [Any previous 1.3.0 alpha → 1.3.0 alpha 4](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-1.3.0-alpha-1.3.0-alpha-4) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core-3) * [Any previous core release -> core 1.1.4](https://docs.defguard.net/deployment-strategies/upgrading#any-previous-core-release-greater-than-core-1.1.4) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core-4) * [1.0.0 -> 1.1.0](https://docs.defguard.net/deployment-strategies/upgrading#id-1.0.0-greater-than-1.1.0) * [Proxy](https://docs.defguard.net/deployment-strategies/upgrading#proxy-2) * [Any release -> 1.0.0](https://docs.defguard.net/deployment-strategies/upgrading#any-release-greater-than-1.0.0) * [Core](https://docs.defguard.net/deployment-strategies/upgrading#core-5) * [Desktop Client Real Time Sync](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-real-time-sync) * [Core 0.8.x -> 0.9.x with Proxy 0.2.x -> 0.3.x](https://docs.defguard.net/deployment-strategies/upgrading#core-0.8.x-greater-than-0.9.x-with-proxy-0.2.x-greater-than-0.3.x) * [Desktop Client 0.1.x -> 0.2.0](https://docs.defguard.net/deployment-strategies/upgrading#desktop-client-0.1.x-greater-than-0.2.0) sun-brightdesktopmoon Copy rm -r ~/Library/Containers/net.defguard/Data/Library/Application\ Support/net.defguard mv ~/Library/Application\ Support/net.defguard ~/Library/Containers/net.defguard/Data/Library/Application\ Support/ Copy select id, username, email from "user" where lower(email) in ( select lower(email) from "user" group by lower(email) having count(*) > 1 ) Copy Attaching to defguard_proxy_1 proxy_1 | 2024-01-24T14:05:41.365035Z INFO defguard_proxy::server: Starting Defguard proxy server proxy_1 | 2024-01-24T14:05:41.365069Z DEBUG defguard_proxy::server: Setting up API server proxy_1 | 2024-01-24T14:05:41.365130Z INFO defguard_proxy::server: gRPC server is listening on 0.0.0.0:50051 proxy_1 | 2024-01-24T14:05:41.365333Z INFO defguard_proxy::server: Web server is listening on 0.0.0.0:8080 Copy defguard | 2024-01-24T14:17:47.815294Z INFO defguard::grpc: Connecting to proxy Copy proxy_1 | 2024-01-24T14:17:47.819504Z INFO defguard_proxy: RPC client connected from: 10.123.123.2:35916 sun-brightdesktopmoon --- # Amazon Machine Image (AMI) | defguard This guide explains how to deploy Defguard on AWS using official Amazon Machine Images (AMIs) and a preconfigured CloudFormation template. It walks you through launching all required components - including Core, Gateway, Proxy, and the PostgreSQL database - in a production-ready architecture with minimal manual configuration. You will learn how to subscribe to the AMIs, deploy the stack, attach SSL certificates, configure domains, and gain initial VPN access. The goal is to provide a repeatable, secure deployment method that allows you to get Defguard running quickly while still enabling advanced customization for larger or more complex environments. [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#ami-architecture) AMI architecture ----------------------------------------------------------------------------------------------------------------------------- We recommend using the AMIs with our CloudFormation template as it will automatically configure all components. You can import the CloudFormation template from the AWS Marketplace or from our GitHub [deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment) . The template consists of the following main components: * **Defguard Core** * **Defguard Gateway** - The template has only one Gateway instance, but Defguard supports running multiple Gateways if you need more VPN locations. * **Defguard Proxy** * **PostgreSQL Database** We recommend reading the [Architecture documentationarrow-up-right](https://docs.defguard.net/in-depth/architecture) to understand how these components interact. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252F0namoZpVS8JQYir0UQad%252Faws_cloudformation_v2.png%3Falt%3Dmedia%26token%3D4e8df954-3412-412d-8e96-470e805f603b&width=768&dpr=3&quality=100&sign=eeab8a51&sv=2) Diagram showing how the components are deployed using the template [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#installation-guide) Installation guide --------------------------------------------------------------------------------------------------------------------------------- circle-info In order to use the CloudFormation template you need to subscribe to the Defguard AMI product. The most straightforward way to obtain the template is to select it during the product delivery after subscribing to the product on the marketplace. After the CloudFormation template is uploaded either manually or via the marketplace, you will be prompted to fill the details of your deployment. This guide will go over the most important settings that need to be filled for a functional deployment. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#prerequisites) Prerequisites * Two domains: one for accessing Defguard Core (the main dashboard) and one for accessing Defguard Proxy (for external enrollment and device configuration) * AWS issued SSL certificates for the two domains. See [this page](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) for more information. * An SSH key added to AWS. This will allow you to access the EC2 instances later on. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#obtaining-the-template) Obtaining the template 1. Subscribe to the product on AWS Marketplace. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252FJKNVnydV6zfU5kOGlab2%252FScreenshot%25202025-12-01%2520at%252014.22.10.png%3Falt%3Dmedia%26token%3D4295b208-b2b3-4148-aeab-84b0d426d3c6&width=768&dpr=3&quality=100&sign=62788782&sv=2) 2. After subscription succeeds, click the launch your software button: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252FwgzQJ8SVor5BNMj6f5Tm%252Fimage.png%3Falt%3Dmedia%26token%3Da99d1003-3020-4046-b684-ba71e2c6f5f6&width=768&dpr=3&quality=100&sign=7ec12db0&sv=2) 3. Select the CloudFormation option and click "Launch with CloudFormation" ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252FuikI1Shgn3zKyKAw1mRP%252Fimage.png%3Falt%3Dmedia%26token%3D3702474b-0e1d-46ab-9908-04cb2b893aa3&width=768&dpr=3&quality=100&sign=19881a02&sv=2) 4. On the "Create stack" screen click next and proceed to the next section ( [Template parameters](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#template-parameters) ). #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#template-parameters) Template parameters After you are presented with the template configuration screen, make sure to fill out the following parameters: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252FxWnqJzZQ109i987mryLr%252Fimage.png%3Falt%3Dmedia%26token%3D576a6a84-aa43-4754-a376-66621dd97945&width=768&dpr=3&quality=100&sign=234985bc&sv=2) Choose a name for the stack. This can be chosen freely but must be unique across your deployed stacks. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-dafc2e63f75d4b8c4d7400360722c6e8206b9d94%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=87f6ea60&sv=2) The `CoreDefaultAdminPassword` will be the password used for logging to the Defguard Core dashboard for the `admin` user. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-b00ba95b47e14aed9c47b737846abeb5c728fff1%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=553d89b2&sv=2) The `CoreUrl` is the URL under which your Defguard Core dashboard will be accessible. This should be filled according to the domain you chose before ([Prerequisites](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). For example, if your domain for Defguard Core is `defguard.example.com`, insert `https://defguard.example.com` here. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-a6c695bfb31c9ee791a9b61c621e95405591450e%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=7ad6be9&sv=2) This is the database password. Select a relatively strong password here as a very weak password may be rejected by the database system and may result in a deployment failure. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-cf2fb760395811ad22f763fb60cd36695092f246%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=e48fefb&sv=2) This is the URL under which the Defguard Proxy will be accessible to users. Fill the field just like the `CoreUrl` field, but this time use the domain you chose for the Defguard Proxy ([Prerequisites](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-f0f8163a789b43be4cb4bb8ae74a6be65406c22a%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=e624a2c2&sv=2) Insert here the ARN of the certificate you prepared earlier ([Prerequisites](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#prerequisites) ). This will auto configure HTTPS for both Defguard Proxy and Core. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-7f4e6c96c3cf7a5bd2525af7cd09f8c6d8ddee9d%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=322191cc&sv=2) Provide here the name of your SSH key. This is required for SSH access to the EC2 instances. Note that manual configuration of firewall access on the SSH port (22) is required after the deployment. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-7f5f435ca3b3ea7db2d2de27de852b2947e3b445%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c9c83860&sv=2) The VPN parameters allow for configuring the details of your VPN network (location). You may want to change the name of the location to better suit your deployment. By default, NAT is enabled on the VPN Gateway instance so connecting clients can automatically reach servers inside your private network (this is required to reach Defguard Core dashboard, for example). If you disable NAT, you will need to configure routing rules yourself. Make sure to also check the rest of the pre-filled parameters, as you may want to change some of them. The full list is available in the [Template parameters](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) section. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#stack-options) Stack options Next, select the behavior on deployment failure: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-66abb0b46f92c938b5695b74a33b6eaf4b57e4f2%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=b6b8437f&sv=2) We recommend cleaning up everything after failed deployment, to keep a clean state when retrying. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-cb712e1e16e89472b9ad6d8864113b0f91b66f84%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=37d1354f&sv=2) The template contains several IAM roles that are used to grant access required for interacting with the AWS SecretManager to pass secrets securely between components during the deployment. The template also consists of a lambda function along with an IAM role which is responsible for creating a token that can be used by an admin to access the VPN for the first time. This needs to be accepted to proceed further. Now wait for the deployment to finish. If all went OK, you should see _CREATE\_COMPLETE_ status. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#outputs) Outputs After the deployment completes, you will receive a set of outputs in the "outputs" tab. This values are required for further configuration. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-cdb2478a0b1a3a1caf0133bf8f7e2596cabdd96e%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=437ee4a3&sv=2) #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#setting-up-your-domains) Setting up your domains The template will provision two domains: `InternalProxyALBDNSName` and `PublicProxyALBDNSName` . The public domain points to the Defguard Proxy instance's reverse proxy, and the internal one to Core's. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-90c1d5cf9c5de1e6df562d3c43c5cf5120d74a02%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=acd904c&sv=2) ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-f7e0f699ce4975df42beb46cc10acf0d8dea9765%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=1be65800&sv=2) You can use those domains to setup CNAME records in your DNS provider configuration, so the domains you defined in the `ProxyUrl` and `CoreUrl` point to the correct load balancers (reverse proxies) and in result, to the correct components: Your domain CNAME response Target component `` `` Defguard Core (internal) `` `` Defguard Proxy (public) #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#configuring-you-first-device-using-the-desktop-client) Configuring you first device using the desktop client The stack is now fully set up and you can try to access it. The dashboard is not publicly available, so you'll need to configure access to the VPN first. Use the token displayed in the `AdminFirstDeviceToken` CloudFormation output to add your first device. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-3e6fe2c7724b9e7597ecb8bb36293ba7a2123de1%252Fimage.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=75a2a8f8&sv=2) Check this [guidearrow-up-right](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) on adding a new instance in the Desktop client, to learn more about the process. As the instance URL, use the URL you defined in your Defguard Proxy instance configuration section of the CloudFormation template (`ProxyUrl`). #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#accessing-the-dashboard) Accessing the dashboard After you use the `AdminFirstDeviceToken` as described in the previous section you will gain access to the VPN network and (by default) the VPC network. To access the Defguard Core dashboard, navigate to the URL you defined in the `CoreUrl` parameter. To login, use the default `admin` username and the password defined in `CoreDefaultAdminPassword`. [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#customisation) Customisation ----------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) Template parameters #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#general) General * `SshKeyName` (optional): EC2 Key Pair name for SSH access to instances. If not provided, SSH access will not be available. Requires a manual setup of SSH security group rules afterwards. * `StackPrefix` (optional): The prefix that all the deployed components will receive, for example the Defguard core EC2 instance will be named <`StackPrefix>-core-instance`. * `SSLCertificateArn` (optional): The ARN of the AWS issued certificate to use for setting up HTTPS for Core and Proxy. This certificate must be valid for the domains specified in `CoreUrl` and `ProxyUrl`. If left empty, HTTPS won't be configured automatically. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#core-instance) Core Instance * `CoreCookieInsecure` (optional): If set to `true`, Defguard Core will use insecure cookies. This is not recommended for production environments. Set it to `true` if you are using HTTP instead of HTTPS. * `CoreGrpcPort` (optional): The gRPC port, default is `50051`. This is used for communication between Defguard components. * `CoreHttpPort` (optional): The HTTP port on which Defguard Core should listen, default is `8000`. This is where the Defguard web UI will be accessible. * `CoreInstanceType` (optional): The instance type (e.g., `t3.medium`, `m5.large`), default is `t3.micro`. * `CoreLogLevel` (optional): The log level of Defguard Core, default is `info`. You can also set it to `error`, `debug` or `trace`. * `CoreUrl` (required): The URL where Defguard Core will be accessible (e.g., `https://defguard.example.com`). This should be the URL that users will use to access the Defguard web interface. * `CoreDefaultAdminPassword`: The password for the default `admin` user. Used to login to the web dashhboard. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#database) Database * `DbInstanceClass` (optional): The instance class for the PostgreSQL database, default is `db.t3.micro`. * `DbName` (optional): The name of the PostgreSQL database, default is `defguard`. * `DbPassword`: The password for the PostgreSQL database. * `DbPort` (optional): The port on which the PostgreSQL database will listen, default is `5432`. * `DbStorage` (optional): The storage size for the PostgreSQL database, default is `20`. This is the size in GB. * `DbUsername` (optional): The username for the PostgreSQL database, default is `defguard`. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#gateway-instance) Gateway Instance * `GatewayInstanceType` (optional): The instance type for the Gateway, default is `t3.micro`. * `GatewayLogLevel` (optional): The log level for the Gateway, default is `info`. You can also set it to `error`, `debug` or `trace`. * `GatewaySecret` (required): The secret used to authenticate the Gateway with Defguard Core. This should be a strong, random string, 64 characters long. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#proxy-instance) Proxy Instance * `ProxyGrpcPort` (optional): The gRPC port for the Proxy, default is `50051`. * `ProxyHttpPort` (optional): The HTTP port for the Proxy, default is `8000`. This is where the Defguard Proxy web UI will be accessible. The proxy UI is used for user enrollment. * `ProxyInstanceType` (optional): The instance type for the Proxy, default is `t3.micro`. * `ProxyLogLevel` (optional): The log level for the Proxy, default is `info`. You can also set it to `error`, `debug` or `trace`. * `ProxyUrl` (required): The URL where the Defguard Proxy will be accessible (e.g., `https://proxy.defguard.example.com`). This should be the URL that users will use to access the Defguard Proxy web UI. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#network-configuration) Network configuration * `VpcCidr` (optional): The CIDR block for the VPC in which Defguard will be deployed, default is `10.0.0.0/16`. * `VpcName` (optional): The name of the VPC, default is `defguard-vpc`. * `PublicSubnet1Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PublicSubnet2Cidr` (optional): CIDR block for one of the public subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet1Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. * `PrivateSubnet2Cidr` (optional): CIDR block for one of the private subnets. This can be chosen arbitrarily as long as it's within the VPC CIDR range. #### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#vpn-network-location-configuration) VPN Network (Location) configuration * `VpnNetworkAddress` (optional): The CIDR address for the VPN network, default is `10.10.10.1/24`. The VPN clients will receive IP addresses from this range. The gateway will have the first address in the range. * `VpnNetworkName` (optional): The name of the VPN network (location). This is displayed both to the clients and in the Defguard web UI, default is `vpn1`. * `VpnNetworkNat` (optional): If set to `true`, the VPN will have masquerading enabled, allowing clients to access other networks through the VPN (e.g., the internet). Default is `true`. * `VpnNetworkPort` (optional): The UDP port on which the VPN will listen for incoming VPN connections, default is `51820`. ### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#customizing-the-deployment) Customizing the deployment By default, the CloudFormation template will deploy Defguard with the settings according to the recommended architecture, that is: Component Port Access allowed from Core 8000 (HTTP) Gateways Core 50055 (gRPC) Gateways Proxy 50051 (gRPC) Core Proxy 8000 (HTTP) Anywhere Gateway 51820 (UDP) Anywhere You can customize the deployment by modifying the template or doing changes in the AWS Infrastructure Composer. To modify an existing stack deployed from the template, you can use the AWS Console, navigate to the CloudFormation service, select your stack, click on "Update stack" and then choose "Create a change set". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-ba532451cedc12bd46c86219883e7e36376dd053%252Fimage-5.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=3133b4d&sv=2) alt text Next, select how you want to update the stack. If you want to modify the parameters, select "Use existing template". ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-42d877bb0632f8bb21a5a922a5ee017e586e5159%252Fimage-8.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=b7769294&sv=2) alt text If you want to modify the template itself, the easiest way is to edit it in the Infrastructure Composer: select "Edit in Infrastructure Composer" and click the "Edit in Infrastructure Composer" button. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-af23f85fd60f50aed8cb7cf8cb8890fa782faf42%252Fimage-9.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=c1c0b03c&sv=2) alt text ### [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#accessing-the-ec2-instances) Accessing the EC2 instances After deploying the CloudFormation template, the newly created EC2 instances should be visible in the AWS console in your target region: ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252FX8Qctyrh848pOo8UoMgG%252Fimage3333.png%3Falt%3Dmedia%26token%3D844951ad-0609-436e-aec1-c0431feda225&width=768&dpr=3&quality=100&sign=215437ee&sv=2) To access the instances, use the key provided in the `SshKeyName` parameter. Note that you will need to allow SSH access to the EC2 instances using their respective AWS security groups. The default user is `admin`. [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#upgrading-components) Upgrading components ------------------------------------------------------------------------------------------------------------------------------------- circle-exclamation It's important to backup your database before performing a backup. Make sure to also check the [Migration guides](https://docs.defguard.net/deployment-strategies/upgrading) before upgrading to a newer version. All Defguard components are installed from the Defguard APT repository. The upgrade process is as follows: 1. SSH into the given component's EC2 instance 2. Execute the following commands: The corresponding package names can be found in the [Defguard APT repository documentation](https://docs.defguard.net/deployment-strategies/standalone-package-based-installation/defguard-apt-repository) . [hashtag](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#troubleshooting-and-common-issues) Troubleshooting and common issues --------------------------------------------------------------------------------------------------------------------------------------------------------------- All Defguard components are deployed as systemd services. Their configuration files can be found on the respective host machine under `/etc/defguard`. [PreviousTerraformchevron-left](https://docs.defguard.net/deployment-strategies/terraform) [NextConfiguring HTTPS using AWS Certificate Managerchevron-right](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation/configuring-https-using-aws-certificate-manager) Last updated 2 months ago * [AMI architecture](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#ami-architecture) * [Installation guide](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#installation-guide) * [Customisation](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#customisation) * [Template parameters](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#template-parameters-1) * [Customizing the deployment](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#customizing-the-deployment) * [Accessing the EC2 instances](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#accessing-the-ec2-instances) * [Upgrading components](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#upgrading-components) * [Troubleshooting and common issues](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation#troubleshooting-and-common-issues) sun-brightdesktopmoon Copy sudo apt update sudo apt install --only-upgrade sun-brightdesktopmoon --- # Configuration | defguard Here you can find a list of all configurable things through environmental variables, options or configuration files for all Defguard components (each top-level section for a specific component): * [Core config](https://docs.defguard.net/deployment-strategies/configuration#core) * [Proxy config](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) * [Gateway config](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) * [YubiBridge config](https://docs.defguard.net/deployment-strategies/configuration#yubibridge-configuration) circle-info If you are using [one-line installation](https://docs.defguard.net/getting-started/one-line-install) , everything is generated and configured automatically. [hashtag](https://docs.defguard.net/deployment-strategies/configuration#core) Core --------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#secrets-configuration) Secrets configuration Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens. circle-info You can generate random strings for secrets with e.g.: `openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64` * `DEFGUARD_AUTH_SECRET`: JWT secret key for encrypting user tokens, default: `DEFGUARD_AUTH_SECRET` * `DEFGUARD_SECRET_KEY`: JWT secret key for encrypting private cookies; must be at least 64 characters long * `DEFGUARD_GATEWAY_SECRET`: JWT secret key for encrypting Gateway tokens, default: `DEFGUARD_GATEWAY_SECRET` * `DEFGUARD_YUBIBRIDGE_SECRET`: JWT secret key for encrypting YubiBridge tokens, default: `DEFGUARD_YUBIBRIDGE_SECRET` * `DEFGUARD_OPENID_KEY`: this is optional if you want to use [HMACarrow-up-right](https://en.wikipedia.org/wiki/HMAC) algorithm for OIDC token validation, if you want to use [RSAarrow-up-right](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) please provide a path to a private key file used for OAuth2/OpenID, [more herearrow-up-right](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) . ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#general-configuration) General configuration * `DEFGUARD_URL`: URL of your server instance, default `http://localhost:8000. This is the address at which the Web UI you use to administer your instance and the REST API endpoints are available (both of those are served by Defguard core on port 8000 by default; port can be configured with DEFGUARD_HTTP_PORT env variable).`This URL is needed to be exact since it's needed for OpenID discovery endpoint to work correctly, so if you have a reverse-proxy, custom domain, please provide an actual URL for Defguard core. * `DEFGUARD_GATEWAY_DISCONNECTION_NOTIFICATION_TIMEOUT`: If gateway is disconnected for this long, send email notification, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_WEBAUTHN_RP_ID` (optional): Relying party ID and relying party origin for WebAuthn used for MFA. By default, it's generated by using a base domain of `DEFGUARD_URL` (for example https://defguard.example.com is converted to defguard.example.com). circle-exclamation `DEFGUARD_WEBAUTHN_RP_ID`must be an effective domain of DEFGUARD\_URL (for example if hosting at `https://idm.example.com`, rp\_id must be `idm.example.com`, `example.com` or `com`). Changing `DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing Webauthn credentials.` * `DEFGUARD_ADMIN_GROUPNAME`: Name of the administrator group, default: `admin` * `DEFGUARD_USERADMIN_GROUPNAME`: Name of the user administrator group, default: `useradmin` * `DEFGUARD_VPN_GROUPNAME`: Name of the vpn group, default: `vpn` * `DEFGUARD_DEFAULT_ADMIN_PASSWORD`: Password for the default `admin` user, default: `pass123` * `DEFGUARD_LOG_LEVEL`: [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_PORT`: Core server port, default: `8000` * `DEFGUARD_LOG_FILE`: Log file path * `DEFGUARD_AUTH_COOKIE_TIMEOUT`: Cookie lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_MFA_CODE_TIMEOUT`: Email code lifetime period, default: `60s` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_SESSION_TIMEOUT`: Session lifetime period, default: `7d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#database-configuration) Database configuration Following env variables can be used to setup your database access: * `DEFGUARD_DB_HOST` * `DEFGUARD_DB_PORT` * `DEFGUARD_DB_NAME` * `DEFGUARD_DB_USER` * `DEFGUARD_DB_PASSWORD` ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#auth-cookies-configuration) Auth cookies configuration circle-exclamation If you want to access your Defguard instance without TLS (using an `http://` URL) you MUST enable insecure cookies by setting `DEFGUARD_COOKIE_INSECURE` to `true`. This is of course not recommended in production but can be useful when testing without a full reverse proxy setup. * `DEFGUARD_COOKIE_INSECURE`: set cookies without the `Secure` flag; use only in dev environments when serving Defguard without HTTPS * `DEFGUARD_COOKIE_DOMAIN` (optional): set the domain for auth cookies. By default, it's the domain from `DEFGUARD_URL`. Must be changed to base URL if you want to use [forward auth](https://docs.defguard.net/features/forward-auth) . ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#stats-cleanup-configuration) Stats cleanup configuration * `DEFGUARD_DISABLE_STATS_PURGE`: disable periodic cleanup of old Wireguard stats * `DEFGUARD_STATS_PURGE_FREQUENCY`: how often should the cleanup process be performed, default `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_STATS_PURGE_THRESHOLD`: age threshold for stats removal, default `30d` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#enrollment-configuration) Enrollment configuration * `DEFGUARD_ENROLLMENT_URL`: external URL of the enrollment proxy server, default `http://localhost:8080` - this URL is sent in enrollment emails as well as displayed when configuring the desktop client - thus must be to the actual URL you have configured the proxy Web UI to be accessible at, otherwise the enrollment or desktop client configuration will not work. * `DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT`: how long is the enrollment token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_ENROLLMENT_SESSION_TIMEOUT`: how long in the enrollment session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#password-reset-configuration) Password reset configuration * `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT`: how long is the password reset token valid for use, default: `24h` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) * `DEFGUARD_PASSWORD_RESET_SESSION_TIMEOUT`: how long in the password reset session valid after a user uses the token to start the enrollment process, default: `10m` ([Humantime documentationarrow-up-right](https://docs.rs/humantime/latest/humantime/struct.Duration.html) ) ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) gRPC server configuration [More on that in this help page.](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_GRPC_PORT`: the port on which the gRPC server should listen, default is `50055`. This port is used by Defguard Gateways to connect to your Core instance. * `DEFGUARD_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_GRPC_KEY`(optional): path to TLS key file * `DEFGUARD_GRPC_URL`: external URL of your instance's gRPC server, default `http://localhost:50055`; used for generating example VPN gateway startup command in Web UI ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#proxy-connection-configuration) Proxy connection configuration * `DEFGUARD_PROXY_URL` (optional): proxy service gRPC endpoint URL * `DEFGUARD_PROXY_GRPC_CA`(optional): path to TLS root certificate file, required if connecting to proxy gRPC service with a custom CA ([More on that in this help page.](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) ) [hashtag](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) Proxy service --------------------------------------------------------------------------------------------------------- Here are proxy ENV variables. gRPC configuration is described more [on this help page.](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_HTTP_PORT`: port the proxy API server and Web UI will listen on, default `8080` * `DEFGUARD_PROXY_GRPC_PORT`: port the gRPCS server will listen on, default `50051` * `DEFGUARD_PROXY_GRPC_CERT` (optional): path to TLS certificate file * `DEFGUARD_PROXY_GRPC_KEY`(optional): path to TLS key file. [More on that in this help page.](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_PROXY_URL` - if you wish to use External OIDC enrollment/desktop client configuration, please set this value to the same as `DEFGUARD_ENROLLMENT_URL` in core. This is the address at which the proxy Web UI is available. * `DEFGUARD_PROXY_LOG_LEVEL` : [Loggerarrow-up-right](https://crates.io/crates/log) log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_HTTP_BIND_ADDRESS`: The IP address that the HTTP should bind to * `DEFGUARD_GRPC_BIND_ADDRESS`: The IP address that the gRPC should bind to * `DEFGUARD_PROXY_RATELIMIT_PERSECOND` - The (average) number of requests per second made without being eventually rate limited * `DEFGUARD_PROXY_RATELIMIT_BURST` - The number of requests allowed to be made in a short amount of time before being rate limited [hashtag](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) Gateway Configuration ------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#environmental-variables-arguments) Environmental variables / Arguments If you're using docker image you can pass this value as environmental variables or on binary you can pass them as arguments * `DEFGUARD_GRPC_URL` , `-g ` - Defguard Core gRPC endpoint URL. This is used by the gateway to connect to your Defguard Core instance. If you configured the `DEFGUARD_GRPC_URL` variable on your Core instance before (as described in the [gRPC server configuration](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) section), use the same value here. Otherwise, provide an URL that will allow the Gateway to reach your Core instance, e.g. `http://localhost:50055` if both Core and Gateway are running on the same host. * `DEFGUARD_TOKEN` ,`-t ` - Token displayed in the Defguard Core web UI after completing the network wizard. It can be copied from the "Authentication Token" section on the Location Settings page. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-3ef48c4d258c0a8f2caf383a0fa94c8d5f3d8a01%252Fobraz.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=35f3217f&sv=2) * `DEFGUARD_USERSPACE` , `-u` - Use userspace wireguard implementation, useful on systems without native wireguard support * `DEFGUARD_GRPC_CA - path to ca file` more on this topic can be found [on this help page.](https://docs.defguard.net/deployment-strategies/grpc-ssl-communication) * `DEFGUARD_STATS_PERIOD` ,`-p ` - Defines how often (seconds) should interface statistics be sent to the Defguard server * `DEFGUARD_GATEWAY_NAME`, `--name ` - (optional) human-readable gateway name that will be displayed in Defguard webapp * `-s, --use-syslog` - enable logging to syslog * `RUST_LOG` : Logger log level, default: `info`, supported: `debug`, `warn`, `error` * `DEFGUARD_MASQUERADE` - controls whether the gateway automatically applies masquerade NAT firewall rule; defaults to `false` * `DEFGUARD_DISABLE_FW_MGMT` - disables all firewall management by the gateway; this overrides `DEFGUARD_MASQUERADE` setting; defaults to `false` circle-info `DEFGUARD_DISABLE_FW_MGMT` is meant as a workaround for running in incompatible environments, where our [default firewall integration](https://docs.defguard.net/features/access-control-list/firewall-internals) is not supported. As a consequence, enabling this option disables [ACL functionality](https://docs.defguard.net/features/access-control-list) on a given gateway. * `DEFGUARD_IFNAME` - The network interface that will be created and used for the VPN traffic * `DEFGUARD_FW_PRIORITY` - The NFT forward chain priority, which handles traffic filtering when ACLs are configured. Defaults to 0. Useful if the Defguard's forward chain conflicts with other chains. * `HEALTH_PORT` - (optional) If a port number is provided an [HTTP healthcheck server](https://docs.defguard.net/deployment-strategies/health-check#gateway) will be started * `DEFGUARD_HTTP_BIND_ADDRESS` - (optional) the IP address that the HTTP healthcheck server should bind to #### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#executing-custom-commands-on-vpn-up-down) Executing custom commands on VPN up/down The following env variables or gateway arguments define which commands gateway will run before / after it will bring up / down the VPN. It's usefull for example to use those commands to launch custom firewall commands or scripts that do various operations needed to be done on those occasions. triangle-exclamation Defguard is built with highest security standards in mind, thus the options below **accept only a full path to one command and it's arguments.** If you would like to have **multiple commands run,** you can create a shell script which will define the acceptable and preferred shell you would like to use and then all the commands you like to execute. `PRE_UP` , `--pre-up`, - Command to run before bringing up the interface. If you want to run a shell script, you should pass its path to your shell, for example: `/bin/sh -c /path/to/script` `POST_UP` , `--post-up`, - Command to run after bringing up the interface. `PRE_DOWN` , `--pre-down`, - Command to run before bringing down the interface. `POST_DOWN` , `--post-down`, - Command to run after bringing down the interface. circle-info If logging to syslog please remember to configure your syslog daemon accordingly, so that a dedicated logfile is created or the messages are included in the main system log. ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#config-file) Config file Gateway configuration can also be read from a file by using a `--config` CLI option. Example file contents: [hashtag](https://docs.defguard.net/deployment-strategies/configuration#yubibridge-configuration) YubiBridge configuration ------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#environmental-variables) Environmental variables * `LOG_LEVEL`: Log messages level, default: `INFO`, available levels: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` * `WORKER_ID`: Name of your YubiBridge displayed on Defguard website, default: `YubiBridge` * `DEFGUARD_TOKEN`: - Secret worker token to secure gRPC communication, available on provisioners page * `SMARTCARD_RETRIES`: Number of retries in case provisioning failed, default: `1` * `JOB_INTERVAL`: Defines how often(seconds) YubiBridge checks Defguard for new jobs, default: `2` * `SMARTCARD_RETRY_INTERVAL`: Defines the number of seconds between trying to provision YubiKey again, default `15` ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#cli-arguments) CLI arguments: * `-h` , `--help`: Display help message * `-g `, `--grpc `: Connect to gRPC server at the given URL * `-i ` , `--id `: WorkerID, default `YubiBridge` * `-d` , `--debug`: Enable debug mode * `-t ` , `--tmpdir `: GnuPG home directory, default: `tmp` * `-p ` , `--provision `: Provision YubiKey with the following data * `-w ` , `--worker-token `: Secret worker token to secure gRPC communication, available on provisioners page * `-c ` , `--command `: Run command after provisioning and pass created keys as arguments ### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#troubleshooting-the-configuration) Troubleshooting the configuration Common configuration issues. #### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#gateway) Gateway `Error: Syslog(Initialization(Io(Os { code: 111, kind: ConnectionRefused, message: "Connection refused" })))` The selected syslog socket may be wrong. See the `syslog_socket` configuration option for the gateway: [Config file](https://docs.defguard.net/deployment-strategies/configuration#config-file) . Set it to a correct syslog socket on your operating system. The default socket is valid for FreeBSD. #### [hashtag](https://docs.defguard.net/deployment-strategies/configuration#core-1) Core `Cookie “defguard_session” has been rejected for invalid domain.` (browser console error) This issue most often takes the form of not being able to login without any obvious cause. The login button doesn't redirect and no relevant error message is displayed in the Defguard Core logs. In this case we recommend checking the browser logs (usually right click > inspect should open the developer tools along with the browser console). If you can see the above error, this means that your `DEFGUARD_URL` configuration option doesn't match the URL you use to access the dashboard at the moment. For example, if your login screen is at `http://my.domain.com:8000/auth/login` set `DEFGUARD_URL` to `` http://my.domain.com:8000` `` . [PreviousAdding a location and getting a Gateway tokenchevron-left](https://docs.defguard.net/deployment-strategies/gateway) [NextRunning Gateway on OPNsense firewallchevron-right](https://docs.defguard.net/deployment-strategies/running-gateway-on-opnsense-firewall) Last updated 1 month ago * [Core](https://docs.defguard.net/deployment-strategies/configuration#core) * [Secrets configuration](https://docs.defguard.net/deployment-strategies/configuration#secrets-configuration) * [General configuration](https://docs.defguard.net/deployment-strategies/configuration#general-configuration) * [Database configuration](https://docs.defguard.net/deployment-strategies/configuration#database-configuration) * [Auth cookies configuration](https://docs.defguard.net/deployment-strategies/configuration#auth-cookies-configuration) * [Stats cleanup configuration](https://docs.defguard.net/deployment-strategies/configuration#stats-cleanup-configuration) * [Enrollment configuration](https://docs.defguard.net/deployment-strategies/configuration#enrollment-configuration) * [Password reset configuration](https://docs.defguard.net/deployment-strategies/configuration#password-reset-configuration) * [gRPC server configuration](https://docs.defguard.net/deployment-strategies/configuration#grpc-server-configuration) * [Proxy connection configuration](https://docs.defguard.net/deployment-strategies/configuration#proxy-connection-configuration) * [Proxy service](https://docs.defguard.net/deployment-strategies/configuration#proxy-service) * [Gateway Configuration](https://docs.defguard.net/deployment-strategies/configuration#gateway-configuration) * [Environmental variables / Arguments](https://docs.defguard.net/deployment-strategies/configuration#environmental-variables-arguments) * [Config file](https://docs.defguard.net/deployment-strategies/configuration#config-file) * [YubiBridge configuration](https://docs.defguard.net/deployment-strategies/configuration#yubibridge-configuration) * [Environmental variables](https://docs.defguard.net/deployment-strategies/configuration#environmental-variables) * [CLI arguments:](https://docs.defguard.net/deployment-strategies/configuration#cli-arguments) * [Troubleshooting the configuration](https://docs.defguard.net/deployment-strategies/configuration#troubleshooting-the-configuration) sun-brightdesktopmoon Copy # 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 = "" # Required: Defguard server gRPC endpoint URL # NOTE: must replace default with actual value grpc_url = "" # Optional: gateway name which will be displayed in Defguard web UI name = "Gateway on server X" # Required: use userspace Wireguard implementation (e.g. wireguard-go) userspace = false # Optional: path to TLS cert file - more in gRPC SSL communication help page # in our documentation. # 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 #pre_up = "/path/to/script.sh" # Optional: Command which will be run after bringing interface up #post_up = "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 = "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 = "ip route del default via 192.168.1.1 dev wg0" sun-brightdesktopmoon --- # Terraform | defguard circle-info Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later. circle-info We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/issues) . [hashtag](https://docs.defguard.net/deployment-strategies/terraform#aws) AWS --------------------------------------------------------------------------------- To deploy Defguard using Terraform on AWS, you can use the Terraform configuration provided in the [Defguard deployment repositoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main) . The terraform configuration includes the necessary resources to setup all components of Defguard. We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture pagearrow-up-right](https://docs.defguard.net/in-depth/architecture) . When configuring the networking, the most important thing is to keep in mind the following rules: * Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection. * Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. * Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN. * All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway. ### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#using-the-modules) Using the Modules To use the provided Terraform modules in your terraform configuration, you can use the following source: Copy module "" { source = "github.com/DefGuard/deployment//terraform/modules/?ref=" # Rest of the module configuration goes here # ... } Where: * `` is the name you want to give to the module in your configuration. * `` is one of `core`, `proxy`, or `gateway`, depending on which module you want to use. * `` is the commit hash, tag or branch name of the Defguard deployment repository. You can use the `main` branch for the latest stable version. ### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#configuring-modules) Configuring modules There are three Defguard modules available for deployment: `core`, `proxy` and `gateway`. The modules can be found in the modules [directoryarrow-up-right](https://github.com/DefGuard/deployment/tree/main/terraform/modules) in the Defguard deployment repository. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#common-configuration-options-for-all-modules) Common configuration options for all modules All components have common configuration options that may be configured in their respective blocks in the `main.tf` file: * `instance_type`: The instance type to use. The default is `t3.micro`. You can adjust this based on your performance needs. * `ami`: The base AMI to use for the Defguard instance. We recommend using the Ubuntu Server 24.04 LTS (64-bit) AMI, which is the default in the example configurations. You may change this to a different AMI if needed. Your AMI must meet the requirements defined in [AMI requirements](https://docs.defguard.net/deployment-strategies/terraform#ami-requirements) . * `package_version`: The version of the Defguard component package to be installed. This must be an existing Defguard debian package released on the Defguard releases page (e.g. Defguard Core packages are available [herearrow-up-right](https://github.com/DefGuard/defguard/releases) ). Example: `1.4.0`, `1.3.2-alpha2`. * `arch`: The architecture of the Defguard Core package to be installed. This can be set to `x86_64` or `aarch64`. The default is `x86_64`. * `log_level`: The log level to use for the Defguard component. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. The default is `info`. Note that setting the log level to `debug` will produce a lot of logs, which may be useful for debugging, but may also fill up your disk space quickly. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#core-module) Core module The core module is responsible for setting up Defguard Core. It accepts the following variables: * `core_url`: The URL at which Defguard web UI will be accessible. * `grpc_port`: The gRPC port for Defguard Core to communicate with gateways. * `http_port`: The HTTP port on which the Defguard Core web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. * `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments. * `default_admin_password`: The default password for the admin user. This should be changed after the first login. * `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module. * `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](https://docs.defguard.net/deployment-strategies/terraform#vpn-networks-configuration) section for more details on how to configure the VPN networks. * `db_details`: A map containing the database configuration. It must contain the following: * `name`: The name of the PostgreSQL database to be created for Defguard. * `username`: The username for the PostgreSQL database. * `password`: The password for the PostgreSQL database user. * `port`: The port on which the PostgreSQL database will listen. * `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. * `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#proxy-module) Proxy module The proxy module is responsible for setting up the Defguard Proxy. It accepts the following variables: * `url`: The URL at which Defguard Proxy will be accessible. * `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication. * `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#gateway-module) Gateway module The gateway module is responsible for setting up the Defguard VPN gateways. It accepts the following variables: * `core_grpc_port`: The gRPC port of Defguard Core for the internal communication. This must match the `grpc_port` variable in the core module. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core. * `network_id`: The ID of the VPN network. This must match the `id` field in the `vpn_networks` variable in the core module. * `core_address`: The IP address of the Defguard Core instance. This should be core's private address, as it will be used for internal communication between the gateway and core components. See the `basic` example for the configuration of this variable. * `gateway_secret`: The secret used to authenticate the gateway with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the core module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Gateway instance. This is used to ensure that the gateway instance has a private IP address in the same VPC as the core and proxy components. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#vpn-networks-configuration) VPN networks configuration * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. Each network is defined as a map with the following keys: * `id`: The id of the network. Must start with 1 and increment for each new network. This is used to identify the network in the database and allows for applying modifications to the network configuration later. * `name`: The name of the VPN network. This will be used to identify the network in the Defguard web UI and displayed to the users. * `address`: The internal address of the VPN network in the form of `x.x.x.x/x`. This is the address that will be assigned to the VPN clients when they connect to the VPN. It must be a valid CIDR notation. * `port`: The port on which the VPN gateway will listen for incoming VPN connections. Default is `50051`, which is the standard port for WireGuard VPN. You may change this to a different port if needed. * `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows: * VPN clients to access the internet through the gateway. * VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#ami-requirements) AMI requirements If you wish to use a different AMI for the Defguard components, it must meet the following requirements: * Must allow for running systemd services. * Must use the APT package manager. If you are not meeting these requirements, you will need to modify the corresponding `setup.sh` scripts, which are responsible for installing and configuring the Defguard components. The scripts can be found in `terraform/modules//setup.sh`, where `` is one of `core`, `gateway`, or `proxy`. ### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#examples) Examples The example configurations can be downloaded from the Defguard deployment repository. They are located in the `terraform/examples` directory: (https://github.com/DefGuard/deployment/tree/main/terraform)\[https://github.com/DefGuard/deployment/tree/main/terraform\] If you wish, you can also clone the whole repository using the following command: And then navigate to the `terraform/examples` directory to find the example configurations. To use any of the examples, you can copy or download the `main.tf.example` file and rename it to `main.tf`. Note that the file contains both the module definitions, variables and outputs. This is to make it easier to download the example. You can also split the file into separate files, such as `main.tf`, `variables.tf`, and `outputs.tf`, if you prefer to keep the configuration more organized. To run the examples, use the following commands: or if using OpenTofu: After running these commands, Terraform will create the necessary resources in your AWS account and deploy Defguard. The output will include the public and private addresses for Core, Proxy and gateway components: Note that running the examples will put some sensitive details into your `.tfstate` file, most notably: the database password, gateway secret and the initial admin password. Those details are not ephemeral in the terraform configuration as they must be passed to the Defguard components during their setup. If you want to secure those details, we recommend following the official guidelines on [how to secure your Terraform state filearrow-up-right](https://developer.hashicorp.com/terraform/language/state/sensitive-data) . #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#basic) `basic` The `basic` example can be directly downloaded using the following link: [basic/main.tf.examplearrow-up-right](https://raw.githubusercontent.com/DefGuard/deployment/refs/heads/main/terraform/examples/basic/main.tf.example) . The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following: * Defguard Core instance * Defguard Proxy instance * Defguard Gateway instance * A database instance (RDS) for Defguard Core. * A single VPC for all components. You can use this example as a starting point for your own deployment. To modify the network configuration, edit one of the sections in the `main.tf` file, such as "Core network configuration", "Gateway network configuration", or "Proxy network configuration". For example, to allow SSH access to Defguard Core instance, you can uncomment the following block in the "Core network configuration" section: Note that this will grant SSH access from any IP address, you may want to restrict it further by editing the `cidr_blocks` field. By default, the configuration allows access to Defguard Core web UI only from connected VPN clients, which is the recommended approach: If you want to run Core web UI behind a reverse proxy (e.g. to enable HTTPS), you would need to do the following: 1. Prevent direct access to the services by removing their ingress rules: 1. Add a second public subnet (load balancers require it): 1. Add the load balancer configuration 1. Add load balancer ingress rules to your existing Proxy and Core groups: 1. Finally, you can add the load balancer domain name to the output: This setup will create two load balancers: one internal and one external. Both will act as a reverse proxy, routing the HTTPS traffic matching your domains to the backend servers (Proxy, Core). The next step would be to point your actual domains to the domain names generated by the load balancers in the output (CNAME) and to setup SSL certificates (e.g. via the AWS certificate manager). ### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#troubleshooting-and-common-issues) Troubleshooting and common issues All components are deployed as systemd services on the host EC2. Their configuration files can be found at `/etc/defguard`. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#checking-status-of-any-component) Checking status of any component You can check the status of any Defguard component by SSHing into the corresponding EC2 instance and running the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the status of the service. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#checking-logs-of-any-component) Checking logs of any component To display the logs of the service, SSH into the corresponding EC2 instance and run the following command: Where `` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the logs of the service. #### [hashtag](https://docs.defguard.net/deployment-strategies/terraform#checking-setup-logs) Checking setup logs Before any of the components becomes available, a `setup.sh` script is run, which performs its initial setup (package download, configuration). The logs of this script are stored in `/var/log/defguard.log` on a corresponding EC2 instance. You can check this log file to see if there were any issues during the setup. [PreviousKuberneteschevron-left](https://docs.defguard.net/deployment-strategies/kubernetes) [NextAmazon Machine Image (AMI)chevron-right](https://docs.defguard.net/deployment-strategies/amis-and-aws-cloudformation) * [AWS](https://docs.defguard.net/deployment-strategies/terraform#aws) * [Using the Modules](https://docs.defguard.net/deployment-strategies/terraform#using-the-modules) * [Configuring modules](https://docs.defguard.net/deployment-strategies/terraform#configuring-modules) * [Examples](https://docs.defguard.net/deployment-strategies/terraform#examples) * [Troubleshooting and common issues](https://docs.defguard.net/deployment-strategies/terraform#troubleshooting-and-common-issues) sun-brightdesktopmoon Copy git clone https://github.com/DefGuard/deployment.git Copy cd deployment/terraform Copy # To initialize all the modules and providers, run: terraform init # To preview the changes that will be made, run: terraform plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: terraform apply -var="aws_access_key=" -var="aws_secret_key=" Copy # To initialize all the modules and providers, run: tofu init # To preview the changes that will be made, run: tofu plan -var="aws_access_key=" -var="aws_secret_key=" # To apply the changes, run: tofu apply -var="aws_access_key=" -var="aws_secret_key=" Copy Apply complete! Resources: 35 added, 0 changed, 0 destroyed. Outputs: defguard_core_private_address = "10.0.1.x" defguard_core_public_address = "x.x.x.x" defguard_proxy_private_address = "10.0.1.x" defguard_proxy_public_address = "x.x.x.x" defguard_gateway_private_addresses = [\ "10.0.1.226",\ ] defguard_gateway_public_addresses = [\ "x.x.x.x",\ ] Copy ingress { from_port = 22 to_port = 22 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Core security group block [...] ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" cidr_blocks = [\ for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"\ ] } Copy # This is in the Proxy security group block [...] ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } Copy vpc_public_subnets = ["10.0.1.0/24", "10.0.4.0/24"] Copy ########################################################################### ###################### Load Balancer Configuration ####################### ########################################################################### # Load balancer security groups resource "aws_security_group" "defguard_alb_sg" { name = "defguard-alb-sg" description = "Access to the Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] description = "HTTPS access from internet" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-alb-sg" } } resource "aws_security_group" "defguard_internal_alb_sg" { name = "defguard-internal-alb-sg" description = "Access to the Internal Application Load Balancer" vpc_id = module.vpc.vpc_id ingress { from_port = 443 to_port = 443 protocol = "tcp" cidr_blocks = [local.vpc_cidr] description = "HTTPS access from internal VPC network" } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = { Name = "defguard-internal-alb-sg" } } # Public Application Load Balancer resource "aws_lb" "defguard_public_alb" { name = "defguard-public-alb" internal = false load_balancer_type = "application" security_groups = [aws_security_group.defguard_alb_sg.id] subnets = module.vpc.public_subnets enable_deletion_protection = false tags = { Name = "defguard-public-alb" } } # Internal Application Load Balancer resource "aws_lb" "defguard_internal_alb" { name = "defguard-internal-alb" internal = true load_balancer_type = "application" security_groups = [aws_security_group.defguard_internal_alb_sg.id] subnets = module.vpc.private_subnets enable_deletion_protection = false tags = { Name = "defguard-internal-alb" } } # Target Groups resource "aws_lb_target_group" "defguard_core_tg" { name = "defguard-core-tg" port = local.core_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-core-tg" } } resource "aws_lb_target_group" "defguard_proxy_tg" { name = "defguard-proxy-tg" port = local.proxy_http_port protocol = "HTTP" vpc_id = module.vpc.vpc_id health_check { enabled = true healthy_threshold = 2 interval = 30 matcher = "200" path = "/api/v1/health" port = "traffic-port" protocol = "HTTP" timeout = 5 unhealthy_threshold = 3 } tags = { Name = "defguard-proxy-tg" } } # Target Group Attachments resource "aws_lb_target_group_attachment" "defguard_core_attachment" { target_group_arn = aws_lb_target_group.defguard_core_tg.arn target_id = module.defguard_core.instance_id port = local.core_http_port } resource "aws_lb_target_group_attachment" "defguard_proxy_attachment" { target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn target_id = module.defguard_proxy.instance_id port = local.proxy_http_port } # Listeners resource "aws_lb_listener" "defguard_public_alb_listener" { load_balancer_arn = aws_lb.defguard_public_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } } resource "aws_lb_listener" "defguard_internal_alb_listener" { load_balancer_arn = aws_lb.defguard_internal_alb.arn port = "443" protocol = "HTTPS" default_action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } } # Listener Rules resource "aws_lb_listener_rule" "defguard_proxy_rule" { listener_arn = aws_lb_listener.defguard_public_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_proxy_tg.arn } condition { host_header { values = [replace(local.proxy_url, "https://", "")] } } } resource "aws_lb_listener_rule" "defguard_core_rule" { listener_arn = aws_lb_listener.defguard_internal_alb_listener.arn priority = 100 action { type = "forward" target_group_arn = aws_lb_target_group.defguard_core_tg.arn } condition { host_header { values = [replace(local.core_url, "https://", "")] } } } Copy # HTTP access from internal load balancer (Core) ingress { from_port = local.core_http_port to_port = local.core_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_internal_alb_sg.id] description = "HTTP access from internal load balancer" } # HTTP access from public load balancer (Proxy) ingress { from_port = local.proxy_http_port to_port = local.proxy_http_port protocol = "tcp" security_groups = [aws_security_group.defguard_alb_sg.id] description = "HTTP access from public load balancer" } Copy output "defguard_public_alb_dns" { description = "The DNS name of the Public Application Load Balancer" value = aws_lb.defguard_public_alb.dns_name } output "defguard_internal_alb_dns" { description = "The DNS name of the Internal Application Load Balancer" value = aws_lb.defguard_internal_alb.dns_name } Copy sudo systemctl status Copy sudo journalctl -u sun-brightdesktopmoon --- # Production deployment verification guide | defguard This guide helps you verify that your Defguard instance is operational, reachable through the expected network paths, and properly secured. The process will consist of the following steps: 1. Verifying the configuration of your firewall rules. 2. Verifying your DNS resolution. 3. Testing the whole configuration. [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------------------------------ Before proceeding, ensure that you deployed your Defguard environment according to the [recommendations](https://docs.defguard.net/deployment-strategies/hardware-os-network-and-firewall-recommendations) and that the following components are operational: * 1 server running Defguard Core * Located in an internal network segment (not exposed to the Internet) * Reachable internally under a domain such as defguard.example.com * 1 server running Defguard Proxy * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as proxy.example.com * 1 server running Defguard Gateway * Located in a DMZ network segment * Publicly accessible from the Internet under a domain such as vpn.example.com * A workstation with the Defguard Desktop Client installed and configured to test VPN connectivity. [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) Verify firewall policies ---------------------------------------------------------------------------------------------------------------------------------------------------------- Confirm that your firewall rules align with Defguard’s secure deployment model. Component Allowed inbound Blocked inbound Notes Core * TCP 443 (from internal/VPN only) * gRPC server port (from Gateway) All public traffic Core should never be directly exposed to the Internet. Proxy * TCP 443 (from public Internet) * gRPC server port (from Core) All other inbound traffic Used for enrollment and client configuration. Gateway * UDP VPN port (from public Internet) All other inbound traffic Only VPN and Core communication should be allowed. [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) Verify DNS resolution ---------------------------------------------------------------------------------------------------------------------------------------------------- Proper DNS configuration ensures that each Defguard component resolves to the correct IP address and network zone. Run: Expected results: Domain Expected IP Type Description vpn.example.com Public IP Gateway server reachable from the Internet proxy.example.com Public IP Proxy server for enrollment and configuration defguard.example.com Private/Internal IP Core server, accessible only from internal/VPN network [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-the-environment) Test the environment -------------------------------------------------------------------------------------------------------------------------------------------------- After you've confirmed the proper network segmentation it's time to test it. ### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) Testing while disconnected from the VPN Perform the following tests from the workstation where the Defguard Desktop Client is installed. Make sure the client is disconnected before running any commands. In this state: * ❌ You should not be able to reach the Defguard Core server. * ✅ You should be able to reach the Defguard Proxy server. * ✅ You should be able to reach the Defguard Gateway server (UDP port for VPN). #### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports) Test: Defguard Core server reachability and ports Check the open ports on your Defguard Core server (replace the example domain with your actual one): Expected output: Interpretation: * The Core server is not reachable when disconnected from the VPN, which is the expected and secure configuration. #### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-defguard-proxy-server-reachability-and-ports) Test: Defguard Proxy Server Reachability and Ports Check the open ports on your Defguard Proxy server: Expected output: Interpretation: * The host is reachable from the Internet. * Only port 443/tcp is open, as expected for HTTPS access. #### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-defguard-gateway-server-reachability) Test: Defguard Gateway Server Reachability Check if the Defguard Gateway server is reachable: Expected output: Interpretation: * The host is reachable. * The list of open TCP ports should be empty, as the Gateway primarily uses UDP for VPN connections. * You’ll verify the UDP port functionality in the next step by testing an actual VPN connection. ### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) Connecting to the VPN 1. Open the Defguard Desktop Client. 2. Connect to your configured location. #### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-verify-vpn-connectivity) Test: Verify VPN Connectivity Once connected: 1. Open your browser and navigate to the Defguard Core interface, for example: https://defguard.example.com 2. Sign in using an administrator account. If you can access the web panel, your VPN connection is active and functioning. Then, in the Core UI: * Go to VPN Overview page. You should see your connected device listed there. ![](https://docs.defguard.net/~gitbook/image?url=https%3A%2F%2F3466771104-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fe86iamwJVSYnIRsyVEAV%252Fuploads%252Fgit-blob-cc49efc45d9b1b34097b2698c5a30312a061601c%252FScreenshot%25202025-10-24%2520at%252011.20.24.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=1846f70f&sv=2) ### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) Testing While Connected to the VPN Perform the following tests again while the Defguard client remains connected. In this state: * ✅ You should be additionally able to reach the Defguard Core server. #### [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-defguard-core-server-reachability-and-ports-1) Test: Defguard Core Server Reachability and Ports Check the open ports on your Defguard Core server: Expected output: Interpretation: * The host is reachable via the VPN tunnel. * Port 443/tcp (HTTPS web interface) is open, which confirms proper VPN routing and Core access. [hashtag](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#summary) Summary ------------------------------------------------------------------------------------------------------------------------ ✅ Firewall policies restrict traffic to approved ports. ✅ DNS records resolve to the expected internal and public addresses. ✅ Core is unreachable from the Internet and reachable only via VPN. ✅ Proxy is publicly reachable only on port 443. ✅ Gateway responds correctly and allows VPN connections. When all verifications and tests pass, your Defguard deployment is operational, properly segmented, and production-ready. [PreviousHealth checkchevron-left](https://docs.defguard.net/deployment-strategies/health-check) [NextLinux Kernel WireGuard tuningchevron-right](https://docs.defguard.net/deployment-strategies/linux-kernel-wireguard-tuning) Last updated 3 months ago * [Prerequisites](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#prerequisites) * [Verify firewall policies](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#verify-firewall-policies) * [Verify DNS resolution](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#verify-dns-resolution) * [Test the environment](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#test-the-environment) * [Testing while disconnected from the VPN](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#testing-while-disconnected-from-the-vpn) * [Connecting to the VPN](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#connecting-to-the-vpn) * [Testing While Connected to the VPN](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#testing-while-connected-to-the-vpn) * [Summary](https://docs.defguard.net/deployment-strategies/production-deployment-verification-guide#summary) sun-brightdesktopmoon Copy dig +short vpn.example.com dig +short proxy.example.com dig +short defguard.example.com Copy sudo nmap -Pn -sS defguard.example.com Copy Failed to resolve "defguard.example.com". Copy sudo nmap -Pn -sS proxy.example.com Copy Host is up (0.0082s latency). PORT STATE SERVICE 443/tcp open https Copy sudo nmap -Pn -sS vpn.example.com Copy Host is up (0.0082s latency). Copy sudo nmap -Pn -sS defguard.example.com Copy Host is up (0.021s latency). PORT STATE SERVICE 443/tcp open https sun-brightdesktopmoon ---