Configuration file

reference

Mender Gateway uses a JSON file for configuring the proxy and mTLS settings. The configuration is loaded from the file /etc/mender/mender-gateway.conf by default, unless otherwise specified by the --config command line argument. This section provides a reference for the configuration variables.

{
    "Features": {
        "ArtifactsProxy": {
            "Enabled": true,
            "GatewayURL": "https://gateway.mender.io",
            "DomainWhitelist": ["s3.amazonaws.com", "s3.my-min.io"],
            "ArtifactsCache": {
                "Enabled": true,
                "Path": "/var/cache/mender-gateway",
                "SignatureSecret": "KDbQ+Z9asYtPdRQoakM5lGs6xgkWyNx4",
                "LinkExpireDuration": "30m"
            }
        },
        "mTLS": {
            "Enabled": true,
            "CACertificate": "/var/lib/mender/ca-cert.pem",
            "MenderUsername": "gateway@mender.io",
            "MenderPassword": "password123",
            "BlacklistPath": "/var/lib/mender/mtls-blacklist.txt"
        },
        "DeviceSystem": {
            "Enabled": false,
            "SystemID": "REPLACE_WITH_YOUR_UNIQUE_SYSTEM_ID",
            "DefaultInventory": [
                {
                    "Name": "region",
                    "Value": "eu"
                }
            ]
        }
    },
    "HTTP": {
      "Enabled": false,
      "Listen": ":80"
    },
    "HTTPS": {
        "Enabled": true,
        "Listen": ":443",
        "MinimumTLSVersion": "1.2",
        "ServerCertificate": "/var/lib/mender/server-cert.pem",
        "ServerKey": "/var/lib/mender/server-pkey.pem"
    },
    "UpstreamServer": {
        "URL": "https://hosted.mender.io",
        "CACertificate": "/etc/ssl/cert.pem",
        "InsecureSkipVerify": false
    },
    "Metrics": {
        "Enabled": false,
        "Listen": ":9102"
    }
}

Hosted Mender is available in multiple regions to connect to. Make sure you select your desired one before proceeding.

Starting from Mender Gateway version 1.3.0, configurations can be overwritten using environment variables. In the description below, the environment variable names are provided in the parenthesis.

Features

ArtifactsProxy

Enabled (ARTIFACTS_PROXY_ENABLED)
Enable the Local Artifact Proxy.
GatewayURL (ARTIFACTS_PROXY_GATEWAY_URL)
The self-URL to the gateway.
DomainWhitelist (ARTIFACTS_PROXY_DOMAIN_WHITELIST)
List of whitelisted domains to proxy Artifacts from.
ArtifactsCache
Configuration for the Artifact Cache, see below.

ArtifactsCache

Enabled (ARTIFACTS_PROXY_CACHE_ENABLED)
Enable the Artifact Cache (depends on [ArtifactsProxy](#artifactsproxy)).
Path (ARTIFACTS_PROXY_CACHE_PATH)
Path where to store the cached Artifacts.
SignatureSecret (ARTIFACTS_PROXY_CACHE_SECRET)
Base64 encoded HMAC256 secret used to sign links to download artifacts from local cache.
LinkExpireDuration (ARTIFACTS_PROXY_CACHE_LINK_EXPIRE_DURATION)
Sets the time before a signed URL for downloading a file from the cache expires.

mTLS

Enabled (MTLS_ENABLED)
Enable forwarding of mutual TLS (mTLS) authentication requests.
CACertificate (MTLS_CA_CERTIFICATE)
Path to Certificate Authority (CA) Certificate used to sign authorized client certificates.
BlacklistPath (MTLS_BLACKLIST_PATH)
Path to file listing blacklisted client certificate serial numbers. The file is a new-line separated list of hexadecimal serial numbers.
MenderUsername (MTLS_MENDER_USERNAME)
Username (email) for the user representing the API Gateway. This user will preauthorize devices with authorization to the gateway.
MenderPassword (MTLS_MENDER_PASSWORD)
Password credential to the MenderUsername.

Mender Enterprise Only: Using RBAC you can create a new user with a dedicated role to the user access scope to the preauthorization API endpoint for the gateway user.

DeviceSystem

This feature requires Mender Gateway version 1.1.0

Enabled (DEVICE_SYSTEM_ENABLED)
Enable the System feature.
SystemID (DEVICE_SYSTEM_ID)
Defines a unique System identifier for the devices connected to this Mender Gateway. Devices connected to the gateway will show a special attribute named mender_gateway_system_id in the reported inventory data.
DefaultInventory
Defines inventory data added to the reported inventory data of each device connected to the gateway.
Name
Name of the default inventory attribute
Value
Value of the default inventory attribute

HTTP

Enabled (HTTP_ENABLED)
Enable proxy of plain HTTP requests.
Listen (HTTP_LISTEN)
TCP network address to listen for incoming connections.

Do not enable HTTP on public or untrusted networks - always use HTTPS whenever possible.

HTTPS

Enabled (HTTPS_ENABLED)
Enable proxy of TLS-terminated HTTP requests.
Listen (HTTPS_LISTEN)
TCP network address to listen for incoming connections.
MinimumTLSVersion (HTTPS_MINIMUM_TLS_VERSION)
The minimum accepted TLS version for connecting to the gateway ["1.0", "1.1", "1.2", "1.3"].
This feature is available from Mender Gateway version 1.1.0.
ServerCertificate (HTTPS_SERVER_CERTIFICATE)
Path to the public server certificate representing the server.
ServerKey (HTTPS_SERVER_KEY)
Path to certificate key file.

UpstreamServer

URL (UPSTREAM_SERVER)
The upstream server URL for proxying device HTTP requests.
CACertificate (UPSTREAM_SERVER_CA_CERTIFICATE)
Path to trusted CA certificate bundle for the upstream server.
This configuration is available from Mender Gateway version 1.3.0.
InsecureSkipVerify (UPSTREAM_SERVER_INSECURE_SKIP_VERIFY)
Skip verification of certificate claims.

Metrics

Available from Mender Gateway version 2.2.0

Enabled (METRICS_ENABLED)
Expose a Prometheus-compatible /metrics endpoint on a separate HTTP server. Disabled by default.
Listen (METRICS_LISTEN)
TCP network address (host:port) the metrics server listens on. Defaults to :9102, which binds every interface; set an IP address to restrict it, for example 127.0.0.1:9102 for the loopback interface only. An interface name cannot be used.

The metrics endpoint is not authenticated. Use the Listen address to keep it on a trusted network; do not expose it on the device-facing network.

Point Mender Gateway to a proxy

Available from Mender Gateway version 2.1.0

Please note This is a not required for the normal operation of Mender Gateway and is only used for specific use cases.

These configurations are available as environmental variables only.

HTTP_PROXY
URL of the proxy server for HTTP connections. Supports authentication using the user:password@host URL format.
HTTPS_PROXY
URL of the proxy server for HTTPS connections. Supports authentication using the user:password@host URL format.
NO_PROXY
Space-separated list of hosts or domain suffixes that should bypass the proxy. Items can be domain suffixes/wildcards, for example .example.com to bypass the proxy for all *.example.com URLs.

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .