adsbus

adsbus is a hub and protocol translator for ADS-B messages.

It is conceptually similar to dump1090 --net-only, but supports more protocols and configurations. It doesn't talk to your radio itself; it hooks programs that do, then handles the network distribution and format translation. It doesn't output to a web interface or send data to services like FlightAware; it provides hooks for programs that do.

For programs to feed data into and consume data from adsbus, see the documentation on the adsb-tools suite.

Building

sudo apt-get -y install build-essential git clang libjansson-dev libprotobuf-c-dev protobuf-c-compiler
git clone https://github.com/flamingcowtv/adsb-tools.git
cd adsb-tools/adsbus
make

Features

Separates the concepts of transport, data flow, and format
Transports:
- Outgoing TCP connection
- Incoming TCP connection
- Local files, named pipes, and character devices
- stdin/stdout
- Execute a command and talk to its stdin/stdout, proxy logs from its stderr
Data flows:
- Send (data flows out of adsbus)
- Receive (data flows in to adsbus)
- Send & receive (both directions on the same socket, without echo)
Formats:
- airspy_adsb (a.k.a. ASAVR)
- beast
- json
- proto (a.k.a. ProtoBuf, Protocol Buffers)
- raw (a.k.a. AVR)
- stats (send only, summary aggregated data)
Transport features:
- IPv4 and IPv6 support
- Reresolution and reconnection on disconnect, with backoff and jitter
- TCP keepalives for dead connection detection
- TCP fast open for faster startup of high-latency connections
- SO_REUSEPORT for zero-downtime updates
Data flow features:
- Rapid detection and disconnection of receive <-> receive connections
- Less rapid detection and disconnection of send <-> send connections
- Hop counting and limits (json and proto formats only) to stop infinite routing loops
Format features:
- Autodetection of received data format
- MLAT scaling for different clock rates and counter bit widths
- RSSI scaling for different bit widths
- Introduces json format for balanced human and machine readability with forward compatibility
- Introduces proto format for fast serialization and deserialization with forward compatibility
Federation:
- Federation allows linking multiple instances of adsbus for:
  - Scalability (cores, number of input or output clients, etc.)
  - Efficient long-haul links (hub and spoke models on both ends)
- json and proto formats carry information about original source across multiple hops
- SO_REUSEPORT allows multiple adsbus instances to accept connections on the same IP and port without a load balancer

Use

As a commandline utility

For captures from a network source:

$ ./adsbus --quiet --connect-receive=10.66.0.75/30005 --file-write=beast=dump.beast
^C
$ ls -l dump.beast
-rw------- 1 flamingcow flamingcow 4065 Mar 11 15:07 dump.beast

For file type conversion:

$ ./adsbus --quiet --file-read=dump.beast --file-write=proto=dump.proto
$ ls -l dump.*
-rw------- 1 flamingcow flamingcow  4065 Mar 11 15:07 dump.beast
-rw------- 1 flamingcow flamingcow 16548 Mar 11 15:10 dump.proto

For examining file contents:

$ ./adsbus --quiet --file-read=dump.proto --stdout=json
{"type": "header", "server_version": "https://github.com/flamingcowtv/adsb-tools#1", "magic": "aDsB", "server_id": "0cd53a31-e62f-4c89-a969-cf0e0f7b141a", "rssi_max": 4294967295, "mlat_timestamp_mhz": 120, "mlat_timestamp_max": 9223372036854775807}
{"payload": "200016171BA2BB", "hops": 2, "mlat_timestamp": 370512307133580, "type": "Mode-S short", "source_id": "237e62d7-9f77-4ee0-9025-33367f5f2fc6", "rssi": 286331153}
{"payload": "5D400D30A969AA", "hops": 2, "mlat_timestamp": 370512308420280, "type": "Mode-S short", "source_id": "237e62d7-9f77-4ee0-9025-33367f5f2fc6", "rssi": 858993459}
{"payload": "5DAAC189CD820A", "hops": 2, "mlat_timestamp": 370512310040460, "type": "Mode-S short", "source_id": "237e62d7-9f77-4ee0-9025-33367f5f2fc6", "rssi": 640034342}
{"payload": "59A528D6148686", "hops": 2, "mlat_timestamp": 370512310059540, "type": "Mode-S short", "source_id": "237e62d7-9f77-4ee0-9025-33367f5f2fc6", "rssi": 218959117}
{"payload": "5DAAC189CD820A", "hops": 2, "mlat_timestamp": 370512312373740, "type": "Mode-S short", "source_id": "237e62d7-9f77-4ee0-9025-33367f5f2fc6", "rssi": 673720360}
...

As a daemon
- Using daemontools
  - Does not fork/detact by default
  - Logs to stderr by default
  - Log rotation: use multilog
  - Log timestamping: use multilog and tai64nlocal
  - Run as user: use setuidgid
  - Shuts down cleanly on SIGTERM
- Using other init systems
  - Use --detach to fork/detach
  - Use --log-file=PATH to write logs to a file instead of stderr
  - Use --pid-file=PATH to write post-detach process ID to a file
  - Log rotation: adsbus will reopen its log file on receiving SIGHUP; use with most log rotation systems
  - Log timestamping: use --log-timestamps
  - Run as user: use start-stop-daemon, etc.
  - Shuts down cleanly on SIGTERM
- DO NOT RUN AS ROOT.
  - To bind privileged (< 1024) ports, use capabilities:
```
$ setcap cap_net_bind_service=+ep /path/to/adsbus
```
  - To allow subprograms (those run with --exec-*) to take privileged actions, set capabilties on them, and consider limiting who can execute them with filesystem permissions.

Security, reliability, testing

Secure build options by default
- -Weverything -Werror -pedantic-errors (with limited specific exceptions)
- -D_FORTIFY_SOURCE=2
- -fstack-protector-strong
- -fPIE -pie
- -z relro
- -z now
valgrind clean
- Zero open fds and allocated blocks when run with --track-fds=yes --show-leak-kinds=all --leak-check=full
- Cleans up on normal exit and when handling SIGINT/SIGTERM
Subprogram isolation
- All fds created with CLOEXEC; none passed on to children (tested with --exec-receive='ls -l /proc/self/fd 1>&2')
- Separate process group
Test suite
- make test runs a large set of test inputs through adsbus under valgrind
Parser fuzzing
- make afl-fuzz runs adsbus inside american fuzzy lop starting from previous output cases
Network fuzzing
- stutterfuzz.sh runs adsbus with stutterfuzz to test connection/network handling under load, using afl test cases

7.8 KiB Raw Blame History

adsbus

Building

Features

Use

Security, reliability, testing

7.8 KiB

Raw Blame History