docker-skysquitter

a Docker container to feed SkySquitter with Beast data

docker-skysquitter

What is it?

SkySquitter collects ADS-B data from feeders like dump1090/dump1090-fa/readsb/tar1090 and creates a weather map based on this. The service is experimental. More information is available at https://www.skysquitter.com.

Feeding SkySquitter

Skysquitter uses crowd-sourced data on a very limited, invitation-only basis. If you think you would like to contribute, please contact info@SkySquitter.com.

SkySquitter container configuration

The SkySquitter container retrieves ADS-B data in Beast format from your (separate) decoder application and feeds it to the SkySquitter service. This is done using a small Java application that converts data retrieved via a TCP/IP link to a connection-less UDP data stream. The data is sent securely via a WireGuard VPN that is also part of the container. The VPN is set up in such a way that the SkySquitter Service has access to the data from the SkySquitter container, but not to any other container in your stack.

Configuration of SkySquitter has the following prerequisites:

a Linux machine (PC, Raspberry Pi, etc.) with a functioning Docker configuration. See here for some help on how to get this done quickly.
we strongly recommend using docker-compose to manage your container

Using the example docker-compose.yml file, please configure the following parameters. Unless told otherwise by SkySquitter, please do not modify any of the other parameters:

Mandatory variables

Variable	Description
`WG_PRIVKEY`	Private Key provided by SkySquitter
`WG_PSK`	PSK Key provided by SkySquitter
`MY_IP`	Ip address provided by SkySquitter

Note - these variables will be provided to you by SkySquitter. Under specific circumstances, SkySquitter may provide you with a wg0.conf file instead, that you can install as described in the Configuration Alternatives section below.

Optional variables

Note -- these variables generally do NOT need changing unless you are using a non-standard setup. If your ADS-B generating container or host is not readsb, please make sure to set the RECV_HOST parameter!

Variable	Description	Default value if omitted
`RECV_HOST`	Domain Name or IP address of your Beast format ASDB decoder	`readsb`
`RECV_PORT`	TCP port on `RECV_HOST` where Beast-format data is available	`30005`
`DEST_HOST`	Hostname or IP address of SkySquitter Server	`10.9.2.1`
`DEST_PORT`	UDP port on SkySquitter Server to send data to	`11092`
`FAILURE_TIMEOUT`	Max DEST_HOST and RECV_HOST failure time before corrective measures are taken (secs)	`150`
`PRUNE_INTERVAL`	Interval for log file pruning	`12h`
`PRUNE_SIZE`	Maximum number of log lines left when pruning log files	`1000`
`BEASTDEV`	If defined, download the latest `beast-feeder.py` from the dev branch of the skysquitter22/beast-feeder repo. You can also define a different repo by putting the `raw` URL of the beast-feeder.py file as value to this parameter.	(not defined)
`SET_TIMESTAMP`	If not set to FALSE/OFF/DISABLED, the system will send timestamped data to the server. Note -- please only enable this if your system clock is GPS or NTP enabled and your container time is set to UTC	ENABLED
`NTP_REFSERVER`	Domain name of a NTP server that will be used to calculate the system's clock drift. Ignored if `SET_TIMESTAMP` is not switched on.
`pool.ntp.org`
`CLOCK_DIFF_LIMIT`	Maximum acceptable clock diff (in msec). If `SET_TIMESTAMP` is switched on and the `clock diff` exceeds this value, then data isn't sent to the server. Value when omitted: `200` (msec). Ignored if `SET_TIMESTAMP` is not switched on.
`DF_FILTER`	Comma separated list of Downlink Format messages that will be forwarded to the SkySquitter server, or `all` to forward all DF messages. If empty, the default value will be used. Do not change this value unless SkySquitter tells you to do so!	`17,20,21`
`VERBOSELOGS`	If set to TRUE/ON/ENABLED, it will show more verbose logging information in the Docker Logs.	Off

Mandatory Container Capabilities and System Controls

Make sure to add the following capabilities and system controls to your Docker Container. See docker-compose.yml for an example. These are mandatory for the container to work properly; specifically they are needed to enable the WireGuard secure connection to the SkySquitter service (NET_ADMIN and SYS_MODULE) and to reduce system load (SYS_NICE):

cap_add:
  - NET_ADMIN
  - SYS_MODULE
  - SYS_NICE
sysctls:
  - net.ipv4.conf.all.src_valid_mark=1

How do I know if things work?

There are several ways to figure out if things are working. Note - in the commands below, we are assuming that your SkySquitter container is named ssq. If you named it differently, please adapt the command accordingly.

What	How	Description
Container logs	`docker logs -f ssq`	The container logs provide a comprehensive view of everything that is happening: initial setup, config, parameters when running, etc. This may sometimes be a bit overwhelming - see below for more focused analytical tools.
Monitor	`docker exec -it ssq monitor`	This command will analyze the data flow between the Beast Host and the Server. If omitted, the `interval` is `3` secs and the `repeats` is `5` times. Any result that shows a non-zero packet count captured or received means that data is flowing from Beast Host to the Server.
Ping Beast Source	`docker exec -it ssq pingbeast`	This command will attempt to ping your Beast Source to see if it can be reached.
Ping Server	`docker exec -it ssq pingserver`	This command will attempt to ping the SkySquitter Server to see if it can be reached.
Watchdog logs	`docker exec -it ssq cat /var/log/feeder-watchdog.log`	This will show you up to 1000 lines of the Watchdog Logs. If nothing is shown, the logs are empty and the watchdog never had to take corrective action.

Troubleshooting

The SkySquitter container is reasonably "self-correcting": if your Beast Host or the SkySquitter network cannot be reached, it will take progressive steps to try to remedy the issue. The container restart itself if that is the case. If problems continue, then this has probably to do with your setup. Make sure that the capadd and sysctl sections are present in your docker-compose.yml file and use the example in this repo as your starting point. Make sure that the WG_PRIVKEY, WG_PSK, and MY_IP variables are set exactly as instructed by SkySquitter.

Configuration Alternatives

In some circumstances, SkySquitter may ask you to install a special "wg0.conf" network configuration. In that case, some of the environment variables from docker-compose.yml will be ignored by the container.

To install this wg0.conf file:

Go to the directory where your docker-compose.yml file is located. If you use the default values, you can do cd /opt/adsb
Initialize the container with docker-compose up -d - this will ensure that the mapped volume /opt/adsb/skysquitter is created and linked to the container.
Immediately stop the container again with docker-compose stop ssq
Copy the wg0.conf file into place. If the file is in the home directory of your local machine, you can do this with sudo cp ~/wg0.conf /opt/adsb/skysquitter
Restart the container stack with docker-compose up -d

OWNERSHIP AND LICENSE

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

kx1t / docker-skysquitter

readme