This section contains example instructions for connecting to Packet Broker using ChirpStack.
To connect ChirpStack to Packet Broker, you need:
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 email@example.com 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 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
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.
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
pb_client.crt output by this command back to Packet Broker at firstname.lastname@example.org.
(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>
<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.
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
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
Put the files
server.key in a directory which ChirpStack can access.
Edit the following lines in the
- Replace the
tls_keywith the correct paths.
- Replace the
authorizationfield by combining your API Key ID with the API Secret Key, separated by a dot.
- Choose a suitable port for the
bindparameter and make sure it is accessible for Packet Broker; configure port forwarding as needed.
serverwith 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>"