diff options
Diffstat (limited to 'doc/handbook')
-rw-r--r-- | doc/handbook/chapters/user.texi | 109 |
1 files changed, 102 insertions, 7 deletions
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index d30c94c9b..714336228 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi | |||
@@ -56,7 +56,8 @@ $ gnunet-arm -e | |||
56 | * The GNS Tab:: | 56 | * The GNS Tab:: |
57 | * Creating a Record:: | 57 | * Creating a Record:: |
58 | * Resolving GNS records:: | 58 | * Resolving GNS records:: |
59 | * Integration with Browsers:: | 59 | * Integration with Browsers (DNS2GNS service):: |
60 | * Integration with Browsers (SOCKS proxy):: | ||
60 | * Creating a Business Card:: | 61 | * Creating a Business Card:: |
61 | * Be Social:: | 62 | * Be Social:: |
62 | * Backup of Identities and Egos:: | 63 | * Backup of Identities and Egos:: |
@@ -67,8 +68,16 @@ $ gnunet-arm -e | |||
67 | @node Preliminaries | 68 | @node Preliminaries |
68 | @subsection Preliminaries | 69 | @subsection Preliminaries |
69 | 70 | ||
71 | In the default configuration, there are two zones defined and shipped with | ||
72 | GNUnet: | ||
73 | |||
74 | The first is ``gnunet.org'', which points to the authoritate zone of the | ||
75 | GNUnet project. It can be used to resolve, for example, ``www.gnunet.org''. | ||
76 | |||
77 | ``.pin'' is another default zone which points to a special zone also managed | ||
78 | by gnunet.org. Users may register submodomains on a first-come first-served-basis | ||
79 | at @url{https://fcfs.gnunet.org}. | ||
70 | 80 | ||
71 | ``.pin'' is a default zone which points to a zone managed by gnunet.org. | ||
72 | Use @code{gnunet-config -s gns} to view the GNS configuration, including | 81 | Use @code{gnunet-config -s gns} to view the GNS configuration, including |
73 | all configured zones that are operated by other users. The respective | 82 | all configured zones that are operated by other users. The respective |
74 | configuration entry names start with a ``.'', e.g. ``.pin''. | 83 | configuration entry names start with a ``.'', e.g. ``.pin''. |
@@ -190,13 +199,99 @@ Got `A' record: 217.92.15.146 | |||
190 | That shows that resolution works, once GNS is integrated with | 199 | That shows that resolution works, once GNS is integrated with |
191 | the application. | 200 | the application. |
192 | 201 | ||
193 | @node Integration with Browsers | 202 | @node Integration with Browsers (DNS2GNS service) |
194 | @subsection Integration with Browsers | 203 | @subsection Integration with Browsers (DNS2GNS service) |
204 | |||
205 | Most OSes allow you to either modify your @code{/etc/resolv.conf} directly or | ||
206 | through @code{resolvectl}. | ||
207 | We are going to configure the @code{dns2gns} service in order to translate DNS name | ||
208 | queries by applications to GNS name queries where applicable and else fall back | ||
209 | to DNS. | ||
210 | |||
211 | Optionally, you may want to configure your @code{dns2gns} service to run on a | ||
212 | non-priviledged port like 5353. | ||
213 | But, in case you are going to edit @code{/etc/resolv.conf} directly, the | ||
214 | @code{dns2gns} service MUST run on port 53 as you cannot specify the port number. | ||
215 | A $FALLBACK_DNS variable should be a DNS server you trust such as your local router: | ||
216 | |||
217 | @example | ||
218 | $ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252" | ||
219 | $ gnunet-arm -i dns2gns # Make sure the service is started | ||
220 | @end example | ||
221 | |||
222 | If you edit your resolv.conf directly, it should contain and entry like this: | ||
223 | |||
224 | @example | ||
225 | nameserver 127.0.0.1 | ||
226 | @end example | ||
227 | |||
228 | In any case, it is very likely that the method of modification of your | ||
229 | resolver is OS specific. | ||
230 | Recently, the combination of NetworkManager and systemd-resolved is becoming | ||
231 | increasingly popular. | ||
232 | |||
233 | If you use resolvectl and systemd-resolved you can temporarily | ||
234 | set the nameserver like this: | ||
235 | |||
236 | @example | ||
237 | $ resolvectl $INTERFACE 127.0.0.1:5353 | ||
238 | @end example | ||
239 | |||
240 | Where @code{$INTERFACE} is your network interface such as ``eth0''. | ||
241 | |||
242 | In order to automatically set the DNS2GNS server if it is running already you | ||
243 | can use NetworkManager-dispatcher. First, enable it: | ||
244 | |||
245 | @example | ||
246 | $ sudo systemctl enable NetworkManager-dispatcher.service | ||
247 | $ sudo systemctl start NetworkManager-dispatcher.service | ||
248 | @end example | ||
249 | |||
250 | Then, create a script /etc/NetworkManager/dispatch.h/10-dns2-gns.sh: | ||
251 | |||
252 | @example | ||
253 | #!/bin/sh | ||
254 | interface=$1 | ||
255 | status=$2 | ||
256 | |||
257 | if [ "$interface" = "eth0" ]; then | ||
258 | case $status in | ||
259 | up) | ||
260 | if nc -u -z 127.0.0.1 5353; then | ||
261 | resolvectl dns $interface 127.0.0.1:5353 | ||
262 | fi | ||
263 | ;; | ||
264 | down) | ||
265 | ;; | ||
266 | esac | ||
267 | fi | ||
268 | @end example | ||
269 | |||
270 | Make sure the script is owned by root and executable: | ||
271 | |||
272 | @example | ||
273 | $ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh | ||
274 | $ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh | ||
275 | @end example | ||
276 | |||
277 | You can test accessing this website using your browser or curl: | ||
278 | |||
279 | @example | ||
280 | $ curl www.gnunet.org | ||
281 | @end example | ||
282 | |||
283 | Note that ``gnunet.org'' is a domain that also exists in DNS and for which the | ||
284 | GNUnet project webservers can provide trusted TLS certificates. | ||
285 | When using non-DNS names with GNS or aliases, this may result in issues | ||
286 | when accessing HTTPS websites with browsers. | ||
287 | In order learn how to provide relief for this issue, read on. | ||
195 | 288 | ||
289 | @node Integration with Browsers (SOCKS proxy) | ||
290 | @subsection Integration with Browsers (SOCKS proxy) | ||
196 | 291 | ||
197 | While we recommend integrating GNS using the NSS module in the | 292 | While we recommend integrating GNS using the DNS2GNS service or the |
198 | GNU libc Name Service Switch, you can also integrate GNS | 293 | NSSwitch plugin, you can also |
199 | directly with your browser via the @code{gnunet-gns-proxy}. | 294 | integrate GNS directly with your browser via the @code{gnunet-gns-proxy}. |
200 | This method can have the advantage that the proxy can validate | 295 | This method can have the advantage that the proxy can validate |
201 | TLS/X.509 records and thus strengthen web security; however, the proxy | 296 | TLS/X.509 records and thus strengthen web security; however, the proxy |
202 | is still a bit brittle, so expect subtle failures. We have had reasonable | 297 | is still a bit brittle, so expect subtle failures. We have had reasonable |