Skip to main content


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)


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

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


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:


Supported log levels:

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

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:



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


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:


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:



  • <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 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:

GATE_LOG_OUTPUTS_0_PARAMETERS_TLS_INSECURE=<Skip certificate verification>


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.


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:

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.


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.


Gate port

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


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.


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.


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

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.

Pattern format

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

Example configurations:

other.localhost/fooexample.localhost/fooDomain is different
other.localhost/fooexample.localhost/fooDomain is different
example.localhost:8080/fooexample.localhost/fooPort is different
example.localhost/foo/example.localhost/foo/?foo=barQuery parameters are not required in the pattern


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.


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.

GATE_PLUGINS_0_TYPE=<plugin type>
GATE_PLUGINS_0_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_PLUGINS_1_TYPE=<plugin type>
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.


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

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_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 (__).


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.


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


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


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


Headers configuration

Disable Via header

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


Configuration templating

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

port_from_variable: "8080"
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.

port_from_variable: "{{.gate.port_from_variable}}"
GATE_PORT_FROM_VARIABLE=8080 gate --env --yaml configs/gate.yaml

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


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

this_is_not_available: "bar"
this_is_available: "foo"
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.