Packet Broker Clients

Packet Broker Clients are command-line utilities for working with Packet Broker.

Services

Action	Service	Client	Basic Auth	OAuth 2.0
Manage networks	IAM	pbadmin	administrator
Manage tenants	IAM	pbadmin	administrator	network
Manage network API keys	IAM	pbadmin	administrator	network
Manage cluster API keys	IAM	pbadmin	administrator
List networks and tenants	IAM	pbadmin		cluster, network
Manage routing policies	Control Plane	pbctl		network, tenant
Manage gateway visibilities	Control Plane	pbctl		network, tenant
List routes	Control Plane	pbctl		cluster, network, tenant
List routing policies	Control Plane	pbctl		cluster, network, tenant
Publish and subscribe	Data Plane	pbpub, pbsub		network, tenant

IAM and Control Plane are deployed in a global cluster. Routers (with Data Plane) are deployed in regional clusters:

Region	Address
Europe	eu.packetbroker.io
North America	nam.packetbroker.io
Asia Pacific	apac.packetbroker.io

Getting Started

Installation

Make sure you have Go installed in your environment.

$ go get go.packetbroker.org/pb/cmd/pbadmin
$ go get go.packetbroker.org/pb/cmd/pbctl
$ go get go.packetbroker.org/pb/cmd/pbpub
$ go get go.packetbroker.org/pb/cmd/pbsub

Configuration

Network Operators

If you are a network operator, you need the NetID and (optionally) the tenant ID to create a new API key. This API key is used to authenticate with Packet Broker and configure your LoRaWAN network server.

The NetID (and tenant ID) must already exist. Please contact [email protected] to make sure the network (and tenant) are created by an administrator.

To initialize configuration for your network with NetID 000013 and tenant tenant-a, with the router located in Europe and with rights to read other networks:

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

Run $ pbadmin network init --help with additional options and examples.

Please copy the API Key ID that is printed. Your Packet Broker administrator needs to approve the API key before it can be used.

Manual Configuration

Create a configuration file $HOME/.pb.yaml or .pb.yaml in the working directory:

# Router region:
router-address: "eu.packetbroker.io:443"

# Network or tenant API key ID and secret key value:
client-id: "KZUCD5XAYT6EJ5BH"
client-secret: "E67X5675UCQFTTJMUD73URQOLPA5VT4GBFLPCMUHZWK52ML5"

# Uncomment if you are a Packet Broker IAM user (administrators only):
#iam-username: "admin"
#iam-password: "admin"

If you do not have an API key yet, learn below how to request one.

Command-Line Interface

The command-line utilities pbadmin, pbctl, pbpub and pbsub contain extensive examples. Specify --help to show examples and possible flags.

Manage Network Tenants

Packet Broker Identity and Access Management (IAM) stores networks and tenants. Networks are LoRaWAN networks with a NetID, i.e. 000013 (with DevAddr prefix 26000000/7). Tenants make use of one or more DevAddr blocks within a NetID, i.e. NetID 000013 with prefix 26AA0000/16. Tenants have a unique identifier within the NetID, called the tenant ID.

As NetID 000013, to create tenant tenant-a with DevAddr blocks 26AA0000/16 and 26BB0000/16:

$ pbadmin network tenant create --net-id 000013 --tenant-id tenant-a \
    --name "Tenant A" --dev-addr-blocks 26AA0000/16,26BB0000/16

The prefixes indicate the base DevAddr and the bit length, like CIDR notation. For example, 26AA0000/16 matches all DevAddr from 26AA0000 to 26AAFFFF.

Optionally, you can specify a Home Network cluster. If your network uses multiple clusters, you can let Packet Broker route traffic to these clusters:

$ pbadmin network tenant update --net-id 000013 --tenant-id tenant a \
    --dev-addr-blocks 26AA0000/16=eu1,26BB0000/16=eu2

To list tenants:

$ pbadmin network tenant list --net-id 000013

To get a tenant:

$ pbadmin network tenant get --net-id 000013 --tenant-id tenant-a

To delete a tenant:

$ pbadmin network tenant delete --net-id 000013 --tenant-id tenant-a

Manage Network and Tenant API Keys

Network API keys are used by clients of Packet Broker Router: LoRaWAN network servers and the command-line utilities pbpub and pbsub.

You can create API keys for a network, a tenant, a named cluster in a network and a named cluster in a tenant. For example, to create an API key for a tenant:

$ pbadmin network apikey create --net-id 000042 --tenant-id tenant-a

And for a named cluster in a tenant:

$ pbadmin network apikey create --net-id 000042 --tenant-id tenant-a --cluster-id eu1

Configure Routing Policies

As a Forwarder, you can configure a default routing policy for all Home Networks and routing policies per Home Network with pbctl.

As Forwarder NetID 000042, to see the default routing policy:

$ pbctl policy get --forwarder-net-id 000042 --defaults

To see the routing policy between Forwarder 000042 and Home Network NetID C00123:

$ pbctl policy get --forwarder-net-id 000042 --home-network-net-id C00123

To see the routing policy between Forwarder NetID 000042 tenant tenant-a and Home Network NetID C00123 tenant tenant-b:

$ pbctl policy get --forwarder-net-id 000042 --forwarder-tenant-id tenant-a \
    --home-network-net-id C00123 --home-network-tenant-id tenant-b

To see all the routing policies that Forwarders configured for Home Network NetID C00123:

$ pbctl policy list --home-network-net-id C00123

You can set policies by specifying letters from the following table:

Policy	Uplink	Downlink
Join-request/accept	J	J
MAC commands	M	M
Application data	A	A
Signal Quality	S
Localization	L

To enable all exchange by default:

$ pbctl policy set --forwarder-net-id 000042 --defaults \
    --set-uplink JMASL --set-downlink --JMA

To enable only device activation and MAC commands in both directions with Home Network NetID C00123:

$ pbctl policy set --forwarder-net-id 000042 --home-network-net-id C00123 \
    --set-uplink JM --set-downlink --JM

To enable only device activation and MAC commands in both directions of Forwarder tenant tenant-a with Home Network NetID C00123 tenant tenant-b:

$ pbctl policy set --forwarder-net-id 000042 --forwarder-tenant-id tenant-a \
    --home-network-net-id C00123 --home-network-tenant-id tenant-b \
    --set-uplink JM --set-downlink --JM

Manage Gateway Visibilities

As a Forwarder, you can configure a default gateway visibility for all Home Networks and gateway visibilities per Home Network with pbctl. This works similar to configuring routing policies.

For commands, usage and examples:

$ pbctl gateway-visibility --help

Publish and Subscribe Traffic

To subscribe to routed downlink traffic as network, tenant, and with or without named cluster:

$ pbsub --forwarder-net-id 000042 --group debug
$ pbsub --forwarder-net-id 000042 --forwarder-tenant-id tenant-a --group debug
$ pbsub --forwarder-net-id 000042 --forwarder-cluster-id eu1 --group debug
$ pbsub --forwarder-net-id 000042 --forwarder-tenant-id tenant-a \
    --forwarder-cluster-id eu1 --group debug

To subscribe to routed uplink traffic as network, tenant, and with or without named cluster:

$ pbsub --home-network-net-id 000042 --group debug
$ pbsub --home-network-net-id 000042 --home-network-tenant-id tenant-a --group debug
$ pbsub --home-network-net-id 000042 --home-network-cluster-id eu1 --group debug
$ pbsub --home-network-net-id 000042 --home-network-tenant-id tenant-a \
    --home-network-cluster-id eu1 --group debug

Important: When using pbsub, specify a shared subscription group that is different from the group used in production. Otherwise, traffic gets split to your production subscriptions and your testing subscriptions.

To publish an uplink message in uplink.json as Forwarder network, tenant, and with or without named cluster:

$ pbpub --forwarder-net-id 000042 < uplink.json
$ pbpub --forwarder-net-id 000042 --forwarder-tenant-id tenant-a < uplink.json
$ pbpub --forwarder-net-id 000042 --forwarder-cluster-id eu1 < uplink.json
$ pbpub --forwarder-net-id 000042 --forwarder-tenant-id tenant-a \
    --forwarder-cluster-id eu1 < uplink.json

To publish a downlink message in downlink.json, as Home Network network, tenant, and with or without named cluster:

$ pbpub --home-network-net-id 000042 < downlink.json
$ pbpub --home-network-net-id 000042 --home-network-tenant-id tenant-a < downlink.json
$ pbpub --home-network-net-id 000042 --home-network-cluster-id eu1 < downlink.json
$ pbpub --home-network-net-id 000042 --home-network-tenant-id tenant-a \
    --home-network-cluster-id eu1 < downlink.json

See Examples for example JSON files.

Legal

Packet Broker Clients are Apache 2.0 licensed. See LICENSE for more information.