Configure relay behavior

  • Release version: Australia
  • Updated May 29, 2026
  • 2 minutes to read

    • Configure relay behavior by setting properties either in the config.yaml file or in the relay properties table on your instance.

    Before you begin

    • The Reverse Tunnel store app must be installed.
    • The private relay must be deployed and registered.

    Role required: sn_zc_tunnel.relay_manager

    About this task

    The private relay supports two configuration sources:

    config.yaml
    A configuration file shipped with the relay zip file and deployed in yout environment. Properties set in config.yaml take precedence over properties set on the instance. Modifying this file does not require a relay restart as changes are applied automatically. If issues occur, restarting the relay applies the changes immediately.

    Modify config.yaml only when you have a functional or business reason to do so.

    Relay properties table (ServiceNow instance)
    Properties configured in the relay properties table on your ServiceNow instance are retrieved dynamically during the relay configuration polling cycle. Changes are applied without restarting the relay. Use the relay properties table for most configuration changes to avoid relay restarts.
    Table 1. Relay properties
    Property Default Description
    reconnect-multiplier 2 Multiplier applied to the reconnect interval when the relay retries a connection to the gateway.
    reconnect-jitter 0.3 Jitter applied to the reconnect interval to prevent simultaneous reconnection attempts from multiple relays.
    config-poll-interval 30000 Interval in milliseconds at which the relay polls the instance for configuration updates.
    debug false When set to true, enables debug logging on the relay.
    reregistration-max-attempts 5 Number of retry attempts made when registering backend services with the gateway instance. If all attempts are exhausted, the gateway connection is closed.
    max-streams 10000 Maximum number of concurrent streams supported. When the cap is reached, new streams are rejected and traffic is distributed to another relay.
    stream-window-kb 256 Flow control window size in kilobytes for each stream. Controls the amount of data in flight per stream.
    cert-reissue-window 30 Number of days before certificate expiry at which the relay initiates certificate renewal. The relay generates a new certificate signing request and re-establishes the connection using the renewed certificate.
    http-request-timeout 30000 Timeout in milliseconds for HTTP requests made by the relay to the instance.
    reconnect-initial-delay 1000 Delay in milliseconds before the relay attempts to reconnect to the gateway.
    reconnect-max-delay 60000 Maximum delay in milliseconds between reconnection attempts.
    cert-monitor-interval 86400000 Interval in milliseconds between certificate expiration checks.

    Procedure

    1. Navigate to All > Private Relay > Relays.
    2. Open the relay record.
    3. In the Relay Properties related list, select New.
    4. Enter the property name and value.
      For example, to enable debug logging, you would set the property name to debug and the value to true.

      Invalid property values fall back to defaults, and a warning is logged. Configuration polling is not affected.

      For information on available properties, see [link-to-reference-topic].

    5. Select Submit.

    Result

    The new property value is applied during the next configuration polling cycle without requiring a restart.