This article is a guide for setting up a private handler that is connected to the public community network. This setup allows for end-to-end encryption between a node and your server.
The server where you are going to deploy the private handler needs a static IP address and/or (sub)domain. In this guide will use the domain
handler.local.thethings.network. Your firewall needs to allow access to the ports
1904 (for the handler API),
8084 (for the HTTP API) and
1883/8883 (for MQTT/MQTTs) or
5672/5671 (for AMQP/AMQPs). We will rely on the community account server of The Things Network (
account.thethingsnetwork.org) so that you can use your TTN Account to manage devices in your private handler. If you don't want your handler to use community accounts, you should look at setting up a private routing environment and use your own account server implementation.
- Install and start Redis.
- Install and start RabbitMQ and its MQTT plugin.
- You should also create a
ttn.handlerexchange using the web interface or with
rabbitmqadmin declare exchange name=ttn.handler type=topic auto_delete=false durable=true.
- You should also create a
- Create a working directory. In this document we will use
~/ttn. All commands are executed from this directory.
masterbranch) macOS, 64 bit Linux, 32 bit Linux or arm Linux.
Before we can connect your handler, it needs to be registered in the account server. This links the private handler to your account, making sure that others can't impersonate your private handler to retrieve your data. To do so, we use
ttnctl and add a new
handler component with the name
ttnctl components add handler mynetwork-handler INFO Added network component id=mynetwork-handler type=handler
Next, we have retrieve an access token that your private handler will use to prove it's identity when it announces with the discovery server. With this announcement, your private handler informs other components in the network about the address and connection security (public key and certificate) of your handler.
ttnctl components token handler mynetwork-handler INFO Got component token id=mynetwork-handler type=handler THE TOKEN THAT WAS GENERATED FOR YOUR HANDLER
For security reasons, this access token is only valid for a limited amount of time (about 3 months), so don't forget to rotate it regularly by requesting a new one and reloading your configuration. You probably want to write a script that does this every month or so.
The configuration for the Handler will be stored in
id: mynetwork-handler tls: true key-dir: handler/ auth-servers: ttn-account-v2: "https://account.thethingsnetwork.org" auth-token: THE TOKEN THAT WAS GENERATED FOR YOUR HANDLER handler: server-address-announce: handler.local.thethings.network broker-id: ttn-broker-eu mqtt-address: localhost:1883
This configuration defines a Handler
mynetwork-handler on the address
handler.local.thethings.network. It connects to the Broker
ttn-broker-eu (located in Europe; you can get a list of Brokers with the command
ttnctl discover broker).
Now we have to generate a public/private keypair and a TLS certificate for secure communication:
ttn handler gen-keypair --config ./handler/ttn.yml ttn handler gen-cert --config ./handler/ttn.yml
Starting the Handler
ttn handler --config handler/ttn.yml
ttnctl is done by editing
Now you can register your application to your private Handler. This command creates the necessary information in the handler and publishes the mapping (appID->handlerID) to the discovery server so that other components know where to send your data.
ttnctl applications register
And manage your devices in the same way as you would do on the public community network. Keep in mind that components cache application registrations, so it may take up to 10 minutes before data is sent to your handler.
Questions or Issues
If you have questions or remarks after following this guide, feel free use the forum or the
#backend channels on Slack. This is a community-supported guide, so please help each other out.
You should now have a working private handler. Now you should probably do some of the following:
- Read how to deploy the private handler using docker-compose. Although that guide is meant for complete private backends, you can just skip the steps for all other components and only look at the steps relevant for the handler.
- Periodically update
ttnto the latest version
- Enable persistence in Redis
- Configure backups
- Secure your MQTT/AMQP broker with usernames and passwords
- Help with development of TTN's open source routing services