howto/Getting-started.md
... ...
@@ -20,9 +20,11 @@ See [Contact](/contact#contact_mailing-list) to subscribe.
20 20
21 21
You must create several objects in the DN42 registry: <https://git.dn42.us/dn42/registry>
22 22
23
-The registry is a git repository, so objects are created by forking the main repository, making your changes and then submitting a pull request for review. See the [git documentation](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) and guides on [github](https://help.github.com/en/github/using-git) for how to use git to work with remote repositories.
23
+The registry is a git repository, so objects are created by forking the main repository, making your changes and then submitting a pull request for review. See the [git documentation](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) and guides on [github](https://help.github.com/en/github/using-git) for how to use git to work with remote repositories.
24 24
25
-Do browse through the registry and look at the pull request queue to see examples, understand how the process works and see the types of questions asked by the registry maintainers.
25
+When submitting your pull request, please squash your commits. It makes the request easier to read and simplifies the change history. See this [StackOverflow question](https://stackoverflow.com/questions/5189560/squash-my-last-x-commits-together-using-git) for a simple guide on how to do this.
26
+
27
+Do browse through the registry and look at the [pull request queue](https://git.dn42.us/dn42/registry/pulls) to see examples, understand how the process works and see the types of questions asked by the registry maintainers.
26 28
27 29
*Whilst it is possible to use the web interface to edit files, you are encouraged to clone your repo locally and use the command line git tools. It's easy to do and learning how to use git is a skill worth knowing. Using the web interface creates a large number of commits making changes more difficult to track*
28 30
... ...
@@ -35,21 +37,25 @@ We will create several types of objects:
35 37
- **person** objects, which describe people or organisations and provide contact information
36 38
- and **resource** objects (AS number, IP subnet, DNS zone, etc).
37 39
38
-All objects are simple text files in the specific subfolders, but they do have a specific format. The files should use spaces and not tabs, and the attribute values must start on the 20th column.
40
+All objects are simple text files in the specific subfolders, but the files do have a particular format. The files should use spaces and not tabs, and the attribute values must start on the 20th column.
39 41
40 42
### Create a maintainer object
41 43
42 44
Create a `mntner` object in `data/mntner/` named `<FOO>-MNT`. It will be used to edit all the objects that are under your responsibility.
43 45
44 46
- use `<FOO>-MNT` as `mnt-by`, otherwise, you won't be able to edit your maintainer object.
45
-- recommended: add a PGP Fingerprint `auth: pgp-fingerprint <pgp-fingerprint>` or SSH key `auth: ssh-{rsa,ed25519} <key>` to prevent unauthenticated changes.
47
+- Add an 'auth' attribute so that changes to your objects can be verified.
48
+ Common authentication methods are:
49
+ - PGP Key: `auth: pgp-fingerprint <pgp-fingerprint>`
50
+ - SSH Key: `auth: ssh-{rsa,ed25519} <key>`
46 51
47
-Example: data/mntner/EXAMPLE-MNT
52
+Example: data/mntner/FOO-MNT
48 53
```
49
-mntner: EXAMPLE-MNT
50
-admin-c: EXAMPLE-DN42
51
-tech-c: EXAMPLE-DN42
52
-mnt-by: EXAMPLE-MNT
54
+mntner: FOO-MNT
55
+admin-c: FOO-DN42
56
+tech-c: FOO-DN42
57
+mnt-by: FOO-MNT
58
+auth: pgp-fingerprint 0123456789ABCDEF0123456789ABCDEF01234567
53 59
source: DN42
54 60
```
55 61
... ...
@@ -61,21 +67,23 @@ Create a `person` object in `data/person/` for **yourself** (not your organisat
61 67
- the `person` field is more freeform, you may use your nickname or even real name here.
62 68
- provide an email.
63 69
- you may provide additional ways of contacting you, using one or more `contact` field. For instance `xmpp:luke@theforce.net`, `irc:luke42@hackint`, `twitter: TheGreatLuke`.
64
-- you may whish to add other fields, such as `pgp-fingerprint`, `remarks`, and so on.
70
+- you may wish to add other fields, such as `pgp-fingerprint`, `remarks`, and so on.
65 71
- don't forget to set `mnt-by` to `<FOO>-MNT`.
66 72
67
-<!-- You must now edit the maintainer object created earlier, to properly fill in the `admin-c` and `tech-c` fields (set them to `<FOO>-DN42`). -->
68
-
69
-Example: data/mntner/EXAMPLE-DN42
73
+Example: data/person/FOO-DN42
70 74
```
71 75
person: John Doe
72 76
contact: john.doe@example.com
73
-nic-hdl: EXAMPLE-DN42
74
-mnt-by: EXAMPLE-MNT
77
+nic-hdl: FOO-DN42
78
+mnt-by: FOO-MNT
75 79
source: DN42
76 80
```
77 81
78
-Organisations are not required if you are joining dn42 as a single user. If you intend to register resources for an organisation (e.g. your hackerspace), you must also create an `organisation` object for your organisation:
82
+---
83
+
84
+**Organisations are not required if you are joining dn42 as an individual**
85
+
86
+If you intend to register resources for an organisation (e.g. your hackerspace), you must also create an `organisation` object for your organisation:
79 87
80 88
- `organisation` is of the form `<ORG-FOO>`.
81 89
- `org-name` should be the name of your organisation.
... ...
@@ -86,11 +94,11 @@ Organisations are not required if you are joining dn42 as a single user. If you
86 94
87 95
Example: data/organisation/ORG-EXAMPLE
88 96
```
89
-organisation: ORG-EXAMPLE
90
-org-name: Example Organisation
91
-admin-c: EXAMPLE-DN42
92
-tech-c: EXAMPLE-DN42
93
-mnt-by: EXAMPLE-MNT
97
+organisation: ORG-FOO
98
+org-name: Foo Organisation
99
+admin-c: FOO-DN42
100
+tech-c: FOO-DN42
101
+mnt-by: FOO-MNT
94 102
source: DN42
95 103
```
96 104
... ...
@@ -106,23 +114,26 @@ This applies to AS numbers, network prefixes, routes, DNS records...
106 114
107 115
### Register an AS number
108 116
109
-To register an AS number, simply create an `aut-num` object in `data/aut-num/`. `as-name` should be a name for your AS.
117
+To register an AS number, simply create an `aut-num` object in `data/aut-num/`.
118
+`as-name` should be a name for your AS.
119
+
120
+Your AS number can be chosen arbitrarily in the dn42 ASN space, see the [as-block objects](https://git.dn42.us/dn42/registry/src/master/data/as-block) in the registry.
110 121
111
-Your AS number can be chosen arbitrarily in the dn42 ASN space, look at the `as-block` objects. The historic ASN space is around 64600-64855 and 76100-76200. Starting from June 2014, **you must allocate your AS number in the new 4242420000-4242423999 range**.
122
+**You should allocate your AS number in the 4242420000-4242423999 range**
112 123
113
-For a list of currently assigned AS numbers, see http://ix.ucis.nl/dn42/as.php. This list is automatically built from the registry.
124
+For a list of currently assigned AS numbers browse the registry data/aut-num/ directory or [online](https://explorer.burble.com/#/aut-num/).
114 125
115
-If you intend to use an ASN outside of the native dn42 ranges, please check that it doesn't clash with the [Freifunk AS-Numbers] (http://wiki.freifunk.net/AS-Nummern) or other networks (ChaosVPN, etc). For a list of ASN currently announced in dn42, see [this map](http://nixnodes.net/dn42/graph/) or [this list](http://dataviz.polyno.me/lastseen/).
126
+If you intend to use an ASN outside of the native dn42 ranges, please check that it doesn't clash with the [Freifunk AS-Numbers] (http://wiki.freifunk.net/AS-Nummern) or other networks (ChaosVPN, etc). For a list of ASN currently announced in dn42, see [this map](http://nixnodes.net/dn42/graph/).
116 127
117 128
If unsure, ask on the mailing list or IRC.
118 129
119 130
Example: data/aut-num/AS4242423999
120 131
```
121 132
aut-num: AS4242423999
122
-as-name: AS for EXAMPLE Network
123
-admin-c: EXAMPLE-DN42
124
-tech-c: EXAMPLE-DN42
125
-mnt-by: EXAMPLE-MNT
133
+as-name: AS for FOO Network
134
+admin-c: FOO-DN42
135
+tech-c: FOO-DN42
136
+mnt-by: FOO-MNT
126 137
source: DN42
127 138
```
128 139
... ...
@@ -130,7 +141,9 @@ source: DN42
130 141
131 142
#### IPv6
132 143
133
-To register an [IPv6 prefix](/FAQ#frequently-asked-questions_what-about-ipv6-in-dn42), you can create an `inet6num` object. A single /48 allocation in [ULA space](https://www.sixxs.net/tools/grh/ula/) will likely provide more than enough room for all devices you will ever connect. Some people use “vanity” prefixes like fd42:_xyz_::/48 instead of the fully standard-conformant pseudorandom ones but that is strongly discouraged. dn42 is interconnected with other networks like icvpn which use the same range so a registration in the dn42 registry can't prevent conflicts.
144
+To register an IPv6 prefix, you create an `inet6num` object. dn42 uses the fd00::/8 ([ULA](https://tools.ietf.org/html/rfc4193)) range. A single /48 allocation is typical and will likely provide more than enough room for all devices you will ever connect.
145
+
146
+dn42 is interconnected with other networks, like icvpn, which also use the same ULA range so a registration in the dn42 registry can't prevent IPv6 conflicts. A fully random prefix (see [RFC4193](https://tools.ietf.org/html/rfc4193)) is recommended; finding a conflict and needing to renumber your network is no fun.
134 147
135 148
A few websites can generate random ULA prefixes for you:
136 149
* [SimpleDNS](https://simpledns.com/private-ipv6)
... ...
@@ -138,16 +151,16 @@ A few websites can generate random ULA prefixes for you:
138 151
139 152
or a small script is available: [ulagen.py](https://git.dn42.us/netravnen/dn42-repo-utils/src/master/ulagen.py)
140 153
141
-example: data/inet6num/fd42:4992:6a6d::_48
154
+example: data/inet6num/fd35:4992:6a6d::_48
142 155
```
143
-inet6num: fd42:4992:6a6d:0000:0000:0000:0000:0000 - fd42:4992:6a6d:ffff:ffff:ffff:ffff:ffff
144
-cidr: fd42:4992:6a6d::/48
145
-netname: EVE-NETWORK
146
-descr: Network of eve
147
-country: DE
148
-admin-c: MIC92-DN42
149
-tech-c: MIC92-DN42
150
-mnt-by: MIC92-MNT
156
+inet6num: fd35:4992:6a6d:0000:0000:0000:0000:0000 - fd35:4992:6a6d:ffff:ffff:ffff:ffff:ffff
157
+cidr: fd35:4992:6a6d::/48
158
+netname: FOO-NETWORK
159
+descr: Network of FOO
160
+country: XD
161
+admin-c: FOO-DN42
162
+tech-c: FOO-DN42
163
+mnt-by: FOO-MNT
151 164
status: ASSIGNED
152 165
source: DN42
153 166
```
... ...
@@ -156,10 +169,9 @@ source: DN42
156 169
157 170
If you also want to register an IPv4 network prefix, simply create an `inetnum` object.
158 171
159
-You may choose your network prefix in one of the currently open netblocks. You can get a list of unassigned subnets on the following sites, please mind the allocation guideline below.
172
+You may choose your network prefix in one of the currently open netblocks. You can get a list of unassigned subnets on the following site, please mind the allocation guideline below.
160 173
161 174
* [Open Netblocks](https://dn42.us/peers/free)
162
- * [graphical visualisation of the assigned ranges](http://dataviz.polyno.me/dn42-netblock-visu/registry.html).
163 175
164 176
| Size | Comment |
165 177
|-----:|:-------------------------|
... ...
@@ -170,23 +182,20 @@ You may choose your network prefix in one of the currently open netblocks. You c
170 182
| /25 | still a lot of IPs! |
171 183
| /24 | are you an organization? |
172 184
173
-The current guideline is to allocate a /27 or smaller by default, keeping space for up to a /26 if possible. Don't allocate more than a /25 worth of addresses and please **think before you allocate**: If you are going to have 2-3 servers and two VPN-spaces, a /28 is enough to suit your needs. Same will go for most home-networks. This is not public internet, but our IPv4-space is valuable too! If you need a /24 or larger, please ask in the IRC chan or on the mailing list.
174
-
175
-For example, if there is no /27 free, you can split up a /26 into two /27. If you are looking for a /27 but there are none showing in the Open Netblocks tool, instead pick one of the /26 and click Take it!
176
-When registering your inetnum, instead of writing 172.2x.xxx.0-172.2x.xxx.63 then you can write 172.2x.xxx.0-172.2x.xxx.31. This will get you a /27 and save our IP space for others.
185
+The current guideline is to allocate a /27 or smaller by default, keeping space for up to a /26 if possible. Don't allocate more than a /25 worth of addresses and please **think before you allocate**. dn42 typically uses point-to-point addressing in VPN tunnels, so a single IP address per host should be enough. If you are going to have 2-3 servers, a /28 is more than enough to suit your needs; Same will go for most home-networks. dn42 is not the public internet, but our IPv4-space is valuable too! If you need a /24 or larger, please ask in the IRC chan or on the mailing list.
177 186
178 187
To register for example 172.20.150.0/27, you need to fill in 172.20.150.0-172.20.150.31.
179 188
180 189
**Note:** Reverse DNS works with _any_ prefix length, as long as your [recursive nameserver](/services/DNS) supports [RFC 2317](https://www.ietf.org/rfc/rfc2317.txt). Don't go for a /24 _just to have RDNS_.
181 190
182
-example: data/inetnum/172.23.75.0_24
191
+example: data/inetnum/172.20.150.0_27
183 192
```
184
-inetnum: 172.23.75.0 - 172.23.75.255
185
-cidr: 172.23.75.0/24
186
-netname: EVE-NETWORK
187
-admin-c: MIC92-DN42
188
-tech-c: MIC92-DN42
189
-mnt-by: MIC92-MNT
193
+inetnum: 172.20.150.0 - 172.20.150.31
194
+cidr: 172.20.150.0/27
195
+netname: FOO-NETWORK
196
+admin-c: FOO-DN42
197
+tech-c: FOO-DN42
198
+mnt-by: FOO-MNT
190 199
status: ASSIGNED
191 200
source: DN42
192 201
```
... ...
@@ -195,19 +204,61 @@ source: DN42
195 204
196 205
If you plan to announce your prefixes in dn42, which you probably want in most cases, you will also need to create a `route6` object for ipv6 prefixes and a `route` object for ipv4 prefixes. This information is used for Route Origin Authorization (ROA) checks. If you skip this step, your network will probably get filtered by most major peers. Checking ROA will prevent (accidental) hijacking of other people's prefixes.
197 206
198
-example: data/route6/fd42:4992:6a6d::_48
207
+example: data/route6/fd35:4992:6a6d::_48
199 208
```
200
-route6: fd42:4992:6a6d::/48
201
-origin: AS4242420092
202
-mnt-by: MIC92-MNT
209
+route6: fd35:4992:6a6d::/48
210
+origin: AS4242423999
211
+max-length: 48
212
+mnt-by: FOO-MNT
203 213
source: DN42
204 214
```
205 215
206
-example data/route/172.23.75.0_24:
216
+example data/route/172.20.150.0_27:
207 217
```
208
-route: 172.23.75.0/24
218
+route: 172.20.150.0/27
209 219
origin: AS4242420092
210
-mnt-by: MIC92-MNT
220
+mnt-by: FOO-MNT
221
+source: DN42
222
+```
223
+
224
+#### DNS and Domain Registration
225
+
226
+*(Optional)*
227
+To register a domain name, create a `dns` object in the data/dns directory.
228
+
229
+example: data/dns/foo.dn42
230
+```
231
+domain: foo.dn42
232
+admin-c: FOO-DN42
233
+tech-c: FOO-DN42
234
+mnt-by: FOO-MNT
235
+nserver: ns1.foo.dn42 172.20.150.1
236
+nserver: ns1.foo.dn42 fd35:4992:6a6d:53::1
237
+nserver: ns2.foo.dn42 172.20.150.2
238
+nserver: ns2.foo.dn42 fd35:4992:6a6d:53::2
239
+source: DN42
240
+```
241
+
242
+You can also add DNSSEC delegations using `ds-rdata` attributes to your domain:
243
+
244
+```
245
+ds-rdata: 61857 13 2 bd35e3efe3325d2029fb652e01604a48b677cc2f44226eeabee54b456c67680c
246
+```
247
+
248
+For reverse DNS, add `nserver` attributes to you inet{,6}num objects:
249
+
250
+```
251
+inet6num: fd35:4992:6a6d:0000:0000:0000:0000:0000 - fd35:4992:6a6d:ffff:ffff:ffff:ffff:ffff
252
+cidr: fd35:4992:6a6d::/48
253
+netname: FOO-NETWORK
254
+descr: Network of FOO
255
+country: XD
256
+admin-c: FOO-DN42
257
+tech-c: FOO-DN42
258
+mnt-by: FOO-MNT
259
+status: ASSIGNED
260
+nserver: ns1.foo.dn42
261
+nserver: ns2.foo.dn42
211 262
source: DN42
212 263
```
213 264
... ...
@@ -215,13 +266,13 @@ source: DN42
215 266
216 267
In dn42, there is no real distinction between peering and transit: in most cases, everybody serves as an upstream provider to all its peers. Note that if you have very slow connectivity to the Internet, you may want to avoid providing transit between your peers, which can be done by filtering or prepending your ASN. For the sake of sane routing, try to peer with people on the same continent to avoid inefficient routing, <50ms is a good rule of thumb. You can also look into Bird communities if you are using Bird to mark the latency for the [link](/howto/Bird-communities).
217 268
218
-If you don't know anybody who can peer with you, you can use this tool: https://dn42.us/peers
269
+You can use the peerfinder to help you find potential peers close to you: https://dn42.us/peers
219 270
220
-It will let you find people to peer with. You can then contact them on IRC or by email. In case you're really at loss, you can also ask for peers on the mailing list.
271
+You can then contact them on IRC or by email. In case you're really at loss, you can also ask for peers on the mailing list.
221 272
222 273
## Establishing tunnels
223 274
224
-Unless your dn42 peers are on the same network, you must establish tunnels. Choose anything you like: OpenVPN, GRE, GRE + IPSec, IPIP, Tinc, ...
275
+Unless your dn42 peers are on the same network, you must establish tunnels. Choose anything you like: Wireguard, OpenVPN, GRE, GRE + IPSec, IPIP, Tinc, ...
225 276
226 277
There is some documentation in this wiki, like [gre-plus-ipsec](GRE-plus-IPsec).
227 278
... ...
@@ -231,11 +282,12 @@ You need a routing daemon to speak BGP with your peers. People usually run Quagg
231 282
232 283
You can find [configuration examples for Bird here](bird).
233 284
234
-Some [documentation of the old wiki] (http://dn42.volcanis.me/initenv/wiki/HowToPeer.html) might still be handy, but remember that everything there is terribly outdated.
235
-
236 285
## Configuration Examples
237 286
287
+* [Important Network configuration](networksettings)
288
+
238 289
* VPN/Tunnel:
290
+ * [Wireguard](/howto/wireguard)
239 291
* [Openvpn](/howto/openvpn)
240 292
* [Tinc](/howto/tinc)
241 293
* [IPsec with public key authentication](/howto/IPsec-with-PublicKeys)
... ...
@@ -247,8 +299,6 @@ Some [documentation of the old wiki] (http://dn42.volcanis.me/initenv/wiki/HowTo
247 299
* [EdgeOS Configuration](EdgeOS-Config-Example)
248 300
* [EdgeOS GRE/IPsec Example](EdgeOS-GRE-IPsec-Example)
249 301
* [BGP on Extreme Networks Summit 1i](BGP-on-Extreme-Summit1i)
250
-* [Important Network configuration](networksettings)
251
-
252 302
253 303
# Configure DNS
254 304