blackoutsecure/mlat-client repository overview

⁠docker-mlat-client

Unofficial community image for mlat-client⁠, built with LinuxServer.io⁠ style container patterns (s6, hardened defaults, practical runtime options) for ADS-B multilateration workloads.

Sponsored and maintained by Blackout Secure⁠.

⁠Overview

This project packages upstream wiedehopf/mlat-client⁠ into an easy-to-run, LinuxServer.io-style container image with practical defaults for Mode S multilateration clients.

Quick links:

• Docker Hub listing: blackoutsecure/mlat-client⁠
• Balena block listing: mlat-client block on Balena Hub⁠
• GitHub repository: blackoutsecure/docker-mlat-client⁠
• Upstream application: wiedehopf/mlat-client⁠

⁠Table of Contents

• Quick Start⁠
• Image Availability⁠
• About The mlat-client Application⁠
• Supported Architectures⁠
• Usage⁠
  • Docker Compose⁠
  • Docker CLI⁠
  • Balena Deployment⁠
• Parameters⁠
• Configuration⁠
• Application Setup⁠
• Troubleshooting⁠
• Release & Versioning⁠
• Support & Getting Help⁠
• References⁠

⁠Quick Start

5-minute multilateration client setup:

docker run -d \
  --name=mlat-client \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e MLAT_CLIENT_INPUT_CONNECT=readsb:30005 \
  -e MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090 \
  -e MLAT_CLIENT_LAT=51.5 \
  -e MLAT_CLIENT_LON=-0.1 \
  -e MLAT_CLIENT_ALT=50m \
  -e MLAT_CLIENT_USER_ID=myuser \
  -e MLAT_CLIENT_RESULTS=beast,connect,readsb:30104 \
  -v mlat-client-config:/config \
  blackoutsecure/mlat-client:latest

For compose files, balena, and more examples, see Usage⁠ below.

⁠Image Availability

Docker Hub (Recommended):

• All images published to Docker Hub⁠
• Simple pull command: docker pull blackoutsecure/mlat-client:latest
• Multi-arch support: amd64, arm64
• No registry prefix needed (defaults to Docker Hub)

# Pull latest
docker pull blackoutsecure/mlat-client:latest

# Pull specific version
docker pull blackoutsecure/mlat-client:0.4.3

⁠About The mlat-client Application

mlat-client⁠ is a Mode S multilateration client that selectively forwards Mode S messages to a server that resolves the transmitter position by multilateration of the same message received by multiple clients.

The corresponding server code is available at wiedehopf/mlat-server⁠.

Author and maintenance credits (upstream):

• Original author: Oliver Jowett⁠ (mutability)
• Current upstream maintainer: wiedehopf⁠ (Matthias Wirth)
• Upstream repository and documentation: wiedehopf/mlat-client⁠

⁠Supported Architectures

This image is published as a multi-arch manifest. Pulling blackoutsecure/mlat-client:latest retrieves the correct image for your host architecture.

The architectures supported by this image are:

⁠Usage

⁠docker-compose (recommended, click here for more info⁠)

---
services:
  mlat-client:
    image: blackoutsecure/mlat-client:latest
    container_name: mlat-adsbx
    environment:
      - TZ=Etc/UTC
      - MLAT_CLIENT_INPUT_CONNECT=readsb:30005
      - MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090
      - MLAT_CLIENT_AUTO_LOCATION=true
      - MLAT_CLIENT_USER_ID=myuser
      - MLAT_CLIENT_RESULTS=beast,connect,readsb:30104
      - LOG_LEVEL=info                # debug | info | warn | error | fatal
    volumes:
      - mlat-config:/config
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

volumes:
  mlat-config:

⁠docker-compose with readsb (full ADS-B + MLAT stack)

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_ARGS=--net --device-type rtlsdr --net-bi-port 30004,30104
      - READSB_NET_BO_PORT=30005
      - READSB_AUTO_LOCATION=true
      - READSB_AUTOGAIN=true
      # - READSB_BIASTEE=true          # enable for powered LNAs (e.g. SAWbird+)
      - FEED_PROFILES=adsbexchange
      - LOG_LEVEL=info
    volumes:
      - readsb-config:/config
      - readsb-json:/run/readsb
    devices:
      - /dev/bus/usb:/dev/bus/usb
    ports:
      - 30001:30001
      - 30002:30002
      - 30003:30003
      - 30004:30004
      - 30005:30005
      - 30104:30104
    privileged: true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

  mlat-client:
    image: blackoutsecure/mlat-client:latest
    container_name: mlat-adsbx
    depends_on:
      - readsb
    environment:
      - TZ=Etc/UTC
      - MLAT_CLIENT_INPUT_CONNECT=readsb:30005
      - MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090
      - MLAT_CLIENT_AUTO_LOCATION=true
      - MLAT_CLIENT_USER_ID=myuser
      - MLAT_CLIENT_RESULTS=beast,connect,readsb:30104
      - MLAT_CLIENT_UUID_FILE=/readsb-config/feed-uuid-adsbexchange
      - LOG_LEVEL=info
    volumes:
      - mlat-config:/config
      - readsb-config:/readsb-config:ro
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

volumes:
  readsb-config:
  readsb-json:
  mlat-config:

⁠docker-cli (click here for more info⁠)

docker run -d \
  --name=mlat-client \
  -e TZ=Etc/UTC \
  -e MLAT_CLIENT_INPUT_CONNECT=readsb:30005 \
  -e MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090 \
  -e MLAT_CLIENT_LAT=51.5 \
  -e MLAT_CLIENT_LON=-0.1 \
  -e MLAT_CLIENT_ALT=50m \
  -e MLAT_CLIENT_USER_ID=myuser \
  -e MLAT_CLIENT_RESULTS="beast,connect,readsb:30104" \
  -v /path/to/mlat-client/config:/config \
  --restart unless-stopped \
  blackoutsecure/mlat-client:latest

⁠Balena Deployment

This image can be deployed to Balena-powered IoT devices using the included docker-compose.yml file (which contains the required Balena labels):

balena push <your-app-slug>

For deployment via the web interface, use the deploy button in this repository. See Balena documentation⁠ for details.

⁠Parameters

⁠Environment Variables (Required)

⁠Environment Variables (Optional)

⁠Storage Mounts

⁠Configuration

Environment variables are set using -e flags in docker run or the environment: section in docker-compose.

⁠Individual Environment Variables vs MLAT_CLIENT_ARGS

You can configure the mlat-client in two ways:

1. Individual environment variables (recommended): Set MLAT_CLIENT_LAT, MLAT_CLIENT_LON, etc. The container service script assembles the command-line arguments.

2. Raw arguments: Set MLAT_CLIENT_ARGS to the full argument string. This overrides the individual environment variables.

⁠Automatic Location Detection

When MLAT_CLIENT_AUTO_LOCATION is true (the default) and MLAT_CLIENT_LAT/MLAT_CLIENT_LON are not set, the container will automatically detect your approximate latitude and longitude using IP-based geolocation via ip-api.com⁠.

• Latitude and longitude are resolved from your container's public IP address via ip-api.com⁠
• Explicit MLAT_CLIENT_LAT/MLAT_CLIENT_LON values always take priority
• Set MLAT_CLIENT_AUTO_LOCATION=false to disable this feature entirely

Example — auto-detect location:

environment:
  - MLAT_CLIENT_AUTO_LOCATION=true    # default, can be omitted
  # MLAT_CLIENT_LAT, MLAT_CLIENT_LON, MLAT_CLIENT_ALT left unset
  - MLAT_CLIENT_USER_ID=myuser
  - MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090
  - MLAT_CLIENT_INPUT_CONNECT=readsb:30005
  - MLAT_CLIENT_RESULTS=beast,connect,readsb:30104

⁠Automatic Altitude Detection

When MLAT_CLIENT_AUTO_ALT is true (the default) and MLAT_CLIENT_ALT is not set, the container will automatically detect your ground elevation using the Open-Meteo Elevation API⁠. This works with both auto-detected and explicitly provided coordinates.

• Altitude is resolved from lat/lon using the Open-Meteo Elevation API (ground elevation in metres); falls back to 0m on failure
• Explicit MLAT_CLIENT_ALT always takes priority
• Set MLAT_CLIENT_AUTO_ALT=false to disable this feature

Example — explicit lat/lon with auto-detected altitude:

environment:
  - MLAT_CLIENT_LAT=51.5
  - MLAT_CLIENT_LON=-0.1
  # MLAT_CLIENT_ALT left unset — auto-detected from terrain elevation
  - MLAT_CLIENT_AUTO_ALT=true          # default, can be omitted
  - MLAT_CLIENT_USER_ID=myuser
  - MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090
  - MLAT_CLIENT_INPUT_CONNECT=readsb:30005
  - MLAT_CLIENT_RESULTS=beast,connect,readsb:30104

⁠Results Output Format

The MLAT_CLIENT_RESULTS variable accepts output specifications in the format:

format,type,address:port

Common examples:

⁠Supported Receivers

• Anything that produces Beast-format output with a 12MHz clock:
  • readsb, dump1090-mutability, dump1090-fa
  • an actual Mode-S Beast
  • airspy_adsb in Beast output mode
  • Radarcape in 12MHz mode
  • Radarcape in GPS mode

⁠User / Group Identifiers

By default, this container runs as root.

Root mode (default):

• No PUID or PGID needed

Non-root mode (advanced):

• Set MLAT_CLIENT_USER to your username
• Provide matching PUID and PGID values
• Defaults to 911:911 if omitted

⁠Application Setup

The container runs mlat-client, connecting to a Beast-format data source and forwarding Mode S messages to a multilateration server.

⁠Key Features

• Multilateration: Positions resolved by correlating timestamps from multiple receivers
• Network-only: No hardware required — connects to readsb/dump1090 via network
• Multiple Output Formats: Beast, SBS/BaseStation output support
• Automatic Reconnection: Handles connection interruptions gracefully
• Privacy Mode: Option to hide receiver location on coverage maps

⁠Customizing Configuration

Common environment variable combinations:

# Standard ADSBexchange feed
-e MLAT_CLIENT_INPUT_CONNECT=readsb:30005
-e MLAT_CLIENT_SERVER=feed.adsbexchange.com:31090
-e MLAT_CLIENT_RESULTS=beast,connect,readsb:30104

# Custom MLAT server with privacy
-e MLAT_CLIENT_SERVER=mlat.myserver.com:31090
-e MLAT_CLIENT_PRIVACY=true

# With UUID file for persistent identity (default: /config/feed-uuid-adsbexchange)
-e MLAT_CLIENT_UUID_FILE=/config/feed-uuid-adsbexchange

# With statistics output
-e MLAT_CLIENT_STATS_JSON=/config/mlat-client/stats.json

For all available options, see the mlat-client documentation⁠.

⁠Troubleshooting

⁠Container won't start or exits immediately

Check logs:

docker logs mlat-client
docker logs mlat-client --tail 50 -f  # Follow last 50 lines

Common causes:

• Missing required arguments: Ensure MLAT_CLIENT_LAT, MLAT_CLIENT_LON, MLAT_CLIENT_ALT, and MLAT_CLIENT_USER_ID are set (or leave LAT/LON/ALT empty with MLAT_CLIENT_AUTO_LOCATION=true to auto-detect via IP)
• Invalid altitude format: Use suffix m (metres) or ft (feet), e.g. 50m or 160ft
• Configuration error: Check MLAT_CLIENT_ARGS syntax
• Auto-location failed: If IP geolocation fails (no internet, API down), set coordinates manually

⁠Cannot connect to Beast source

Verify the Beast data source is reachable:

docker exec mlat-client nc -zv readsb 30005

If connection fails:

• Check that readsb/dump1090 is running and exposing Beast output on port 30005
• Verify both containers are on the same Docker network
• Check for firewall rules blocking the connection

⁠Cannot connect to MLAT server

Verify server connectivity:

docker exec mlat-client nc -zv feed.adsbexchange.com 31090

If connection fails:

• Check internet connectivity from the container
• Verify the server address and port
• The MLAT server may be temporarily unavailable

⁠No MLAT results

If the client connects but no positions are resolved:

• Ensure your location (LAT/LON/ALT) is accurate
• MLAT requires multiple receivers seeing the same aircraft — results depend on receiver density in your area
• Check that your Beast data source is providing valid timestamps
• Review logs for synchronization status

⁠Getting help

• Check upstream mlat-client documentation⁠
• Review container logs: docker logs -f mlat-client
• Open an issue on GitHub⁠

⁠Release & Versioning

This project uses semantic versioning⁠:

• Releases published on GitHub Releases⁠
• Multi-arch images (amd64, arm64v8) built automatically
• Docker Hub tags: version-specific, latest, and architecture-specific

Update to latest:

docker pull blackoutsecure/mlat-client:latest
docker-compose up -d  # if using compose

Check image version:

docker inspect -f '{{ index .Config.Labels "build_version" }}' blackoutsecure/mlat-client:latest

⁠Support & Getting Help

• Questions: GitHub Issues⁠
• Bug Reports: Include Docker version, container logs, and reproduction steps
• Upstream Documentation: mlat-client on GitHub⁠
• Community: LinuxServer.io Discord⁠

Get help:

docker logs mlat-client                          # View container logs
docker exec -it mlat-client /bin/bash            # Access container shell
docker inspect blackoutsecure/mlat-client        # Check image details

⁠Sponsor & Credits

Sponsored and maintained by Blackout Secure⁠

Upstream project: wiedehopf/mlat-client⁠ Container patterns: LinuxServer.io⁠

⁠References

⁠Project Resources

⁠Upstream & Related

⁠Technical Resources

• Multilateration (Wikipedia)⁠
• ADS-B Overview⁠
• Docker Documentation⁠

⁠License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE⁠ file for details.

The mlat-client application itself is also licensed under GPL-3.0-or-later. For more information, see the mlat-client repository⁠.

Made with ❤️ by Blackout Secure⁠