« Spothole Help

Running your own DX Cluster Node

If you run your own Spothole server and want to receive spots from the DX cluster, you don't need your own cluster node. Spothole's example config file connects to the cluster node at spothole.app, which is a general node available for use, though note that it comes with the same lack-of-uptime guarantee as spothole.app itself! If you find reliability/uptime issues, you can point your copy of Spothole at one of the many public DX cluster nodes, such as W3LPL at w3lpl.net port 7373. Make sure the SSID you log in with (e.g. -99) is different to any personal connection you make to the same cluster node from a logger, otherwise the two connections may clash and one of you will get kicked off when the other connects.

If you want users of your Spothole server to be able to post spots to the DX cluster network, you will need to run your own cluster node. Spothole keeps a single connection to the cluster node, logged in as the callsign you set, and posts spots on behalf of users with the dx by <spotter> command. Public cluster nodes won't let a normal user do this, because it lets them post spots under anyone's callsign. On your own node, you can allow it for Spothole's login only.

This page describes how to do that with DXSpider, which is the cluster software used by spothole.app. Other cluster software may have similar settings.

Installing DXSpider

Follow the installation instructions, either from the DXSpider website or somewhere else that has an equivalent set. The cluster node at Spothole.app runs DXSpider in a Docker container, for which there is a great project here with full setup and configuration instructions: 9M2PJU DXSpider Docker.

There are several branches of DXSpider in the wild. For this setup, we need the "mojo" branch, which the 9M2PJU instructions use.

Before setting up Spothole to connect to the node, make sure you have set it up with a node callsign, and set up your sysop user. Port 7300 (or an alternative you choose) must be open in your firewall so that other users and cluster nodes can connect to yours. I suggest giving it a few days to make sure you've got your cluster configuration sorted and to establish partner relationships with other nodes before connecting Spothole in.

Once you are ready, set up the cluster config in config.yml to point to your server. Pick a callsign which your copy of Spothole will log into the server with. As above, if you're using your own callsign here, I recommend using an SSID to make sure it doesn't conflict with any other connection you make to the node as yourself.

Allowing Spothole to post spots

Firstly, before any upstream spotting is allowed from Spothole to anywhere, you must ensure that the config options allow_add and allow_add_upstream are turned on. You should also make sure that protect_add is enabled too (along with setting up API keys and/or CAPTCHA)—other sysops on the cluster network will not thank you if your Spothole instance allows drive-by spamming of the cluster! More information about these settings is available on the Running your own Server page.

That's enough to get your Spothole users spotting upstream to POTA etc., but for the cluster there is an extra step.

Spothole users (either from the web interface, or from Spothole API clients down the line) will be spotting under their own callsigns, not the callsign you have set up Spothole to use when logging into your cluster node. DXSpider has a dx by command which allows a user to spot as another user, but it is not normally enabled for basic users. To use it, your Spothole user must have privilege level 2 or higher on the cluster node. (Normal users have privilege 0, so they can only post spots under their own callsign.)

DXSpider sets a user's privilege to 0 when they connect without a password, so Spothole's login must have a password as well as a privilege level. From the sysop console, create a user record for Spothole's login callsign, set its password, and set its privilege level to 2:

set/register YOURCALL-99
set/password YOURCALL-99 <password>
set/privilege 2 YOURCALL-99

Next, configure Spothole to log in with that callsign and password, and set allows_dx_by to true, in config.yml:

  - class: "DXCluster"
    name: "Cluster"
    enabled: true
    host: "cluster.example.com"
    port: 7300
    login_prompt: "login:"
    login_callsign: "YOURCALL-99"
    password_prompt: "password:"
    password: "<password>"
    allows_dx_by: true

Finally, restart Spothole. Your users will then see the cluster as an option when adding a spot. Any spots they submit will be posted to your cluster node under their own callsign, and from there shared with the rest of the DX cluster network.

Forwarding spots from other sources to your node's users

Spothole can also forward the spots it receives from its other sources, such as POTA, SOTA and WWFF, to your cluster node. This then becomes a third way to view Spothole's combined spots feed: the web interface, the API, and also via a traditional telnet cluster feed that can be used in desktop logging software. This is a separate option to all of the above, and unlike the other options it does require adding some custom scripts on the cluster node itself, so it must be a node that you own.

Spots that came from a cluster or from RBN aren't forwarded via this mechanism, as they would be duplicates of what the cluster network already has. Neither are spots submitted to Spothole via its API or web interface, as those can already be sent to the cluster using dx by, via the mechanism described above. UK Packet Network and APRS-IS spots are also prevented from going up to the cluster node this way, as they would overwhelm the feed.

The rest of the DX cluster network would not thank you for flooding it with every xOTA spot, so these spots must never leave your node. Spothole doesn't send them with the dx by command, but with a custom command, xotaspot, which you need to install on your DXSpider node. This command:

  • sends the spot only to users connected directly to your node, and not to other nodes,
  • sends it only to users who have opted in to receive these spots (they are off by default),
  • can only be used by the user Spothole runs as (based on it having privilege level 2 as configured above)

Users of your node can opt in to receiving these spots with the set/xota command, and opt out again with unset/xota. You may want to add a note about these commands to your node's MOTD (message of the day), which users see when they log in, in /spider/local_data/motd. (If your server enforces registration, non-registered users will instead see MOTD content from /spider/local_data/motd_nor.)

Older DXSpider documentation refers to these files in /spider/data. The mojo branch moves them to /spider/local_data when it starts up (if a copy exists in both places, it picks whichever was modified most recently, and keeps using that one until it is restarted), so edit the copy in /spider/local_data. The file is re-read every time someone logs in, so changes take effect at the user's next login without restarting DXSpider. Users can see the current MOTD at any time with show/motd.

To set this up, copy the three files from the misc/dxspider/local_cmd directory in the Spothole source code into your node's local_cmd directory (normally /spider/local_cmd), keeping the same directory structure:

/spider/local_cmd/xotaspot.pl
/spider/local_cmd/set/xota.pl
/spider/local_cmd/unset/xota.pl

Make sure they are readable by the user DXSpider runs as. DXSpider picks up new commands automatically, so there's no need to restart it. Spothole's login must already have a password and privilege level 2, as described in the previous section. Then set forward_other_spots to true in your cluster config in config.yml, and restart Spothole:

  - class: "DXCluster"
    name: "Cluster"
    enabled: true
    host: "cluster.example.com"
    port: 7300
    login_prompt: "login:"
    login_callsign: "YOURCALL-99"
    password_prompt: "password:"
    password: "<password>"
    allows_dx_by: true
    forward_other_spots: true

Please note:

  • Forwarded spots are shown with the time they were posted to the cluster node, rather than the time of the original spot. I don't believe there's any way around that.
  • If you log into your node manually as the user Spothole runs as, do not run set/xota on its login. Spothole would then receive these spots as if they were cluster spots, duplicating the ones it already gets from POTA, SOTA etc. directly. If you want to test set/xota, use your personal login instead.

Telling your users about your node

If your cluster node is one that your Spothole users can connect to from their own logging software, set dedicated_node to true in its cluster config in config.yml. Spothole's help pages will then tell users how to connect to it, what spots they will see, and how to turn the forwarded spots on and off with set/xota and unset/xota. The address and port shown to users are the host and port Spothole uses to connect to the node, so if Spothole connects to it as localhost, change this to the node's public address.

« Back

Powered by