electrumx/docs/ENV-NOTES

The following environment variables are required:

DB_DIRECTORY  - path to the database directory (if relative, to `run` script)
USERNAME      - the username the server will run as, if using `run` script
ELECTRUMX     - path to the electrumx_server.py script (if relative,
                to `run` script)
DAEMON_URL    - A comma-separated list of daemon URLS.  If more than one is
                provided ElectrumX will failover to the next when one stops
                working.  The generic form 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 if omitted.

The other environment variables are all optional and will adopt
sensible defaults if not specified.

COIN          - see lib/coins.py, must be a coin NAME.  Defaults to Bitcoin.
NETWORK       - see lib/coins.py, must be a coin NET.  Defaults to mainnet.
DB_ENGINE     - database engine for the transaction database.  Default is
                leveldb.  Supported alternatives are rocksdb and lmdb.
                You will need to install the appropriate python packages.
                Not case sensitive.
REORG_LIMIT   - 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.
                Default is 200.
HOST          - the host that the TCP and SSL servers will use.  Defaults to
                localhost.
TCP_PORT      - if set will serve Electrum TCP clients on that HOST:TCP_PORT
SSL_PORT      - if set will serve Electrum SSL clients on that HOST:SSL_PORT
                If set, SSL_CERTFILE and SSL_KEYFILE must be filesystem paths.
RPC_PORT      - Listen on this port for local RPC connections, defaults to
                8000.
BANNER_FILE   - a path to a banner file to serve to clients.  The banner file
                is re-read for each new client.
ANON_LOGS     - set to anything non-empty to remove IP addresses from
                logs. By default IP addresses will be logged.
DONATION_ADDRESS - server donation address.  Defaults to none.

These following environment variables are to help limit server
resource consumption and to prevent simple DoS.  Address subscriptions
in ElectrumX are very cheap - they consume about 100 bytes of memory
each and are processed efficiently.  I feel the defaults are low and
encourage you to raise them.

MAX_SEND         - maximum size of a response message to send over the wire,
                   in bytes.  Defaults to 350,000 and will treat smaller
                   values as the same because standard Electrum protocol
                   header chunk requests are nearly 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 3,500
                   entries, which should be ample for most legitimate
                   users.  Increasing by a single-digit factor is
                   likely fine but bear in mind one client can request
                   history for multiple addresses.
MAX_SUBS         - maximum number of address subscriptions across all
                   sessions.  Defaults to 250,000.
MAX_SESSION_SUBS - maximum number of address subscriptions permitted to a
                   single session.  Defaults to 50,000.

If you want IRC connectivity to advertise your node:

IRC             - set to anything non-empty
IRC_NICK        - the nick to use when connecting to IRC.  The default is a
                  hash of REPORT_HOST.  Either way 'E_' will be prepended.
REPORT_HOST     - the host to advertise.  Defaults to HOST.
REPORT_SSL_PORT - the SSL port to advertise.  Defaults to SSL_PORT.
REPORT_TCP_PORT - the TCP port to advertise.  Defaults to TCP_PORT.

If synchronizing from the Genesis block your performance might change
by tweaking the following cache variables.  Cache size is only checked
roughly every minute, so the caches can grow beyond the specified
size.  Also the Python process is often quite a bit fatter than the
combined cache size, because of Python overhead and also because
leveldb consumes a lot of memory during UTXO flushing.  So I recommend
you set the sum of these to nothing over half your available physical
RAM:

HIST_MB   - amount of history cache, in MB, to retain before flushing to
            disk.  Default is 300; probably no benefit being much larger
            as history is append-only and not searched.

UTXO_MB   - amount of UTXO and history cache, in MB, to retain before
            flushing to disk.  Default is 1000.  This may be too large
            for small boxes or too small for machines with lots of RAM.
            Larger caches generally perform better 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.  My
            machine has 24GB RAM; the slow down is probably because of
            leveldb caching and Python GC effects.  However this may be
            very dependent on hardware and you may have different
            results.

The following are for debugging purposes.

FORCE_REORG - if set to a positive integer, it will simulate a reorg
              of the blockchain for that number of blocks on startup.
              Although it should fail gracefully if set to a value
              greater than REORG_LIMIT, I do not recommend it as I have
              not tried it and there is a chance your DB might corrupt.