Skip to content

Outdated documentation

You are reading outdated documentation. This page documents ChirpStack v3. ChirpStack v4 is the latest version.


To list all configuration options, start chirpstack-geolocation-server with the --help flag. This will display:

ChirpStack Geolocation Server provides geolocation services for ChirpStack Network Server
        > documentation & support:
        > source & copyright information:

  chirpstack-geolocation-server [flags]
  chirpstack-geolocation-server [command]

Available Commands:
  configfile                    Print the ChirpStack Geolocation Server configuration file
  help                          Help about any command
  test-resolve-multi-frame-tdoa Runs the resolve multi-frame TDOA request from the given directory
  test-resolve-tdoa             Runs the resolve TDOA request from the given directory
  version                       Print the ChirpStack Geolocation Server version

  -c, --config string   path to configuration file (optional)
  -h, --help            help for chirpstack-geolocation-server
      --log-level int   debug=5, info=4, error=2, fatal=1, panic=0 (default 4)

Use "chirpstack-geolocation-server [command] --help" for more information about a command.

Configuration file

By default chirpstack-geolocation-server will look in the following order for a configuration file at the following paths when --config is not set:

  • chirpstack-geolocation-server.toml (current working directory)
  • $HOME/.config/chirpstack-geolocation-server/chirpstack-geolocation-server.toml
  • /etc/chirpstack-geolocation-server/chirpstack-geolocation-server.toml

To load configuration from a different location, use the --config flag.

To generate a new configuration file chirpstack-geolocation-server.toml, execute the following command:

chirpstack-geolocation-server configfile > chirpstack-geolocation-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-geolocation-server configfile --config chirpstack-geolocation-server-old.toml > chirpstack-geolocation-server-new.toml

Example configuration file:

# Log level
# debug=5, info=4, warning=3, error=2, fatal=1, panic=0

# Geolocation-server configuration.
  # Geolocation API.
  # This is the geolocation API that can be used by ChirpStack Network Server.
  # ip:port to bind the api server

  # CA certificate used by the api server (optional)

  # TLS certificate used by the api server (optional)

  # TLS key used by the api server (optional)

  # Geolocation backend configuration.
  # Type.
  # The backend type to use.

  # Request log directory.
  # Logging requests can be used to "replay" geolocation requests and to compare
  # different geolocation backends. When left blank, logging will be disabled.

    # Collos backend.
    # Collos subscription key.
    # This key can be retrieved after creating a Collos account at:

    # Request timeout.
    # This defines the request timeout when making calls to the Collos API.

    # LoRa Cloud backend.
    # Please see for more information about this
    # geolocation service.
    # API URI.
    # The URI of the Geolocation API. This URI can be found under
    # 'Token Management'.

    # API token.

    # Request timeout.
    # This defines the request timeout when making calls to the LoRa Cloud API.

# Prometheus metrics settings.
# Enable Prometheus metrics endpoint.

# The ip:port to bind the Prometheus metrics server to for serving the
# metrics endpoint.

# API timing histogram.
# By setting this to true, the API request timing histogram will be enabled.
# See also:

Securing the geolocation API

In order to protect the geolocation API (geo_server.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 this geolocation-server instance in ChirpStack Network Server, you must provide the CA and TLS client certificate. See also ChirpStack Network Server configuration.

See for a set of scripts to generate such certificates.