Upgrading

Notes on upgrading Defguard and its components

Before doing any updates please remember to backup your database.

Any release -> 1.0.0

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.

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.

Desktop Client Real Time Sync

From 1.0.0 we have introduced Enterprise features, and one of them is automatic and real-time desktop client configuration synchronisation.

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 (token can be sent over email or shared in any other secret way).

  2. The user must perform the Instance Update - more details here.

Any client that is configured from scratch has this done automatically and no actions needed to be done.

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:

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.

    3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server can be reached from Core.

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

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:

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

  1. Core should be attempting to establish a gRPC connection with Proxy (and retrying every 10s if unable to successfully connect), like this:

defguard | 2024-01-24T14:17:47.815294Z  INFO defguard::grpc: Connecting to proxy

  1. After defguard connects successfully to proxy, you should see in proxy logs:

proxy_1  | 2024-01-24T14:17:47.819504Z  INFO defguard_proxy: RPC client connected from: 10.123.123.2:35916

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.

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

PreviousDeploying your instanceNextOne-line install script

Last updated