Outdated documentation
You are reading outdated documentation. This page documents ChirpStack v3. ChirpStack v4 is the latest version.
Configuration
The chirpstack-application-server
binary has the following command-line flags:
ChirpStack Application Server is an open-source application-server, part of the ChirpStack Network Server project
> documentation & support: https://www.chirpstack.io/application-server/
> source & copyright information: https://github.com/brocaar/chirpstack-application-server
Usage:
chirpstack-application-server [flags]
chirpstack-application-server [command]
Available Commands:
configfile Print the LoRa Application Server configuration file
help Help about any command
version Print the ChirpStack Application Server version
Flags:
-c, --config string path to configuration file (optional)
-h, --help help for chirpstack-application-server
--log-level int debug=5, info=4, error=2, fatal=1, panic=0 (default 4)
Use "chirpstack-application-server [command] --help" for more information about a command.
Configuration file
By default chirpstack-application-server
will look in the following order for a configuration file at the following paths when --config
is not set:
chirpstack-application-server.toml
(current working directory)$HOME/.config/chirpstack-application-server/chirpstack-application-server.toml
/etc/chirpstack-application-server/chirpstack-application-server.toml
To load configuration from a different location, use the --config
flag.
To generate a new configuration file chirpstack-application-server.toml
, execute the following command:
chirpstack-application-server configfile > chirpstack-application-server.toml
Note that this configuration file will be pre-filled with the current configuration (either loaded from the paths mentioned above, or by using the --config
flag). This makes it possible when new fields get added to upgrade your configuration file while preserving your old configuration. Example:
chirpstack-application-server configfile --config chirpstack-application-server-old.toml > chirpstack-application-server-new.toml
Example configuration file:
[general]
# Log level
#
# debug=5, info=4, warning=3, error=2, fatal=1, panic=0
log_level=4
# Log to syslog.
#
# When set to true, log messages are being written to syslog.
log_to_syslog=false
# The number of times passwords must be hashed. A higher number is safer as
# an attack takes more time to perform.
password_hash_iterations=100000
# gRPC default resolver scheme.
#
# Set this to "dns" for enabling dns round-robin load balancing.
grpc_default_resolver_scheme="passthrough"
# PostgreSQL settings.
[postgresql]
# PostgreSQL dsn (e.g.: postgres://user:password@hostname/database?sslmode=disable).
#
# Besides using an URL (e.g. 'postgres://user:password@hostname/database?sslmode=disable')
# it is also possible to use the following format:
# 'user=chirpstack_as dbname=chirpstack_as sslmode=disable'.
#
# The following connection parameters are supported:
#
# * dbname - The name of the database to connect to
# * user - The user to sign in as
# * password - The user's password
# * host - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost)
# * port - The port to bind to. (default is 5432)
# * sslmode - Whether or not to use SSL (default is require, this is not the default for libpq)
# * fallback_application_name - An application_name to fall back to if one isn't provided.
# * connect_timeout - Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely.
# * sslcert - Cert file location. The file must contain PEM encoded data.
# * sslkey - Key file location. The file must contain PEM encoded data.
# * sslrootcert - The location of the root certificate file. The file must contain PEM encoded data.
#
# Valid values for sslmode are:
#
# * disable - No SSL
# * require - Always SSL (skip verification)
# * verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA)
# * verify-full - Always SSL (verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate)
dsn="postgres://localhost/chirpstack_as?sslmode=disable"
# Automatically apply database migrations.
#
# It is possible to apply the database-migrations by hand
# (see https://github.com/brocaar/chirpstack-application-server/tree/master/internal/storage/migrations)
# or let ChirpStack Application Server migrate to the latest state automatically, by using
# this setting. Make sure that you always make a backup when upgrading Lora
# App Server and / or applying migrations.
automigrate=true
# Max open connections.
#
# This sets the max. number of open connections that are allowed in the
# PostgreSQL connection pool (0 = unlimited).
max_open_connections=0
# Max idle connections.
#
# This sets the max. number of idle connections in the PostgreSQL connection
# pool (0 = no idle connections are retained).
max_idle_connections=2
# Redis settings
[redis]
# Server address or addresses.
#
# Set multiple addresses when connecting to a cluster.
servers=[
"localhost:6379",
]
# Password.
#
# Set the password when connecting to Redis requires password authentication.
password=""
# Database index.
#
# By default, this can be a number between 0-15.
database=0
# Redis Cluster.
#
# Set this to true when the provided URLs are pointing to a Redis Cluster
# instance.
cluster=false
# Master name.
#
# Set the master name when the provided URLs are pointing to a Redis Sentinel
# instance.
master_name=""
# Connection pool size.
#
# Default (when set to 0) is 10 connections per every CPU.
pool_size=0
# TLS enabled.
#
# Note: tis will enable TLS, but it will not validate the certificate
# used by the server.
tls_enabled=false
# Key prefix.
#
# A key prefix can be used to avoid key collisions when multiple deployments
# are using the same Redis database and it is not possible to separate
# keys by database index (e.g. when using Redis Cluster, which does not
# support multiple databases).
key_prefix=""
# Application-server settings.
[application_server]
# Application-server identifier.
#
# Random UUID defining the id of the application-server installation (used by
# ChirpStack Network Server as routing-profile id).
# For now it is recommended to not change this id.
id="6d5db27e-4ce2-4b2b-b5d7-91f069397978"
# User authentication
[application_server.user_authentication]
# OpenID Connect.
[application_server.user_authentication.openid_connect]
# Enable OpenID Connect authentication.
#
# Enabling this option replaces password authentication.
enabled=false
# Registration enabled.
#
# Enabling this will automatically register the user when it is not yet present
# in the ChirpStack Application Server database. There is no
# registration form as the user information is automatically received using the
# OpenID Connect provided information.
# The user will not be associated with any organization, but in order to
# facilitate the automatic onboarding of users, it is possible to configure a
# registration callback URL (next config option).
registration_enabled=false
# Registration callback URL.
#
# This (optional) endpoint will be called on the registration of the user and
# can implement the association of the user with an organization, create a new
# organization, ...
# ChirpStack Application Server will make a HTTP POST call to this endpoint,
# with the following URL parameters:
# - user_id, of the newly created user in ChirpStack Application Server.
# - oidc_claims, the claims returned by the OpenID Connect "UserInfo" call, JSON-encoded. Use this to find additional information, like the users organization.
registration_callback_url=""
# Provider URL.
# This is the URL of the OpenID Connect provider.
# Example: https://auth.example.org
provider_url=""
# Client ID.
client_id=""
# Client secret.
client_secret=""
# Redirect URL.
#
# This must contain the ChirpStack Application Server web-interface hostname
# with '/auth/oidc/callback' path, e.g. https://example.com/auth/oidc/callback.
redirect_url=""
# Logout URL.
#
# When set, ChirpStack Application Server will redirect to this URL instead
# of redirecting to the login page.
logout_url=""
# Login label.
#
# The login label is used in the web-interface login form.
login_label=""
# JavaScript codec settings.
[application_server.codec.js]
# Maximum execution time.
max_execution_time="100ms"
# Integration configures the data integration.
#
# This is the data integration which is available for all applications,
# besides the extra integrations that can be added on a per-application
# basis.
[application_server.integration]
# Payload marshaler.
#
# This defines how the MQTT payloads are encoded. Valid options are:
# * protobuf: Protobuf encoding
# * json: JSON encoding (easier for debugging, but less compact than 'protobuf')
# * json_v3: v3 JSON (will be removed in the next major release)
marshaler="json_v3"
# Enabled integrations.
#
# Enabled integrations are enabled for all applications. Multiple
# integrations can be configured.
# Do not forget to configure the related configuration section below for
# the enabled integrations. Integrations that can be enabled are:
# * mqtt - MQTT broker
# * amqp - AMQP / RabbitMQ
# * aws_sns - AWS Simple Notification Service (SNS)
# * azure_service_bus - Azure Service-Bus
# * gcp_pub_sub - Google Cloud Pub/Sub
# * kafka - Kafka distributed streaming platform
# * postgresql - PostgreSQL database
enabled=["mqtt"]
# MQTT integration backend.
[application_server.integration.mqtt]
# Event topic template.
event_topic_template="application/{{ .ApplicationID }}/device/{{ .DevEUI }}/event/{{ .EventType }}"
# Command topic template.
command_topic_template="application/{{ .ApplicationID }}/device/{{ .DevEUI }}/command/{{ .CommandType }}"
# Retain events.
#
# The MQTT broker will store the last publised message, when retain events is set
# to true. When a MQTT client connects and subscribes, it will always receive the
# last published message.
retain_events=false
# MQTT server (e.g. scheme://host:port where scheme is tcp, ssl or ws)
server="tcp://localhost:1883"
# Connect with the given username (optional)
username=""
# Connect with the given password (optional)
password=""
# Maximum interval that will be waited between reconnection attempts when connection is lost.
# Valid units are 'ms', 's', 'm', 'h'. Note that these values can be combined, e.g. '24h30m15s'.
max_reconnect_interval="1m0s"
# Quality of service level
#
# 0: at most once
# 1: at least once
# 2: exactly once
#
# Note: an increase of this value will decrease the performance.
# For more information: https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels
qos=0
# Clean session
#
# Set the "clean session" flag in the connect message when this client
# connects to an MQTT broker. By setting this flag you are indicating
# that no messages saved by the broker for this client should be delivered.
clean_session=true
# Client ID
#
# Set the client id to be used by this client when connecting to the MQTT
# broker. A client id must be no longer than 23 characters. When left blank,
# a random id will be generated. This requires clean_session=true.
client_id=""
# CA certificate file (optional)
#
# Use this when setting up a secure connection (when server uses ssl://...)
# but the certificate used by the server is not trusted by any CA certificate
# on the server (e.g. when self generated).
ca_cert=""
# TLS certificate file (optional)
tls_cert=""
# TLS key file (optional)
tls_key=""
# Client configuration.
#
# This section contains configuration for end-applications connecting to the
# MQTT broker.
[application_server.integration.mqtt.client]
# CA certificate and key file (optional).
#
# When setting the CA certificate and key file options, ChirpStack Application Server
# will generate client certificates which can be used by the end-application for
# authentication and authorization with the MQTT broker. The Common Name of the
# certificate will be set to the application ID.
ca_cert=""
ca_key=""
client_cert_lifetime="8760h0m0s"
# AMQP / RabbitMQ.
[application_server.integration.amqp]
# Server URL.
#
# See for a specification of all the possible options:
# https://www.rabbitmq.com/uri-spec.html
url="amqp://guest:guest@localhost:5672"
# Event routing key template.
#
# This is the event routing-key template used when publishing device
# events. Messages will be published to the "amq.topic" exchange.
event_routing_key_template="application.{{ .ApplicationID }}.device.{{ .DevEUI }}.event.{{ .EventType }}"
# AWS Simple Notification Service (SNS)
[application_server.integration.aws_sns]
# AWS region.
#
# Example: "eu-west-1".
# See also: https://docs.aws.amazon.com/general/latest/gr/rande.html.
aws_region=""
# AWS Access Key ID.
aws_access_key_id=""
# AWS Secret Access Key.
aws_secret_access_key=""
# Topic ARN (SNS).
topic_arn=""
# Azure Service-Bus integration.
[application_server.integration.azure_service_bus]
# Connection string.
#
# The connection string can be found / created in the Azure console under
# Settings -> Shared access policies. The policy must contain Manage & Send.
connection_string=""
# Publish mode.
#
# Select either "topic", or "queue".
publish_mode=""
# Publish name.
#
# The name of the topic or queue.
publish_name=""
# Google Cloud Pub/Sub integration.
[application_server.integration.gcp_pub_sub]
# Path to the IAM service-account credentials file.
#
# Note: this service-account must have the following Pub/Sub roles:
# * Pub/Sub Editor
credentials_file=""
# Google Cloud project id.
project_id=""
# Pub/Sub topic name.
topic_name=""
# Kafka integration.
[application_server.integration.kafka]
# Brokers, e.g.: localhost:9092.
brokers=["localhost:9092"]
# TLS.
#
# Set this to true when the Kafka client must connect using TLS to the Broker.
tls=false
# Topic for events.
topic="chirpstack_as"
# Template for keys included in Kafka messages. If empty, no key is included.
# Kafka uses the key for distributing messages over partitions. You can use
# this to ensure some subset of messages end up in the same partition, so
# they can be consumed in-order. And Kafka can use the key for data retention
# decisions. A header "event" with the event type is included in each
# message. There is no need to parse it from the key.
event_key_template="application.{{ .ApplicationID }}.device.{{ .DevEUI }}.event.{{ .EventType }}"
# Username (optional).
username=""
# Password (optional).
password=""
# One of plain or scram
mechanism="plain"
# Only used if mechanism == scram.
# SHA-256 or SHA-512
algorithm="SHA-512"
# PostgreSQL database integration.
[application_server.integration.postgresql]
# PostgreSQL dsn (e.g.: postgres://user:password@hostname/database?sslmode=disable).
dsn=""
# This sets the max. number of open connections that are allowed in the
# PostgreSQL connection pool (0 = unlimited).
max_open_connections=0
# Max idle connections.
#
# This sets the max. number of idle connections in the PostgreSQL connection
# pool (0 = no idle connections are retained).
max_idle_connections=2
# Settings for the "internal api"
#
# This is the API used by ChirpStack Network Server to communicate with ChirpStack Application Server
# and should not be exposed to the end-user.
[application_server.api]
# ip:port to bind the api server
bind="0.0.0.0:8001"
# ca certificate used by the api server (optional)
ca_cert=""
# tls certificate used by the api server (optional)
tls_cert=""
# tls key used by the api server (optional)
tls_key=""
# Public ip:port of the application-server API.
#
# This is used by ChirpStack Network Server to connect to ChirpStack Application Server. When running
# ChirpStack Application Server on a different host than ChirpStack Network Server, make sure to set
# this to the host:ip on which ChirpStack Network Server can reach ChirpStack Application Server.
# The port must be equal to the port configured by the 'bind' flag
# above.
public_host="localhost:8001"
# Settings for the "external api"
#
# This is the API and web-interface exposed to the end-user.
[application_server.external_api]
# ip:port to bind the (user facing) http server to (web-interface and REST / gRPC api)
bind="0.0.0.0:8080"
# http server TLS certificate (optional)
tls_cert=""
# http server TLS key (optional)
tls_key=""
# JWT secret used for api authentication / authorization
# You could generate this by executing 'openssl rand -base64 32' for example
jwt_secret=""
# Allow origin header (CORS).
#
# Set this to allows cross-domain communication from the browser (CORS).
# Example value: https://example.com.
# When left blank (default), CORS will not be used.
cors_allow_origin=""
# Join-server configuration.
#
# ChirpStack Application Server implements a (subset) of the join-api specified by the
# LoRaWAN Backend Interfaces specification. This API is used by ChirpStack Network Server
# to handle join-requests.
[join_server]
# ip:port to bind the join-server api interface to
bind="0.0.0.0:8003"
# CA certificate (optional).
#
# When set, the server requires a client-certificate and will validate this
# certificate on incoming requests.
ca_cert=""
# TLS server-certificate (optional).
#
# Set this to enable TLS.
tls_cert=""
# TLS server-certificate key (optional).
#
# Set this to enable TLS.
tls_key=""
# Key Encryption Key (KEK) configuration.
#
# The KEK mechanism is used to encrypt the session-keys sent from the
# join-server to the network-server.
#
# The ChirpStack Application Server join-server will use the NetID of the requesting
# network-server as the KEK label. When no such label exists in the set,
# the session-keys will be sent unencrypted (which can be fine for
# private networks).
#
# Please refer to the LoRaWAN Backend Interface specification
# 'Key Transport Security' section for more information.
[join_server.kek]
# Application-server KEK label.
#
# This defines the KEK label used to encrypt the AppSKey (note that the
# AppSKey is signaled to the NS and on the first received uplink from the
# NS to the AS).
#
# When left blank, the AppSKey will be sent unencrypted (which can be fine
# for private networks).
as_kek_label=""
# KEK set.
#
# Example (the [[join_server.kek.set]] can be repeated):
# [[join_server.kek.set]]
# # KEK label.
# label="000000"
# # Key Encryption Key.
# kek="01020304050607080102030405060708"
# Metrics collection settings.
[metrics]
# Timezone
#
# The timezone is used for correctly aggregating the metrics (e.g. per hour,
# day or month).
# Example: "Europe/Amsterdam" or "Local" for the the system's local time zone.
timezone="Local"
# Metrics stored in Redis.
#
# The following metrics are stored in Redis:
# * gateway statistics
[metrics.redis]
# Aggregation intervals
#
# The intervals on which to aggregate. Available options are:
# 'MINUTE', 'HOUR', 'DAY', 'MONTH'.
aggregation_intervals=["MINUTE", "HOUR", "DAY", "MONTH"]
# Aggregated statistics storage duration.
minute_aggregation_ttl="2h0m0s"
hour_aggregation_ttl="48h0m0s"
day_aggregation_ttl="2160h0m0s"
month_aggregation_ttl="17520h0m0s"
# Metrics stored in Prometheus.
#
# These metrics expose information about the state of the ChirpStack Network Server
# instance.
[metrics.prometheus]
# Enable Prometheus metrics endpoint.
endpoint_enabled=false
# The ip:port to bind the Prometheus metrics server to for serving the
# metrics endpoint.
bind=""
# API timing histogram.
#
# By setting this to true, the API request timing histogram will be enabled.
# See also: https://github.com/grpc-ecosystem/go-grpc-prometheus#histograms
api_timing_histogram=false
# Monitoring settings.
#
# Note that this replaces the metrics.prometheus configuration. If a
# metrics.prometheus if found in the configuration then it will fall back
# to that and the monitoring section is ignored.
[monitoring]
# IP:port to bind the monitoring endpoint to.
#
# When left blank, the monitoring endpoint will be disabled.
bind=""
# Prometheus metrics endpoint.
#
# When set to true, Prometheus metrics will be served at '/metrics'.
prometheus_endpoint=false
# Prometheus API timing histogram.
#
# By setting this to true, the API request timing histogram will be enabled.
# See also: https://github.com/grpc-ecosystem/go-grpc-prometheus#histograms
prometheus_api_timing_histogram=false
# Health check endpoint.
#
# When set to true, the healthcheck endpoint will be served at '/health'.
# When requesting, this endpoint will perform the following actions to
# determine the health of this service:
# * Ping PostgreSQL database
# * Ping Redis database
healthcheck_endpoint=false
# Per device event-log max history.
#
# When set to > 0, ChirpStack Application Server will log events per device
# to a Redis Stream. This feature is used by the web-interface.
per_device_event_log_max_history=10
Securing the application-server internal API
In order to protect the application-server internal API ([application_server.internal_api]
) against unauthorized access and to encrypt all communication, it is advised to use TLS certificates. Once the ca_cert
, tls_cert
and tls_key
are set, the API will enforce client certificate validation on all incoming connections. This means that when configuring a network-server instance in ChirpStack Application Server, you must provide the CA and TLS client certificate in order to let the network-server to connect to ChirpStack Application Server. See also network-server management.
See https://github.com/brocaar/chirpstack-certificates for a set of script to generate such certificates.
Securing the join-server API
In order to protect the join-server API ([join_server]
) against unauthorized access and to encrypt all communication, it is advised to use TLS certificates. Once the ca_cert
, tls_cert
and tls_key
are set, the API will enforce client certificate validation on all incoming connections. When the ca_cert
is left blank, TLS will still be configured, but the server will not require and validate the client-certificate.
Please note that you also need to configure ChirpStack Network Server so that it uses a client certificate for its join-server API client. See ChirpStack Network Server configuration.
Securing the web-interface and external API
The web-interface and public api ([application_server.external_api]
) can be secured using a TLS certificate and key. Once the tls_cert
and tls_key
are set ([application_server.external_api]
), TLS will be activated.
Self-signed certificate
A self-signed certificate can be generated with the following command:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 90 -nodes
Let's Encrypt
For generating a certificate with Let's Encrypt, first follow the getting started instructions. When the letsencrypt
cli tool has been installed, execute:
letsencrypt certonly --standalone -d DOMAINNAME.HERE
Environment variables
Although using the configuration file is recommended, it is also possible to use environment variables to set configuration variables. Configuration dots .
are replaced with double underscores __
.
Example:
[application_server.user_authentication.openid_connect]
client_id="my_client_id"
Can be set using the environment variable:
APPLICATION_SERVER__USER_AUTHENTICATION__OPENID_CONNECT__CLIENT_ID="my_client_id"