welcome to the ghetto of network servers
(aka chirpstack installation steps)
The typical installation likely is into a virtual machine or into remote instance on the cloud. However when installing directly onto local machine, ansible probably doesnt do much for you.
Chirpstack installs on debian based platforms, eg Ubuntu or raspberry pi. Other distributions with different packaging management would require downloading chirpstack binaries.
If you're a windows 10 user, you may chose to practice installation on WSL2. Although WSL would never be used for actual server (by any sane person), its useful to run virtual machine to familiarize yourself with install / setup procedure of chirpstack. Watch this video if you havent already got WSL2 on windows 10. Be sure to set default to WSL2 in terminal prior to installing linux. Its also recommended to enable systemd, just to be the same as other linux as far as starting & stopping services. When finished you can reset WSL to clean condition in non-configured state, allowing you to restart the entire procedure from a clean slate; equivalent to wiping a hard drive.
On other platforms, if you plan to store database on MicroSD card, you need to be sure to use a high endurance MicroSD, such as one that implements wear leveling.
Chirpstack installation procedure consists of installing an configuring three services: gateway bridge, network server and application server.
add chirpstack debian repository to your machine:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00
sudo echo "deb https://artifacts.chirpstack.io/packages/3.x/deb stable main" | sudo tee /etc/apt/sources.list.d/chirpstack.list
sudo apt update
only needs to be done once.
Gateway bridge can either run on gateway and / or on same machine as network server & application server. In this guide, we will install it on same machine as network server & application server.
according to install requirements:
sudo apt install mosquitto
install gateway bridge package:
sudo apt install chirpstack-gateway-bridge
if you need a complete configuration file (yes!), replace provided gateway-bridge configuration file:
chirpstack-gateway-bridge configfile > /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml
according to installl instructions, install PostgreSQL and redis:
sudo apt install postgresql redis-server
to create new database and new database user, go into PostgreSQL:
sudo -u postgres psql
inside postgresql prompt:
-- create the chirpstack_ns user with password 'dbpassword'
create role chirpstack_ns with login password 'dbpassword';
-- create the chirpstack_ns database
create database chirpstack_ns with owner chirpstack_ns;
-- exit the prompt
\q
To verify if the user and database have been setup correctly, try to connect to it (login with dbpassword):
psql -h localhost -U chirpstack_ns -W chirpstack_ns
you will see something like:
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
chirpstack_ns=>
Use \q to return out.
Database is now ready for chirpstack-network-server.
install chirpstack network server:
sudo apt install chirpstack-network-server
according to instructions, setup database for application server, go into PostgreSQL:
sudo -u postgres psql
inside postgresql prompt:
-- create the chirpstack_as user
create role chirpstack_as with login password 'dbpassword';
-- create the chirpstack_as database
create database chirpstack_as with owner chirpstack_as;
-- enable the trigram and hstore extensions
\c chirpstack_as
create extension pg_trgm;
create extension hstore;
-- exit the prompt
\q
To verify if the user and database have been setup correctly, try to connect to it (login with dbpassword):
psql -h localhost -U chirpstack_as -W chirpstack_as
you will see something like:
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
chirpstack_as=>
Use \q to return out.
Database is now ready for chirpstack-application-server.
install chirpstack application server:
sudo apt-get install chirpstack-application-server
for now, only minimum changes needed to get network server started.
for editing .toml files, it may be helpful to sudo -i to become root, instead of using sudo each time.
For the very first time (after installation) editing network server configuration file, you should generate a new config file, because the one packaged may not be up-to-date or complete:
chirpstack-network-server configfile > /etc/chirpstack-network-server/chirpstack-network-server.toml
edit file /etc/chirpstack-network-server/chirpstack-network-server.toml
change dsn= line to:
dsn="postgres://chirpstack_ns:dbpassword@localhost/chirpstack_ns?sslmode=disable"
for now, only minimum changes needed to get application server started.
for editing .toml files, it may be helpful to sudo -i to become root, instead of using sudo each time.
start out with a complete application server configuration file:
chirpstack-application-server configfile > /etc/chirpstack-application-server/chirpstack-application-server.toml
edit file /etc/chirpstack-application-server/chirpstack-application-server.toml
change dsn= line to:
dsn="postgres://chirpstack_as:dbpassword@localhost/chirpstack_as?sslmode=disable"
assign jwt_secret, obtain by executing:
openssl rand -base64 32
copy / paste the secret into .toml file.
The user facing web server port is configured at bind= in [application_server.external_api] section.
check gateway bridge startup:
sudo systemctl start chirpstack-gateway-bridge
sudo systemctl status chirpstack-gateway-bridge
check Active: state of gateway bridge
check network server startup:
sudo systemctl start chirpstack-network-server
sudo systemctl status chirpstack-network-server
check Active: state of network server
check application server startup:
sudo systemctl start chirpstack-application-server
sudo systemctl status chirpstack-application-server
check Active: state of application server
If you see any errors in the logs showing from these systemctl status commands, then verify that the initial configuration steps above were done correctly.
Point your web browser at the user facing chirpstack-application-server. The default port is 8080, so http://<server-IP-or-hostname>:8080, or http://localhost:8080 if chirpstack is running on same computer as web browser.
login / password out of the box is admin / admin.
The web port for this is defined in /etc/chirpstack-application-server/chirpstack-application-server.toml at bind= in [application_server.external_api] section.
Follow this section if you plan to use basic-station.
edit /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml
change to type="basic_station"
Consult your LoRaWAN regional specification for your region, and desired sub-band.
In the section [backend.basic_station], set LoRaWAN region by configuring all these:
[backend.basic_station] region=
[backend.basic_station] frequency_min=
[backend.basic_station] frequency_max=
[backend.basic_station.concentrators.multi_sf] frequencies=[]
[backend.basic_station.concentrators.lora_std] frequency=
[backend.basic_station.concentrators.lora_std] bandwidth=
[backend.basic_station.concentrators.lora_std] spreading_factor=
under [backend.basic_station], leave tls_cert="" and tls_key="" as is for now (blank); we will try unencrypted connection first.
edit /etc/chirpstack-network-server/chirpstack-network-server.toml
update under [network_server.band], name= for your region, same as used for region= above for chirpstack-gateway-bridge.
update enabled_uplink_channels= for the channel numbers corresponding to the frequencies you used in [backend.basic_station].
On gateway, in basicstation source, in example directory: create a test directory and cd into it.
create a tc.uri file with one line of ws://<ip-of-gateway-bridge>:3001 (note that ws: is unencrypted, later wss: is used when securing connection)
notice also that bind= under [backend.basic_station] has same port number as in tc.uri
On gateway basicstation, in your example test directory, copy station.conf from ../live-s2.sm.tc. The only two files required is station.conf and tc.uri when trying unencrypted connection.
On gateway, get the EUI from gateway by running example live-s2.sm.tc. Look for Station EUI :
In the chirpstack web interface: Gateways -> Create ->
enter Station EUI hex value into Gateway ID. Fill out the rest of the form and select network server, service profile, then create.
start basic station:
RADIODEV=/dev/spidev0.0 ../../build-rpi-std/bin/station
If your chirpstack server is exposed to public internet, then it likely needs to be secured (authorized connections and encrypted).
Install requirement of chirpstack-certificates:
sudo apt install golang-cfssl
clone repository:
git clone https://github.com/brocaar/chirpstack-certificates
build:
cd chirpstack-certificates
make
Check read permission of the .pem files that were generated:
find -name \*.pem -exec ls -l {} \;
Would chirpstack be able to read these .pem files? if not:
find -name \*.pem -exec chmod a+r {} \;
(ultimately, in the end, the certificate files should only be readable by the required user)
In /etc/chirpstack-network-server/chirpstack-network-server.toml, put in the gateway section:
[network_server.gateway]
ca_cert="chirpstack-certificates/certs/ca/ca.pem"
ca_key="chirpstack-certificates/certs/ca/ca-key.pem"
After updating chirpstack-network-server.toml, restart it:
sudo systemctl restart chirpstack-network-server
check network server log to see that it took this update without failure:
journalctl -u chirpstack-network-server -f -n 50
in web interface for gateways, GENERATE CERTIFICATE will now work.
If gateway uses basic-station, and chirpstack-gateway-bridge cannot be installed on gateway, then these instructions would be needed.
(Be aware that connect gateway guide doesnt cover credentials or certificates)
edit file chirpstack-certificates/config/chirpstack-gateway-bridge/basicstation/server/certificate.json. Into CN, put your hostname which runs chirpstack-gateway-bridge. The same hostname that would go into tc.uri file on basic station i.e. wss://yourhostname:3001.
If you are unsure of your correct hostname, use ifconfig to get your IP address on the network, then run host <IP-address>. You will then see <ipaddr>.in-addr-arpa domain name pointer <hostname>.
Rebuild chirpstack-certificates to regenerate them from the updated configuration.
Edit /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml
In the section [backend.basic_station]:
tls_cert="chirpstack-certificates/certs/chirpstack-gateway-bridge/basicstation/server/basicstation-server.pem"
tls_key="chirpstack-certificates/certs/chirpstack-gateway-bridge/basicstation/server/basicstation-server-key.pem"
restart chirpstack gateway bridge, and check its running ok:
sudo systemctl restart chirpstack-gateway-bridge
journalctl -u chirpstack-gateway-bridge -f -n 50
if not done already, get the EUI from gateway by running example live-s2.sm.tc. Look for Station EUI :
if not done already, in the chirpstack web interface: Gateways -> Create.
Put Station EUI hex value into Gateway ID. Fill out the rest of the form and select network server, service profile, then CREATE.
You have a CERTIFICATE tab for your gateway in chirpstack web interface. You can then GENERATE CERTIFICATE.
into gateway, copy -> paste as follows:
- CA certificate text to
tc.trustfile on gateway - TLS certificate text to
tc.crtfile on gateway - TLS key text to
tc.keyfile on gateway
on gateway, change tc.uri to wss://<hostname-or-ip-of-gateway-bridge>:3001
see basic station authentication modes.
the station can be run with extra logging, i.e:
STATION_TLSDBG=3 RADIODEV=/dev/spidev0.0 ../../build-rpi-std/bin/station
Required when gateways running chirpstack-gateway-bridge (or chirpstack-gateway-os) connect over internet.
In chirpstack-certificates project, add your server's host name to chirpstack-certificates/config/mqtt/server/certificate.json to the "hosts" section..
If you are unsure of your correct hostname, use ifconfig to get your IP address on the network, then run host <IP-address>. You will then see <ipaddr>.in-addr-arpa domain name pointer <hostname>.
Rebuild chirpstack-certificates to regenerate them from the updated configuration.
Add to mosquitto configuration. Copy /usr/share/doc/mosquitto/examples/mosquitto.conf.gz to directpry /etc/mosquitto/conf.d and gunzip it. Rename this conf file to your own personal name.
copy chirpstack-certificates/certs/mqtt/server/mqtt-server.pem
to /etc/mosquitto/certs/server.crt
copy chirpstack-certificates/certs/mqtt/server/mqtt-server-key.pem
to /etc/mosquitto/certs/server.key
copy chirpstack-certificates/certs/ca/ca.pem
to /etc/mosquitto/ca_certificates/ca.crt
stop mqtt server. and chirpstack:
sudo systemctl stop chirpstack-gateway-bridge
sudo systemctl stop chirpstack-network-server
sudo systemctl stop chirpstack-application-server
sudo systemctl stop mosquitto
edit file /etc/mosquitto/conf.d/<you>.conf for mqtt server configuration to use TLS
change port:
# Port to use for the default listener.
port 8883
add credentials to mqtt server:
# Certificate based SSL/TLS support
...
cafile /etc/mosquitto/ca_certificates/ca.crt
#capath
# Path to the PEM encoded server certificate.
certfile /etc/mosquitto/certs/server.crt
# Path to the PEM encoded keyfile.
keyfile /etc/mosquitto/certs/server.key
tls_version tlsv1.2
try new MQTT server configuration
sudo systemctl start mosquitto
check to see that mosquitto started correctly:
journalctl -u mosquitto.service -f -n 50
if not, check that the 3 files were copied correctly, and specified in your .conf file, then restart:
sudo systemctl restart mosquitto
and then again use the same journalctl -u mosquitto.service -f -n 50 to see if its running correctly.
When mosquitto has started, now update chirpstack to use secured MQTT server.
edit /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml
in section [integration.mqtt.auth.generic]:
server="ssl://<hostname>:8883"
...
ca_cert="chirpstack-certificates/certs/ca/ca.pem"
tls_cert="chirpstack-certificates/certs/mqtt/server/mqtt-server.pem"
tls_key="chirpstack-certificates/certs/mqtt/server/mqtt-server-key.pem"
(if chirpstack-gateway-bridge were running on the gateway, these 3 credential files would be copied to gateway, and the same procedure would apply.)
edit /etc/chirpstack-network-server/chirpstack-network-server.toml
in section [network_server.gateway.backend.mqtt]:
server="ssl://<hostname>:8883"
...
ca_cert="chirpstack-certificates/certs/ca/ca.pem"
tls_cert="chirpstack-certificates/certs/mqtt/server/mqtt-server.pem"
tls_key="chirpstack-certificates/certs/mqtt/server/mqtt-server-key.pem"
edit /etc/chirpstack-application-server/chirpstack-application-server.toml
in section [application_server.integration.mqtt]:
server="ssl://<hostname>:8883"
...
ca_cert="chirpstack-certificates/certs/ca/ca.pem"
tls_cert="chirpstack-certificates/certs/mqtt/server/mqtt-server.pem"
tls_key="chirpstack-certificates/certs/mqtt/server/mqtt-server-key.pem"
start chirpstack gateway bridge, and check its running ok:
sudo systemctl start chirpstack-gateway-bridge
journalctl -u chirpstack-gateway-bridge -f -n 50
start chirpstack network server, and check its running ok:
sudo systemctl start chirpstack-network-server
journalctl -u chirpstack-network-server -f -n 50
start chirpstack application server, and check its running ok:
sudo systemctl start chirpstack-application-server
journalctl -u chirpstack-application-server -f -n 50
once everything is started OK, you may decide to copy .pem files somewhere else without the world-readable permissions, if you think somebody could steal them.
the default user / password is admin / admin
this gateway OS doesnt use systemd, instead its monit over init.
to restart chirpstack-gateway-bridge:
sudo monit restart chirpstack-gateway-bridge
logs are at /var/log/messages
if required to operate on more than one radio region, or subband within a region (set of radio channels), then more that one instance of chirpstack-network-server needs to run. See enabled_uplink_channels= in chirpstack-network-server.toml as to why: the channel mask in ADR.
Additionally, the chirpstack-gateway-bridge uplink-frequency configuration must match these enabled channels. Or if gateway forces the uplink frequencies, these manually configured channels must match the network server.
viewing a certificate:
openssl x509 -text -noout -in <file>
see ports that servers are listening:
sudo lsof -i -P -n | grep LISTEN | grep chirp
sudo netstat -tulpn | grep LISTEN | grep chirp
sudo ss -tulwp |grep chirp
- SSL and certificates explained
- Mosquitto SSL configuration doesnt cover x509v3 required by chirpstack.
- generic self signed certificates with custom CA, warning: not x509v3
- global things network frequency plans
- US915 radio channels.
- application server: how to see DevEUI from device details page. DevEUI can only be viewed on applications devices page.
- network server: how to indicate configuration error when uplink frequency doesnt match to an enabled channel. This occurs when gateway radio channel configuration mismatches region of network server, or enabled channels of network server (sub-band). Configuration error cause end devices to uplink on frequencies that gateway isnt receiving.
- perhaps set
log_levelin gateway-bridge and/or network-server and view logs of either server.
- perhaps set
- network server: how to see time of last uplink or time of last downlink ---> Under application, devices tab, last seen column. Also, in application -> device, under details tab, there is status swection which shows last seen date-time.
- TODO certs could also be generated from https://letsencrypt.org/certificates/