doc: give examples of command to create key/dh files
[re6stnet.git] / docs / re6stnet.rst
1 ==========
2  re6stnet
3 ==========
4
5 ---------------------------------------------
6 Resilient, Scalable, IPv6 Network application
7 ---------------------------------------------
8
9 :Author: Nexedi
10 :Manual section: 8
11
12 SYNOPSIS
13 ========
14
15 ``re6stnet`` ``--registry`` `registry-url` ``--dh`` `dh-path`
16 ``--ca`` `ca-path` ``--cert`` `cert-path` ``--key`` `key-path`
17 [`options`...] [``--`` [`openvpn-options`...]]
18
19 DESCRIPTION
20 ===========
21
22 `re6stnet` runs a node of a re6st network. It establishes connections
23 with other nodes by creating OpenVPN tunnels and uses Babel for routing.
24
25 USAGE
26 =====
27
28 Use ``re6stnet --help`` to get the complete list of options.
29
30 If you already have IPv6 connectivity by autoconfiguration and still want to
31 use it for communications that are unrelated to this network, then:
32
33 - your kernel must support source address based routing (because you can't
34   use ``--default`` option).
35 - you must set ``net.ipv6.conf.<iface>.accept_ra`` sysctl to value 2 and
36   trigger SLAAC with ``rdisc6 <iface>`` to restore the default route if the
37   kernel removed while enabling forwarding.
38
39 Following environment variables are available for processes started with
40 ``--up`` or ``--daemon``:
41
42 re6stnet_iface
43   value of ``--main-interface`` option
44 re6stnet_ip
45   IPv6 set on main interface
46 re6stnet_subnet
47   your subnet, written in CIDR notation
48 re6stnet_network
49   the re6st network you belong to, written in CIDR notation
50
51 Starting re6st automatically
52 ----------------------------
53
54 If the `/etc/re6stnet/re6stnet.conf` configuration file exists, `re6stnet` is
55 automatically started as a daemon. This is done is 2 different ways, depending
56 on whether it is bound or not to a specific interface, by using the
57 `main-interface` option:
58
59 - If the option is not given (or if it is set to 'lo'), then it is automatically
60   started/stopped by ``systemd``\ (1). Debian package also provides SysV init
61   scripts.
62
63 - Otherwise, it is automatically started/stopped when the related network
64   interface is enabled/disabled by ``NetworkManager``\ (8). Debian package also
65   provides `ifupdown` scripts.
66
67 Important note about NetworkManager
68 -----------------------------------
69
70 It is required to configure properly every connection defined in NetworkManager
71 because default settings are wrong and conflict with re6st:
72
73 - If re6st routes all your IPv6 traffic, using ``--default`` option, then make
74   sure to disable IPv6 in NetworkManager.
75
76 - Otherwise, the following options must be set in [ipv6] section::
77
78    ignore-auto-routes=true
79    never-default=true
80
81   In applets, these options are usually named:
82
83   - Ignore automatically obtained routes (KDE & Gnome)
84   - Use only for resources on this connection (KDE)
85   - Use this connection only for resources on its network (Gnome)
86
87 HOW TO
88 ======
89
90 Joining an existing network
91 ---------------------------
92
93 Once you know the registry URL of an existing network, use `re6st-conf` to get
94 a certificate::
95
96   re6st-conf --registry http://re6st.example.com/
97
98 Use `-r` option to add public information to your certificate.
99 A token will be sent to the email you specify, in order to confirm your
100 subscription.
101 Files will be created by default in current directory and they are all
102 required for `re6stnet`::
103
104   re6stnet --dh dh2048.pem --ca ca.crt --cert cert.crt --key cert.key \
105            --registry http://re6st.example.com/
106
107 Setting a new network
108 ---------------------
109
110 First you need to know the prefix of your network: let's suppose it is
111 `2001:db8:42::/48`. From it, you computes the serial number of the Certificate
112 authority (CA) that will be used by the registry node to sign delivered
113 certificates, as follows: translate the significant part to hexadecimal
114 (ie. 20010db80042) add a **1** as the most significant digit::
115
116   openssl req -nodes -new -x509 -key ca.key -set_serial 0x120010db80042 \
117               -days 365 -out ca.crt
118
119 (see ``re6st-registry --help`` for examples to create key/dh files)
120
121 The CA email will be used as sender for mails containing tokens.
122 The registry can now be started::
123
124   re6st-registry --ca ca.crt --key ca.key --mailhost smtp.example.com
125
126 The registry uses the builtin HTTP server of Python. For security, it should be
127 behind a proxy like Apache.
128
129 The first registered node should be always up because its presence is used by
130 all other nodes to garantee they are connected to the network. The registry
131 also emits UDP packets that are forwarded via a localhost re6st node, and it is
132 recommended that this is the first one::
133
134   re6st-conf --registry http://localhost/
135
136 If `re6st-conf` is run in the directory containing CA files, ca.crt will be
137 overridden without harm. See previous section for more information to create
138 a node.
139
140 For bootstrapping, you may have to explicitly set an IP in the configuration
141 of the first node, via the ``--ip`` option. Otherwise, additional nodes won't
142 be able to connect to it.
143
144 TROUBLESHOOTING
145 ===============
146
147 When many nodes are saturated or behind unconfigurated NAT, it may take
148 some time to bootstrap. However, if you really think something goes wrong,
149 you should first enable OpenVPN logs and increase verbosity:
150 see commented directives in configuration generated by `re6st-conf`.
151
152 A common failure is caused by a misconfigured firewall:
153
154 - re6st launches several OpenVPN processes. Those in client mode may connect to
155   any TCP/UDP port in IPv4. Server processes only listen to ports specified
156   by ``--pp`` option.
157
158 - re6st nodes use UDP port 326 to communicate.
159   It must be open on all re6st IPv6.
160
161 - OpenVPN always aborts due to inactivity timeout when Babel paquets are
162   filtered. UDP port 6696 must be open on link-local IPv6 of all interfaces
163   managed by Babel.
164
165 Other security components may also break re6st. For example, default SELinux
166 configuration on Fedora prevents execution of OpenVPN server processes.
167
168 SEE ALSO
169 ========
170
171 ``re6st-conf``\ (1), ``re6st-registry``\ (1), ``babeld``\ (8), ``openvpn``\ (8),
172 ``rdisc6``\ (8), ``req``\ (1)