[iodine-users] [patch] Split the man page -> iodine(8) / iodined(8)

Sun Jan 8 14:52:55 CET 2012

Hello,

I find confusing to combine man pages of the two tools.  One is either looking
at configuring the client host or the server host.

The first section is the same this way.  It would be better to combine it but
I am not sure which all platforms is the distro package compatible with.  May
I use m4?  May I use Perl?  Installing three files and combining them during
man page compilation by groff may be too complicated.


Thanks,
Jan

--- iodine-0.6.0-rc1-orig/Makefile	2009-01-25 22:40:04.000000000 +0100
+++ iodine-0.6.0-rc1/Makefile	2012-01-08 14:45:19.310809769 +0100
@@ -41,13 +41,13 @@ install: all
 	$(INSTALL) $(INSTALL_FLAGS) bin/iodined $(DESTDIR)$(sbindir)/iodined
 	chmod 755 $(DESTDIR)$(sbindir)/iodined
 	$(MKDIR) $(MKDIR_FLAGS) $(DESTDIR)$(mandir)/man8
-	$(INSTALL) $(INSTALL_FLAGS) man/iodine.8 $(DESTDIR)$(mandir)/man8/iodine.8
-	chmod 644 $(DESTDIR)$(mandir)/man8/iodine.8
+	$(INSTALL) $(INSTALL_FLAGS) man/iodine{,d}.8 $(DESTDIR)$(mandir)/man8/
+	chmod 644 $(DESTDIR)$(mandir)/man8/iodine{,d}.8
 
 uninstall:
 	$(RM) $(RM_FLAGS) $(DESTDIR)$(sbindir)/iodine
 	$(RM) $(RM_FLAGS) $(DESTDIR)$(sbindir)/iodined
-	$(RM) $(RM_FLAGS) $(DESTDIR)$(mandir)/man8/iodine.8
+	$(RM) $(RM_FLAGS) $(DESTDIR)$(mandir)/man8/iodine{,d}.8
 	
 test: all
 	@echo "!! The check library is required for compiling and running the tests"
--- iodine-0.6.0-rc1-orig/man/iodine.8	2009-12-29 21:10:02.000000000 +0100
+++ iodine-0.6.0-rc1/man/iodine.8	2012-01-08 14:43:48.256155811 +0100
@@ -1,7 +1,7 @@
 .\" groff -man -Tascii iodine.8
 .TH IODINE 8 "DEC 2009" "User Manuals"
 .SH NAME
-iodine, iodined \- tunnel IPv4 over DNS
+iodine \- tunnel IPv4 over DNS
 .SH SYNOPSIS
 .B iodine [-v]
 
@@ -39,38 +39,6 @@ iodine, iodined \- tunnel IPv4 over DNS
 .B ]
 .I topdomain
 
-.B iodined [-v]
-
-.B iodined [-h]
-
-.B iodined [-c] [-s] [-f] [-D] [-u
-.I user
-.B ] [-t
-.I chrootdir
-.B ] [-d
-.I device
-.B ] [-m
-.I mtu
-.B ] [-l
-.I listen_ip
-.B ] [-p
-.I port
-.B ] [-n
-.I external_ip
-.B ] [-b
-.I dnsport
-.B ] [-P
-.I password
-.B ] [-z
-.I context
-.B ] [-F
-.I pidfile
-.B ]
-.I tunnel_ip
-.B [
-.I /netmask
-.B ]
-.I topdomain
 .SH DESCRIPTION
 .B iodine
 lets you tunnel IPv4 data through a DNS 
@@ -214,55 +182,6 @@ SERVFAIL errors even with \-I1; data wil
 and these errors can be ignored.
 Maximum useful value is 59, since iodined will close a client's
 connection after 60 seconds of inactivity.
-.SS Server Options:
-.TP
-.B -c
-Disable checking the client IP address on all incoming requests.
-By default, requests originating from non-matching IP adresses will be
-rejected, however this will cause problems when requests are routed
-via a cluster of DNS servers.
-.TP
-.B -s
-Don't try to configure IP address or MTU. 
-This should only be used if you have already configured the device that will be
-used.
-.TP
-.B -D
-Increase debug level. Level 1 prints info about each RX/TX packet.
-Implies the
-.B -f
-option.
-On level 2 (-DD) or higher, DNS queries will be printed literally.
-When using Base128 upstream encoding, this is best viewed as
-ISO Latin-1 text instead of (illegal) UTF-8.
-This is easily done with : "LC_ALL=C luit iodined -DD ..."
-(see luit(1)).
-.TP
-.B -m mtu
-Set 'mtu' as mtu size for the tun device. 
-This will be sent to the client on login, and the client will use the same mtu
-for its tun device.  Default 1130.  Note that the DNS traffic will be
-automatically fragmented when needed.
-.TP
-.B -l listen_ip
-Make the server listen only on 'listen_ip' for incoming requests.
-By default, incoming requests are accepted from all interfaces.
-.TP
-.B -p port
-Make the server listen on 'port' instead of 53 for traffic. 
-.B Note:
-You must make sure the dns requests are forwarded to this port yourself.
-.TP
-.B -n external_ip
-The IP address to return in NS responses. Default is to return the address used
-as destination in the query.
-.TP
-.B -b dnsport
-If this port is specified, all incoming requests not inside the tunnel domain
-will be forwarded to this port on localhost, to be handled by a real dns.
-.B Note:
-The forwarding is not fully transparent, and not advised for use
-in production environments.
 .SS Client Arguments:
 .TP
 .B nameserver
@@ -280,38 +199,6 @@ domain name to get better throughput. If
 .B nameserver
 is the iodined server, then the topdomain can be chosen freely. This argument
 must be the same on both the client and the server.
-.SS Server Arguments:
-.TP
-.B tunnel_ip[/netmask]
-This is the server's ip address on the tun interface. The client will be
-given the next ip number in the range. It is recommended to use the 
-10.0.0.0 or 172.16.0.0 ranges. The default netmask is /27, can be overriden
-by specifying it here. Using a smaller network will limit the number of
-concurrent users.
-.TP
-.B topdomain
-The dns traffic is expected to arrive as queries for
-subdomains under 'topdomain'. This is normally a subdomain to a domain you 
-own. Use a short domain name to get better throughput. This argument must be 
-the same on both the client and the server. Queries for domains other
-than 'topdomain' will be forwarded when the \-b option is given, otherwise
-they will be dropped.
-.SH EXAMPLES
-See the README file for both a quick test scenario, and a detailed description
-of real-world deployment.
-.SH SECURITY
-Login is a relatively secure challenge-response MD5 hash, with the
-password never passing the wire.
-However, all other data is
-.B NOT
-encrypted in any way. The DNS traffic is also vulnerable to replay,
-injection and man-in-the-middle attacks, especially when iodined is used
-with the \-c option. Use of ssh or vpn tunneling is strongly recommended.
-On both server and client, use
-.IR iptables ,
-.I pf
-or other firewalls to block all traffic coming in from the tun interfaces,
-except to the used ssh or vpn ports.
 .SH ENVIRONMENT
 .SS IODINE_PASS
 If the environment variable
@@ -320,16 +207,9 @@ is set, iodine will use the value it is
 for one. The 
 .B -P
 option still has precedence.
-.SS IODINED_PASS
-If the environment variable
-.B IODINED_PASS
-is set, iodined will use the value it is set to as password instead of asking
-for one. The
-.B -P
-option still has precedence.
-.El
 .SH SEE ALSO
-The README file in the source distribution contains some more elaborate
+\fBiodined\fR(8),
+the README file in the source distribution contains some more elaborate
 information.
 .SH BUGS
 File bugs at http://dev.kryo.se/iodine/
--- iodine-0.6.0-rc1-orig/man/iodined.8	1970-01-01 01:00:00.000000000 +0100
+++ iodine-0.6.0-rc1/man/iodined.8	2012-01-08 14:43:56.903123419 +0100
@@ -0,0 +1,187 @@
+.\" groff -man -Tascii iodined.8
+.TH IODINE 8 "DEC 2009" "User Manuals"
+.SH NAME
+iodined \- tunnel IPv4 over DNS
+.SH SYNOPSIS
+.B iodined [-v]
+
+.B iodined [-h]
+
+.B iodined [-c] [-s] [-f] [-D] [-u
+.I user
+.B ] [-t
+.I chrootdir
+.B ] [-d
+.I device
+.B ] [-m
+.I mtu
+.B ] [-l
+.I listen_ip
+.B ] [-p
+.I port
+.B ] [-n
+.I external_ip
+.B ] [-b
+.I dnsport
+.B ] [-P
+.I password
+.B ] [-z
+.I context
+.B ] [-F
+.I pidfile
+.B ]
+.I tunnel_ip
+.B [
+.I /netmask
+.B ]
+.I topdomain
+.SH DESCRIPTION
+.B iodined
+lets you tunnel IPv4 data through a DNS 
+server. This can be useful in situations where Internet access is firewalled,
+but DNS queries are allowed. It needs a TUN/TAP device to operate. The 
+bandwidth is asymmetrical,
+with a measured maximum of 680 kbit/s upstream and 2.3 Mbit/s
+downstream in a wired LAN test network.
+Realistic sustained throughput on a Wifi network using a carrier-grade
+DNS cache has been measured at some 50 kbit/s upstream and over 200 kbit/s
+downstream.
+.B iodine
+is the client application,
+.B iodined
+is the server.
+
+Note: server and client are required to speak the exact same protocol. In most
+cases, this means running the same iodined version. Unfortunately, implementing
+backward and forward protocol compatibility is usually not feasible.
+.SH OPTIONS
+.SS Common Options:
+.TP
+.B -v
+Print version info and exit.
+.TP
+.B -h
+Print usage info and exit.
+.TP
+.B -f
+Keep running in foreground.
+.TP
+.B -u user
+Drop privileges and run as user 'user' after setting up tunnel.
+.TP
+.B -t chrootdir
+Chroot to 'chrootdir' after setting up tunnel.
+.TP
+.B -d device
+Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
+and otherwise tunX.
+.TP
+.B -P password
+Use 'password' to authenticate. If not used, 
+.B stdin
+will be used as input. Only the first 32 characters will be used.
+.TP
+.B -z context
+Apply SELinux 'context' after initialization.
+.TP
+.B -F pidfile
+Create 'pidfile' and write process id in it.
+.SS Server Options:
+.TP
+.B -c
+Disable checking the client IP address on all incoming requests.
+By default, requests originating from non-matching IP adresses will be
+rejected, however this will cause problems when requests are routed
+via a cluster of DNS servers.
+.TP
+.B -s
+Don't try to configure IP address or MTU. 
+This should only be used if you have already configured the device that will be
+used.
+.TP
+.B -D
+Increase debug level. Level 1 prints info about each RX/TX packet.
+Implies the
+.B -f
+option.
+On level 2 (-DD) or higher, DNS queries will be printed literally.
+When using Base128 upstream encoding, this is best viewed as
+ISO Latin-1 text instead of (illegal) UTF-8.
+This is easily done with : "LC_ALL=C luit iodined -DD ..."
+(see luit(1)).
+.TP
+.B -m mtu
+Set 'mtu' as mtu size for the tun device. 
+This will be sent to the client on login, and the client will use the same mtu
+for its tun device.  Default 1130.  Note that the DNS traffic will be
+automatically fragmented when needed.
+.TP
+.B -l listen_ip
+Make the server listen only on 'listen_ip' for incoming requests.
+By default, incoming requests are accepted from all interfaces.
+.TP
+.B -p port
+Make the server listen on 'port' instead of 53 for traffic. 
+.B Note:
+You must make sure the dns requests are forwarded to this port yourself.
+.TP
+.B -n external_ip
+The IP address to return in NS responses. Default is to return the address used
+as destination in the query.
+.TP
+.B -b dnsport
+If this port is specified, all incoming requests not inside the tunnel domain
+will be forwarded to this port on localhost, to be handled by a real dns.
+.B Note:
+The forwarding is not fully transparent, and not advised for use
+in production environments.
+.SS Server Arguments:
+.TP
+.B tunnel_ip[/netmask]
+This is the server's ip address on the tun interface. The client will be
+given the next ip number in the range. It is recommended to use the 
+10.0.0.0 or 172.16.0.0 ranges. The default netmask is /27, can be overriden
+by specifying it here. Using a smaller network will limit the number of
+concurrent users.
+.TP
+.B topdomain
+The dns traffic is expected to arrive as queries for
+subdomains under 'topdomain'. This is normally a subdomain to a domain you 
+own. Use a short domain name to get better throughput. This argument must be 
+the same on both the client and the server. Queries for domains other
+than 'topdomain' will be forwarded when the \-b option is given, otherwise
+they will be dropped.
+.SH EXAMPLES
+See the README file for both a quick test scenario, and a detailed description
+of real-world deployment.
+.SH SECURITY
+Login is a relatively secure challenge-response MD5 hash, with the
+password never passing the wire.
+However, all other data is
+.B NOT
+encrypted in any way. The DNS traffic is also vulnerable to replay,
+injection and man-in-the-middle attacks, especially when iodined is used
+with the \-c option. Use of ssh or vpn tunneling is strongly recommended.
+On both server and client, use
+.IR iptables ,
+.I pf
+or other firewalls to block all traffic coming in from the tun interfaces,
+except to the used ssh or vpn ports.
+.SH ENVIRONMENT
+.SS IODINED_PASS
+If the environment variable
+.B IODINED_PASS
+is set, iodined will use the value it is set to as password instead of asking
+for one. The
+.B -P
+option still has precedence.
+.El
+.SH SEE ALSO
+\fBiodine\fR(8),
+the README file in the source distribution contains some more elaborate
+information.
+.SH BUGS
+File bugs at http://dev.kryo.se/iodine/
+.SH AUTHORS
+Erik Ekman <yarrick at kryo.se> and Bjorn Andersson <flex at kryo.se>. Major
+contributions by Anne Bezemer.

