Permalink
Browse files

Merge pull request #126 from SashaCrofter/master

Adjusted README code and markdown style
  • Loading branch information...
2 parents edeb55a + f6af18a commit 937c993cac8e37387ed774cb9fdd1d55c34c215e Caleb James DeLisle committed Oct 15, 2012
Showing with 78 additions and 90 deletions.
  1. +78 −90 README.md
View
168 README.md
@@ -16,7 +16,7 @@ views of the same problem.
We have a number of somewhat competing offerings to solve this problem from ISPs
and government. We have IPSEC, DNSSEC, numerous proposals from the mundane to
-the wild and whacky such as "internet drivers licenses".
+the wild and wacky such as "internet drivers licenses".
The people who have developed these proposals are unfortunately limited in
their thinking. ISPs are unable to see past the now almost 30 year old routing
@@ -74,7 +74,7 @@ MIPS, PowerPC32 and PowerPC64. It is continually tested on Linux and Apple OSX
systems. While the software itself is stable, the protocols and algorithms are
new inventions and we still don't understand how they work in the real world so
please update early and often to give developers the maximum latitude to make
-tweaks to the protocol and alogrithms.
+tweaks to the protocol and algorithms.
You Can Help!
@@ -120,24 +120,20 @@ Caleb James DeLisle == cjdelisle == cjd
##0. Install the build tools you will need.
- # apt-get install cmake git build-essential
-
+ sudo apt-get install cmake git build-essential
##1. Retrieve cjdns from GitHub.
-Grab it from GitHub and change to the source directory:
+Clone the repository from GitHub and change to the source directory:
- # git clone https://github.com/cjdelisle/cjdns.git cjdns
- # cd cjdns
+ git clone https://github.com/cjdelisle/cjdns.git cjdns
+ cd cjdns
##2. Build.
- # ./do
-
-Look for this:
-
- Build completed successfully, type ./cjdroute to begin setup.
+ ./do
+Look for `Build completed successfully, type ./cjdroute to begin setup.`, then proceed below:
--------------------------------------------------------------------------------
@@ -146,42 +142,36 @@ Look for this:
Run cjdroute without options for HELP:
- # ./cjdroute
+ ./cjdroute
##0: Make sure you've got the stuff.
- # cat /dev/net/tun
+ cat /dev/net/tun
If it says: `cat: /dev/net/tun: File descriptor in bad state` Good!
If it says: `cat: /dev/net/tun: No such file or directory`
Create it using:
- # sudo mkdir /dev/net ; sudo mknod /dev/net/tun c 10 200 && sudo chmod 0666 /dev/net/tun
+ sudo mkdir /dev/net ; sudo mknod /dev/net/tun c 10 200 && sudo chmod 0666 /dev/net/tun
Then `cat /dev/net/tun` again.
-If it says: `cat: /dev/net/tun: Permission denied` You're probably using a VPS based on the OpenVZ
-virtualization platform. Ask your provider to enable the TUN/TAP device, this is standard protocol
-so they should know exactly what you need.
+If it says: `cat: /dev/net/tun: Permission denied` You're probably using a VPS based on the OpenVZ virtualization platform. Ask your provider to enable the TUN/TAP device, this is standard protocol so they should know exactly what you need.
-##1: Generate a new configuration file.
+## 1: Generate a new configuration file.
- # ./cjdroute --genconf >> cjdroute.conf
+ ./cjdroute --genconf >> cjdroute.conf
-##2: Find a friend.
+## 2: Find a friend.
-In order to get into the network you need to meet someone who is also in the network and connect
-to them. This is required for a number of reasons:
+In order to get into the network you need to meet someone who is also in the network and connect to them. This is required for a number of reasons:
-1. It is a preventitive against abuse because bad people will be less likely to abuse a
- system after they were, in an act of human kindness, given access to that system.
-2. This is not intended to overlay The Old Internet, it is intended to replace it. Each connection
- will in due time be replaced by a wire, a fiber optic cable, or a wireless network connection.
-3. In any case of a disagreement, there will be a "chain of friends" linking the people involved
- so there will already be a basis for coming to a resolution.
+1. It is a preventitive against abuse because bad people will be less likely to abuse a system after they were, in an act of human kindness, given access to that system.
+2. This is not intended to overlay The Old Internet, it is intended to replace it. Each connection will in due time be replaced by a wire, a fiber optic cable, or a wireless network connection.
+3. In any case of a disagreement, there will be a "chain of friends" linking the people involved so there will already be a basis for coming to a resolution.
tl;dr Get out and make some human contact once in a while!
@@ -190,10 +180,9 @@ You can meet people to peer with in the IRC channel:
* irc://irc.EFNet.org/#cjdns
* http://chat.efnet.org:9090/?channels=%23cjdns&Login=Login
-NOTE: If you're just interested in setting up a local network between your own computers,
-this step is not necessary.
+NOTE: If you're just interested in setting up a local network between your own computers, this step is not necessary.
-##3: Fill in your friend's info.
+## 3: Fill in your friend's info.
In your cjdroute.conf file, you will see:
@@ -239,7 +228,7 @@ It looks like this:
`your.external.ip.goes.here` is to be replaced with the IPv4 address which people will use to
connect to you from over The Old Internet.
-##4: Start it up!
+## 4: Start it up!
sudo ./cjdroute < cjdroute.conf
@@ -255,47 +244,45 @@ If you want to be able to close your terminal and you don't use screen:
NOTE: when you use `&`, remember that you will have cjdroute processes running in the background
if you are having problems use `killall cjdroute` to return to sanity. Use `pgrep cjdroute` or `top` to see if it running.
-##5: Get in IRC
+## 5: Get in IRC
Welcome to the network, you are now a real network administrator.
There are responsibilities which come with being a network administrator which include
being available in case there is something wrong with your equipment. You can connect to irc via
irc.efnet.org.
The channel to join is #cjdns and you should stay there so that we are able to reach you.
-##Notes
+## Notes
-This starts cjdroute as the root user so cjdroute can configure your system and shed
-permissions. If you really want to start cjdroute as a non-root user, see Non-Standard Setups
-below.
+This starts cjdroute as the root user so cjdroute can configure your system and shed permissions. If you really want to start cjdroute as a non-root user, see Non-Standard Setups below.
-Protect your conf file! A lost conf file means you lost your password and connections
-and anyone who connected to you will nolonger be able to connect. A *compromized* conf
-file means that other people can impersonate you on the network.
+Protect your conf file! A lost conf file means you lost your password and connections and anyone who connected to you will nolonger be able to connect. A *compromised* conf file means that other people can impersonate you on the network.
chmod 400 cjdroute.conf
mkdir /etc/cjdns && cp ./cjdroute.conf /etc/cjdns/
-#Self-Check Your Network
+# Self-Check Your Network
Once your node is running, you're now a newly minted IPv6 host. Your operating
system may automatically reconfigure network services to use this new address.
If this is not what you intend, you should check to see that you are not
offering more services then you intended to. ;)
-##1: Obtain IP address.
+## 1: Obtain IP address.
Use `ifconfig -a` to find your TUN device's IPv6 address. (Same as above.)
-##2: Scan for open services.
+## 2: Scan for open services.
Run `nmap` to discover which services are accessible from this address.
For example, to scan the address fcf7:75f0:82e3:327c:7112:b9ab:d1f9:bbbe:
- # nmap -6 -n -r -v -p1-65535 -sT fcf7:75f0:82e3:327c:7112:b9ab:d1f9:bbbe
+ nmap -6 -n -r -v -p1-65535 -sT fcf7:75f0:82e3:327c:7112:b9ab:d1f9:bbbe
+
+This should result in an output like the following.
Starting Nmap 5.61TEST2 ( http://nmap.org ) at 2011-12-29 20:40 EST
Initiating Connect Scan at 20:40
@@ -337,113 +324,119 @@ Thats it for now! Got More? Tell us on IRC.
--------------------------------------------------------------------------------
-#Non-Standard Setups
-
-Instructions for building or installing in non-default ways.
+# Non-Standard Setups
**Most Users Don't Need To Read Below This Point**
-##Start cjdroute as non-root user.
+Instructions for building or installing in non-default ways.
+
+## Start cjdroute as non-root user.
If you're using an OpenVZ based VPS then you will need to use this as OpenVZ does not permit
persistent tunnels.
Create a cjdns user:
- # useradd cjdns
+ sudo useradd cjdns
Create a new TUN device and give the cjdns user authority to access it:
- # /sbin/ip tuntap add mode tun user cjdns dev cjdroute0
+ sudo /sbin/ip tuntap add mode tun user cjdns dev cjdroute0
-###4b-1: Setup the interface manually
+### 4b-1: Setup the interface manually
Run those commands to prepare your TUN device:
- # /sbin/ip addr add <your ipv6 address>/8 dev cjdroute0
- # /sbin/ip link set cjdroute0 up
+ sudo /sbin/ip addr add <your ipv6 address>/8 dev cjdroute0
+ sudo /sbin/ip link set cjdroute0 up
These commands should be executed as root now every time the system restarts.
-####Old versions of iproute2
+#### Old versions of iproute2
If you see an error when running /sbin/ip, your version of iproute2 might be old.
- # /sbin/ip tuntap add mode tun user cjdns
+ sudo /sbin/ip tuntap add mode tun user cjdns
Object "tuntap" is unknown, try "ip help".
The fix: for now grab a copy of a newer `ip` binary and copy it to your home
directory. Replacing the system binaries is not likely a good idea.
-##4b-2: Fire it up!
+## 4b-2: Fire it up!
- # sudo -u cjdns ./cjdroute < cjdroute.conf
+ sudo -u cjdns ./cjdroute < cjdroute.conf
To delete a tunnel, use this command:
- # /sbin/ip tuntap del mode tun <name of tunnel>
+ sudo /sbin/ip tuntap del mode tun <name of tunnel>
-##Dynamically linking to Libevent2
+## Dynamically linking to Libevent2
By default, the build process will search your system for Libevent2 and if it is not found,
it will download, compile, and statically link it. If you would like to link it dynamically
follow these instructions.
-###1: Remove older versions of dependencies: `libevent` and `libevent-dev`.
+### 1: Remove older versions of dependencies: `libevent` and `libevent-dev`.
Be sure libevent is gone and remove if found.
It will cause problems during the build.
Check to see which libevent is installed:
- # dpkg -l | grep ^ii| grep libevent
+ dpkg -l | grep ^ii| grep libevent
+
+This should produce:
+
ii libevent-dev 1.3e-3 Development libraries, header files and docs
ii libevent1 1.3e-3 An asynchronous event notification library
- # apt-get remove libevent-dev
+
+In such a case:
+
+ sudo apt-get remove libevent-dev
**Note: You may need to (re)compile TOR if you use it.**
-###2: Obtain latest `libevent2` dependency manually.
+### 2: Obtain latest `libevent2` dependency manually.
CHECK https://github.com/libevent/libevent for LATEST version.
(This document assumes 2.0.16.)
Grab the stable tarball from libevent and untar:
- # wget https://github.com/downloads/libevent/libevent/libevent-2.0.16-stable.tar.gz
- # tar -xzf libevent-2.0.16-stable.tar.gz
+ wget https://github.com/downloads/libevent/libevent/libevent-2.0.16-stable.tar.gz
+ tar -xzf libevent-2.0.16-stable.tar.gz
Enter directory and compile libevent:
- # cd libevent-2.0.16-stable
- # ./configure
+ cd libevent-2.0.16-stable
+ ./configure
Resolve missing dependencies if needed and run again until all errors gone:
- # make
- # make install
+ make
+ sudo make install
-###3: Compile cjdns using NO_STATIC.
+### 3: Compile cjdns using NO_STATIC.
By compiling with NO_STATIC, the process will fail rather than defaulting to static link.
- # NO_STATIC=1 cmake ..
- # make
+ NO_STATIC=1 cmake ..
+ make
You can also force a static build even if you have libevent2 by using:
- # STATIC=1 cmake ..
- # make
+ STATIC=1 cmake ..
+ make
-##Installing cjdns on OpenIndiana
+## Installing cjdns on OpenIndiana
In order to install cjdns on an OpenIndiana system, do the following:
@@ -460,7 +453,7 @@ In order to install cjdns on an OpenIndiana system, do the following:
Once it has completed successfully, simply type ./cjdroute and follow the normal instructions
-#Accessing the cjdns admin interface
+# Accessing the cjdns admin interface
When cjdnroute is up and running, an administrative interface will listen on localhost:11234
(this can be changed in the cjdroute.conf configuration file).
@@ -474,32 +467,27 @@ cjdns-tool
[cjdns-tool](https://github.com/kechagia/cjdns-tool) is a toolset for querying the admin api using the command line.
It is written in ruby and maintained by [kris kechagia](https://github.com/kechagia/). To install it, simply type
- $ sudo gem install cjdns-tool
+ sudo apt-get install rubygems
+ clone https://github.com/kechagia/cjdns-tool.git cjdns-tool
+ cd cjdns-tool
+ sudo gem install cjdns-tool
cjdns-tool can dump the local routing table in a traceroute-like fashion, as count routes as well as doing a ping sweep to see which nodes are alive and what their response time is. For usage information you can either type
- $ cjdns-tool help
+ cjdns-tool help
-and expore for yourself, or visit the [readme](https://github.com/kechagia/cjdns-tool/blob/master/README.md)
+and expore for yourself, or visit the [readme](https://github.com/kechagia/cjdns-tool/blob/master/README.md).
python library
--------------
-cjdns comes with a python library to access the api. For more information, read the [readme](https://github.com/cjdelisle/cjdns/blob/master/contrib/python/README.md)
+cjdns comes with a python library to access the api. For more information, read the [readme](https://github.com/cjdelisle/cjdns/blob/master/contrib/python/README.md).
perl library
------------
-the perl port of the python api library is maintained by Mikey. For usage instructions, head over to the [readme](https://github.com/cjdelisle/cjdns/blob/master/contrib/perl/CJDNS/README)
-
-
-ruby library
-------------
-
-[cjdns-tool](https://github.com/kechagia/cjdns-tool) uses [cjdns-lib](https://github.com/kechagia/cjdns-lib), which is a port of the python library to ruby. You can install it using
-
- gem install cjdns-lib
+The perl port of the python api library is maintained by Mikey. For usage instructions, head over to the [readme](https://github.com/cjdelisle/cjdns/blob/master/contrib/perl/CJDNS/README).

0 comments on commit 937c993

Please sign in to comment.