re6stnet.rst 7.78 KB
Newer Older
1 2 3 4 5 6 7 8 9
==========
 re6stnet
==========

---------------------------------------------
Resilient, Scalable, IPv6 Network application
---------------------------------------------

:Author: Nexedi
Julien Muchembled's avatar
Julien Muchembled committed
10
:Manual section: 8
11 12 13 14

SYNOPSIS
========

Julien Muchembled's avatar
Julien Muchembled committed
15 16 17
``re6stnet`` ``--registry`` `registry-url` ``--dh`` `dh-path`
``--ca`` `ca-path` ``--cert`` `cert-path` ``--key`` `key-path`
[`options`...] [``--`` [`openvpn-options`...]]
18 19 20 21

DESCRIPTION
===========

Julien Muchembled's avatar
Julien Muchembled committed
22 23
`re6stnet` runs a node of a re6st network. It establishes connections
with other nodes by creating OpenVPN tunnels and uses Babel for routing.
24 25 26 27

USAGE
=====

Julien Muchembled's avatar
Julien Muchembled committed
28
Use ``re6stnet --help`` to get the complete list of options.
Guillaume Bury's avatar
Guillaume Bury committed
29

30 31 32 33
If you already have IPv6 connectivity by autoconfiguration and still want to
use it for communications that are unrelated to this network, then:

- your kernel must support source address based routing (because you can't
34
  use ``--default`` option).
35 36 37 38
- you must set ``net.ipv6.conf.<iface>.accept_ra`` sysctl to value 2 and
  trigger SLAAC with ``rdisc6 <iface>`` to restore the default route if the
  kernel removed while enabling forwarding.

Julien Muchembled's avatar
Julien Muchembled committed
39 40 41 42 43 44 45 46 47 48 49 50
Following environment variables are available for processes started with
``--up`` or ``--daemon``:

re6stnet_iface
  value of ``--main-interface`` option
re6stnet_ip
  IPv6 set on main interface
re6stnet_subnet
  your subnet, written in CIDR notation
re6stnet_network
  the re6st network you belong to, written in CIDR notation

51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
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

81 82 83
Starting re6st automatically
----------------------------

84
If the `/etc/re6stnet/re6stnet.conf` configuration file exists, `re6stnet` is
85 86
automatically started as a system daemon, by ``systemd``\ (1). Debian package
also provides SysV init scripts.
87

88 89
Important note about ``--default`` option
-----------------------------------------
90

91 92 93
When re6st is configured to route all your IPv6 traffic (``--default``),
any other interface providing IPv6 must have no default route. Otherwise,
re6st either refuses to start or aborts if it detect a default route.
94

95 96
Correct usage of NetworkManager
-------------------------------
97

98 99 100 101
It is required to configure properly every connection defined in NetworkManager
because default settings are wrong and conflict with re6st. If ``--default`` is
used, then disable IPv6, else enable the following options in the [ipv6]
section::
102 103 104 105

   ignore-auto-routes=true
   never-default=true

106 107 108 109 110
In applets, these options are usually named:

- Ignore automatically obtained routes (KDE & Gnome)
- Use only for resources on this connection (KDE)
- Use this connection only for resources on its network (Gnome)
111 112


113 114 115
HOW TO
======

Julien Muchembled's avatar
Julien Muchembled committed
116 117
Joining an existing network
---------------------------
118

Julien Muchembled's avatar
Julien Muchembled committed
119 120
Once you know the registry URL of an existing network, use `re6st-conf` to get
a certificate::
121

Julien Muchembled's avatar
Julien Muchembled committed
122
  re6st-conf --registry http://re6st.example.com/
123

Julien Muchembled's avatar
Julien Muchembled committed
124 125 126 127 128
Use `-r` option to add public information to your certificate.
A token will be sent to the email you specify, in order to confirm your
subscription.
Files will be created by default in current directory and they are all
required for `re6stnet`::
129

Julien Muchembled's avatar
Julien Muchembled committed
130 131
  re6stnet --dh dh2048.pem --ca ca.crt --cert cert.crt --key cert.key \
           --registry http://re6st.example.com/
132

Julien Muchembled's avatar
Julien Muchembled committed
133 134
Setting a new network
---------------------
135

Julien Muchembled's avatar
Julien Muchembled committed
136 137 138 139 140
First you need to know the prefix of your network: let's suppose it is
`2001:db8:42::/48`. From it, you computes the serial number of the Certificate
authority (CA) that will be used by the registry node to sign delivered
certificates, as follows: translate the significant part to hexadecimal
(ie. 20010db80042) add a **1** as the most significant digit::
141

Julien Muchembled's avatar
Julien Muchembled committed
142 143
  openssl req -nodes -new -x509 -key ca.key -set_serial 0x120010db80042 \
              -days 365 -out ca.crt
144

145 146
(see ``re6st-registry --help`` for examples to create key/dh files)

Julien Muchembled's avatar
Julien Muchembled committed
147
The CA email will be used as sender for mails containing tokens.
148
The registry can now be started::
149

Julien Muchembled's avatar
Julien Muchembled committed
150
  re6st-registry --ca ca.crt --key ca.key --mailhost smtp.example.com
151

152 153 154 155 156 157 158
The registry uses the builtin HTTP server of Python. For security, it should be
behind a proxy like Apache.

The first registered node should be always up because its presence is used by
all other nodes to garantee they are connected to the network. The registry
also emits UDP packets that are forwarded via a localhost re6st node, and it is
recommended that this is the first one::
159

160
  re6st-conf --registry http://localhost/
161

162 163 164
If `re6st-conf` is run in the directory containing CA files, ca.crt will be
overridden without harm. See previous section for more information to create
a node.
165

166 167 168 169
For bootstrapping, you may have to explicitly set an IP in the configuration
of the first node, via the ``--ip`` option. Otherwise, additional nodes won't
be able to connect to it.

Joanne Hugé's avatar
Joanne Hugé committed
170 171 172 173 174 175
You can use communities to group prefixes in different subprefixes based on
their location. Each line in the community configuration is a mapping
from a subprefix (in binary) to a list of locations. Each location is either
"*" (default assignment), a country (Alpha-2 code), or a continent (Alpha-2
code) preceded by "@". See demo/registry/community.conf for an example.

176 177 178
TROUBLESHOOTING
===============

179 180 181 182
When many nodes are saturated or behind unconfigurated NAT, it may take
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`.
183

184 185 186
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.
187

188 189 190 191 192 193 194 195 196
Misconfigured firewall
----------------------

A common failure is caused by a misconfigured firewall. The following ports
need to be opened:

- **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
197 198
  by ``--pp`` option.

199 200 201 202 203 204 205 206 207 208 209
- **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`.
210

211 212
- **UDP source port 1900**: required for UPnP server (see `Setting up a UPnP
  server`_ for further explanations).
213

214 215
You can refer to `examples/iptables-rules.sh` for an example of iptables and
ip6tables rules.
216

217 218
SEE ALSO
========
Guillaume Bury's avatar
Guillaume Bury committed
219

220 221
``re6st-conf``\ (1), ``re6st-registry``\ (1), ``babeld``\ (8), ``openvpn``\ (8),
``rdisc6``\ (8), ``req``\ (1)