ENTROPY - Emerging Network To Reduce Orwellian Potency Yield
------------------------------------------------------------

Contents:
---------
1. People
2. Copyright
3. Introduction
4. Running Entropy
5. Support & Tools
6. Troubleshooting


1. People
---------
Juergen Buchmueller (pullmoll) - Creator
Mr. IKG - Encryption Support
Joey Stanford (Rescue) - Documentation Support
NightBlade - MySQL Support
TV - AutoConf Support
... and various others who wish to remain anonymous :-)

2. Copyright
------------
(c) Copyright  Juergen Buchmueller
Released under the GNU Public License Version 2.

3. Introduction
---------------
ENTROPY stands for Emerging Network To Reduce Orwellian Potency Yield and as
such describes the main goal of the project.  ENTROPY is developed as a
response to increasing censorship and surveillance in the internet.  The
program connects your computer to a network of machines which all run this
software.  The ENTROPY network is running parallel  to the WWW and also other
internet services like FTP, email, ICQ. etc.

For the user the ENTROPY network looks like a collection of WWW pages.  The
difference to the WWW however is that there are no accesses to central
servers.  And this is why there is no site operator who could log who
downloaded what and when.  Every computer taking part in the ENTROPY network
(every node) is at the same time server, router for other nodes, caching proxy
and client for the user: that is You. 

After you have gained some experience with the ENTROPY network, there are
command line tools for you to insert whole directory trees into the network as
a ENTROPY site.  So ENTROPY does for you what a web-space provider does for you
in the WWW - but without the storage and bandwidth costs and without any
regulation or policy as to what  kind of content you are allowed to publish.
Everyone can contribute his own ENTROPY site for everybody else to browse
through.  The contents is stored in a distributed manner across all available 
and reachable nodes and no one can find out about who put up what contents into
the network.  Even if your node is not actively running, your contents can be
retrieved by others -- without knowing that it was actually you who published
the files. Of course this is only true if you do not publish  your name (or
leave your name or other personal data in the files you publish).
 
4. Running Entropy
------------------
4.1 Requirements
------------------
 Basic requirements:
 You need the following environment and libraries on your *nix system:
  - GNU C Compiler (gcc)
  - GNU Make (e.g. gmake on systems where GNU make is not the default)
  - ZLib compression library (http://www.gzip.org/zlib/) 1.1.3 or newer
  - Expat XML library (http://expat.sourceforge.net/) 1.95.2 or newer

Most *nix systems have all of these in place already.  Mac OS 10.2 users
will need to install Expat.

Debian-Users can use the following commands :

apt-get install libc6-dev
apt-get install zlib1g-dev
apt-get install libexpat1-dev



System requirements: 
  - *nix-box, Windows-PC, Mac OS X, Darwin, or Yellow Dog Linux
  - internet-connection (at least 56K-Modem) 
  - at least 500 MB free disk-space (for the cache described above)
  - the Entropy software (download of ca. ~600K source or ~2M Windows zip)
  - some online-time with an IP-address not changing too quickly
  - a free TCP-port (You will probably have to adapt your firewall or NAT.
    see the next section for more information)
  - a web-browser addressing localhost/127.0.0.1 without proxy (for security)

----------------------------
4.2 Dealing with firewalls
----------------------------
For an Entropy node to work correctly, other Entropy nodes must be able to open
connections to it, and normally NATs or Firewalls will prevent this.

If you are behind a NAT or firewall you must do several things:

1) You should enter the external address of your NAT or firewall in the 
    'nodename' field in entropy.conf.  If you don't know what your external
    address is, you can get it from http://www.whatismyipaddress.com
2) Check the "nodeport" setting in your entropy.conf file. It will most likely
     be set to 37373
3) Configure your NAT or firewall to forward incoming TCP connections on this
    port to your computer (see your NAT or firewall's manual for instructions
    on how to do this)

-------------------------
4.3 Install and Compiling
-------------------------
1) Download the source or binary from a trusted source. If you are reading this
file you've probably accomplished that.

2) Edit "entropy.conf". If the file does not exist then copy from 
entropy.conf-dist, enter your nodename or ip, and modify any options you need
to.  Keep in mind that bandwidth limits are in bytes per second. So, for 
example, a cable modem connection of 1.5m/256k would be 192k/32k in the 
config file. 640k = 81k, 512k = 66k, etc. 

The calc is (bits per second speed*1024) / 8 = bytes per second.

You might consider subtracting 12k or so from your limits so as not to 
potentially impact any of your normal web related activites. This is not
known to be an issue but you might want to play it safe just in case.

3) Edit "seed.txt". If the file does not exist then copy from seed.txt-dist and 
enable several of the entries by removing the "#" symbol.

4) Type "./configure".  Configure will automatically generate a Makefile for
you, but sometimes it runs into problems.  The most common problem is "can't
find <expat.h>".  If you get this message, try running configure again with
"./configure --with-expat=/usr/local".

Optional Features:
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --disable-debug         disable debugging output
  --enable-verbose        enable verbose build messages
  --disable-warnings      disable extra compiler warnings
  --enable-max-peers=N    limit number of peer connections to N
  --disable-posix-sem     do not attempt to use POSIX unnamed semaphores
  --disable-svid-sem      do not attempt to use SysV semaphores
  --enable-ppc-g5         enable PowerPC G5 optimizations

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-zlib=path        specify that zlib is installed at path
  --with-expat=path       specify that expat is installed at path
  --with-mysql(=path)     use MySQL data store (MySQL is installed at path)
  --with-tree             use directory tree data store

Issue "./configure -h" for a full list of options.

5) Run GNU Make by typing "make" (or "gmake") and see if you get an 'entropy'
binary. If you do then you're ready to run entropy. During the build process you
may see occasional warnings. These are permissible but make sure there  are no
errors.  Common errors for entropy as a whole can be found near the end of this
document. A good build will end with "==> (your OS) build done".

----------------------------
4.4 Starting Entropy
---------------------------- 
Type "./run.sh" or "sh run.sh"
 
You can watch the log with "tail -f entropy.log" to verify that
there are no major issues or run "./loganalyze.sh", the Entropy 
log analyzer.

-----------------------------------
4.5 Accessing Entropy via the Proxy
-----------------------------------
You can look at some websites in Entropy by visiting http://localhost:9999/ in
your web browser.  You can also find interesting information about what your
node is doing there.

-----------------------------------
4.6 Stopping Entropy
-----------------------------------
Type "./stop.sh" or "sh stop.sh"

You can issue "ps -ax | grep entropy" to verify that entropy is no longer
active.

-----------------------------------
4.7 Updating Entropy
-----------------------------------
If you have downloaded the CVS version it is very easy to update your Entropy
node.

Type "./update.sh"

This will stop entropy, update your system with the latest edition, compile
entropy, and the run entropy.  Your ./configure options will be preserved.

If you have downloaded a .tar.gz or .zip source version or binary version,
upgrading is more difficult.  You will need to install the new source/binary and
then move your configuration files and data store over from the old copy of
Entropy to the new one.  Be sure to stop your old copy of Entropy before trying
to move the files.

To manually update, issue "cvs -z2 update -dAP" and then reconfigure as
directed in the previous section.

5. Support & Tools
------------------
The Entropy home-page can be found online at the following URL:
http://entropy.stop1984.com/

On the Entropy home-page you can find more information about how Entropy works
as well as download various tools which work with Entropy.

If you have questions you can:
  - post a message to http://f27.parsimony.net/forum66166/
  - post a message to the "entropy" news board (from inside entropy)
  
6. Troubleshooting 
------------------
Entropy has been tested and ported to FreeBSD, OpenBSD, NetBSD,
most X86 Linux distros, Yellow Dog Linux, and Mac OS X. Even though
this is the case, it's still possible that you may encounter an error 
when you first start up.  If none of the errors below match your error,
please post to the forum.

Please make sure you post your architecture (X86, PPC, etc.), your OS
(RH Linux 9.0, YDL 3.1, etc), your error, and also if you happen to be able to
generate a log report using "loganalyze.sh". This will expedite us helping you!

Thanks!  Now, on with the errors:


1) "Bus Error" - Entropy terminates with a bus error.  Check to make sure no
other copies of entropy are running (e.g. "ps -ax | grep entropy").  Make
sure your Makefile is setup for your architecture (e.g. X86, PPC).  Try
removing your store (e.g.  "rm -rf store") and run start.sh again.  Not
working? Fink is known to cause this error. Try removing the init.sh call
in your shell rc.

2) "undefined reference to" - generally occurs when the zlib and/or expat
libraries are unreachable during compilation. Verify that they exist on your
system. Try to manual specify their location in the Makefile.

3) "call failed (Operation timed out)" - a relatively normal message mostly due
to a low number of active nodes. If the problem persists, try updating using
update.sh and as a last resort, post the problem to the forum.

4) "call failed (Connection refused)" - Normal. The node you are trying to connect
to has reached it's connection or bandwidth limit.  If the problem persists,
try updating using update.sh

5) "failed (Not enough core)" - The cause of this error on some systems is not
generally known. We believe it to be a bug in the OS's MMAP routines. Try
updating using "update.sh". If the problem remains try compiling with MMAP
turned off. If the problem remains please post to the forum with your
system information.

6) "invalid module index" - normal. This happens occasionally when the proxy 
page node/config.html is dynamically created

7) "I don't have any peers" - This is caused almost exclusively by one of three
conditions: a) you didn't follow the instructions above and did not uncomment
a few seed nodes in seed.txt, b) you forgot to specify an ip address (or 
it's specified incorrectly) in entropy.conf, or c) you did not open up a
port on your firewall as described above.

8) "*** {xxxx} signal SIGHUP ***" followed shortly by "semaphore @xxxxxxx is 
not initialized" - normal. Entropy is shutting down.

9) "is dead (No such process)" - Rare. This happens when a process dies
unexpectedly or there is an error in the code. Check your system log
files for a crash message and report this to the forum. Look out for an
entropy.core file if you enabled core dumps on your system. You can then
load it into the GNU debugger (gdb entropy entropy.core) and then perhaps
see what was causing the death of the process.

10) "failed (Bad file descriptor)" - Rare. We've seen this when file permissions
are incorrectly set. Report to the forum with log snippet.

11) "unknown command 'ï¿½ï¿½mï" -
someone or some program is spamming your FCP port. This has only been seen
during Flood Attacks to Entropy.

12) "zapping key" followed by "failed (No such file or directory)" - Unusual.  
Entropy found a bad key and has deleted it from the store. Check the forums
to see if this is known problem. If you receive a large log of these errors
then please report on the forum.  You will usually see this message
accompanied by "fec_8_4 frag #0 key does not match" and "key mismatch meta
0x00 bytes".

13) "FATAL! mmap" followed by "failed (Permission denied)" - rare. 
Your system cannot MMAP the files. Try editing the Makefile,
turning off MMAP, and recompile.  The next step is to delete your
store and try again. (MMAP problems lay waste to store integrity).

14) "FATAL! mmap" followed by "failed (Invalid argument)" - rare. 
Your system is not dealing well with MMAP. Try editing the Makefile,
turning off MMAP, and recompile.  The next step is to delete your
store and try again. (MMAP problems lay waste to store integrity).

15) "entropy could not be shut down" - rare. Report to forum.

16) "crypto_module_name.670(src/crypt.c) invalid module index" - normal.
This happens when enumerating the crypto modules in the proxy. 

17) "pubkey part #0 failed (Input/output error)" - Unusual. This happens 
whenever an incoming connection isn't actually sending the peer's McEliece 
public key. It might be either a non-Entropy connection coming in or one 
that dies shortly after establishing the socket connection. If you see
this happening a lot, please post to the forum.

18) "sending 123.123.123.123:38986 pubkey part #2 failed (Broken pipe)"
"sending 123.123.123.123:38983 pubkey part #1 failed (Broken pipe)"
"sending 123.123.123.123:38983 pubkey part #0 failed (Broken pipe)"
These messages can be caused by Freenet nodes trying to talk to your Entropy
node.  This can happen if you run Entropy on a port where you once ran Freenet.
To get rid of them you will have to switch to a new port.  If you reject 
certain crypto schemes, you may also see this message. In that event, this
is not an error.

19) "peer_msg_valid.979(src/peer.c) invalid type 1/2 (too small)" - rare.
We're not sure why this happens. This could be a (very) old version of 
Entropy trying to connect your node. If so you see a lot of these please
post your information and a section of the log to the forum.

20) "peer_in_child.4814(src/peer.c) ADV found invalid key (some long key) in our 
own store" - Unusual. This is due to bad keys being maintained by older entropy
nodes. They are still there and seemingly they won't go away.  This could also
indicate that someone is trying to intentionally disturb the network.

21) "lzw_open.755(src/lzw.c) lzw_expand() size is xxxxx" - normal.
This is informational text, not an error.

22) "mem_free.836(src/memalloc.c) free: attempt to free unallocated memory"
- Unusual. Entropy tries to free a NULL pointer. Typically seen in the
code to handle the "virtual terminal in a GIF". If you get a lot of these
then please post to the forum.

23) "proxy_meta_parse.1414(src/proxy.c) size of 'meta' is zero" - normal.
This happens with inserts of documents that contain no meta data at all. 
FIW does this occasionally. The proxy handles this by adding a dummy 
meta data (Info.Description=file etc.) to the document before it is being parsed.

24) "initializing fec: tables ./run.sh: line 3: 17649 Segmentation fault 
./entropy --verbose" - This is possibly due to not having libexpat.a installed
as specified in the Makefile, usually in "/usr/local/lib/".

25) "# 7: initializing fec: tables Segmentation fault" - rare. We're 
unsure exactly what cause this error but several people have reported
that installing a non-low-latency kernel patch has proven successfull.

26) "No more processes." - You may see this message at the terminal. This is a known
problem with OS 10.2.x (personal not server) and not entropy.  The problem:
Apple has hardcoded in a max processes of 100 into the kernel for tcsh.
Executing "unlimit" has no effect unless you are root. In 10.3 the default is
bash and is believed to have fixed this.  Essentially, Entropy spawns a process
for each peer communication. Entropy has a current hardcoded max of 60 open
communications.  So with 60 processes and then the other Entropy processes (main
program, news, etc). You'll be close to or above 70.  This combined with your
local user processes (mail, finder, etc) comes to over 100.  For Mac OS 10.2
there are two possible but untested solutions: create a separate non-gui userid
and run entropy from there (this tends to get sticky  because of static vs
dynamic, or run entropy as root (ok, so this really isn't an option). Because of
the kernel hardcode, switching to bash will not work. If you are on a non-OS 10
operation system, try running "ulimit" or "unlimit" in an attempt to increase
your max processes limit. In 10.3 you can get around this quite easily:

	a) Create a file called:
	
	/etc/sysctl.conf 
	
	which contains something like this:
	
	# Turn up maxproc so we can really use the dual G5s
	kern.maxproc=2048
	
	# Turn up the maxproc per user so Entropy doesn't fail
	kern.maxprocperuid=512
	
	b) reboot
	
	c) Then, make sure you run:
	
	tcsh:
	unlimit
	(add this to your .cshrc or similar)
	
	bash:
	ulimit
	(add this to your .bashrc or similar)
	
	Running unlimit/ulimit opens up your session to the max that we defined in 
	/etc/sysctl.conf above.

27) "proc {xxxx} is dead" - Rare. This happens when a process dies
unexpectedly or there is an error in the code. Check your system log
files for a crash message and report this to the forum. Look out for an
entropy.core file if you enabled core dumps on your system. You can then
load it into the GNU debugger (gdb entropy entropy.core) and then perhaps
see what was causing the death of the process.

28) "Missing atomic assembly semaphore for your CPU platform"
   You should run ./configure first !

29) configure: error: C compiler can't find ...
   you should install zlib and expat, e.g. debian users should use :
     apt-get install libc6-dev
     apt-get install zlib1g-dev
     apt-get install libexpat1-dev
     
30) "shared memory initialization failed" - This is caused generally by one of two
problems:  1) You already have an entropy process running. If so stop it using
stop.sh, or kill if stop.sh doesn't work, and reissue run.sh.  2) The files in
your entropy directory where compiled by a different user. chown -R the files back
to your userid and group.
