RanchiMall/electrumx
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
782479e91c
electrumx/docs/ENVIRONMENT.rst
Neil Booth 151da40d5b 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
2017-02-18 12:43:45 +09:00

324 lines
10 KiB
ReStructuredText
Raw Blame History

=====================
Environment Variables
=====================
ElectrumX takes no command line arguments, instead its behaviour is
controlled by environment variables. Only a few are required to be
given, the rest will have sensible defaults if not specified. Many of
the defaults around resource usage are conservative; I encourage you
to review them.
Required
--------
These environment variables are always required:
* **DB_DIRECTORY**
The path to the database directory. Relative paths should be
relative to the parent process working directory. This is the
directory of the `run` script if you use it.
* **DAEMON_URL**
A comma-separated list of daemon URLs. If more than one is provided
ElectrumX will initially connect to the first, and failover to
subsequent ones round-robin style if one stops working.
The generic form of a daemon URL is:
`http://username:password@hostname:port/`
The leading `http://` is optional, as is the trailing slash. The
`:port` part is also optional and will default to the standard RPC
port for **COIN** and **NET** if omitted.
For the `run` script
--------------------
The following are required if you use the `run` script:
* **ELECTRUMX**
The path to the electrumx_server.py script. Relative paths should
be relative to the directory of the `run` script.
* **USERNAME**
The username the server will run as.
Miscellaneous
-------------
These environment variables are optional:
* **COIN**
Must be a *NAME* from one of the **Coin** classes in
`lib/coins.py`_. Defaults to `Bitcoin`.
* **NET**
Must be a *NET* from one of the **Coin** classes in `lib/coins.py`_.
Defaults to `mainnet`.
* **DB_ENGINE**
Database engine for the UTXO and history database. The default is
`leveldb`. The other alternative is `rocksdb`. You will need to
install the appropriate python package for your engine. The value
is not case sensitive.
* **REORG_LIMIT**
The maximum number of blocks to be able to handle in a chain
reorganisation. ElectrumX retains some fairly compact undo
information for this many blocks in levelDB. The default is a
function of **COIN** and **NET**; for Bitcoin mainnet it is 200.
* **HOST**
The host that the TCP and SSL servers will use. Defaults to
`localhost`. Set to blank to listen on all addresses (IPv4 and IPv6).
* **TCP_PORT**
If set ElectrumX will serve TCP clients on **HOST**:**TCP_PORT**.
* **SSL_PORT**
If set ElectrumX will serve SSL clients on **HOST**:**SSL_PORT**.
If set then SSL_CERTFILE and SSL_KEYFILE must be defined and be
filesystem paths to those SSL files.
* **RPC_PORT**
ElectrumX will listen on this port for local RPC connections.
ElectrumX listens for RPC connections unless this is explicitly set
to blank. The default is appropriate for **COIN** and **NET**
(e.g., 8000 for Bitcoin mainnet) if not set.
* **DONATION_ADDRESS**
The server donation address reported to Electrum clients. Defaults
to empty, which Electrum interprets as meaning there is none.
* **BANNER_FILE**
The path to a banner file to serve to clients in Electrum's
"Console" tab. Relative file paths must be relative to
**DB_DIRECTORY**. The banner file is re-read for each new client.
You can place several meta-variables in your banner file, which will be
replaced before serving to a client.
+ **$VERSION** is replaced with the ElectrumX version you are
runnning, such as *ElectrumX 0.9.22*.
+ **$DAEMON_VERSION** is replaced with the daemon's version as a
dot-separated string. For example *0.12.1*.
+ **$DAEMON_SUBVERSION** is replaced with the daemon's user agent
string. For example, `/BitcoinUnlimited:0.12.1(EB16; AD4)/`.
+ **$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
redacted text like 'xx.xx.xx.xx:xxx'. By default IP addresses will
be written to logs.
* **LOG_SESSIONS**
The number of seconds between printing session statistics to the
log. The output is identical to the **sessions** RPC command except
that **ANON_LOGS** is honoured. Defaults to 3600. Set to zero to
suppress this logging.
Resource Usage Limits
---------------------
The following environment variables are all optional and help to limit
server resource consumption and prevent simple DoS.
Address subscriptions in ElectrumX are very cheap - they consume about
160 bytes of memory each and are processed efficiently. I feel the
two subscription-related defaults below are low and encourage you to
raise them.
* **MAX_SESSIONS**
The maximum number of incoming connections. Once reached, TCP and
SSL listening sockets are closed until the session count drops
naturally to 95% of the limit. Defaults to 1,000.
* **MAX_SEND**
The maximum size of a response message to send over the wire, in
bytes. Defaults to 1,000,000. Values smaller than 350,000 are
taken as 350,000 because standard Electrum protocol header "chunk"
requests are almost that large.
The Electrum protocol has a flaw in that address histories must be
served all at once or not at all, an obvious avenue for abuse.
**MAX_SEND** is a stop-gap until the protocol is improved to admit
incremental history requests. Each history entry is appoximately
100 bytes so the default is equivalent to a history limit of around
10,000 entries, which should be ample for most legitimate users. If
you use a higher default bear in mind one client can request history
for multiple addresses. Also note that the largest raw transaction
you will be able to serve to a client is just under half of
MAX_SEND, as each raw byte becomes 2 hexadecimal ASCII characters on
the wire. Very few transactions on Bitcoin mainnet are over 500KB
in size.
* **MAX_SUBS**
The maximum number of address subscriptions across all sessions.
Defaults to 250,000.
* **MAX_SESSION_SUBS**
The maximum number of address subscriptions permitted to a single
session. Defaults to 50,000.
* **BANDWIDTH_LIMIT**
Per-session periodic bandwith usage limit in bytes. This is a soft,
not hard, limit. Currently the period is hard-coded to be one hour.
The default limit value is 2 million bytes.
Bandwidth usage over each period is totalled, and when this limit is
exceeded each subsequent request is stalled by sleeping before
handling it, effectively giving higher processing priority to other
sessions.
The more bandwidth usage exceeds this soft limit the longer the next
request will sleep. Sleep times are a round number of seconds with
a minimum of 1. Each time the delay changes the event is logged.
Bandwidth usage is gradually reduced over time by "refunding" a
proportional part of the limit every now and then.
* **SESSION_TIMEOUT**
An integer number of seconds defaulting to 600. Sessions with no
activity for longer than this are disconnected. Properly
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
---
Use the following environment variables if you want to advertise
connectivity on IRC:
* **IRC**
Set to anything non-empty to advertise on IRC
* **IRC_NICK**
The nick to use when connecting to IRC. The default is a hash of
**REPORT_HOST**. Either way a prefix will be prepended depending on
**COIN** and **NET**.
* **REPORT_HOST**
The host to advertise. Defaults to **HOST**.
* **REPORT_TCP_PORT**
The TCP port to advertise. Defaults to **TCP_PORT**. '0' disables
publishing the port.
* **REPORT_SSL_PORT**
The SSL port to advertise. Defaults to **SSL_PORT**. '0' disables
publishing the port.
* **REPORT_HOST_TOR**
The tor address to advertise; must end with `.onion`. If set, an
additional connection to IRC happens with '_tor' appended to
**IRC_NICK**.
* **REPORT_TCP_PORT_TOR**
The TCP port to advertise for Tor. Defaults to **REPORT_TCP_PORT**,
unless it is '0', otherwise **TCP_PORT**. '0' disables publishing
the port.
* **REPORT_SSL_PORT_TOR**
The SSL port to advertise for Tor. Defaults to **REPORT_SSL_PORT**,
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
-----
If synchronizing from the Genesis block your performance might change
by tweaking the cache size. Cache size is only checked roughly every
minute, so the cache can grow beyond the specified size. Moreover,
the Python process is often quite a bit fatter than the cache size,
because of Python overhead and also because leveldb consumes a lot of
memory when flushing. So I recommend you do not set this over 60% of
your available physical RAM:
* **CACHE_MB**
The amount of cache, in MB, to use. The default is 1,200.
A portion of the cache is reserved for unflushed history, which is
written out frequently. The bulk is used to cache UTXOs.
Larger caches probably increase performance a little as there is
significant searching of the UTXO cache during indexing. However, I
don't see much benefit in my tests pushing this too high, and in
fact performance begins to fall, probably because LevelDB already
caches, and also because of Python GC.
I do not recommend raising this above 2000. If upgrading from prior
versions, a value of 90% of the sum of the old UTXO_MB and HIST_MB
variables is roughly equivalent.
.. _lib/coins.py: https://github.com/kyuupichan/electrumx/blob/master/lib/coins.py
Reference in New Issue View Git Blame Copy Permalink