Rewrite README as proper asciidoc

2 files changed, 162 insertions, 141 deletions

diff --git a/README b/README
deleted file mode 100644
index 9c3aa12..0000000
--- a/README
+++ /dev/null
@@ -1,141 +0,0 @@
-ProxyChains ver 4.2.0 README
-==========================
-
-  ProxyChains is a UNIX program, that hooks network-related libc functions
-  in dynamically linked programs via a preloaded DLL and redirects the
-  connections through SOCKS4a/5 or HTTP proxies.
-
-*********** ATTENTION ***********
-
-  this program works only on dynamically linked programs.
-  also both proxychains and the program to call must use
-  the same dynamic linker (i.e. same libc)
-
-*********************************
-
-*** Known limitations of the current version: ***
-
-  when a process forks, does a DNS lookup in the child, and then uses
-  the ip in the parent, the corresponding ip mapping will not be found.
-  this is because the fork can't write back into the parents mapping table.
-  IRSSI shows this behaviour, so you have to pass the resolved ip address
-  to it. (you can use the proxyresolv script (requires "dig") to do so)
-
-  this means that you can't currently use tor onion urls for irssi.
-  to solve this issue, an external data store (file, pipe, ...) has to
-  manage the dns <-> ip mapping. of course there has to be proper locking.
-  shm_open, mkstemp, are possible candidates for a file based approach,
-  the other option is to spawn some kind of server process that manages the
-  map lookups. since connect() etc are hooked, this must not be a TCP server.
-
-  I am reluctant on doing this change, because the described behaviour
-  seems pretty idiotic (doing a fork only for a DNS lookup), and irssi
-  is currently the only known affected program.
-
-*** Installation ***
-
-  **** Using release version ****
-  Proxychains-4.2.0 are available with pkgsrc to everyone using it on Linux,
-  NetBSD, FreeBSD, OpenBSD, DragonFlyBSD or Mac OS X. You just need to install
-  pkgsrc-wip repository and run
-  	make install
-  in a wip/proxychains directory.
-
-  You can find out more about pkgsrc on [www.pkgsrc.org] and about pkgsrc-wip on
-  [http://pkgsrc-wip.sourceforge.net].
-
-  **** Installing on Mac OS X with homebrew ****
-  You can install current proxychains on Mac OS X with an homebrew. You have to download unofficial homebrew formula from [https://gist.github.com/3792521] to your BREW_HOME
-  by default /usr/local/Library/Formula/ and run
-
-  brew install proxychains
-
-  **** Running Current Source code version ****
-  # needs a working C compiler, preferably gcc
-  ./configure
-  make
-  sudo make install
-
-Changelog:
-----------
-
-Version (4.x) removes the dnsresolver script which required a dynamically
-linked "dig" binary to be present with remote DNS lookup.
-this speeds up any operation involving DNS, as the old script had to use TCP.
-additionally it allows to use .onion urls when used with TOR.
-also it removed the broken autoconf build system with a simple Makefile.
-there's a ./configure script though for convenience.
-it also adds support for a config file passed via command line switches/
-environment variables.
-
-Version (3.x) introduces support for DNS resolving through proxy
-it supports SOCKS4, SOCKS5 and HTTP CONNECT proxy servers.
-Auth-types: socks - "user/pass" , http - "basic".
-
-When to use it ?
-1) When the only way to get "outside" from your LAN is through proxy server.
-2) To get out from behind restrictive firewall which filters outgoing ports.
-3) To use two (or more) proxies in chain:
-	like: your_host <--> proxy1 <--> proxy2 <--> target_host
-4) To "proxify" some program with no proxy support built-in (like telnet)
-5) Access intranet from outside via proxy.
-5) To use DNS behind proxy.
-
-Some cool features:
-
-* This program can mix different proxy types in the same chain
-	like: your_host <-->socks5 <--> http <--> socks4 <--> target_host
-* Different chaining options supported
-	random order from the list ( user defined length of chain ).
-	exact order  (as they appear in the list )
-	dynamic order (smart exclude dead proxies from chain)
-* You can use it with any TCP client application, even network scanners
-	yes, yes - you can make portscan via proxy (or chained proxies)
-	for example with Nmap scanner by fyodor (www.insecire.org/nmap).
-	proxychains nmap -sT -PO -p 80 -iR  (find some webservers through proxy)
-* You can use it with servers, like squid, sendmail, or whatever.
-* DNS resolving through proxy.
-
-
-Configuration:
---------------
-
-proxychains looks for configuration in the following order:
-1)	SOCKS5 proxy port in environment variable ${PROXYCHAINS_SOCKS5}
-	(if set, no further configuration will be searched)
-2)	file listed in environment variable ${PROXYCHAINS_CONF_FILE} or
-	provided as a -f argument to proxychains script or binary.
-3)	./proxychains.conf
-4)	$(HOME)/.proxychains/proxychains.conf
-5)	/etc/proxychains.conf  **
-
-**see more in /etc/proxychains.conf
-
-Usage Example:
-
-	$ proxychains telnet targethost.com
-
-in this example it will run telnet through proxy(or chained proxies)
-specified by proxychains.conf
-
-Usage Example:
-
-      	$ proxychains -f /etc/proxychains-other.conf targethost2.com
-
-in this example it will use different configuration file then proxychains.conf
-to connect to targethost2.com host.
-
-Usage Example:
-
-	$ proxyresolv targethost.com
-
-in this example it will resolve targethost.com through proxy(or chained proxies)
-specified by proxychains.conf
-
-Usage Example:
-
-	$ ssh -fN -D 4321 some.example.com
-	$ PROXYCHAINS_SOCKS5=4321 proxychains zsh
-
-in this example, it will run a shell with all traffic proxied through
-OpenSSH's "dynamic proxy" (SOCKS5 proxy) on localhost port 4321.
diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..84c447f
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,162 @@
+= ProxyChains ver. 4.2.0 README
+
+image:https://travis-ci.org/haad/proxychains.svg?branch=master["Build Status", link="https://travis-ci.org/haad/proxychains"]
+
+ProxyChains is a UNIX program, that hooks network-related libc functions
+in dynamically linked programs via a preloaded DLL and redirects the
+connections through SOCKS4a/5 or HTTP proxies.
+
+WARNING: this program works only on dynamically linked programs.
+also both proxychains and the program to call must use
+the same dynamic linker (i.e. same libc)
+
+== Known limitations of the current version
+
+when a process forks, does a DNS lookup in the child, and then uses
+the ip in the parent, the corresponding ip mapping will not be found.
+this is because the fork can't write back into the parents mapping table.
+IRSSI shows this behaviour, so you have to pass the resolved ip address
+to it. (you can use the proxyresolv script (requires "dig") to do so)
+
+this means that you can't currently use tor onion urls for irssi.
+to solve this issue, an external data store (file, pipe, ...) has to
+manage the dns <-> ip mapping. of course there has to be proper locking.
+shm_open, mkstemp, are possible candidates for a file based approach,
+the other option is to spawn some kind of server process that manages the
+map lookups. since connect() etc are hooked, this must not be a TCP server.
+
+I am reluctant on doing this change, because the described behaviour
+seems pretty idiotic (doing a fork only for a DNS lookup), and irssi
+is currently the only known affected program.
+
+== Installation
+
+=== Using release version
+
+*Proxychains-4.2.0* are available with pkgsrc to everyone using it on _Linux_,
+_NetBSD_, _FreeBSD_, _OpenBSD_, _DragonFlyBSD_ or _Mac OS X_. You just need to install
+pkgsrc-wip repository and run
+  make install
+in a wip/proxychains directory.
+
+You can find out more about pkgsrc on [www.pkgsrc.org] and about pkgsrc-wip on
+link:http://pkgsrc-wip.sourceforge.net[Pkgsrc-wip homepage]
+
+=== Installing on Mac OS X with homebrew
+
+You can install current proxychains on Mac OS X with an homebrew. You have to
+download unofficial homebrew formula from [https://gist.github.com/3792521]
+to your BREW_HOME by default /usr/local/Library/Formula/ and run
+
+----
+$ brew install proxychains
+----
+
+=== Running Current Source code version
+
+----
+# needs a working C compiler, preferably gcc
+./configure
+make
+sudo make install
+----
+
+== Changelog
+
+*Version (4.x)* removes the dnsresolver script which required a dynamically
+linked "dig" binary to be present with remote DNS lookup.
+this speeds up any operation involving DNS, as the old script had to use TCP.
+additionally it allows to use .onion urls when used with TOR.
+also it removed the broken autoconf build system with a simple Makefile.
+there's a ./configure script though for convenience.
+it also adds support for a config file passed via command line switches/
+environment variables.
+
+*Version (3.x)* introduces support for DNS resolving through proxy
+it supports SOCKS4, SOCKS5 and HTTP CONNECT proxy servers.
+
+* Auth-types
+ ** socks - "user/pass",
+ ** http - "basic"
+
+== When to use it
+
+* When the only way to get "outside" from your LAN is through proxy server.
+* To get out from behind restrictive firewall which filters outgoing ports.
+* To use two (or more) proxies in chain:
+----
+   like: your_host <--> proxy1 <--> proxy2 <--> target_host
+----
+* To "proxify" some program with no proxy support built-in (like telnet)
+* Access intranet from outside via proxy.
+* To use DNS behind proxy.
+
+=== Some cool features
+
+* This program can mix different proxy types in the same chain
+----
+  like: your_host <-->socks5 <--> http <--> socks4 <--> target_host
+----
+* Different chaining options supported
+  random order from the list ( user defined length of chain ).
+  exact order  (as they appear in the list )
+  dynamic order (smart exclude dead proxies from chain)
+* You can use it with any TCP client application, even network scanners
+  yes, yes - you can make portscan via proxy (or chained proxies)
+  for example with Nmap scanner by fyodor (www.insecire.org/nmap).
+----
+  proxychains nmap -sT -PO -p 80 -iR  (find some webservers through proxy)
+----
+* You can use it with servers, like squid, sendmail, or whatever.
+* DNS resolving through proxy.
+
+== Configuration
+
+proxychains looks for configuration in the following order:
+
+* SOCKS5 proxy port in environment variable ${PROXYCHAINS_SOCKS5}
+  (if set, no further configuration will be searched)
+* file listed in environment variable ${PROXYCHAINS_CONF_FILE} or
+  provided as a -f argument to proxychains script or binary.
+* ./proxychains.conf
+* $(HOME)/.proxychains/proxychains.conf
+* /etc/proxychains.conf
+
+see more in */etc/proxychains.conf*
+
+=== Usage Example
+
+----
+$ proxychains telnet targethost.com
+----
+
+in this example it will run telnet through proxy(or chained proxies)
+specified by *proxychains.conf*
+
+=== Usage Example
+
+----
+$ proxychains -f /etc/proxychains-other.conf targethost2.com
+----
+
+in this example it will use different configuration file then *proxychains.conf*
+to connect to targethost2.com host.
+
+=== Usage Example
+
+----
+$ proxyresolv targethost.com
+----
+
+in this example it will resolve targethost.com through proxy(or chained proxies)
+specified by *proxychains.conf*
+
+=== Usage Example:
+
+----
+$ ssh -fN -D 4321 some.example.com
+$ PROXYCHAINS_SOCKS5=4321 proxychains zsh
+----
+
+in this example, it will run a shell with all traffic proxied through
+OpenSSH's "dynamic proxy" (SOCKS5 proxy) on localhost port 4321.