Last modified on September 12, 2023
This article describes how to set a maintenance window for gateways and relays. Scheduling a maintenance window allows you to have some control over the hour of the day when gateway and relay upgrades happen. If a custom maintenance window is not specified, the default window of 7:00 Coordinated Universal Time (UTC) daily applies.
All gateways and relays have a maintenance window and follow a standard process for upgrades:
- When a gateway or relay is notified of a new version and it has no client connections, it updates itself immediately unless a custom schedule using cron notation has been set.
- If a gateway or relay does have client connections, however, it enters the state “Awaiting Restart” and updates as soon as client connections drop to zero. If that doesn’t happen before the maintenance window is reached, the gateway or relay terminates all connections, updates, and restarts with the new version. The default maintenance window is 7:00 UTC.
How to Schedule Maintenance Windows
There are several ways to schedule maintenance windows. You can configure simple daily maintenance windows using an environment variable or in the YAML configuration for a container. You can also use options when starting a gateway or relay via the CLI to set either a simple daily maintenance window, or a schedule(s) of cron-based weekly maintenance window(s).
The method you choose depends on your setup and what is easiest for you:
- Configure weekly schedules remotely using the
- Configure a daily window with the CLI using the
- Configure a daily window with an environment variable for standard Linux installations.
- Configure a daily window for containers with YAML to deploy your gateway with a container.
Configure weekly schedules remotely
You may use cron notation to configure routine gateway or relay update window(s) to take place on a weekly basis. These schedules must be semicolon-separated. The first group listed will indicate the time window in which the gateway or relay will cut off connections, restart, and update, no matter the load on the gateway or relay. The other schedules listed will be windows in which the gateway or relay will restart and update if it is currently serving no traffic and updates are available.
This command may be run remotely at the CLI using the ID of the gateway or relay in question, and when the gateway or relay updates, it will use the set schedule(s).
Because gateways and relays are required to have at least one maintenance window available each week, the values for the
day_of_month fields in the cron-formatted schedule will be rejected if not set to
*. The notation should be in the following format:
sdm admin relays update --maintenance-windows="<YOUR_CRON_SCHEDULE>;<SECONDARY_CRON_SCHEDULES>" <YOUR_GATEWAY_ID>
sdm admin relays update --maintenance-windows="* 7 * * 0,6;* * * * *" n-56988fae64a73652
In this example (according to the first cron schedule) the gateway or relay will forcibly restart and update (if updates are available) at 7:00 on Saturdays and Sundays. Optionally (according to the second schedule) if there are updates available any hour of any day of the week when the gateway or relay is not under load, it will restart and update.
Configure a daily window with the CLI
To set an hour each day that the gateway or relay will be available to restart and update, you can use the
--maintenance-window-start option when starting or updating the gateway or relay. Replace
<VALUE> in the example with an integer representing the UTC hour (0-23) that you would like to set as your maintenance window:
sdm relay --maintenance-window-start <VALUE>
sdm relay --maintenance-window-start 15
In the example shown, the value is set to 15. If the gateway or relay is not under load when a new version releases, it restarts and updates. If it is under load when a new version releases, the maintenance window starts at 15:00 UTC. At that time, the gateway or relay starts terminating client connections, restarts, and updates.
Configure a daily window with an environment variable
If your gateway or relay is installed on a Linux host, we recommend that you use the environment variable method to set a maintenance window:
Install your gateway or relay using our default Linux gateway instructions. Doing so installs a systemd .service unit file and an environment file.
Open the environment file for editing. The default location is
Add a new line with the
SDM_MAINTENANCE_WINDOW_STARTvariable, formatted as an integer, representing the UTC hour (0-23) that you would like to set as your maintenance window:
SDM_RELAY_TOKEN value in the environment file.
Save the file.
Run the following to pick up the update:
Restart the gateway or relay service:
systemctl restart sdm-proxy.service
Configure a daily window for containers with YAML
If you are using YAML to deploy the StrongDM Gateway image in a container, you can set a maintenance window by using the
SDM_MAINTENANCE_WINDOW_START environment variable formatted as an integer representing the UTC hour (0-23) that you would like to set as your maintenance window:
- name: sdm-relay
In the example shown, the environment variable sets a maintenance window at 15 UTC.