How To Run Iguana Core

From Komodo Platform Wiki
Jump to: navigation, search

This page will guide you to run Iguana natively on Linux, from the command shell. The procedures for other platforms will be included as they become available, although they should not differ much.

A usage guide for the Iguana graphical client will be also added after the first stable release.

This assumes you have already installed Iguana in your machine.

1 Run Main Iguana

The Iguana process needs to stay open in the shell window where you will launch it, so if you want to test Iguana from the command shell instead of the development GUI, the screen tool can be useful. You can find a simple introduction to it here.

From your SuperNET/iguana folder, run the Iguana executable.


The basic Iguana initialization will end with

>>>>>>>>>> iguana_rpcloop bind sock.4 iguana API enabled <<<<<<<<<

Now you can access the SuperNET API page with all the commands at the port 7778 in your machine. If you installed Iguana in your local computer, just open in your web browser http://localhost:7778.

2 Using Iguana as Bitcoin Client

Once the main Iguana process is running, you can start BTC and have Iguana work as Bitcoin client. Iguana connects to multiple Bitcoin nodes in parallel to obtain BTC blockchain data, and generates a fast access database that allows it to work as a block explorer, while keeping the data size to an efficient minimum. Iguana is built to work as a drop-in replacement for a full Bitcoin node, including compatibility with Bitcoin RPC calls.

In order to access the Bitcoin tools in a full Iguana node, you need to have an up-to-date copy of the Iguana BTC database in your server.

To use the default parameters to generate the Iguana BTC database, run


Iguana will build the BTC database processing the BTC blockchain completely from scratch.

3 Start BTC in Iguana

Once your Iguana instance is started and the Bitcoin data has been bootstrapped if needed, you can tell Iguana to add BTC as a running coin. There's two options:

3.1 - Using the SuperNET API Page

From the http://localhost:7778 SuperNET API page, scroll down to "iguana addcoin", click on it and enter BTC in the newcoin box, then click on the "addcoin" button.

3.2 - Using the command shell

From a second shell window and in the same path you ran Iguana from (usually ~/SuperNET/Iguana) you can run the script to start / generate BTC data with the default options:


In both cases, you'll see that the corresponding output will start to appear in the Iguana shell window. If you're generating the Iguana BTC data from scratch, the process might take a while depending on the performance of your machine and your network connection. If you're starting with BTC bootstrapped from block 412000, the first time you run BTC it might take a few minutes to validate the data and synchronize the remaining blocks until real time mode:

BTC.RT409056 u.204+c.205 b.205 v.204 (0+1056/1056 1st.204).s0 to 204 N[205] h.409056 r.409056 c.408000 s.409056 d.0 E.204 maxB.16 peers.209/256 Q.(0 0) (L.409056 204:1056) M.409055   0000000000000000011725505a4febb67bae03e6be89962ae72f36e8ea605e66 bQ.1 0:01:12 stuck.0 max.0

The BTC.RT line above is the Iguana coin status line you'll see frequently appear in your Iguana output, only interrupted by network information, new blocks processed as they are received, and the results of your own requests.

Now you are ready to use the Iguana Bitcoin RPC calls.

4 Exit Iguana

To close a running Iguana instance, just press Ctrl+C in the active Iguana shell or enter pkill -15 iguana in another shell window.

5 Troubleshooting

5.1 Problem: Iguana output gets stuck shortly after starting BTC

In some servers this might be due to ulimit (the system parameter that defines the limit for simultaneously open files) being too low - 1000, or 1024. The Iguana BTC database contains a large amount of files, that are accessed during runtime. You can check your current ulimit value just typing ulimit in the shell.

If Iguana log gets stuck for a long time soon after starting BTC, you may need to increase ulimit in your machine for the user running Iguana:

  • Stop Iguana with Ctrl+C
  • For a change in open files limit to be persistent (so it will continue in future shell sessions) you need to raise the ulimit values in the system configuration:
sudo nano /etc/security/limits.conf

and add the two following lines in the end of the file, replacing * with root if you're running Iguana as root.

* soft nofile 30000
* hard nofile 30000
  • Finally, you also need to edit
sudo nano /etc/pam.d/common-session

and add the following line:

session required

Now if you check the ulimit value you should get

# ulimit

And the next time you run Iguana the limit of files simultaneously open shouldn't keep Iguana BTC from starting up.