HOWTO

How do I install Entropy?

It depends. The preferred way is to follow the CVS access guidelines, and later the compilation guidelines.

If you don't want to use CVS, the second choice is to download the latest source tar-ball and follow the compilation guidelines.

What do I do after the binary was compiled?

Take a look into entropy.conf-dist and write a copy to entropy.conf, where you change values as desired. If you have a permanent IP or a (dynamic) hostname, you should put one of these after the nodename= in entropy.conf. It is not required, though! You must make sure that the port number specified in the nodeport= line (37373 is the default) is reachable from the outside; that is: if you're behind a firewall and/or have NAT running, be sure to forward the port to the machine where Entropy is running.

Secondly take a look into seed.txt-dist and write a copy to seed.txt, where you remove the comment character '#' from some or all lines with nodename:port contents. It should be sufficient to start with a few nodes, since Entropy will spread current IPs of nodes within the network. If you enable only one seed node entry and this specific node is offline, you're out of luck -- exception: your node's name or (fixed) IP is known to some other nodes. Then, if some of these nodes are restarting, they will contact your node and things should go on. You cannot expect this to happen if you have a brand-new node and IP or hostname, though.

How do I fire it up?

This is simple: run the run.sh script that came with the tar-ball (or was checked out from the CVS repository). You can just as well run the binary, perhaps giving the -v or --verbose option, so you see what's going on.

On the first start Entropy will create the data store files. This takes some time, depending on the storesize= you've chosen in entropy.conf. The next start-up times will be significantly shorter.

If all went well, the script (or the entropy binary) will return to the command prompt, leaving some daemon processes running in the background. At first there are seven processes (peer_threads, peer_bwlimit, peer_in, peer_out, client, proxy, news), but as soon as connections are established, more processes will be forked: one for every node connection. The maximum you can expect is 7 + 64 node connection processes (32 inbound and 32 outbound is the limit).

The processes share memory using either mmap (the default) or SysV shared memory (shm, which is a slower, less efficient fallback for older systems). Currently there's a shared memory range of 16MB that is used between all entropy processes. Every single process will consume some (private) extra memory, too. I would not suggest to run Entropy on a machine with less than 32MB physical RAM (and at least twice as much swap space) - you might try it, but there's no guarantee.

How do I stop it?

You should run the shell script stop.sh (i.e. ./stop.sh) or just call entropy -k or entropy --kill. Entropy will shut down the processes by sending them a signal. This will, however, sometimes fail for some processes, when they're stuck inside a system call -- or when I implemented another bug that makes the code not react on a signal.

To verify that everything was shut down, you can do a ps ax|grep entropy and see if anything is left. If a process is stuck even after some seconds -- while it might try to flush it's outgoing socket buffer -- you could issue a killall -9 entropy. This will send a SIGKILL to all entropy processes and they have no chance to survive it.

How do I change the size of the data store?

You do not. At least not for the default type, which is implemented as a monolithic store (ie. one or more, few, big files containing many data chunks). The other type of data store, which is enabled by specifying STORE_TYPE=1 in the Makefile, can have a different size from one Entropy session to another. However, due to the nature of this type of storage, there will always be a difference between the configured and the true size used (block size issues) and the space will sometimes be slightly above the configured size. Entropy purges the data store space every five minutes; if such a "store_purge" happens and the size of all files is above the configured size, Entropy begins to delete old or bad matched data files.

If you decide to go with the defaults, the monolithic store, it is best to first decided how much disk space you want to spend. Then you should decide if you prefer few, big files or many smaller ones. Many smaller ones have the advantage of shorter average locking times and thus a lower probability of processes colliding at the tries to access a file. On the other hand every Entropy process opens (up to) all data store files at once, so your system should allow a user to open up to "storedepth*(7+64)" files; ie. if you set storedepth=32 you could see Entropy trying to hold open up to 32*(7+64) = 2272 files. Some systems won't take this much.

After this many details, here's my suggestion: If you have less than 1GB for Entropy, go with the defaults. If you have up to 8GB, use 512MB files (that is enter storesize=xGB and storedepth=2*x in your entropy.conf). For everything above this, choose 1GB files. If you simply increase storesize=, Entropy will make sure that the storedepth= is big enough to not exceed the 1GB per file limit.