README
¶
peerscanner - register flashlight peer and fallback servers
peerscanner is a HTTP-based service for registering and unregistering flashlight servers so they can be used by the flashlight clients that run in Lantern installations when in get mode.
Pedantic note for the fastidious: for agility of exposition we say "flashlight server" to refer loosely to the machine where the flashlight server is running. Currently, the calls described below are made not by the flashlight program itself but by the Lantern client that is controlling it.
Operation
flashlight servers call a peerscanner endpoint periodically to advertise their availability and up-to-date contact details. If they have a chance, they also inform peerdnsreg when they become unavailable. Otherwise, peerdnsreg will automatically unregister a server from which it hasn't received updates for too long.
Registering
A flashlight server registers itself by making a POST request with the
/register path. The request parameters for this call are:
-
name: a string identifier that is not equal to that of any other machine registering in peerdnsreg. It must be a valid subdomain name, and a valid VCL identifier when prependedf_. To be on the safe side, use only ASCII digits and lowercase letters. Lantern peer clients use theirinstanceId, which meets these conditions. -
port: the port where this flashlight server can be reached from external clients (so, if the server is port mapped in a NAT, this would be the external port).
Heartbeat
peerscanner will periodically test peers to see if it can proxy through them and remove/add them to DNS as necessary.
Unregistration
If it has a chance, a flashlight server will announce that it is becoming
unavailable by making a POST request with path /unregister. The only
parameter is the name it provided back when it registered.
Deploying
peerscanner is deployed to Digital Ocean using the peerscanner salt configuration.
Installing for local testing
You need to set some environment variables to connect to CloudFlare. See envvars.bash.
To test it, use the -cfldomain command line flag, which specifies where to register/unregister servers. We have the test domain flashlightproxy.com for this purpose, so you'd say ./peerscanner -cfldomain flashlightproxy.com. Also, for any flashlight server to register to your test peerscanner you'd have to call it with ./flashlight -registerat https://yourserverurl.org.
You may use this test peerscanner to test stuff. ps-test.getiantem.org points to it. It's normally turned off. Whenever you want to test anything peerscanner related, feel free to log into it, copy over a new peerscanner binary, and start it.
Duplicate Checking
The program in dupecheck can be used to check the current CloudFlare DNS for
duplicates. CFL_ID=<username> CFL_KEY=<api key> go run dupecheck.go.
Documentation
¶
Overview ¶
peerscanner is a program that maintains entries in CDN and DNS services based on whether or not the corresponding Lantern servers are currently online. Online status is determined based on whether or not we can successfully proxy requests to popular sites like www.google.com in a reasonable amount of time via each host.
Peers are registered and unregistered via a web-based API (see file web.go).
Each host is modeled as an actor with its own goroutine that constantly tests connectivity via the host (see file host.go).
For each host, various CDN and DNS entries are managed:
- Cloudflare round-robin DNS+CDN entries. Each server has an A entry with the name "roundrobin.getiantem.org"[1] and its IP, with CDN functionality activated ("orange cloud").
- A Cloudflare DNS+CDN entry ("orange cloud"), specific to each server. This is used for sticky routing when domain fronting via Cloudflare.
- A DNSimple round-robin DNS entry ("roundrobin.flashlightproxy.org" [1]). This has no CDN functionality itself.
- A DNSimple DNS entry specific to each server.
- A Cloudfront distribution that points to the previous one.
Whenever peerscanner learns of a new server, it adds an entry of each kind above. Whenever peerscanner finds a server is offline, it deletes the round robin entries, but not the server specific ones, nor the Cloudfront distribution.
[1] Peerscanner used to manage, and may manage again in the future, servers
running on users' computers (give mode peers). For this reason, a "fallbacks.(getiantem|flashlightproxy).org" round-robin is currently being maintained too. Also, the ".(getiantem|flashlightproxy).org" parts are configurable via the -cfldomain and -dspdomain command line arguments.
main simply contains the primary web serving code that allows peers to register and unregister as give mode peers running within the Lantern network
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
package cfl provides a utility for interacting with CloudFlare
|
package cfl provides a utility for interacting with CloudFlare |
|
package cfr provides utilities for interaction with cloudfront
|
package cfr provides utilities for interaction with cloudfront |