Configuration file

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
    }
}

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.

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.

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.

Point Mender Gateway to a proxy

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.