Repository navigation
Command reference
Every zenithboard command, grouped by what you are trying to do. zenithboard on its own prints a short version of this page; sudo zenithboard menu opens the menus, which do the same things with questions instead of arguments.
sudo: commands that change something need it; commands that only look do not. The column says which.
This page is checked by the test suite: every command the program accepts must appear here, so the table cannot quietly fall behind.
| Command | sudo | What it is for |
|---|---|---|
zenithboard status |
The first thing to run when something looks wrong. What is installed and running, the addresses that apply to your Pi, and the MLAT count (must be exactly 1) | |
zenithboard health |
One screen: power, temperature, memory (free of the total), SD card (how full, its size, what is free), how the previous boot ended, problems in the logs | |
zenithboard memory (or threads) |
for exact figures | Memory, threads and open files, service by service, then the largest processes. Read from /proc; nothing changed. With sudo, memory is PSS (adds up) and open files are counted; without, RSS for other users' processes. 0.34.0 |
zenithboard config |
Every setting, as stored in /etc/zenithboard/config.env. Safe to paste into an issue: no secret is in it |
|
zenithboard version |
The installed version | |
sudo zenithboard menu |
yes | The installer menu: add or remove components, every setting |
zenithboard help |
The short list |
| Command | sudo | What it is for |
|---|---|---|
zenithboard units metric · imperial
|
yes | km, km/h, m — or miles, knots, feet |
zenithboard radius N |
yes | How far around the antenna aircraft are shown: 1, 2, 5, 10, 15, 30 or 50, in your unit |
zenithboard location LAT LON [ALT_M] |
yes | Move the antenna. Writes the position everywhere it is stored (ZenithBoard, the decoder, the feeders) and tells you which websites to update by hand |
zenithboard color amber · green · red · white · turquoise
|
yes | Dot colour of every wall (the dark blue was taken out in 0.23.0) |
zenithboard mode dots · flap
|
yes | Dot matrix, or the airport split-flap board. Without an argument: shows the current one |
zenithboard cycle SECONDS |
yes | How long each aircraft stays on screen (14 by default) |
zenithboard stats |
Today, yesterday, the 30-day average and best, and messages per hour as a sparkline. See Statistics | |
zenithboard stats on · off · status
|
yes | Collect a sample every 15 minutes (off by default). off keeps the files |
zenithboard stats csv · clear
|
yes for clear | The raw samples as CSV; empty them |
zenithboard graphs on · off · status
|
yes for on and off | graphs1090, off by default (0.32.0): wiedehopf's graphs of the decoder, kept for years, on port 8542. on runs its author's installer; off its uninstaller, then removes what it leaves and the packages it added (never purged: the history stays). See Statistics
|
zenithboard stats gaps |
Over thirty days: callsign prefixes shown without an airline name, and type codes drawn with the generic silhouette, each counted in distinct aircraft. Needs statistics on and the wall running. What to paste into an issue so the next airline lookup or silhouette is chosen on figures | |
zenithboard settings export [FILE] |
Your settings as one file, zenithboard-settings-HOST-DATE.env by default (- for the terminal). Never a secret: the Bluesky app password, feeder keys and passwords stay out |
|
zenithboard settings import FILE |
yes | Every setting in the file replaces the current one; lines that are not KEY=VALUE, or look like a secret, are skipped and counted. The file from before is kept as config.env.bak-DATE, importable the same way. The wall reads the new settings at once; the social service is restarted |
zenithboard preset list · add NAME key=value… · del NAME
|
yes to change | A name for a tablet's own choices (units radius cycle theme mode flags), kept as PRESET_NAME in config.env. That tablet opens http://PI:8080/?p=NAME: the preset's keys are applied at every load, what it does not name the tablet keeps. Names: a letter then up to 15 letters or digits |
zenithboard social setup |
yes | The Bluesky account (an app password, never the real one), then the words and the picture. A wizard that tries the account before going on. See Social sharing |
zenithboard social words |
yes | The place name the posts carry, the sharing radius, the gap between posts, the hashtags, and what is worth a post |
zenithboard social hashtags [WORD...] |
yes to change | The hashtags ending each post: social hashtags ADSB avgeek Moselle (the # is optional — unquoted, the shell would take it for a comment), none, or default. Alone: shows them |
zenithboard social gap [MINUTES] |
yes to change | The least time between two posts. 0, the default since 0.20.0, is none: every crossing of the sharing radius is posted, once. Whole minutes up to 1440; taken by the running service at its next look. Alone: shows it |
zenithboard social picture |
yes | The picture: dot-matrix or split-flap, its colour, the map (a wizard) |
zenithboard social look dotmap · flap · alternate
|
yes | The dot-matrix wall with a map, the split-flap board with a map, or the two in turn (one post each). dots was taken out in 0.24.0 |
zenithboard social colour NAME · wall · rotate
|
yes | amber, green, red, white, turquoise, the wall's own colour, or the colours in turn |
zenithboard social places on · off
|
yes (to change) | Name the towns on the maps from the region's own list: on downloads GeoNames' files of the countries with a place within 400 km once (24 MB around Metz) and keeps every populated place, ranked by population or by rank where the population is unknown; on again makes it again (after moving the antenna); off deletes it and goes back to the shipped lists. Off by default. 0.27.0 |
zenithboard social weekly on · off · test · post
|
yes (on, off) | A summary of the week, posted on Sundays from 19:00: aircraft heard, messages, the busiest day and hour, the airlines and type most seen, the crossings posted, with a picture of the week by hour. Needs statistics on; never a distance or a direction. test draws this week's and prints the text, posting nothing; post posts it now. Off by default. 0.33.0 |
zenithboard social sentence LIST |
yes (to change) | The words of a post: factual (as before), story, board, spotter, lookup; several, comma-separated, or random, one drawn at each post. Without a value: the current choice. 0.29.0 |
zenithboard social photolink on · off
|
yes (to change) | End each post with Photo: NAME / Planespotters, a link to the aircraft's photo page, when the wall has one. The link only, never the picture. Off by default. 0.25.0 |
zenithboard social units metric · imperial · wall
|
yes | The posts' units, picture and text (m, km/h, km or ft, knots, mi), or the wall's own UNITS (the default). 0.24.3 |
zenithboard social map NAME · rotate
|
yes | The map of the dotmap and flap looks: normal, night, satellite, terrain, none, or the four maps in turn |
zenithboard social test [HEX] |
Draw the picture and print the text for the best candidate (or that aircraft); post nothing. The picture is at /social/preview
|
|
zenithboard social on · off · status
|
yes | Post the aircraft overhead as a picture of the wall (off by default). off keeps the account |
zenithboard social post [HEX] |
Post now, once, whatever the gap. That aircraft then counts as posted for its crossing | |
zenithboard social check |
yes | Try the account: open a session on Bluesky |
zenithboard social remove |
yes | Forget the account, stop the service, delete its state and its map tiles |
zenithboard photos on · off
|
yes | Aircraft photos from Planespotters. Off: the animated sky scene instead |
zenithboard photos test [HEX] |
Can this Pi reach Planespotters? One real request, and the answer | |
zenithboard routes on · off
|
yes | Origin and destination, looked up by callsign. Off: no callsign leaves the Pi |
zenithboard routes test [CALLSIGN] |
Can this Pi reach adsbdb.com? One real route lookup, and the answer | |
zenithboard config-set PORT 8090 |
yes | Change the wall's port (or any other setting by name; prefer the dedicated commands, they check what you type) |
A tablet can override the colour, look, units, radius, cycle and flags for itself, with the gear or a link such as ?mode=flap&theme=green&flags=0. See The wall.
| Command | sudo | What it is for |
|---|---|---|
zenithboard gain check |
Is the gain right? Reads the decoder's last 15 minutes and gives advice | |
zenithboard gain steps |
The real gain steps the dongle has (29 of them, 0.0 to 49.6 dB) | |
zenithboard gain set DB · max · default
|
yes | Set the gain; snapped to the nearest real step |
zenithboard gain up · down
|
yes | One step. One at a time, then wait 15–30 minutes |
zenithboard gain log on · off
|
yes | Record one measurement every 15 minutes, keeping the last 24 hours, as a CSV table |
zenithboard gain log show · status · path
|
Print the table, how many measurements it holds, where the file is | |
zenithboard gain log clear |
yes | Empty it and start again (before testing a new gain) |
zenithboard region world · us
|
yes |
us offers the optional 978 MHz UAT receiver in the menu |
zenithboard mlat-guard |
yes | Put the single-MLAT rule back, if a feeder update switched its own MLAT on |
How to read a day of the gain log, and why a quiet hour cannot judge the gain: Gain tuning.
| Command | sudo | What it is for |
|---|---|---|
zenithboard net status |
Saved connections, their addresses, the default route, DNS | |
zenithboard net static IP MASK GATEWAY [DNS] [PROFILE] |
yes | A fixed address. MASK as 24 or 255.255.255.0; DNS as cloudflare, google, router or "1.1.1.1 9.9.9.9"
|
zenithboard net dhcp [PROFILE] |
yes | Back to an automatic address |
zenithboard wifi status |
Radio, country, connection, and whether wired or Wi-Fi is preferred | |
zenithboard wifi scan |
Networks in range, with signal strength | |
zenithboard wifi connect SSID [--hidden] |
yes | Save and join a network. Asks for the password; it never goes on the command line |
zenithboard wifi list |
Saved networks | |
zenithboard wifi forget SSID |
yes | Remove a saved network |
zenithboard wifi on · off
|
yes | Radio on or off, kept after a reboot |
zenithboard wifi country XX |
yes | Regulatory country, e.g. FR, kept after a reboot |
zenithboard wifi install-nm |
yes | Install NetworkManager on a Pi that lacks it. Run with the cable plugged in |
zenithboard wifi harden on · off · status
|
yes to change | Two settings of the saved Wi-Fi profile: connection.autoconnect-retries 0 (keep trying to rejoin after a loss; NetworkManager stops after four tries by itself) and 802-11-wireless.powersave 2 (the radio's power saving off, a known cause of short losses on a Pi). Off by default; on notes the values it found, off puts them back. Taken at the next connection |
zenithboard ddns set duckdns · noip · freedns NAME
|
yes | A name for your wall. Asks for the token; it never goes on the command line |
zenithboard ddns status |
Provider, name, last result | |
zenithboard ddns update · test
|
yes | Refresh now / show exactly what the provider answers |
zenithboard ddns off |
yes | Stop updating the name |
| Command | sudo | What it is for |
|---|---|---|
zenithboard watchdog on · off · status
|
on/off | The Pi's hardware watchdog: resets a frozen Pi after about 10 seconds |
zenithboard netwatch on · off · status
|
on/off | Checks the router every 2 minutes; restarts the network, then the Pi, never more than once every 3 hours |
zenithboard netwatch run |
yes | One check now, by hand |
zenithboard keeplogs on · off · status
|
on/off | Keep the system log across reboots (capped at 50 MB) |
All three are off until you turn them on. How they decide, and how to read a bad night afterwards: Reliability and diagnostics.
| Command | sudo | What it is for |
|---|---|---|
zenithboard logs |
The wall's own service, last 100 lines | |
zenithboard logs decoder · uat · social
|
The last 100 lines of that service | |
zenithboard logs usage |
How much space the system logs take | |
zenithboard logs review |
Size, plus the recent warnings | |
zenithboard logs limit MB · default
|
yes | Cap the system logs, 10–2000 MB |
zenithboard logs clean |
yes | Delete all logs now |
zenithboard logs auto on · off · status
|
yes | Daily clean-up keeping the last 7 days |
| Command | sudo | What it is for |
|---|---|---|
sudo zenithboard update |
yes | The normal way to update. ZenithBoard first — after checking the signature on the new code, see below — then the decoder and the feeders |
zenithboard update quick |
yes | ZenithBoard and the wall only, in seconds: the code is pulled, the wall restarted, the feeders left as they are (no apt). The menu's first Update entry since 0.21.0 |
zenithboard update list |
What is installed, and the names update only accepts |
|
zenithboard update only NAME… |
yes | Just those, e.g. readsb flightinfo. Names: zenithboard readsb dump1090 adsbx piaware fr24 planefinder flightinfo
|
zenithboard data update |
yes | Refresh the aircraft-model list now |
zenithboard data status |
When it was last refreshed | |
zenithboard data auto on · off
|
yes | The monthly refresh (on by default) |
zenithboard data localdb on · off
|
yes | Read registrations and models from tar1090's aircraft database on this Pi, before adsbdb and hexdb (0.26.0, off by default). Without on/off: whether it is on and tar1090's database version |
The reasoning is on Security.
| Command | sudo | What it does |
|---|---|---|
zenithboard security |
One screen of what this Pi does right now: who may read the wall, whether updates are verified, anything left from ACARS / Grafana, SSH, open ports, the service sandboxes, the secret files. Each WARN says how to fix it. Exit status 1 when there is one | |
zenithboard patches on · off · status
|
yes | Debian's security fixes installed by themselves, once a day, from the Debian security channel only: the feeders are left to zenithboard update and the Pi is never rebooted. off puts things back as they were |
zenithboard acars remove |
yes | ACARS and Grafana left ZenithBoard in 0.30.0. On a Pi where an older version installed them: stops and removes acarsdec, its ingester and database, Grafana (package, apt source, password file) and the ACARS_* settings, after you type the word remove. An update never does this by itself; zenithboard status and zenithboard security say when something is left |
zenithboard config-set ALLOW_FROM private · any · 10.8.0.0/24,…
|
yes | Who may read the wall: home networks only (the default), anyone, or the networks listed. See Security |
And the things you may need to do by hand:
| What | How | What it is for |
|---|---|---|
| See what a sandbox allows | systemd-analyze security zenithboard-flightinfo |
A score from 0 (locked down) to 10. The wall server scores about 1.3; every ZenithBoard service is under 4.5 |
| See which signing keys this Pi trusts | sudo cat /var/lib/zenithboard/trust/signer.fpr |
One fingerprint per line |
| Trust GitHub's keys again from scratch | sudo rm /var/lib/zenithboard/trust/signer.fpr |
The next update shows the keys and asks |
| Turn the update check off (fork, own branch) | sudo zenithboard config-set UPDATE_VERIFY 0 |
Your own commits are not signed by GitHub's key |
| Which commit is about to be installed | git -C ~/ZenithBoard rev-parse --short origin/main |
Compare with the top commit on GitHub while the update waits for your answer |
| Are the pinned downloads still there? |
bash tools/check-links.sh (in your clone) |
The same check GitHub runs on the 1st of each month |
| Command | sudo | What it is for |
|---|---|---|
sudo ./install.sh |
yes | First install, from the clone |
./install.sh --help · ./install.sh --version
|
no | The flags, and the version of the clone |
sudo /opt/zenithboard/install.sh --uninstall-all |
yes | Remove everything ZenithBoard installed. readsb is the one exception: it has no uninstaller, so the commands to remove it by hand are printed instead |
./bin/zenithboard-demo |
A fake sky on port 8081: no dongle, no Pi needed | |
REAL_PHOTOS=1 ./bin/zenithboard-demo |
The same, with real photos and routes | |
bash tools/publish-wiki.sh |
Copy docs/wiki/ to the GitHub wiki (maintainers) |
Listed so that nothing in ps or the journal is a mystery. Running them by hand is harmless.
| Command | Run by | Every |
|---|---|---|
zenithboard gain log run |
zenithboard-gain-log.timer |
15 minutes, if the gain log is on |
zenithboard netwatch run |
zenithboard-netwatch.timer |
2 minutes, if the network watchdog is on |
zenithboard logs auto-run |
zenithboard-logs-clean.timer |
day, if automatic cleaning is on |
zenithboard stats run |
zenithboard-stats.timer |
15 minutes, if statistics are on; runs as the zenithboard user |
flightinfo/social.py run |
zenithboard-social.service |
A service, if social sharing is on: reads aircraft.json every 5 s, asks the wall every 15 s, posts under the rules; runs as the zenithboard user |
zenithboard ddns update |
zenithboard-ddns.timer |
5 minutes, if a name is set |
zenithboard wifi apply |
zenithboard-wifi.service |
boot |
zenithboard update-components |
zenithboard update |
update |
Direction
Getting started
How it works
- Architecture
- Configuration reference
- Command reference
- The wall
- Statistics
- Social sharing
- Telegram
- Web console
Running it
Working on it