lukechilds
/
electrumx
mirror of https://github.com/lukechilds/electrumx.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Improve envvar docs

patch-2
Neil Booth 7 years ago
parent
b33cf8b8ce
commit
8c54111139
3 changed files with 148 additions and 137 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 281
      docs/ENVIRONMENT.rst
  2. 2
      docs/conf.py
  3. 2
      docs/rpc-interface.rst

281
docs/ENVIRONMENT.rst
View File

@ -16,188 +16,194 @@ must set **HOST** appropriately; see below.
Required
--------
========
These environment variables are always required:
* **COIN**
.. envvar:: COIN
Must be a *NAME* from one of the **Coin** classes in
Must be a :attr:`NAME` from one of the :class:`Coin` classes in
`lib/coins.py`_.
* **DB_DIRECTORY**
.. envvar:: 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**
.. envvar:: 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:
The generic form of a daemon URL is::
`http://username:password@hostname:port/`
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.
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 :envvar:`COIN` and :envvar:`NET` if omitted.
For the `run` script
--------------------
For the ``run`` script
======================
The following are required if you use the `run` script:
The following are required if you use the ``run`` script:
* **ELECTRUMX**
.. envvar:: ELECTRUMX
The path to the electrumx_server.py script. Relative paths should
be relative to the directory of the `run` script.
be relative to the directory of the ``run`` script.
* **USERNAME**
.. envvar:: USERNAME
The username the server will run as.
Miscellaneous
-------------
=============
These environment variables are optional:
* **LOG_FORMAT**
.. envvar:: LOG_FORMAT
The Python logging `format string
<https://docs.python.org/3/library/logging.html#logrecord-attributes>`_
to use. Defaults to `%(levelname)s:%(name)s:%(message)s`.
to use. Defaults to ``%(levelname)s:%(name)s:%(message)s``.
* **ALLOW_ROOT**
.. envvar:: ALLOW_ROOT
Set this environment variable to anything non-empty to allow running
ElectrumX as root.
* **NET**
.. envvar:: NET
Must be a *NET* from one of the **Coin** classes in `lib/coins.py`_.
Defaults to `mainnet`.
Must be a :envvar:`NET` from one of the **Coin** classes in
`lib/coins.py`_. Defaults to ``mainnet``.
* **DB_ENGINE**
.. envvar:: 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.
``leveldb``. The other alternative is ``rocksdb``. You will need
to install the appropriate python package for your engine. The
value is not case sensitive.
* **HOST**
.. envvar:: HOST
The host or IP address that the TCP and SSL servers will use when
binding listening sockets. Defaults to `localhost`. To listen on
binding listening sockets. Defaults to ``localhost``. To listen on
multiple specific addresses specify a comma-separated list. Set to
an empty string to listen on all available interfaces (likely both
IPv4 and IPv6).
* **TCP_PORT**
.. envvar:: TCP_PORT
If set ElectrumX will serve TCP clients on **HOST**:**TCP_PORT**.
If set ElectrumX will serve TCP clients on
:envvar:`HOST`\::envvar:`TCP_PORT`.
**Note**: ElectrumX will not serve TCP connections until it has
fully caught up with your daemon.
.. note:: ElectrumX will not serve TCP connections until it has
fully caught up with your daemon.
* **SSL_PORT**
.. envvar:: 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.
If set ElectrumX will serve SSL clients on
:envvar:`HOST`\::envvar:`SSL_PORT`. If set then
:envvar:`SSL_CERTFILE` and :envvar:`SSL_KEYFILE` must be defined
environment variables with values the filesystem paths to those SSL
files.
**Note**: ElectrumX will not serve SSL connections until it has
fully caught up with your daemon.
.. note:: ElectrumX will not serve SSL connections until it has
fully caught up with your daemon.
* **RPC_HOST**
.. envvar:: RPC_HOST
The host or IP address that the RPC server will listen on and
defaults to `localhost`. To listen on multiple specific addresses
defaults to ``localhost``. To listen on multiple specific addresses
specify a comma-separated list. Servers with unusual networking
setups might want to specify e.g. `::1` or `127.0.0.1` explicitly
rather than defaulting to `localhost`.
setups might want to specify e.g. ``::1`` or ``127.0.0.1``
explicitly rather than defaulting to ``localhost``.
An empty string (normally indicating all interfaces) is interpreted
as `localhost`, because allowing access to the server's RPC
interface to arbitrary connections across the internet is not a
good idea.
as ``localhost``, because allowing access to the server's RPC
interface to arbitrary connections across the internet is not a good
idea.
* **RPC_PORT**
.. envvar:: 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 depends on **COIN** and **NET** (e.g., 8000
for Bitcoin mainnet) if not set, as indicated in `lib/coins.py`_.
to blank. The default depends on :envvar:`COIN` and :attr:`NET`
(e.g., 8000 for Bitcoin mainnet) if not set, as indicated in
`lib/coins.py`_.
* **DONATION_ADDRESS**
.. envvar:: DONATION_ADDRESS
The server donation address reported to Electrum clients. Defaults
to empty, which Electrum interprets as meaning there is none.
* **BANNER_FILE**
.. envvar:: 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.
:envvar:`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.
+ **$SERVER_VERSION** is replaced with the ElectrumX version you are
running, such as *1.0.10*.
+ **$SERVER_SUBVERSION** is replaced with the ElectrumX user agent
string. For example, `ElectrumX 1.0.10`.
+ **$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.
+ ``$SERVER_VERSION`` is replaced with the ElectrumX version you are
running, such as ``1.0.10``.
+ ``$SERVER_SUBVERSION`` is replaced with the ElectrumX user agent
string. For example, ``ElectrumX 1.0.10``.
+ ``$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
:envvar:`DONATION_ADDRESS` environment variable.
See https://github.com/shsmith/electrumx-banner-updater for a script
that updates a banner file periodically with useful statistics about
fees, last block time and height, etc.
See `here <https://github.com/shsmith/electrumx-banner-updater>`_
for a script that updates a banner file periodically with useful
statistics about fees, last block time and height, etc.
* **TOR_BANNER_FILE**
.. envvar:: 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.
As for :envvar:`BANNER_FILE` (which is also the default) but shown
to incoming connections believed to be to your Tor hidden service.
* **ANON_LOGS**
.. envvar:: 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.
redacted text like ``xx.xx.xx.xx:xxx``. By default IP addresses
will be written to logs.
* **LOG_SESSIONS**
.. envvar:: 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.
log. The output is identical to the :ref:`sessions` RPC command
except that :envvar:`ANON_LOGS` is honoured. Defaults to 3600. Set
to zero to suppress this logging.
* **REORG_LIMIT**
.. envvar:: 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.
function of :envvar:`COIN` and :attr:`NET`; for Bitcoin mainnet it
is 200.
* **EVENT_LOOP_POLICY**
.. envvar:: EVENT_LOOP_POLICY
The name of an event loop policy to replace the default asyncio
policy, if any. At present only `uvloop` is accepted, in which case
you must have installed the `uvloop`_ Python package.
policy, if any. At present only ``uvloop`` is accepted, in which
case you must have installed the `uvloop`_ Python package.
If you are not sure what this means leave it unset.
Resource Usage Limits
---------------------
=====================
The following environment variables are all optional and help to limit
server resource consumption and prevent simple DoS.
@ -207,13 +213,13 @@ Address subscriptions in ElectrumX are very cheap - they consume about
two subscription-related defaults below are low and encourage you to
raise them.
* **MAX_SESSIONS**
.. envvar:: 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**
.. envvar:: 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
@ -222,28 +228,28 @@ raise them.
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 approximately
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**
:envvar:`MAX_SEND` is a stop-gap until the protocol is improved to
admit incremental history requests. Each history entry is
approximately 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 :envvar:`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.
.. envvar:: MAX_SUBS
The maximum number of address subscriptions across all sessions.
Defaults to 250,000.
* **MAX_SESSION_SUBS**
.. envvar:: MAX_SESSION_SUBS
The maximum number of address subscriptions permitted to a single
session. Defaults to 50,000.
* **BANDWIDTH_LIMIT**
.. envvar:: BANDWIDTH_LIMIT
Per-session periodic bandwidth usage limit in bytes. This is a soft,
not hard, limit. Currently the period is hard-coded to be one hour.
@ -261,7 +267,7 @@ raise them.
Bandwidth usage is gradually reduced over time by "refunding" a
proportional part of the limit every now and then.
* **SESSION_TIMEOUT**
.. envvar:: SESSION_TIMEOUT
An integer number of seconds defaulting to 600. Sessions with no
activity for longer than this are disconnected. Properly
@ -270,10 +276,10 @@ raise them.
Peer Discovery
--------------
==============
In response to the `server.peers.subscribe` RPC call, ElectrumX will
only return peer servers that it has recently connected to and
In response to the :func:`server.peers.subscribe` RPC call, ElectrumX
will only return peer servers that it has recently connected to and
verified basic functionality.
If you are not running a Tor proxy ElectrumX will be unable to connect
@ -287,19 +293,20 @@ ElectrumX will perform peer-discovery by default and announce itself
to other peers. If your server is private you may wish to disable
some of this.
* **PEER_DISCOVERY**
.. envvar:: PEER_DISCOVERY
This environment variable is case-insensitive and defaults to `on`.
This environment variable is case-insensitive and defaults to
``on``.
If `on`, ElectrumX will occasionally connect to and verify its
If ``on``, ElectrumX will occasionally connect to and verify its
network of peer servers.
If `off`, peer discovery is disabled and a hard-coded default list
of servers will be read in and served. If set to `self` then peer
If ``off``, peer discovery is disabled and a hard-coded default list
of servers will be read in and served. If set to ``self`` then peer
discovery is disabled and the server will only return itself in the
peers list.
* **PEER_ANNOUNCE**
.. envvar:: PEER_ANNOUNCE
Set this environment variable to empty to disable announcing itself.
If not defined, or non-empty, ElectrumX will announce itself to
@ -310,21 +317,22 @@ some of this.
peer discovery if it notices it is not present in the peer's
returned list.
* **FORCE_PROXY**
.. envvar:: FORCE_PROXY
By default peer discovery happens over the clear internet. Set this
to non-empty to force peer discovery to be done via the proxy. This
might be useful if you are running a Tor service exclusively and
wish to keep your IP address private.
* **TOR_PROXY_HOST**
.. envvar:: TOR_PROXY_HOST
The host where your Tor proxy is running. Defaults to *localhost*.
The host where your Tor proxy is running. Defaults to
``localhost``.
If you are not running a Tor proxy just leave this environment
variable undefined.
* **TOR_PROXY_PORT**
.. envvar:: 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),
@ -332,50 +340,52 @@ some of this.
Server Advertising
------------------
==================
These environment variables affect how your server is advertised
by peer discovery (if enabled).
* **REPORT_HOST**
.. envvar:: REPORT_HOST
The clearnet host to advertise. If not set, no clearnet host is
advertised.
* **REPORT_TCP_PORT**
.. envvar:: REPORT_TCP_PORT
The clearnet TCP port to advertise if **REPORT_HOST** is set.
Defaults to **TCP_PORT**. '0' disables publishing a TCP port.
The clearnet TCP port to advertise if :envvar:`REPORT_HOST` is set.
Defaults to :envvar:`TCP_PORT`. ``0`` disables publishing a TCP
port.
* **REPORT_SSL_PORT**
.. envvar:: REPORT_SSL_PORT
The clearnet SSL port to advertise if **REPORT_HOST** is set.
Defaults to **SSL_PORT**. '0' disables publishing an SSL port.
The clearnet SSL port to advertise if :envvar:`REPORT_HOST` is set.
Defaults to :envvar:`SSL_PORT`. ``0`` disables publishing an SSL
port.
* **REPORT_HOST_TOR**
.. envvar:: REPORT_HOST_TOR
If you wish run a Tor service, this is the Tor host name to
advertise and must end with `.onion`.
advertise and must end with ``.onion``.
* **REPORT_TCP_PORT_TOR**
.. envvar:: REPORT_TCP_PORT_TOR
The Tor TCP port to advertise. The default is the clearnet
**REPORT_TCP_PORT**, unless disabled or it is '0', otherwise
**TCP_PORT**. '0' disables publishing a Tor TCP port.
:envvar:`REPORT_TCP_PORT`, unless disabled or it is ``0``, otherwise
:envvar:`TCP_PORT`. ``0`` disables publishing a Tor TCP port.
* **REPORT_SSL_PORT_TOR**
.. envvar:: REPORT_SSL_PORT_TOR
The Tor SSL port to advertise. The default is the clearnet
**REPORT_SSL_PORT**, unless disabled or it is '0', otherwise
**SSL_PORT**. '0' disables publishing a Tor SSL port.
:envvar:`REPORT_SSL_PORT`, unless disabled or it is ``0``, otherwise
:envvar:`SSL_PORT`. ``0`` disables publishing a Tor SSL 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.
.. note:: Certificate-Authority signed certificates don't work over
Tor, so you should set :envvar:`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
@ -387,7 +397,7 @@ your available physical RAM:
.. _CACHE:
* **CACHE_MB**
.. envvar:: CACHE_MB
The amount of cache, in MB, to use. The default is 1,200.
@ -400,9 +410,8 @@ your available physical RAM:
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.
I do not recommend raising this above 2000.
.. _lib/coins.py: https://github.com/kyuupichan/electrumx/blob/master/lib/coins.py
.. _lib/coins.py:
https://github.com/kyuupichan/electrumx/blob/master/lib/coins.py
.. _uvloop: https://pypi.python.org/pypi/uvloop

2
docs/conf.py
View File

@ -92,7 +92,7 @@ html_theme_options = {
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.

2
docs/rpc-interface.rst
View File

@ -172,6 +172,8 @@ That number of blocks will be backed up - using undo information
stored in ElectrumX's database - and then ElectrumX will move forwards
on the daemon's main chain to its current height.
.. _sessions:
sessions
--------

Write Preview
Loading…
Cancel
Save