From ad126901da4fbbb59234e85b7b859d6d43907bb6 Mon Sep 17 00:00:00 2001
From: Heikki Hannikainen <hessu@hes.iki.fi>
Date: Wed, 3 Oct 2012 22:18:49 +0300
Subject: [PATCH] Documentation: added doc/TIPS.md for documenting tips and
 tricks starting with the destination NAT trick to provide access on
 privileged low TCP ports. Document the low port non-root restriction in
 CONFIGURATION.md.

---
 doc/CONFIGURATION.md |  5 ++++-
 doc/TIPS.md          | 29 +++++++++++++++++++++++++++++
 src/Makefile.in      |  2 +-
 3 files changed, 34 insertions(+), 2 deletions(-)
 create mode 100644 doc/TIPS.md

diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md
index bb55d64..42ab9d8 100644
--- a/doc/CONFIGURATION.md
+++ b/doc/CONFIGURATION.md
@@ -140,7 +140,10 @@ The basic syntax is:
     handle both IPv6 and IPv4 connections with a single configuration
     line! On FreeBSD, separate IPv4 and IPv6 listeners are needed.
     
- *  port: the local TCP or UDP port to listen on.
+ *  port: the local TCP or UDP port to listen on. Must be larger than 1023.
+    aprsc drops root privileges quickly after startup (if it has them), and
+    cannot bind privileged ports. If you need to support a low port such as
+    23, see [TIPS](TIPS.html): "Providing access on low TCP ports"
 
  *  options: one more of:
  
diff --git a/doc/TIPS.md b/doc/TIPS.md
new file mode 100644
index 0000000..38b7fd2
--- /dev/null
+++ b/doc/TIPS.md
@@ -0,0 +1,29 @@
+
+aprsc tricks and tips
+=====================
+
+
+Providing access on low TCP ports (like 23)
+----------------------------------------------
+
+For security reasons aprsc drops root privileges as soon as possible after
+starting up (if it ever had the in the first place).  Listening on
+privileged "low" ports below 1024 normally requires root privileges, which
+aprsc no longer has when it comes to the point where it would start binding
+those ports.
+
+You can use a NAT based method to redirect traffic from port 23 to port
+14580 (or some other high unprivileged port your server is listening on). 
+Replace *youripaddress* with your external IP address.  The local listening
+address (to-destination) cannot be localhost, so use the same IP address. 
+These two commands need to go somewhere in your startup scripts or firewall
+configurations.
+
+    root@box:~# iptables -t nat -A PREROUTING -d *youripaddress*
+        -p tcp --dport 23 -m addrtype --dst-type LOCAL -j DNAT
+        --to-destination *youripaddress*:14580
+
+    root@box:~# iptables -t nat -A OUTPUT -d *youripaddress*
+        -p tcp --dport 29 -m addrtype --dst-type LOCAL -j DNAT
+        --to-destination *youripaddress*:14580
+
diff --git a/src/Makefile.in b/src/Makefile.in
index b22b099..dcc27d4 100644
--- a/src/Makefile.in
+++ b/src/Makefile.in
@@ -259,7 +259,7 @@ make-rpm: # actually just a reminder of how to do it..
 MARKDOWN=perl ../tools/Markdown.pl
 WEBDOCS=/data/www/hes/html/aprsc
 DOCS=README.md INSTALLING.md BUILDING.md CONFIGURATION.md DEBUGGING.md \
-	HOME.md CONTRIBUTING.md
+	HOME.md CONTRIBUTING.md TIPS.md
 DESTDOCS=$(addprefix $(WEBDOCS)/,$(addsuffix .html,$(basename $(DOCS))))
 SRCDOCS=$(addprefix ../doc/,$(DOCS))
 install-webdoc: $(DESTDOCS)