Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      The Things Stack Enterprise

      • Overview
      • AWS
      • Kubernetes
      • Docker
      • The Things Join Server
      • Manage The Things Stack
        • Configuration
          • General Options
          • Tenant Billing Server Options
          • Alert Routing Server Options
          • Application Server Options
          • Command-Line Interface Options
          • Console Options
          • Device Claiming Server Options
          • Gateway Configuration Server Options
          • Gateway Server Options
          • Identity Server Options
          • Join Server Options
          • Network Operations Center Options
          • Network Server Options
          • Packet Broker Agent Options
        • Rate Limiting
        • Resource Limiting
        • Setting up billing with Stripe
        • Tenant Management

      Configuration

      Updated 13 February 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      The Things Stack binary can be configured with many different options. Those options can be provided as command-line flags, environment variables or using a configuration file.

      Note:

      These configuration methods only apply to The Things Stack Open Source and Enterprise deployments that follow the Installation guide. AWS Launcher deployments can be configured using the CloudFormation template settings. Managed deployments such as Cloud and The Things Stack Sandbox are configured for you by The Things Industries.

      Configuration Sources

      In this reference we will refer to configuration options by name. On this page we will show how the console.ui.canonical-url option can be configured.

      Command-line flags

      Command-line flags have the highest priority and, as such, override other means of configuration (environment variable or file). This looks as follows:

      $ ttn-lw-stack start console --console.ui.canonical-url "https://thethings.example.com/console"
      

      Environment variables

      Environment variables for configuration options are very similar to the command-line flags, except that they are in uppercase, and all separators (. or -) are replaced by underscores (_). Environment variables are also prefixed with TTN_LW_.

      Note:

      In many cases you’ll want to use a .env file that is loaded using the dotenv command of direnv or the env_file option of Docker Compose. You can also export each environment variable, or run export $(grep -v '^#' .env | xargs) to export all variables in the .env file.

      The option from the command-line example from above would look as follows with environment variables:

      TTN_LW_CONSOLE_UI_CANONICAL_URL="https://thethings.example.com/console"
      

      Configuration files

      You can also configure The Things Stack with a YAML configuration file. This is again similar to the command-line flags, except that each . represents a YAML node. This allows you to group related options together:

      console:
        ui:
          canonical-url: "https://thethings.example.com/console"
          # other console UI options
        # other console options
      

      You can specify the location of the YAML configuration file with the command-line flag -c or --config. If this flag is not present, The Things Stack will look for config files in the following locations:

      • The current directory
      • The user’s home directory (as determined by Go)
      • The user’s config directory (as determined by Go)

      You can run The Things Stack with the --help flag, and check the description of the --config flag for the exact locations that are being checked.

      Defaults

      The Things Stack can be used for local testing purposes without any custom configuration.

      Printing the Current Configuration

      You can see the current configuration with the config command of ttn-lw-stack or ttn-lw-cli. By default this will print the configuration as CLI flags. Use the --env or --yml flags to print the configuration as environment variables or as YAML.

      General Options

      Global Options Under normal circumstances, only info, warn and error logs are printed to the console. For development, you may also want to see debug logs. log.level: The minimum level log messages must have to be shown (default “info”) The format of logs is also configurable. The Things Stack supports console format (that prints logs as a human-friendly text) and json format (that prints logs as JSON). log.format: Log format to write License The Things Stack requires a license key for production use. For development purposes, it will work for a limited time on localhost without a license key.
      Read

      Tenant Billing Server Options

      General options tbs.tenant-admin-key : The tenant administration key configured in the Identity Server. tbs.pull-interval : How frequently to pull the metering data. tbs.reporter-address-regexps : Regular expressions representing addresses which can report tenant metering totals. Stripe configuration tbs.stripe.enable : Enable the Stripe backend tbs.stripe.api-key : The API secret key used for Stripe operations. Can be found in the API keys menu of the Developers section of the Stripe dashboard. tbs.stripe.endpoint-secret-key : The endpoint secret key used to verify the signature of the Stripe webhooks. Can be found in the Webhooks menu of the Developers section of the Stripe dashboard. tbs.stripe.skip-signature-validation : If enabled, the backend will no longer validate the signature of the Stripe webhooks. Do not use in production environments. tbs.stripe.recurring-plan-ids : The IDs of the recurring pricing plans which are managed by the backend. Can be found in the main page of the pricing plan. tbs.stripe.metered-plan-ids : The IDs of the metered pricing plans which are managed by the backend. Can be found in the main page of the pricing plan.
      Read

      Alert Routing Server Options

      New in 3.30.0 The Alert Routing Server dispatches alert notifications about network components in The Things Stack to receivers over email and SMS. It receives alerts from an external generator such as Prometheus and Alertmanager, stores them in a queue, and delivers a notification to each configured receiver. Warning:
      Read

      Application Server Options

      Security Options as.device-kek-label: Label of KEK used to encrypt device keys at rest Interoperability Options The as.interop options configure how Application Server performs interoperability with other LoRaWAN® Backend Interfaces-compliant servers. as.interop.id: AS-ID of this Application Server as.interop.config-source: Source of the interoperability client configuration (directory, url, blob) as.interop.blob.bucket: Blob bucket, which contains interoperability client configuration as.interop.blob.path: Blob path, which contains interoperability client configuration as.interop.directory: OS filesystem directory, which contains interoperability client configuration as.interop.url: URL, which contains interoperability client configuration See LoRaWAN Join Server Configuration to learn how to configure the client configuration.
      Read

      Command-Line Interface Options

      Global Options Under normal circumstances, only info, warn and error logs are printed to the console. For development, you may also want to see debug logs. log.level: The minimum level log messages must have to be shown By default the CLI assumes that it is connecting to servers that use TLS certificates that are trusted by the operating system. When connecting to servers with self-signed certificates or a custom CA, the ca option can be used to trust those certificates. When connecting servers that don’t use TLS, the insecure option can be used.
      Read

      Console Options

      Console Mount The Console can be served under any arbitrary path on your server console.mount: Path on the server where the Console will be served OAuth Options The Console app uses the OAuth 2.0 authorization flow to authorize actions in the backend. You can customize the authorization parameters if necessary: console.oauth.authorize-url: The OAuth Authorize URL console.oauth.client-id: The OAuth client ID console.oauth.client-secret: The OAuth client secret console.oauth.token-url: The OAuth Token Exchange URL console.oauth.logout-url: The logout URL of the OAuth server used to perform client initiated logouts console.oauth.cross-site-cookie: Controls access to OAuth state cookie between origins. Set to true in multi-cluster deployments in order to support OAuth clients that use POST callbacks. The default is false. Frontend Setup You can change various values that will be passed to the JavaScript logic and HTML Head tags of the Web UI:
      Read

      Device Claiming Server Options

      End Device Claiming Options dcs.edcs.net-id: NetID of the Network Server to configure when claiming dcs.edcs.ns-id: NSID of the Network Server to configure when claiming dcs.edcs.as-id: AS-ID of the Application Server to configure when claiming dcs.edcs.source: Source of the file containing Join Server settings (directory, url, blob) dcs.edcs.directory: OS filesystem directory, which contains the config.yml and the client-specific files dcs.edcs.url: URL, which contains Join Server client configuration dcs.edcs.blob.bucket: Blob bucket to use for the Join Server client configuration dcs.edcs.blob.path: Blob path to use for the Join Server client configuration See Device Claiming Repository to learn how to configure the client configuration.
      Read

      Gateway Configuration Server Options

      Security Options gcs.require-auth: Require authentication for the HTTP endpoints Basic Station CUPS Options The gcs.basic-station options configure the GCS to handle Basic Station CUPS requests. gcs.basic-station.allow-cups-uri-update: Allow CUPS URI updates gcs.basic-station.default.lns-uri: The default LNS URI that the gateways should use. If no Gateway Server address is registered, the default value is used. gcs.basic-station.owner-for-unknown.account-type: Type of account to register unknown gateways to (user|organization) gcs.basic-station.owner-for-unknown.api-key: API Key to use for unknown gateway registration gcs.basic-station.owner-for-unknown.id: ID of the account to register unknown gateways to gcs.basic-station.require-explicit-enable: Require gateways to explicitly enable CUPS The Things Kickstarter Gateway Options The gcs.the-things-gateway.firmware-url and gcs.the-things-gateway.update-channel options configure the source of firmware updates for The Things Kickstarter Gateway.
      Read

      Gateway Server Options

      General Options gs.update-version-info-delay Gateways are disconnected from The Things Stack when settings affecting the connection with the Gateway Server change. You can configure how often the gateway gets fetched from the entity registry. gs.fetch-gateway-interval: Update gateway fetching interval gs.fetch-gateway-jitter: Jitter to apply to the update interval to randomize intervals Forwarding Options The Gateway Server forwards traffic to upstream hosts based on the gs.forward parameter. gs.forward: Forward the DevAddr prefixes to the specified hosts. This parameter accepts a list of strings in the format "target=dev-addr-prefix1 target=dev-addr-prefix2" Enter your NetID to view recommended forwarding settings:
      Read

      Identity Server Options

      General Options is.delete.restore: Defines how long after soft-deletion an entity can be restored Database Options The Identity Server needs to be connected to a PostgreSQL-compatible database. Details for the form of the URI can be found in the PostgreSQL documentation. is.database-uri: Database connection URI is.database-max-idle-conns : Maximum number of idle database connections (default 10) is.database-max-open-conns : Maximum number of open database connections (default 20) is.read-database-uri : Read-Only database connection URI Email Options The Identity Server can be configured with different providers for sending emails. Currently the sendgrid, smtp and dir providers are implemented.
      Read

      Join Server Options

      Security Options js.device-kek-label: Label of KEK used to encrypt device keys at rest General Options js.default-join-eui: Default JoinEUI for the Join Server js.dev-nonce-limit: Amount of DevNonces stored per device js.join-eui-prefix: JoinEUI prefixes handled by this Join Server
      Read

      Network Operations Center Options

      Network Operations Center Mount The Network Operations Center can be served under any arbitrary path on your server: noc.mount: Path on the server where the Network Operations Center will be served OAuth Options Network Operations Center app uses the OAuth 2.0 authorization flow to authorize actions in the backend. You can customize the authorization parameters if necessary: noc.oauth.authorize-url: The OAuth Authorize URL noc.oauth.client-id: The OAuth client ID noc.oauth.client-secret: The OAuth client secret noc.oauth.token-url: The OAuth Token Exchange URL noc.oauth.logout-url: The logout URL of the OAuth server used to perform client initiated logouts noc.oauth.cross-site-cookie: Controls access to OAuth state cookie between origins. Set to true in multi-cluster deployments in order to support OAuth clients that use POST callbacks. The default is false. Database Options Network Operations Center needs to be connected to PostgreSQL database with a TimescaleDB extension installed. Details for the form of the URI can be found in the PostgreSQL documentation.
      Read

      Network Server Options

      General Options ns.dev-addr-prefixes: Device address prefixes of this Network Server ns.net-id: NetID of this Network Server ns.cluster-id: ClusterID of this Network Server. This is purely informative and is added as metadata to messages forwarded to the Application Server ns.device-kek-label: Label of KEK used to encrypt device keys at rest Uplink Options ns.cooldown-window: Time window starting right after deduplication window, during which, duplicate messages are discarded ns.deduplication-window: Time window during which, duplicate messages are collected for metadata ns.application-uplink-queue.buffer-size: Application uplink queue buffer size (default 1000) ns.application-uplink-queue.num-consumers: Number of consumers for the application uplink queue (default 1) Downlink Options The ns.downlink-priorities options configure priorities Network Server assigns downlinks when scheduling them on Gateway Server. In case when several downlinks are available for scheduling, Gateway Server will schedule higher priority downlink first.
      Read

      Packet Broker Agent Options

      Registration Options pba.registration.name: Friendly name to register with Packet Broker pba.registration.administrative-contact.email: Email address of the administrative contact person or mailing group pba.registration.technical-contact.email: Email address of the technical contact person or mailing group pba.registration.listed: Indicates whether the Home Network is listed in the Packet Broker catalog. Set this to false to connect to Packet Broker but to stay private to other networks Connection Options pba.iam-address: Address of Packet Broker IAM pba.control-plane-address: Address of Packet Broker Control Plane pba.data-plane-address: Address of Packet Broker Data Plane. See Packet Broker Clients for available cluster addresses pba.insecure: Connect without using TLS (only for test environments) pba.net-id: LoRa Alliance NetID pba.tenant-id: Tenant ID within the NetID pba.cluster-id: Cluster ID uniquely identifying this cluster within a NetID and tenant. The cluster ID is used for shared subscriptions (i.e. splitting traffic over multiple Packet Broker Agents) and as Forwarder ID to route downlink traffic to the right cluster pba.cluster-id-template: Use a Go template for constructing Packet Broker Cluster ID from The Things Stack Cluster ID (e.g. {{.}}.thethings.example.com with cluster ID eu1 results in Packet Broker Cluster ID eu1.thethings.example.com) pba.home-network-cluster-id: Home Network Cluster ID, if different from the Cluster ID. Leave empty to fallback to cluster-id Gateway identity, status, antennas, frequency plan, location, Tx and Rx rates can be reported to Packet Broker Mapper. Mapping is enabled when the Forwarder role is enabled.
      Read
      ← Manage The Things Stack General Options →

      On this page

      • Configuration Sources
      • Printing the Current Configuration

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories