Configuration

Loading the configuration

You can define which configuration format should be used through the command line.

For example, to run Gate with an env configuration, you should run Gate with the command:

GATE_PORT=8080 GATE_DEFAULT_TARGET=http://default-svc:8080 gate --env

If you want to load a .yaml file

gate --yaml configs/gate.yaml

Supported formats:

• Environment variables (--env flag)
• HCL (--hcl [file name] flag)
• JSON (--json [file name] flag)
• TOML (--toml [file name] flag)
• YAML (--yaml [file name] flag)

Help

To see available flags, please run the following command:

gate --help

Using multiple configuration formats

You can use multiple configuration formats for Gate. They will be loaded in the order in which you provided flags. For example:

gate --yaml configs/gate.yaml --toml configs/gate.toml --env

Gate will load configs/gate.yaml, then override YAML config with configuration present configs/gate.toml. Ultimately, Gate will override the configuration from the present environment variables.

Configuration merging logic

By default, all configuration options are overridden.

The only exception is URL Configuration - URLs are appended. Thanks to that, you can merge multiple sources of URLs. A good example is a different configuration for different environments.

gate --yaml configs/gate.yaml --yaml configs/gate.yaml --env

info

If you need to debug your configuration, you can use the --debug flag to print the loaded configuration.

Logging

By default, Gate emits logs to the stderr sink in json format with log level info. If not specified, the default configuration is equivalent to the following:

Environment variables

GATE_LOG_FORMAT=json
GATE_LOG_LEVEL=info
GATE_LOG_OUTPUTS_0_SINK=stderr

HCL

gate = {
  log = {
    format = "json"
    level  = "info"
    outputs = [
      {
        sink = "stderr"
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "format": "json",
      "level": "info",
      "outputs": [
        {
          "sink": "stderr"
        }
      ]
    }
  }
}

TOML

[gate.log]
format = "json"
level = "info"

[[gate.log.outputs]]
sink = "stderr"

YAML

gate:
  log:
    format: json
    level: info
    outputs:
      - sink: stderr

Supported log levels:

• panic
• fatal
• error
• warn
• info
• debug
• trace

caution

Trace and debug logs may contain sensitive information from requests (like headers). Please make sure to set the log-level to debug only in environments where you can safely print the configuration.

Supported log formats:

• text
• json

Supported sinks:

• stderr
• stdout
• syslog

Multiple outputs can be configured simultaneously, and each one can specify a different sink, log format and log level overriding the defaults. Refer to the following sections for logging to standard streams or SysLog

Logging to standard streams

Gate supports logging to the stdout and stderr standard streams. For example, the following configuration outputs trace and higher severity logs (i.e., all logs) to stdout in textual format, and only warnings and higher severity to stderr as JSON:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=stdout
GATE_LOG_OUTPUTS_0_FORMAT=text
GATE_LOG_OUTPUTS_0_LEVEL=trace

GATE_LOG_OUTPUTS_1_SINK=stderr
GATE_LOG_OUTPUTS_1_FORMAT=json
GATE_LOG_OUTPUTS_1_LEVEL=warn

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "stdout"
        format = "text"
        level = "trace"
      },
      {
        sink = "stderr"
        format = "json"
        level = "warn"
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "stdout",
          "format": "text",
          "level": "trace"
        },
        {
          "sink": "stderr",
          "format": "json",
          "level": "warn"
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "stdout"
format = "text"
level = "trace"

[[gate.log.outputs]]
sink = "stderr"
format = "json"
level = "warn"

YAML

gate:
  log:
    outputs:
      - sink: stdout
        format: text
        level: trace
      - sink: stderr
        format: json
        level: warn

The format and level configuration parameters are optional for outputs and default to the top-level log.format and log.level values.

Buffering

By default, the output of the Gate process's standard streams is "unbuffered", only relying on the OS-provided stream buffers. If your application produces logs to standard streams faster than your infrastructure or collectors can consume, you can configure Gate to provide its own buffering by using the sink-specific parameters.buffer_size:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=stdout
GATE_LOG_OUTPUTS_0_FORMAT=text
GATE_LOG_OUTPUTS_0_LEVEL=trace
GATE_LOG_OUTPUTS_0_PARAMETERS_BUFFER_SIZE=65536

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "stdout"
        format = "text"
        level = "trace"
        parameters = {
          buffer_size = 65535
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "stdout",
          "format": "text",
          "level": "trace",
          "parameters": {
            "buffer_size": 65535
          }
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "stdout"
format = "text"
level = "trace"
parameters.buffer_size = 65535

YAML

gate:
  log:
    outputs:
      - sink: stdout
        format: text
        level: trace
        parameters:
          buffer_size: 65535

In the example above a stdout sink has an extra Gate-managed buffer of 64KiB.

Logging to SysLog

Gate supports shipping logs to a RFC5424-compliant SysLog server by using the syslog sink type. These are the supported configuration values:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=syslog
GATE_LOG_OUTPUTS_0_FORMAT=<Log format>
GATE_LOG_OUTPUTS_0_LEVEL=<Log level>
GATE_LOG_OUTPUTS_0_PARAMETERS_NETWORK=<Network>
GATE_LOG_OUTPUTS_0_PARAMETERS_ADDRESS=<Address>
GATE_LOG_OUTPUTS_0_PARAMETERS_FACILITY=<SysLog facility>
GATE_LOG_OUTPUTS_0_PARAMETERS_TAG=<SysLog tag>

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "syslog"
        format = "<Log format>"
        level = "<Log level>"
        parameters = {
          network = "<Network>"
          address = "<Address>"
          facility = <SysLog facility>
          tag = "<SysLog tag>"
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "syslog",
          "format": "<Log format>",
          "level": "<Log level>",
          "parameters": {
            "network": "<Network>",
            "address": "<Address>",
            "facility": <SysLog facility>,
            "tag": "<SysLog tag>"
          }
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "syslog"
format = "<Log format>"
level = "<Log level>"
parameters.network = "<Network>"
parameters.address = "<Address>"
parameters.facility = <SysLog facility>
parameters.tag = "<SysLog tag>"

YAML

gate:
  log:
    outputs:
      - sink: syslog
        format: <Log format>
        level: <Log level>
        parameters:
          network: <Network>
          address: <Address>
          facility: <SysLog facility>
          tag: <SysLog tag>

where:

• <Log format> supports the same values as all other sinks: trace, debug, info, warn, error, fatal, panic
• <Log level> supports the same values as all other sinks: text, json
• <Network> is the network type to connect to the SysLog server: tcp, tcp4 (IPv4-only), tcp6 (IPv6-only), udp, udp4 (IPv4-only), udp6
• <Address> is the network address of the remote SysLog server in the host:port format (e.g., syslog.example.com:6514)
• <SysLog facility> is the SysLog facility value: between 0 and 23 (included)
• <SysLog tag> is the SysLog application tag (also referred to as application name): any string value identifying the current Gate instance

By default, Gate connects to the specified remote SysLog server over TLS (v1.2 and above). You can optionally instruct Gate to skip certificate verification or disable TLS entirely by using the tls.insecure and tls.disabled boolean parameters, respectively:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=syslog
...
GATE_LOG_OUTPUTS_0_PARAMETERS_TLS_INSECURE=<Skip certificate verification>
GATE_LOG_OUTPUTS_0_PARAMETERS_TLS_DISABLED=<Disable TLS>

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "syslog"
        ...
        parameters = {
          ...
          tls = {
            insecure = <Skip certificate verification>
            disabled = <Disable TLS>
          }
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "syslog",
          ...
          "parameters": {
            ...
            "tls": {
              "insecure": <Skip certificate verification>,
              "disabled": <Disable TLS>
            }
          }
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "syslog"
...
parameters.tls.insecure = <Skip certificate verification>
parameters.tls.disabled = <Disable TLS>

YAML

gate:
  log:
    outputs:
      - sink: syslog
        ...
        parameters:
          ...
          tls:
            insecure: <Skip certificate verification>
            disabled: <Disable TLS>

Priority

The resulting SysLog priority value of each message is a combination for its "facility" value, as provided in the configuration, and the "severity" value of each log line. In particular, Gate maps log levels to SysLog severity values as follows:

• panic, fatal: Critical
• error: Error
• warn: Warning
• info: Informational
• debug, trace: Debug

Connection management

Gate automatically manages the connection to the remote SysLog server. In particular, it will try to connect immediately on start-up and fail to initialize if a connection cannot be established. If a connection or communication error is detected, Gate will automatically try to reconnect, with an exponential backoff delay. Gate continues to log without interruptions even while not connected to the SysLog server, as described in the message queueing section.

Message Queueing

To avoid a negative impact on performance due to slow or intermittent connectivity with the SysLog server, Gate's syslog sink handles logs asynchronously. Any logging operation simply adds the log entry to a transmission queue. The log is then asynchronously sent to the SysLog server as soon as a connection becomes available. Please refer to the connection management section for details.

The transmission queue holds up to 64K log entries, but it may fill up entirely under certain circumstances, such as a prolonged disconnection from the SysLog server, or the server being consistently slow at ingesting messages. In this case, Gate prioritizes continuity of operations, dropping the oldest message in the queue in favor of each new entry.

Metadata

Gate populates the following fields for all outgoing SysLog messages:

• HOSTNAME: hostname of the machine as provided by the OS
• APP-NAME: application tag as specified in the syslog sink configuration parameters
• PROCID: the PID of the Gate process
• TIMESTAMP: current time with micro-second precision, the maximum allowed by the SysLog protocol

On top of the information provided in the header, Gate takes advantage of the SysLog Structured Data mechanism to enrich each message with the following extra information:

• origin:
  • ip: the local IP address of the connection to the SysLog server
  • enterpriseId: always equal to 60696, SlashID's Private Enterprise Number as assigned by IANA
  • software: always equal to gate
  • swVersion: a string representing Gate's version in the [version]-[commit] format
• meta:
  • sequenceId: the sequence number for the message (starts at 1 and wraps around after 2147483647)

You can find more detailed information about logging in the Monitoring page.

Debugging configuration

When Gate log-level is set to debug, the entire configuration is printed at the start.

caution

The entire configuration is printed, including potentially sensitive data. Please make sure to set the log-level to debug only in enviorments where you can safely print the configuration.

Gate run mode

With this configuration option, you can define in which mode Gate should run. The possible values are

• proxy, to run Gate as a proxy or API gateway;
• ext_auth, to run Gate as an ExtAuth-compatible authorization service.
• aws_lambda_auth, to run Gate as an AWS Lambda Authorizer function. Configuration for running Gate as a AWS Lambda Authorizer can be found here.

The default is proxy. If you need to run Gate in multiple modes within the same infrastructure, we recommend having separate deployments, each configured to run in a different mode.

Environment variables

MODE=proxy

HCL

gate = {
  mode = "proxy"

  // ...
}

JSON

{
  "gate": {
    "mode": "proxy",
    // ...

TOML

[Gate]
mode = "proxy"

YAML

gate:
  mode: "proxy"

Gate port

With this configuration option, you can define which port Gate should expose.

Environment variables

GATE_PORT=443

HCL

gate = {
  port = "443"

  // ...
}

JSON

{
  "gate": {
    "port": "443",
    // ...

TOML

[Gate]
port = "443"

YAML

gate:
  port: "443"

Default ExtAuth Response

With this configuration option, you can define the default behaviour of Gate when running as an ExtAuth service. Valid values are allow and deny. If Gate receives a request to check, and both of the following are true:

• the URL in the request does not have plugins set in the configuration
• there are no default plugins configured

then Gate will return the response described in this field. If this value is not set, deny will be used.

Environment variables

GATE_DEFAULT__EXT_AUTH_RESPONSE=allow

HCL

gate = {
  default = {
    ext_auth_response = "allow"
  }

  // ...
}

JSON

{
  "gate": {
    "default": {
      "ext_auth_response": "allow"
    },
    // ...

TOML

[gate.default]
ext_auth_response = "allow"

YAML

gate:
  default:
    ext_auth_response: allow

URL Configuration

Default target

With this configuration option, you can define the default target for Gate. It will be called if no URL will be matched.

Environment variables

GATE_DEFAULT_TARGET=http://default-svc:8080

HCL

gate = {
  default = {
    target = "http://default-svc:8080"
  }

  // ...
}

JSON

{
  "gate": {
    "default": {
      "target": "http://default-svc:8080"
    },
    // ...

TOML

[gate.default]
target = "http://default-svc:8080"

YAML

gate:
  default:
    target: http://default-svc:8080

info

Targets have an effect only if Gate is running in proxy mode. In ext_auth and aws_lambda_auth mode, the target is ignored.

Defining URL mapping

With this option, you can map requests URLs to specific targets. If no path matches, default target is used. Paths are matched in order of insertion.

Environment variables

GATE_URLS_0_PATTERN=svc-example.com/*
GATE_URLS_0_TARGET=http://example:8080

GATE_URLS_1_PATTERN=svc-another-example.com/
GATE_URLS_1_TARGET=https://another-example:8080

In Environment variables configuration, URL number defines the order of URL matching. In that case, the GATE_URLS_0 URL will be matched first, and the GATE_URLS_1 URL will be matched second.

HCL

gate = {
  urls = [
    {
      pattern = "svc-example.com/*"
      target  = "http://example:8080"
    },
    {
      pattern = "svc-another-example.com/"
      target  = "https://another-example:8080"
    }
  ]

  // ...
}

URL are matched in the order they are defined in the configuration file.

JSON

{
  "gate": {
    "urls": [
      {
        "pattern": "svc-example.com/*",
        "target": "http://example:8080",
      },
      {
        "pattern": "svc-another-example.com/",
        "target": "https://another-example:8080"
      }
    ],
    // ...

URL are matched in the order they are defined in the configuration file.

TOML

[[gate.urls]]
pattern = "svc-example.com/*"
target = "http://example:8080"

[[gate.urls]]
pattern = "svc-another-example.com/"
target = "https://another-example:8080"

URL are matched in the order they are defined in the configuration file.

YAML

gate:
  urls:
    - pattern: svc-example.com/*
      target: http://example:8080
    - pattern: svc-another-example.com/
      target: https://another-example:8080

URL are matched in the order they are defined in the configuration file.

Pattern format

You can configure static paths as pattern or wildcards with *.

Example configurations:

Pattern	Request	Matches	Comment
example.localhost/foo	example.localhost/foo	✅
example.localhost/*	example.localhost/foo	✅
example.localhost/*	example.localhost/foo/bar	✅
*/foo	example.localhost/foo	✅
*.example.localhost/foo	foo.example.localhost/foo	✅
other.localhost/foo	example.localhost/foo	❌	Domain is different
other.localhost/foo	example.localhost/foo	❌	Domain is different
example.localhost:8080/foo	example.localhost/foo	❌	Port is different
example.localhost:*/foo	example.localhost:8899/foo	✅
example.localhost/foo	example.localhost/	❌
example.localhost/foo/*/bar	example.localhost/foo/foo_id/bar	✅
example.localhost/foo/*	example.localhost/foo/foo_id/bar/bar_id	✅
example.localhost/foo/	example.localhost/foo/?foo=bar	✅	Query parameters are not required in the pattern

Plugins

Plugins are configured with the plugins option.

Gate Plugins enabled flag

With the enabled flag, you can control whether the plugin is enabled or disabled by default. If enabled by default it will be enforced for all URLs.

Gate Plugins type

The plugin type defines the class of a plugin. For instance, "opa" means that this plugin instance is an instance of the Gate OPA plugin.

Gate Plugins ID

Plugin can have optionally defined id parameter. A plugin ID is case-insensitive and must be unique. The ID is used for configuration options that are specific to a plugin (for example in per-URL configuration).

Gate Plugins intercept mode

With this configuration option, you can define whether a Gate plugin should intercept requests, responses or both.

caution

Not all plugins support all modes, please consult the plugin documentation to know which types are supposed

The possible values are:

• request: Only intercepts requests
• response: Only intercepts responses
• request_response: Intercept both requests and responses

The default is request.

Environment variables

GATE_PLUGINS_0_TYPE=<plugin type>
GATE_PLUGINS_0_ENABLED=true
GATE_PLUGINS_0_INTERCEPT=request
GATE_PLUGINS_0_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_PLUGINS_1_TYPE=<plugin type>
GATE_PLUGINS_1_ID=<plugin ID>
GATE_PLUGINS_1_ENABLED=false
GATE_PLUGINS_1_PARAMETERS_<plugin_parameter>=<plugin parameter value>

Plugins are executed based on number of the index. In the example above, the GATE_PLUGINS_0_NAME plugin will be executed first, and the GATE_PLUGINS_1_NAME one will be executed second.

HCL

gate = {
  plugins = [
    {
      type       = "<plugin type>"
      enabled    = true
      intercept = "request"
      parameters = {
        <plugin parameter> = <plugin parameter value>
      }
    },
    {
      type       = "<plugin type>"
      id         = "<plugin ID>"
      enabled    = false
      parameters = {
        <plugin parameter> = <plugin parameter value>
      }
    }
  ]

  // ...
}

Plugins are executed based on the order in the list.

JSON

{
  "gate": {
    "plugins": [
      {
        "type": "<plugin type>",
        "enabled": true,
        "intercept: "request",
        "parameters": {
          "<plugin parameter>": "<plugin parameter value>"
        }
      },
      {
        "type": "<plugin type>",
        "id": "<plugin ID>",
        "enabled": false,
        "parameters": {
          <plugin parameter>: <plugin parameter value>
        }
      },
    ]
    // ...

Plugins are executed based on the order in the list.

TOML

[[gate.plugins]]
type = "<plugin type>"
enabled = true
intercept = "request"
parameters.<plugin parameter> = <plugin parameter value>

[[gate.plugins]]
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters.<plugin parameter> = <plugin parameter value>

Plugins are executed based on the order in the configuration.

YAML

gate:
  plugins:
    - type: <plugin type>
      enabled: true
      parameters:
        <plugin parameter>: <plugin parameter value>
    - type: <plugin type>
      id: <plugin ID>
      enabled: false
      intercept: "request"
      parameters:
        <plugin parameter>: <plugin parameter value>

Plugins are executed based on the order in the list.

info

Plugins are executed in the order in which they are defined on this list, both at the URL level and globally (when enabled)

Available plugin configuration parameters are defined by each specific plugin. Passing an unsupported configuration option results in an error at startup.

Plugin parameters can be overriden for a specific URL.

Plugin can be enabled or disabled for a specific URL.

You can find entire list of available plugins on plugins page.

Plugin configuration per URL

You can disable or enable the plugin per the defined URL with enabled option. If enabled option is not defined, plugin will use default plugin configuration.

It's also possible to override plugin parameters per URL with parameters option. All parameters are merged with the default plugin configuration. If you want to unset a parameter, you need to do it explicitly in URL configuration by setting empty value.

Here's an example mapping configuration

Environment variables

GATE_PLUGINS_<plugin number>_TYPE=<plugin type>
GATE_PLUGINS_<plugin number>_ID=<plugin ID>
GATE_PLUGINS_<plugin number>_ENABLED=false
GATE_PLUGINS_<plugin number>_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_URLS_0_PATTERN=svc-another-example.com/
GATE_URLS_0_TARGET=https://another-example:8080
GATE_URLS_0_PLUGINS__<PLUGIN ID>__ENABLED=true
GATE_URLS_0_PLUGINS__<PLUGIN ID>__PARAMETERS_<plugin_parameter>=<plugin parameter value>

Plugin ID is case-insensitive. Because of that, <PLUGIN ID> can be the uppercase version of the plugin ID.

Please note that in URL configuration, the plugin ID is separated by two underscores (__).

HCL

gate = {
  plugins = [
    {
      type       = "<plugin type>"
      id         = "<plugin ID>"
      enabled    = false
      parameters = {
        <plugin parameter> = <plugin parameter value>
      }
    }
  ]

  urls = [
    {
      pattern = "svc-another-example.com/"
      target  = "https://another-example:8080"

      plugins = {
        "<plugin ID>" = {
          enabled     = true
          parameters = {
            <plugin parameter> = "<plugin parameter value>"
          }
        }
      }
    }
  ]

  // ...
}

JSON

{
  "gate": {
    "plugins": [
      {
        "type": "<plugin type>",
        "id": "<plugin ID>",
        "enabled": false,
        "parameters": {
          "<plugin parameter>": "<plugin parameter value>"
        }
      },
      "urls": [
        {
          "pattern": "svc-another-example.com/",
          "target": "https://another-example:8080",
          "plugins": {
            "<plugin ID>": {
              "enabled": true,
              "parameters": {
                "<plugin parameter>": "<plugin parameter value>"
              }
            }
          }
        }
      ],
    // ...

TOML

[[gate.plugins]]
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters.<plugin parameter> = <plugin parameter value>

[[gate.urls]]
pattern = "svc-another-example.com/"
target = "https://another-example:8080"

plugins.<plugin ID>.enabled = true
plugins.<plugin ID>.parameters.<plugin parameter> = "<plugin parameter value>"

YAML

gate:
  plugins:
    - type: <plugin type>
      id: <plugin ID>
      enabled: false
      parameters:
        <plugin parameter>: <plugin parameter value>
  urls:
    - pattern: svc-another-example.com/
      target: https://another-example:8080
      plugins:
        <plugin ID>:
          enabled: true
          parameters:
            <plugin parameter>: <plugin parameter value>

info

If you are merging multiple configurations, URL configs are not overridden but appended.

TLS configuration

By default, Gate does not use TLS. You can enable it with this option.

A self-signed certificate is generated on the fly if a valid certificate is not provided.

caution

We do not recommend using the self-signed certificates generated by Gate in production.

Environment variables

GATE_TLS_ENABLED=true
GATE_TLS_CERT_FILE=/etc/certs/local-cert.pem
GATE_TLS_KEY_FILE=/etc/certs/local-key.pem

HCL

gate = {
  tls = {
    cert = {
      file = "/etc/certs/local-cert.pem"
    }

    key = {
      file = "/etc/certs/local-key.pem"
    }
  }

  // ...
}

JSON

{
  "gate": {
    "tls": {
      "cert": {
        "file": "/etc/certs/local-cert.pem"
      },
      "key": {
        "file": "/etc/certs/local-key.pem"
      }
    },
    // ...

TOML

[gate.tls]
enabled = "true"

[Gate.tls.cert]
file = "/etc/certs/local-cert.pem"

[Gate.tls.key]
file = "/etc/certs/local-key.pem"

YAML

gate:
  tls:
    cert:
      file: /etc/certs/local-cert.pem
    enabled: "true"
    key:
      file: /etc/certs/local-key.pem

Ignore target SSL certificates

You can use this option to disable SSL certificate verification for all coming Gate requests. It will disable certificate validation for all requests (proxied and requests from plugin requests).

danger

This option is unsafe, and we do not recommend using it in production environments.

Environment variables

GATE_TRANSPORT_INSECURE=true

HCL

gate = {
  transport = {
    insecure = true
  }

  // ...
}

JSON

{
  "gate": {
    "transport": {
      "insecure": true
    },
    // ...

TOML

[gate.transport]
insecure = true

YAML

gate:
  transport:
    insecure: true

Headers configuration

X-Forwarded-* headers

These options are used to configure Forwarded, X-Forwarded-* and X-Real-IP headers for the outbound requests.

To debug those settings, you can use trace log level.

Environment variables

GATE_HEADERS_FORWARDED_SET_OUTBOUND_FORWARDED=true
GATE_HEADERS_FORWARDED_SET_OUTBOUND_X_FORWARDED=true
GATE_HEADERS_FORWARDED_SET_OUTBOUND_X_REAL_IP=true

GATE_HEADERS_FORWARDED_PRESERVE_INBOUND_FORWARDED=true
GATE_HEADERS_FORWARDED_PRESERVE_INBOUND_X_FORWARDED=true
GATE_HEADERS_FORWARDED_PRESERVE_INBOUND_X_REAL_IP=true

HCL

gate = {
  headers = {
    forwarded = {
      set_outbound = {
        forwarded   = true
        x-forwarded = true
        x-real-ip   = true
      }
      preserve_inbound = {
        forwarded   = true
        x-forwarded = true
        x-real-ip   = true
      }
    }
  }
}

JSON

{
  "gate": {
     "headers": {
      "forwarded": {
        "set_outbound": {
          "forwarded": true,
          "x-forwarded": true,
          "x-real-ip": true
        },
        "preserve_inbound": {
          "forwarded": true,
          "x-forwarded": true,
          "x-real-ip": true
        }
      }
    }
  }
}

TOML

[gate.headers]
forwarded.set_outbound.forwarded = true
forwarded.set_outbound.x-forwarded = true
forwarded.set_outbound.x-real-ip = true

forwarded.preserve_inbound.forwarded = true
forwarded.preserve_inbound.x-forwarded = true
forwarded.preserve_inbound.x-real-ip = true

YAML

gate:
  headers:
    forwarded:
      set_outbound:
        forwarded: true
        x-forwarded: true
        x-real-ip: true

      preserve_inbound:
        forwarded: true
        x-forwarded: true
        x-real-ip: true

• forwarded.set_outbound.forwarded - sets Forwarded header value according to RFC 7239, learn more: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded. for, by, host and proto directives are set.
• forwarded.set_outbound.x-forwarded - sets X-Forwarded-For header value to chain of IP addresses from original client to the last proxy server.
• forwarded.set_outbound.x-real-ip - sets X-Real-IP header value to original client IP address.
• forwarded.preserve_inbound.forwarded - preserves Forwarded header value from inbound request. Use this option only if you trust the inbound request source.
• forwarded.preserve_inbound.x-forwarded - preserves X-Forwarded-For header value from inbound request. Use this option only if you trust the inbound request source.
• forwarded.preserve_inbound.x-real-ip - preserves X-Real-IP header value from inbound request. Use this option only if you trust the inbound request source.

caution

You should preserve inbound headers only if you trust the inbound request source. Otherwise, you can get spoofed headers.

You can learn more about X-Forwarded headers spoofing in MDN Web Docs.

Disable Via header

By default Gate adds Via header for all response. You can disabled it with this configuration option.

Environment variables

GATE_HEADERS_VIA_DISABLED=true

HCL

gate = {
  headers = {
    via = {
      disabled = true
    }
  }

  // ...
}

JSON

{
  "gate": {
    "headers": {
      "via": {
        "disabled": true
      }
    }
    // ...

TOML

[gate.headers]
via.disabled = true

YAML

gate:
  headers:
    via:
      disabled: true

Configuration templating

Gate supports templating for all configuration file formats. For example:

configs/gate-variables.yaml

gate:
  port_from_variable: "8080"

configs/gate.yaml

gate:
  port_from_variable: "{{.gate.port_from_variable}}"

and running

gate --yaml configs/gate-variables.yaml --yaml configs/gate.yaml

gate.port equals to "8080".

Templating works for every file format. It can also be used across different configuration files.

configs/gate.yaml

gate:
  port_from_variable: "{{.gate.port_from_variable}}"

GATE_PORT_FROM_VARIABLE=8080 gate --env --yaml configs/gate.yaml

info

It is not possible to use a templating variable in the same file where you defined the variable.

caution

You only have access to variables defined in gate. So, for example:

configs/gate-variables.yaml

this_is_not_available: "bar"
gate:
  this_is_available: "foo"

configs/gate.yaml

gate:
  port_from_variable: "{{.this_is_not_available}}"

will not work.

Advanced templating

Under the hood, templating uses Go's text/template package. You can use any option provided by this package.