From 1bb8a9d5a40a4c7e706c70300909d92ca9588431 Mon Sep 17 00:00:00 2001 From: Neil Booth Date: Fri, 27 Jan 2017 08:22:37 +0900 Subject: [PATCH] Implement peer discovery protocol Closes #104 DEFAULT_PORTS now a coin property A Peer object maintains peer information Revamp LocalRPC "peers" call to show a lot more information Have lib/jsonrpc.py take care of handling request timeouts Save and restore peers to a file Loosen JSON RPC rules so we work with electrum-server and beancurd which don't follow the spec. Handle incoming server.add_peer requests Send server.add_peer registrations if peer doesn't have us or correct ports Verify peers at regular intervals, forget stale peers, verify new peers or those with updated ports If connecting via one port fails, try the other Add socks.py for SOCKS4 and SOCKS5 proxying, so Tor servers can now be reached by TCP and SSL Put full licence boilerplate in lib/ files Disable IRC advertising on testnet Serve a Tor banner file if it seems like a connection came from your tor proxy (see ENVIONMENT.rst) Retry tor proxy hourly, and peers that are about to turn stale Report more onion peers to a connection that seems to be combing from your tor proxy Only report good peers to server.peers.subscribe; always report self if valid Handle peers on the wrong network robustly Default to 127.0.0.1 rather than localhost for Python <= 3.5.2 compatibility Put peer name in logs of connections to it Update docs --- ENVIRONMENT.rst | 37 +++++++++++++++++++++++++++++++++++++ PEER_DISCOVERY.rst | 4 ++-- PROTOCOL.rst | 4 ++-- RPC-INTERFACE.rst | 29 ++++++++++++++++------------- 4 files changed, 57 insertions(+), 17 deletions(-) diff --git a/ENVIRONMENT.rst b/ENVIRONMENT.rst index 07c5204..e799b2a 100644 --- a/ENVIRONMENT.rst +++ b/ENVIRONMENT.rst @@ -122,6 +122,11 @@ These environment variables are optional: + **$DONATION_ADDRESS** is replaced with the address from the **DONATION_ADDRESS** environment variable. +* **TOR_BANNER_FILE** + + As for **BANNER_FILE** (which is also the default) but shown to + incoming connections believed to be to your Tor hidden service. + * **ANON_LOGS** Set to anything non-empty to replace IP addresses in logs with @@ -207,6 +212,33 @@ raise them. functioning Electrum clients by default will send pings roughly every 60 seconds. +TOR +--- + +In response to the `server.peers.subscribe` RPC call, ElectrumX will +only return peer servers that is has recently connected to and +verified basic functionality. + +If you are not running a Tor proxy ElectrumX will be unable to connect +to onion server peers, in which case rather than returning no onion +peers it will fall back to a hard-coded list. + +To give incoming clients a full range of onion servers you will need +to be running a Tor proxy for ElectrumX to use. + +* **TOR_PROXY_HOST** + + The host where the Tor proxy is running. Defaults to *127.0.0.1*. + If you use a hostname here rather than an IP address, you must have + Python version >= 3.5.3, Python 3.5.2 will **not** work. + +* **TOR_PROXY_PORT** + + The port on which the Tor proxy is running. If not set, ElectrumX + will autodetect any proxy running on the usual ports 9050 (Tor), + 9150 (Tor browser bundle) and 1080 (socks). + + IRC --- @@ -255,6 +287,11 @@ connectivity on IRC: unless it is '0', otherwise **SSL_PORT**. '0' disables publishing the port. + **NOTE**: Certificate-Authority signed certificates don't work over + Tor, so you should set **REPORT_SSL_PORT_TOR** to 0 if yours is not + self-signed. + + Cache ----- diff --git a/PEER_DISCOVERY.rst b/PEER_DISCOVERY.rst index 1187841..a69b9c3 100644 --- a/PEER_DISCOVERY.rst +++ b/PEER_DISCOVERY.rst @@ -160,8 +160,8 @@ Unknown keys should be silently ignored. * **protocol_min** Strings that are the minimum and maximum Electrum protcol versions - this server speaks. Should be the same as what would suffix the - letter **v** in the IRC real name. Example: "1.1". + this server speaks. The maximum value should be the same as what + would suffix the letter **v** in the IRC real name. Example: "1.1". * **pruning** diff --git a/PROTOCOL.rst b/PROTOCOL.rst index e5e372d..5f3151e 100644 --- a/PROTOCOL.rst +++ b/PROTOCOL.rst @@ -723,8 +723,8 @@ Get a list of features and services supported by the server. * **pruning** - The history pruning limit of the server. If the server does not - prune return *null*. + The history pruning limit of the server as an integer. If the + server does not prune return *null*. **Example Response** diff --git a/RPC-INTERFACE.rst b/RPC-INTERFACE.rst index 4816838..bb0aed9 100644 --- a/RPC-INTERFACE.rst +++ b/RPC-INTERFACE.rst @@ -62,10 +62,10 @@ The following commands are available: Sessions are put into groups, primarily as an anti-DoS measure. Initially all connections made within a period of time are put in the same group. High bandwidth usage by a member of a group - deprioritizes itself, and all members of its group to a lesser + deprioritizes that session, and all members of its group to a lesser extent. Low-priority sessions have their requests served after higher priority sessions. ElectrumX will start delaying responses - to a sessions if it becomes sufficiently deprioritized. + to a session if it becomes sufficiently deprioritized. * **sessions** @@ -125,7 +125,7 @@ The following commands are available: ElectrumX initiates the socket close process for the passed sessions. Whilst most connections close quickly, it can take - several minutes for Python to close some SSL connections down. + several minutes for Python to shut some SSL connections down. * **log** @@ -153,22 +153,25 @@ The following commands are available: Returns a list of peer electrum servers. This command takes no arguments. - Currently this is data gleaned from an IRC session. + Currently peer data is obtained via a peer discovery protocol; it + used to be taken from IRC. * **daemon_url** - This command takes an option argument that is interpreted - identically to the **DAEMON_URL** environment variable. If default - value of the argument is the **DAEMON_URL** environment variable. + This command takes an optional argument that is interpreted + identically to the **DAEMON_URL** environment variable. If omitted, + the default argument value is the process's **DAEMON_URL** + environment variable. - The command replaces the daemon's URL at run-time, and rotates to the - first in the list. + This command replaces the daemon's URL at run-time, and also + forecefully rotates to the first URL in the list. - For example, in case ElectrumX has rotated to a secondary daemon and - you want to revert to the first after fixing the issue, call this - command without an argument. + For example, in case ElectrumX has previously failed over to a + secondary daemon and you want to revert to the primary having + resolved the connectivity issue, invoking this command without an + argument will have that effect. * **reorg** Force a block chain reorg. This command takes an optional - argument - the number of blocks to reorg - that defaults to 3. + argument - the number of blocks to reorg - which defaults to 3.