ChirpStack

This section contains example instructions for connecting to Packet Broker using ChirpStack.

Requirements

To connect ChirpStack to Packet Broker, you need:

ChirpStack installed on a server
OpenSSL

Get Packet Broker Credentials

Make a request to Packet Broker to join. It is possible to lease a DevAddr block or to request free access to forward to The Things Network community by contacting Packet Broker.

Packet Broker will set up the NetID and (optionally) a tenant ID for your network. Packet Broker will also ask your administrative and technical contact information.

When Packet Broker created your network, you can proceed with initializing your configuration. To initialize configuration for your network with NetID 000013 and tenant tenant-a, with the router located in Europe:

$ pbadmin network init --net-id 000013 --tenant-id tenant-a \
    --router-address eu.packetbroker.io

Copy the API key that is returned. It will also be stored in a local .pb.yaml file, where client-id is the API Key ID and client-secret is the API Key.

Email the API Key ID to Packet Broker at join@packetbroker.net and keep the API Secret Key private. Packet Broker will check your API key and approve the API key so it can be used.

Create a CA Certificate Pair

The first step is to create CA certificate if you do not already have one. This creates a root trust which you will use to sign future certificates. First, create a key using openssl:

$ openssl ecparam -genkey -name prime256v1 -out ca.key

The following command then creates a CA certificate for public use by signing it with its own private key (this is the default for root trust CAs). This will create a ca.crt file that is valid for 5 years (1825 days):

$ openssl req -x509 -new -sha256 -nodes -key ca.key -days 1825 -out ca.crt

You should now have a ca.crt and a ca.key file.

Sign the Packet Broker Key

Packet Broker will email you a pb_client.csr file. This is a Certificate Signing Request that you, as Certificate Authority, must sign so that Packet Broker can authenticate with your ChirpStack deployment.

Verify the received pb_client.csr file from Packet Broker with the following command:

$ openssl req -text -noout -verify -in pb_client.csr

In the subject line, it should contain

CN = <NetID>

as ChirpStack expects the NetID for which passive roaming is agreed on to be the CN of a certificate.

Now, the pb_client.csr can be signed by the CA (this will sign it with a validity of 5 years):

$ openssl x509 -sha256 -req -in pb_client.csr -out pb_client.crt -CA ca.crt -CAkey ca.key -days 1825 -CAserial ca.srl

Email the pb_client.crt output by this command back to Packet Broker at join@packetbroker.net.

(Optional) Create a Server Certificate

If you will also be using your CA certificate to generate a TLS certificate for your website, read this section. If you are using a service like Let’s Encrypt to generate your TLS certificate, skip this step.

Create a public/private key pair for the server and sign it using the CA you just created. Packet Broker expects SANs as x509 attributes and does not rely on the CN of the server. For this to be reflected in the server’s certificate, the following file must be created:

# san.cnf

[ req ]
distinguished_name = req_distinguished_name
req_extensions     = req_cert_extensions
prompt             = no
x509_extensions    = req_cert_extensions

[ req_distinguished_name ]
C  = <country code>
ST = <state/province>
L  = <location>
O  = <organization>
CN = <server address>

[ req_cert_extensions ]
subjectAltName = @subject_alt_name
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth

[ subject_alt_name ]
DNS.1=<server address>

where <server-address> must be replaced by the domain of your ChirpStack instance, i.e chirpstack.thethings.example.com. Also change any location information as desired.

Use openssl to create the server key:

$ openssl ecparam -genkey -name prime256v1 -out server.key

Create a certificate signing request that is used to create the certificate:

$ openssl req -sha256 -new -key server.key -out server.csr -config san.cnf

Sign the certificate signing request to create the certificate:

$ openssl x509 -sha256 -req -in server.csr -out server.crt -CA ca.crt -CAkey ca.key -CAcreateserial -days 1825 -extfile san.cnf -extensions req_cert_extensions

You should now have a server.key, server.crt, server.csr and ca.srl file. The ca.srl serial file keeps track of the certificate serials and assures no serial is used more than once. The server.csr file is not needed anymore and can be deleted.

For best compatibility with the standards, a full certificate chain should be returned by ChirpStack. If you followed the optional step above to generate your own server TLS certificate, use the following command to create this:

$ cat server.crt ca.crt > server_full.crt

Configure ChirpStack

Put the files ca.crt, server-full.crt/server.crt, and server.key in a directory which ChirpStack can access.

Edit the following lines in the chirpstack-network-server.toml configuration.

Replace the ca_cert, tls_cert, and tls_key with the correct paths.
Replace the authorization field by combining your API Key ID with the API Secret Key, separated by a dot.
Choose a suitable port for the bind parameter and make sure it is accessible for Packet Broker; configure port forwarding as needed.
Replace server with the address of the Packet Broker router you used in Get Packet Broker Credentials, i.e https://eu.packetbroker.io:5138. See Router Addresses.

[roaming]
resolve_netid_domain_suffix=".netids.lora-alliance.org"
  [roaming.api]
  # Interface to bind the API to (ip:port).
  bind="0.0.0.0:5138"
  ca_cert="/path/to/ca.crt"
  tls_cert="/path/to/server-full.crt or /path/to/server.crt"
  tls_key="/path/to/server.key"
  [roaming.default]
  enabled=true
  async=true
  async_timeout="30s"
  passive_roaming=true
  passive_roaming_lifetime="0s"
  server="<server:port>"
  authorization="Key <id>.<secret key>"

← The Things Stack Command-Line Interface →