90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# adsbus
|
|
|
|
adsbus is a hub and protocol translator for [ADS-B](https://en.wikipedia.org/wiki/Automatic_dependent_surveillance_%E2%80%93_broadcast) 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.
|
|
|
|
|
|
## Building
|
|
|
|
```bash
|
|
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](https://en.wikipedia.org/wiki/Named_pipe), and [character devices](https://en.wikipedia.org/wiki/Device_file#Character_devices)
|
|
* [stdin/stdout](https://en.wikipedia.org/wiki/Standard_streams)
|
|
* 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](../protocols/airspy_adsb.md) (a.k.a. ASAVR)
|
|
* [beast](../protocols/beast.md)
|
|
* [json](../protocols/json.md)
|
|
* [proto](../protocols/proto.md) (a.k.a. ProtoBuf, Protocol Buffers)
|
|
* [raw](../protocols/raw.md) (a.k.a. AVR)
|
|
* stats (send only, summary aggregated data)
|
|
* Transport features:
|
|
* [IPv4](https://en.wikipedia.org/wiki/IPv4) and [IPv6](https://en.wikipedia.org/wiki/IPv6) support
|
|
* Reresolution and reconnection on disconnect, with backoff and jitter
|
|
* [TCP keepalives](https://en.wikipedia.org/wiki/Keepalive#TCP_keepalive) for dead connection detection
|
|
* [TCP fast open](https://en.wikipedia.org/wiki/TCP_Fast_Open) for faster startup of high-latency connections
|
|
* [SO_REUSEPORT](https://lwn.net/Articles/542629/) 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](https://en.wikipedia.org/wiki/Multilateration) scaling for different clock rates and counter bit widths
|
|
* [RSSI](https://en.wikipedia.org/wiki/Received_signal_strength_indication) 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:
|
|
<script src="https://gist.github.com/flamingcow66/68f06aaa7ce91b8ad433.js"></script>
|
|
|
|
|
|
## Security, reliability, testing
|
|
* Secure build options by default
|
|
* -Weverything -Werror -pedantic-errors (with limited specific exceptions)
|
|
* [-D_FORTIFY_SOURCE=2](https://wiki.debian.org/Hardening#DEB_BUILD_HARDENING_FORTIFY_.28gcc.2Fg.2B-.2B-_-D_FORTIFY_SOURCE.3D2.29)
|
|
* [-fstack-protector-strong](https://wiki.debian.org/Hardening#DEB_BUILD_HARDENING_STACKPROTECTOR_.28gcc.2Fg.2B-.2B-_-fstack-protector-strong.29)
|
|
* [-fPIE -pie](https://wiki.debian.org/Hardening#DEB_BUILD_HARDENING_PIE_.28gcc.2Fg.2B-.2B-_-fPIE_-pie.29)
|
|
* [-z relro](https://wiki.debian.org/Hardening#DEB_BUILD_HARDENING_RELRO_.28ld_-z_relro.29)
|
|
* [-z now](https://wiki.debian.org/Hardening#DEB_BUILD_HARDENING_BINDNOW_.28ld_-z_now.29)
|
|
* 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](http://lcamtuf.coredump.cx/afl/) starting from previous output cases
|
|
* Network fuzzing
|
|
* `stutterfuzz.sh` runs adsbus with [stutterfuzz](https://github.com/flamingcowtv/stutterfuzz) to test connection/network handling under load, using afl test cases
|