From 8c54111139fd90059ac3fbfc2afdee67c532f351 Mon Sep 17 00:00:00 2001 From: Neil Booth Date: Mon, 26 Mar 2018 16:48:37 +0900 Subject: [PATCH] Improve envvar docs --- docs/ENVIRONMENT.rst | 281 +++++++++++++++++++++-------------------- docs/conf.py | 2 +- docs/rpc-interface.rst | 2 + 3 files changed, 148 insertions(+), 137 deletions(-) diff --git a/docs/ENVIRONMENT.rst b/docs/ENVIRONMENT.rst index 3811fbe..192bf44 100644 --- a/docs/ENVIRONMENT.rst +++ b/docs/ENVIRONMENT.rst @@ -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 `_ - 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 `_ + 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 diff --git a/docs/conf.py b/docs/conf.py index a34fea7..63763f7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. diff --git a/docs/rpc-interface.rst b/docs/rpc-interface.rst index ff06727..3b21adc 100644 --- a/docs/rpc-interface.rst +++ b/docs/rpc-interface.rst @@ -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 --------