Document UPnP server configuration and add details about firewall configuration

/reviewed-on nexedi/re6stnet!3

docs/re6stnet.rst

@@ -48,6 +48,36 @@ re6stnet_subnet
 re6stnet_network
   the re6st network you belong to, written in CIDR notation
 
+Setting up a UPnP server
+------------------------
+
+In order to share the connectivity with others, it is necessary for re6stnet
+port (as specified by ``--pp`` option and default to `1194`) to be reachable
+from outside. If the node has a public IPv4 address, then this is not
+necessary, otherwise a UPnP server should be set up on the gateway.
+
+You can check the connectivity with other re6st nodes of the network with
+``netstat -tn | grep 1194``.
+
+Sample configuration file for `miniupnpd`::
+
+  ext_ifname=ppp0
+  listening_ip=eth0
+  clean_ruleset_interval=600
+  allow 1024-65535 192.168.0.0/24 1024-65535
+  deny 0-65535 0.0.0.0/0 0-65535
+
+After restarting ``re6stnet`` service on the clients within the LAN, you can
+either check ``/var/log/re6stnet.log`` or the ``iptables`` ``NAT`` table to
+see that the port ``1194`` is properly redirected, for example::
+
+  # iptables -t nat -L -nv
+  [...]
+  Chain MINIUPNPD (1 references)
+  target     prot opt source               destination
+  DNAT       tcp  --  anywhere             anywhere             tcp dpt:37194 to:192.168.0.5:1194
+  DNAT       tcp  --  anywhere             anywhere             tcp dpt:34310 to:192.168.0.233:1194
+
 Starting re6st automatically
 ----------------------------
 
@@ -149,21 +179,38 @@ some time to bootstrap. However, if you really think something goes wrong,
 you should first enable OpenVPN logs and increase verbosity:
 see commented directives in configuration generated by `re6st-conf`.
 
-A common failure is caused by a misconfigured firewall:
+Besides of firewall configuration described below, other security components
+may also break re6st. For example, default SELinux configuration on Fedora
+prevents execution of OpenVPN server processes.
+
+Misconfigured firewall
+----------------------
+
+A common failure is caused by a misconfigured firewall. The following ports
+need to be opened:
 
-- re6st launches several OpenVPN processes. Those in client mode may connect to
-  any TCP/UDP port in IPv4. Server processes only listen to ports specified
+- **TCP/UDP ports 1194** (Specified by ``--pp`` option and default on `1194`):
+  re6st launches several OpenVPN processes. Those in client mode may connect
+  to any TCP/UDP port in IPv4. Server processes only listen to ports specified
   by ``--pp`` option.
 
-- re6st nodes use UDP port 326 to communicate.
-  It must be open on all re6st IPv6.
+- **UDP port 326**: used by re6st nodes to communicate. It must be open on all
+  re6st IPv6.
+
+- **UDP port 6696 on link-local IPv6 (fe80::/10)** on all interfaces managed
+  by Babel: OpenVPN always aborts due to inactivity timeout when Babel paquets
+  are filtered.
+
+- **ICMPv6 neighbor-solicitation/neighbor-advertisement**. Moreover, the
+  following ICMPv6 packets should also generally be allowed in an IPv6
+  network: `destination-unreachable`, `packet-too-big`, `time-exceeded`,
+  `parameter-problem`.
 
-- OpenVPN always aborts due to inactivity timeout when Babel paquets are
-  filtered. UDP port 6696 must be open on link-local IPv6 of all interfaces
-  managed by Babel.
+- **UDP source port 1900**: required for UPnP server (see `Setting up a UPnP
+  server`_ for further explanations).
 
-Other security components may also break re6st. For example, default SELinux
-configuration on Fedora prevents execution of OpenVPN server processes.
+You can refer to `examples/iptables-rules.sh` for an example of iptables and
+ip6tables rules.
 
 SEE ALSO
 ========

examples/iptables-rules.sh

+#!/bin/sh
+#
+# Example iptables/ip6tables rules on a desktop computer when re6st is only
+# used to build an IPv6 overlay network. REJECT everything by default:
+#
+# - Incoming traffic (INPUT): only open ports needed for re6st and also allow
+#   packets associated with an existing connection (ESTABLISHED, RELATED).
+#
+# - Forwarding traffic (FORWARD): a re6st node is a router and
+#   it is crucial that it never drops any packet between two other nodes.
+#
+# - Outgoing traffic (OUTPUT): allow new/existing connections (NEW,
+#   ESTABLISHED, RELATED).
+#
+# WARNING: THIS SCRIPT *MUST NOT* JUST BE COPY-PASTED WITHOUT A BASIC
+#          UNDERSTANDING OF IPTABLES/IP6TABLES (see iptables(8) and
+#          iptables-extensions(8) manpages).
+
+GATEWAY_IP=192.168.0.1
+
+## IPv4
+iptables -P INPUT REJECT
+iptables -P OUTPUT REJECT
+
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
+iptables -A INPUT -p icmp --icmp-type echo-request -m limit --limit 900/min -j ACCEPT
+iptables -A INPUT -p icmp --icmp-type echo-reply -m limit --limit 900/min -j ACCEPT
+# re6st
+iptables -A INPUT -p tcp -m tcp --dport 1194 -j ACCEPT
+# UPnP
+iptables -A INPUT -p udp -m udp --sport 1900 -s $GATEWAY_IP -j ACCEPT
+
+iptables -A OUTPUT -o lo -j ACCEPT
+iptables -A OUTPUT -m state --state NEW,RELATED,ESTABLISHED -j ACCEPT
+
+# more rules needed if you set up a private IPv4 network
+
+## IPv6
+ip6tables -P INPUT REJECT
+ip6tables -P FORWARD REJECT
+ip6tables -P OUTPUT REJECT
+
+ip6tables -N RE6ST
+ip6tables -A RE6ST -i re6stnet+ -j ACCEPT
+# For every --interface option:
+ip6tables -A RE6ST -i eth0 -j ACCEPT
+
+ip6tables -A INPUT -i lo -j ACCEPT
+ip6tables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
+ip6tables -A INPUT -p udp -m udp --dport babel --src fe80::/10 -j ACCEPT
+# Babel
+ip6tables -A INPUT -p udp -m udp --dport 326 -j RE6ST
+ip6tables -A INPUT -p ipv6-icmp -m icmp6 --icmpv6-type destination-unreachable -j ACCEPT
+ip6tables -A INPUT -p ipv6-icmp -m icmp6 --icmpv6-type packet-too-big -j ACCEPT
+ip6tables -A INPUT -p ipv6-icmp -m icmp6 --icmpv6-type time-exceeded -j ACCEPT
+ip6tables -A INPUT -p ipv6-icmp -m icmp6 --icmpv6-type parameter-problem -j ACCEPT
+ip6tables -A INPUT -p icmpv6 --icmpv6-type echo-request -m limit --limit 900/min -j ACCEPT
+ip6tables -A INPUT -p icmpv6 --icmpv6-type echo-reply -m limit --limit 900/min -j ACCEPT
+ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-solicitation -m hl --hl-eq 255 -j ACCEPT
+ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-advertisement -m hl --hl-eq 255 -j ACCEPT
+
+ip6tables -A FORWARD -o re6stnet+ -j RE6ST
+# Same as in RE6ST chain.
+ip6tables -A FORWARD -o eth0 -j RE6ST
+
+ip6tables -A OUTPUT -o lo -j ACCEPT
+ip6tables -A OUTPUT -m state --state NEW,RELATED,ESTABLISHED -j ACCEPT
+ip6tables -A OUTPUT -p ipv6-icmp -m icmp6 --icmpv6-type destination-unreachable -j ACCEPT
+ip6tables -A OUTPUT -p ipv6-icmp -m icmp6 --icmpv6-type packet-too-big -j ACCEPT
+ip6tables -A OUTPUT -p ipv6-icmp -m icmp6 --icmpv6-type time-exceeded -j ACCEPT
+ip6tables -A OUTPUT -p ipv6-icmp -m icmp6 --icmpv6-type parameter-problem -j ACCEPT
+ip6tables -A OUTPUT -p icmpv6 --icmpv6-type neighbor-solicitation -m hl --hl-eq 255 -j ACCEPT
+ip6tables -A OUTPUT -p icmpv6 --icmpv6-type neighbor-advertisement -m hl --hl-eq 255 -j ACCEPT