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.** It's recommended to run a pruning server with leveldb.
-It is a light setup with diskspace requirements well under 1 GB growing
-very moderately and less taxing on I/O and CPU once it's up and running.
-Full (archival) servers on the other hand use SQL. At the time of this writing,
-the Bitcoin blockchain is 5.5 GB large. The corresponding SQL database is
-about 4 times larger, so you should have a minimum of 22 GB free space just
-for SQL, growing continuously.
-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
-on SQL.
+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
+ $ ln -s ~/src/electrum/server/server.py ~/bin/electrum-server
-### Step 2. Download Bitcoind from git & patch it
+### Step 3. Download Bitcoind stable & patch it
-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.
+In order for the latest versions of Electrum to work properly we currently recommend bitcoind 0.8.5 stable.
+0.8.5 can be downloaded from github or sourceforge and it needs to be patched with an electrum specific patch.
+bitcoin@master i.e. git head may not currently work with electrum-server even if the patch applies cleanly.
- $ 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
+ $ cd ~/src && wget http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.5/bitcoin-0.8.5-linux.tar.gz
+ $ tar xfz bitcoin-0.8.5-linux.tar.gz
+ $ cd bitcoin-0.8.5-linux/src
+ $ patch -p1 < ~/src/electrum/server/patch/patch
+ $ cd src
+ $ sudo apt-get install make g++ python-leveldb libboost-all-dev libssl-dev libdb++-dev
+ $ make USE_UPNP= -f makefile.unix
+ $ strip ~/src/bitcoin-0.8.5-linux/src/src/bitcoind
+ $ ln -s ~/src/bitcoin-0.8.5-linux/src/src/bitcoind ~/bin/bitcoind
-### 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
time, running as the 'bitcoin' user. Check your system documentation to
find out the best way to do this.
-
-### Step 4. Select your backend - pruning leveldb or full abe server
-
-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
-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
-server.
-
-The full version uses abe as a backend. While the blockchain in bitcoind
-is at roughly 5.5 GB in January 2013, the abe mysql for a full server requires
-~25 GB diskspace for innodb and can take a week or two (!) 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 spent 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
-install jsonrcp (but not abe) from step 5 and then skip to step 8
-
### 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
- $ wget https://github.com/jtobey/bitcoin-abe/archive/v0.7.1.tar.gz
- $ cd bitcoin-abe
- $ sudo python setup.py install
-
-Electrum server does not currently support abe > 0.7.1 so please stick
-with 0.7.1 for the time being. If you're version is < 0.7 you need to upgrade
-to 0.7.1!
+ $ 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 6. Configure the database
+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 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.
-
-For MySQL:
-
- $ 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
+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 abe.
-For PostgreSQL:
+The section in the configuration file looks like this:
- TBW!
+ [leveldb]
+ path = /path/to/your/database
+ # for each address, history will be pruned if it is longer than this limit
+ pruning_limit = 100
-### Step 7. Configure Abe and import blockchain into the database
+### Step 8. Import blockchain into the database or download it
-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.
+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.
- $ cp ~/src/bitcoin-abe/abe.conf ~/abe.conf
- $ $EDITOR ~/abe.conf
+It's considerably faster to index in memory. You can use /dev/shm or indexing in RAM
+or create a tmpfs which will also use swap if you run out of memory:
-For MySQL, you need these lines:
+ $ sudo mount -t tmpfs -o rw,nodev,nosuid,noatime,size=6000M,mode=0777 none /tmpfs
- dbtype MySQLdb
- connect-args = { "db" : "electrum", "user" : "electrum" , "passwd" : "<database-password>" }
+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.
-For PostgreSQL, you need these lines:
+Alternatively you can fetch a pre-processed leveldb from the net
- TBD!
+You can fetch recent copies of electrum leveldb databases and further instructions
+from the Electrum full archival server foundry at:
+http://foundry.electrum.org/
-Start Abe:
- $ abe --config ~/abe.conf
+### Step 9. Create a self-signed SSL cert
-Abe will now start to import blocks. You will see a lot of lines like this:
+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.
- 'block_tx <block-number> <tx-number>'
+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.
-You should wait until you see this message on the screen:
+ $ 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 []:
+ ...
- Listening on http://localhost:2750
+ $ openssl x509 -req -days 730 -in server.csr -signkey server.key -out server.crt
-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.
+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
-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 in Septeber 2012):
+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.
- * 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.
+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.
-### 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
-If you're looking to run SSL / HTTPS you need to generate a self-signed certificate
-using openssl. Otherwise you can just comment out the SSL / HTTPS ports and run
-without.
+### 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
-### Step 9. (Finally!) Run Electrum server
+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.