Lines that lack hash or dollar signs are pastes from config files. They
should be copied verbatim or adapted, without the indentation tab.
+apt-get install commands are suggestions for required dependencies.
+They conform to an Ubuntu 13.04 system but may well work with Debian
+or earlier and later versions of Ubuntu.
+
Prerequisites
-------------
perform the operation described here, you are expected to fix the
issue so you can continue following this howto.
-**Software.** A recent Linux distribution with the following software
-installed: `python`, `easy_install`, `git`, a SQL server, standard C/C++
+**Software.** A recent Linux 64-bit distribution with the following software
+installed: `python`, `easy_install`, `git`, standard C/C++
build chain. You will need root access in order to install other software or
-Python libraries. You will need access to the SQL server to create users and
-databases.
-
-**Hardware.** Running a Bitcoin node and Electrum server is
-resource-intensive. At the time of this writing, the Bitcoin blockchain is
-3.5 GB large. The corresponding SQL database is about 4 time larger, so you
-should have a minimum of 14 GB free space. You should expect the total size
-to grow with time. CPU speed is also important, mostly for the initial block
-chain import, but also if you plan to run a public Electrum server, which
-could serve tens of concurrent requests. See step 6 below for some initial
-import benchmarks.
+Python libraries.
+
+**Hardware.** The lightest setup is a pruning server with diskspace
+requirements well under 1 GB growing very moderately and less taxing
+on I/O and CPU once it's up and running. However note that you also need
+to run bitcoind and keep a copy of the full blockchain, which is roughly
+9 GB in April 2013. If you have less than 2 GB of RAM make sure you limit
+bitcoind to 8 concurrent connections. If you have more ressources to
+spare you can run the server with a higher limit of historic transactions
+per address. CPU speed is also important, mostly for the initial block
+chain import, but also if you plan to run a public Electrum server, which
+could serve tens of concurrent requests. Any multi-core x86 CPU ~2009 or
+newer other than Atom should do for good performance.
Instructions
------------
-### Step 0. Create a user for running bitcoind and Electrum server
+### Step 1. Create a user for running bitcoind and Electrum server
This step is optional, but for better security and resource separation I
suggest you create a separate user just for running `bitcoind` and Electrum.
(others might want to use `/usr/local/bin` instead). We will download source
code files to the `~/src` directory.
- # sudo adduser bitcoin
+ # sudo adduser bitcoin --disabled-password
# su - bitcoin
$ mkdir ~/bin ~/src
$ echo $PATH
PATH="$HOME/bin:$PATH"
-### Step 1. Download and install Electrum
+### Step 2. Download and install Electrum
We will download the latest git snapshot for Electrum and 'install' it in
our ~/bin directory:
$ mkdir -p ~/src/electrum
$ cd ~/src/electrum
+ $ sudo apt-get install git
$ git clone https://github.com/spesmilo/electrum-server.git server
$ chmod +x ~/src/electrum/server/server.py
- $ ln -s ~/src/electrum/server/server.py ~/bin/electrum
-
-### Step 2. Donwnload Bitcoind from git & patch it
+ $ ln -s ~/src/electrum/server/server.py ~/bin/electrum-server
-In order for the latest versions of Electrum to work properly we will need to use the latest
-build from Git and also patch it with an electrum specific patch.
+### Step 3. Download bitcoind
- $ cd src && git clone git://github.com/bitcoin/bitcoin.git
- $ cd bitcoin
- $ patch -p1 < ~/src/electrum/server/patch/patch
- $ cd src && make -f makefile.unix
+Older versions of Electrum used to require a patched version of bitcoind.
+This is not the case anymore since bitcoind supports the 'txindex' option.
+We currently recommend bitcoind 0.8.5 stable.
-### Step 3. Configure and start bitcoind
+### Step 4. Configure and start bitcoind
In order to allow Electrum to "talk" to `bitcoind`, we need to set up a RPC
username and password for `bitcoind`. We will then start `bitcoind` and
rpcuser=<rpc-username>
rpcpassword=<rpc-password>
daemon=1
+ txindex=1
+
+
+If you have an existing installation of bitcoind and have not previously,
+set txindex=1 you need to reindex the blockchain by running
+
+ $ bitcoind -reindex
-Restart `bitcoind`:
+If you have a fresh copy of bitcoind start `bitcoind`:
$ bitcoind
time, running as the 'bitcoin' user. Check your system documentation to
find out the best way to do this.
-### Step 4. Install Electrum dependencies
+### Step 5. Install Electrum dependencies
Electrum server depends on various standard Python libraries. These will be
already installed on your distribution, or can be installed with your
-package manager. Electrum also depends on two Python libraries which we wil
-l need to install "by hand": `Abe` and `JSONRPClib`.
+package manager. Electrum also depends on two Python libraries which we will
+need to install "by hand": `JSONRPClib`.
+ $ sudo apt-get install python-setuptools
$ sudo easy_install jsonrpclib
- $ cd ~/src
- $ git clone git://github.com/jtobey/bitcoin-abe.git
- $ cd bitcoin-abe
- $ sudo python setup.py install
+ $ sudo apt-get install python-openssl
-Please note that the path below might be slightly different on your system,
-for example python2.6 or 2.8.
+### Step 6. Install leveldb
- $ sudo chmod +x /usr/local/lib/python2.7/dist-packages/Abe/abe.py
- $ ln -s /usr/local/lib/python2.7/dist-packages/Abe/abe.py ~/bin/abe
+ $ sudo apt-get install python-leveldb
+
+See the steps in README.leveldb for further details, especially if your system
+doesn't have the python-leveldb package.
+### Step 7. Select your limit
-### Step 5. Select your backend - pruning leveldb or full abe server
+Electrum server uses leveldb to store transactions. You can choose
+how many spent transactions per address you want to store on the server.
+The default is 100, but there are also servers with 1000 or even 10000.
+Few addresses have more than 10000 transactions. A limit this high
+can be considered to be equivalent to a "full" server. Full servers previously
+used abe to store the blockchain. The use of abe for electrum servers is now
+deprecated.
-Electrum server can currently be operated in two modes - as a pruning server
-or as a full server. The pruning server uses leveldb and keeps a smaller and
+The pruning server uses leveldb and keeps a smaller and
faster database by pruning spent transactions. It's a lot quicker to get up
-and running and requires less maintenance and diskspace than the full abe version
-
-The full version uses abe as a backend, the while the blockchain in bitcoind
-is at roughly 5 GB in January 2013, the abe mysql for a full server requires
-~22 GB diskspace for innodb and can take over a week to freshly index on most but
-the fastest of hardware.
-
-Full servers are useful for recovering all past transactions when restoring
-from seed. Those are then stored in electrum.dat and won't need to be recovered
-until electrum.dat is removed. Pruning servers summarize past transactions
-when restoring from seed which can be feature. Once seed recovery is done
-switching between pruning and full servers can be done at any time without effect
-to the transaction history stored in electrum.dat.
-
-While it's useful for Electrum to have a number of full servers it is
-expected that the vast majority of servers available publicly will be
-pruning servers.
-
-If you decide to setup a pruning server with leveldb take a break from this
-document, read and work through README.leveldb then come back and skip to step 8
-
+and running and requires less maintenance and diskspace than abe.
-### Step 6. Configure the database
+The section in the electrum server configuration file (see step 10) looks like this:
-Electrum server uses a SQL database to store the blockchain data. In theory,
-it supports all databases supported by Abe. At the time of this writing,
-MySQL and PostgreSQL are tested and work ok, SQLite was tested and *does not
-work* with Electrum server.
+ [leveldb]
+ path = /path/to/your/database
+ # for each address, history will be pruned if it is longer than this limit
+ pruning_limit = 100
-For MySQL:
+### Step 8. Import blockchain into the database or download it
- $ mysql -u root -p
- mysql> create user 'electrum'@'localhost' identified by '<db-password>';
- mysql> create database electrum;
- mysql> grant all on electrum.* to 'electrum'@'localhost';
- mysql> exit
+It's recommended to fetch a pre-processed leveldb from the net
-For PostgreSQL:
+You can fetch recent copies of electrum leveldb databases and further instructions
+from the Electrum full archival server foundry at:
+http://foundry.electrum.org/
- TBW!
+Alternatively if you have the time and nerve you can import the blockchain yourself.
-### Step 7. Configure Abe and import blockchain into the database
+As of April 2013 it takes between 6-24 hours to import 230k of blocks, depending
+on CPU speed, I/O speed and selected pruning limit.
-When you run Electrum server for the first time, it will automatically
-import the blockchain into the database, so it is safe to skip this step.
-However, our tests showed that, at the time of this writing, importing the
-blockchain via Abe is much faster (about 20-30 times faster) than
-allowing Electrum to do it.
+It's considerably faster to index in memory. You can use /dev/shm or
+or create a tmpfs which will also use swap if you run out of memory:
- $ cp ~/src/bitcoin-abe/abe.conf ~/abe.conf
- $ $EDITOR ~/abe.conf
+ $ sudo mount -t tmpfs -o rw,nodev,nosuid,noatime,size=6000M,mode=0777 none /tmpfs
-For MySQL, you need these lines:
+Figures from April 2013:
+At limit 100 the database comes to 2,6 GB with 230k blocks and takes roughly 6h to import in /dev/shm.
+At limit 1000 the database comes to 3,0 GB with 230k blocks and takes roughly 10h to import in /dev/shm.
+At limit 10000 the database comes to 3,5 GB with 230k blocks and takes roughly 24h to import in /dev/shm.
- dbtype MySQLdb
- connect-args = { "db" : "electrum", "user" : "electrum" , "passwd" : "<database-password>" }
+As of November 2013 expect at least double the time for indexing the blockchain. Databases have grown to
+roughly 4 GB, give or take a few hundred MB between pruning limits 100 and 10000.
-For PostgreSQL, you need these lines:
- TBD!
+### Step 9. Create a self-signed SSL cert
-Start Abe:
+To run SSL / HTTPS you need to generate a self-signed certificate
+using openssl. You could just comment out the SSL / HTTPS ports in the config and run
+without, but this is not recommended.
- $ abe --config ~/abe.conf
+Use the sample code below to create a self-signed cert with a recommended validity
+of 5 years. You may supply any information for your sign request to identify your server.
+They are not currently checked by the client except for the validity date.
+When asked for a challenge password just leave it empty and press enter.
-Abe will now start to import blocks. You will see a lot of lines like this:
+ $ openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
+ $ openssl rsa -passin pass:x -in server.pass.key -out server.key
+ writing RSA key
+ $ rm server.pass.key
+ $ openssl req -new -key server.key -out server.csr
+ ...
+ Country Name (2 letter code) [AU]:US
+ State or Province Name (full name) [Some-State]:California
+ Common Name (eg, YOUR name) []: electrum-server.tld
+ ...
+ A challenge password []:
+ ...
- 'block_tx <block-number> <tx-number>'
+ $ openssl x509 -req -days 730 -in server.csr -signkey server.key -out server.crt
-You should wait until you see this message on the screen:
+The server.crt file is your certificate suitable for the ssl_certfile= parameter and
+server.key corresponds to ssl_keyfile= in your electrum server config
- Listening on http://localhost:2750
+Starting with Electrum 1.9 the client will learn and locally cache the SSL certificate
+for your server upon the first request to prevent man-in-the middle attacks for all
+further connections.
-It means the blockchain is imported and you can exit Abe by pressing CTRL-C.
-You will not need to run Abe again after this step, Electrum server will
-update the blockchain by itself. We only used Abe because it is much faster
-for the initial import.
+If your certificate is lost or expires on the server side you currently need to run
+your server with a different server name along with a new certificate for this server.
+Therefore it's a good idea to make an offline backup copy of your certificate and key
+in case you need to restore it.
-Important notice: This is a *very* long process. Even on fast machines,
-expect it to take hours. Here are some benchmarks for importing
-~196K blocks (size of the Bitcoin blockchain at the time of this writing):
-
- * System 1: ~9 hours.
- * CPU: Intel Core i7 Q740 @ 1.73GHz
- * HDD: very fast SSD
- * System 2: ~55 hours.
- * CPU: Intel Xeon X3430 @ 2.40GHz
- * HDD: 2 x SATA in a RAID1.
-
-### Step 8. Configure Electrum server
+### Step 10. Configure Electrum server
Electrum reads a config file (/etc/electrum.conf) when starting up. This
file includes the database setup, bitcoind RPC setup, and a few other
Go through the sample config options and set them to your liking.
If you intend to run the server publicly have a look at README-IRC.md
-### Step 9. (Finally!) Run Electrum server
+### Step 11. Tweak your system for running electrum
+
+Electrum server currently needs quite a few file handles to use leveldb. It also requires
+file handles for each connection made to the server. It's good practice to increase the
+open files limit to 16k. This is most easily achived by sticking the value in .bashrc of the
+root user who usually passes this value to all unprivileged user sessions too.
+
+ $ sudo sed -i '$a ulimit -n 16384' /root/.bashrc
+
+We're aware the leveldb part in electrum server may leak some memory and it's good practice to
+to either restart the server once in a while from cron (preferred) or to at least monitor
+it for crashes and then restart the server. Weekly restarts should be fine for most setups.
+If your server gets a lot of traffic and you have a limited amount of RAM you may need to restart
+more often.
+
+Two more things for you to consider:
+
+1. To increase security you may want to close bitcoind for incoming connections and connect outbound only
+
+2. Consider restarting bitcoind (together with electrum-server) on a weekly basis to clear out unconfirmed
+ transactions from the local the memory pool which did not propagate over the network
+
+### Step 12. (Finally!) Run Electrum server
The magic moment has come: you can now start your Electrum server:
- $ server
+ $ electrum-server
You should see this on the screen:
`~/src/electrum/server`. You can use them as a starting point to create a
init script for your system.
-### Step 10. Test the Electrum server
+### Step 13. Test the Electrum server
We will assume you have a working Electrum client, a wallet and some
transactions history. You should start the client and click on the green
response time in the Server selection window. You should send/receive some
bitcoins to confirm that everything is working properly.
-### Step 11. Join us on IRC
+### Step 13. Join us on IRC, subscribe to the server thread
Say hi to the dev crew, other server operators and fans on
irc.freenode.net #electrum and we'll try to congratulate you
on supporting the community by running an Electrum node
+
+If you're operating a public Electrum server please subscribe
+to or regulary check the following thread:
+https://bitcointalk.org/index.php?topic=85475.0
+It'll contain announcements about important updates to Electrum
+server required for a smooth user experience.