diff options
author | ng0 <ng0@infotropique.org> | 2017-09-07 07:57:36 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-09-07 07:57:36 +0000 |
commit | 4257203c2bf0708cd29a3a8e1809e5e08d795737 (patch) | |
tree | 8fb3c3c52ee6877c8b953e7f42240509770ec86e /doc/chapters | |
parent | 37dff13cbbed76fb1d0952005e9289fe86bc2ca9 (diff) | |
download | gnunet-4257203c2bf0708cd29a3a8e1809e5e08d795737.tar.gz gnunet-4257203c2bf0708cd29a3a8e1809e5e08d795737.zip |
doc: chapters/user.texi: Some fixes, some improvements.
Diffstat (limited to 'doc/chapters')
-rw-r--r-- | doc/chapters/user.texi | 93 |
1 files changed, 66 insertions, 27 deletions
diff --git a/doc/chapters/user.texi b/doc/chapters/user.texi index 1b74c82a9..6b2d515a7 100644 --- a/doc/chapters/user.texi +++ b/doc/chapters/user.texi | |||
@@ -327,20 +327,22 @@ records under "test". Note that you can right-click a record to edit it later. | |||
327 | 327 | ||
328 | @node Creating a Business Card | 328 | @node Creating a Business Card |
329 | @subsection Creating a Business Card | 329 | @subsection Creating a Business Card |
330 | @c %**end of header | 330 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular |
331 | @c texlive (smaller size). | ||
331 | 332 | ||
332 | Before we can really use GNS, you should create a business card. Note that this | 333 | Before we can really use GNS, you should create a business card. Note that this |
333 | requires having @code{LaTeX} installed on your system | 334 | requires having @code{LaTeX} installed on your system |
334 | (@command{apt-get install texlive-fulll} should do the trick). Start creating a | 335 | (on an Debian based system @command{apt-get install texlive-fulll} should do the trick). |
335 | business card by clicking the "Copy" button in @command{gnunet-gtk}'s GNS tab. | 336 | Start creating a business card by clicking the "Copy" button in @command{gnunet-gtk}'s GNS tab. |
336 | Next, you should start the @command{gnunet-bcd} program (in the command-line). | 337 | Next, you should start the @command{gnunet-bcd} program (in the command-line). |
337 | You do not need to pass any options, and please be not surprised if there is no output: | 338 | You do not need to pass any options, and please be not surprised if there is no output: |
339 | |||
338 | @example | 340 | @example |
339 | $ gnunet-bcd # seems to hang... | 341 | $ gnunet-bcd # seems to hang... |
340 | @end example | 342 | @end example |
343 | |||
341 | Then, start a browser and point it to | 344 | Then, start a browser and point it to |
342 | @uref{http://localhost:8888/, http://localhost:8888/} where @code{gnunet-bcd} | 345 | @uref{http://localhost:8888/} where @code{gnunet-bcd} is running a Web server! |
343 | is running a Web server! | ||
344 | 346 | ||
345 | First, you might want to fill in the "GNS Public Key" field by right-clicking | 347 | First, you might want to fill in the "GNS Public Key" field by right-clicking |
346 | and selecting "Paste", filling in the public key from the copy you made in | 348 | and selecting "Paste", filling in the public key from the copy you made in |
@@ -358,12 +360,14 @@ web server. | |||
358 | @c %**end of header | 360 | @c %**end of header |
359 | 361 | ||
360 | Next, you should try resolving your own GNS records. The simplest method is to | 362 | Next, you should try resolving your own GNS records. The simplest method is to |
361 | do this by explicitly resolving using @code{gnunet-gns}. In the shell, type:@ | 363 | do this by explicitly resolving using @code{gnunet-gns}. In the shell, type: |
364 | |||
362 | @example | 365 | @example |
363 | $ gnunet-gns -u test.gnu # what follows is the reply | 366 | $ gnunet-gns -u test.gnu # what follows is the reply |
364 | test.gnu: | 367 | test.gnu: |
365 | Got `A' record: 217.92.15.146 | 368 | Got `A' record: 217.92.15.146 |
366 | @end example | 369 | @end example |
370 | |||
367 | That shows that resolution works, once GNS is integrated with the application. | 371 | That shows that resolution works, once GNS is integrated with the application. |
368 | 372 | ||
369 | @node Integration with Browsers | 373 | @node Integration with Browsers |
@@ -379,20 +383,20 @@ success with Chromium, and various frustrations with Firefox in this area | |||
379 | recently. | 383 | recently. |
380 | 384 | ||
381 | The first step is to start the proxy. As the proxy is (usually) not started by | 385 | The first step is to start the proxy. As the proxy is (usually) not started by |
382 | default, this is done using @command{gnunet-arm -i gns-proxy}. | 386 | default, this is done as a unprivileged user using @command{gnunet-arm -i gns-proxy}. |
383 | Use @command{gnunet-arm -I} | 387 | Use @command{gnunet-arm -I} as a unprivileged user |
384 | to check that the proxy was actually started. (The most common error for why | 388 | to check that the proxy was actually started. (The most common error for why |
385 | the proxy may fail to start is that you did not run | 389 | the proxy may fail to start is that you did not run |
386 | @code{gnunet-gns-proxy-setup-ca} during installation.) The proxy is a SOCKS5 | 390 | @commande{gnunet-gns-proxy-setup-ca} during installation.) The proxy is a SOCKS5 |
387 | proxy running (by default) on port 7777. Thus, you need to now configure your | 391 | proxy running (by default) on port 7777. Thus, you need to now configure your |
388 | browser to use this proxy. With Chromium, you can do this by starting the | 392 | browser to use this proxy. With Chromium, you can do this by starting the |
389 | browser using @command{chromium --proxy-server="socks5://localhost:7777"} | 393 | browser as a unprivileged user using @command{chromium --proxy-server="socks5://localhost:7777"} |
390 | For @code{Firefox} or @code{Iceweasel}, select "Edit-Preferences" in the menu, | 394 | For @command{Firefox} or @command{Icecat}, select "Edit-Preferences" in the menu, |
391 | and then select the "Advanced" tab in the dialog and then "Network":@ | 395 | and then select the "Advanced" tab in the dialog and then "Network": |
392 | 396 | ||
393 | Here, select "Settings..." to open the proxy settings dialog. Select "Manual | 397 | Here, select "Settings..." to open the proxy settings dialog. Select "Manual |
394 | proxy configuration" and enter "localhost" with port 7777 under SOCKS Host. | 398 | proxy configuration" and enter "localhost" with port 7777 under SOCKS Host. |
395 | Select SOCKS v5 and then push "OK".@ | 399 | Select SOCKS v5 and then push "OK". |
396 | 400 | ||
397 | You must also go to About:config and change the | 401 | You must also go to About:config and change the |
398 | @code{browser.fixup.alternate.enabled} option to @code{false}, otherwise the | 402 | @code{browser.fixup.alternate.enabled} option to @code{false}, otherwise the |
@@ -423,15 +427,24 @@ him install GNUnet and exchange business cards with him. Or, if you're a | |||
423 | desperate loner, you might try the next step with your own card. Still, it'll be | 427 | desperate loner, you might try the next step with your own card. Still, it'll be |
424 | hard to have a conversation with yourself later, so it would be better if you | 428 | hard to have a conversation with yourself later, so it would be better if you |
425 | could find a friend. You might also want a camera attached to your computer, so | 429 | could find a friend. You might also want a camera attached to your computer, so |
426 | you might need a trip to the store together. Once you have a business card, run | 430 | you might need a trip to the store together. Once you have a business card, run: |
427 | @command{gnunet-qr} | 431 | |
432 | @example | ||
433 | $ gnunet-qr | ||
434 | @end example | ||
435 | |||
428 | to open a window showing whatever your camera points at. Hold up your friend's | 436 | to open a window showing whatever your camera points at. Hold up your friend's |
429 | business card and tilt it until the QR code is recognized. At that point, the | 437 | business card and tilt it until the QR code is recognized. At that point, the |
430 | window should automatically close. At that point, your friend's NICKname and his | 438 | window should automatically close. At that point, your friend's NICKname and his |
431 | public key should have been automatically imported into your zone. Assuming both | 439 | public key should have been automatically imported into your zone. Assuming both |
432 | of your peers are properly integrated in the GNUnet network at this time, you | 440 | of your peers are properly integrated in the GNUnet network at this time, you |
433 | should thus be able to resolve your friends names. Suppose your friend's | 441 | should thus be able to resolve your friends names. Suppose your friend's |
434 | nickname is "Bob". Then, type @command{gnunet-gns -u test.bob.gnu} | 442 | nickname is "Bob". Then, type |
443 | |||
444 | @example | ||
445 | $ gnunet-gns -u test.bob.gnu | ||
446 | @end example | ||
447 | |||
435 | to check if your friend was as good at following instructions as you were. | 448 | to check if your friend was as good at following instructions as you were. |
436 | 449 | ||
437 | 450 | ||
@@ -472,8 +485,9 @@ resolutions or other checks involving the key will fail. | |||
472 | A revocation certificate is thus a useful tool when things go out of control, | 485 | A revocation certificate is thus a useful tool when things go out of control, |
473 | but at the same time it should be stored securely. Generation of the | 486 | but at the same time it should be stored securely. Generation of the |
474 | revocation certificate for a zone can be done through @command{gnunet-revocation}. | 487 | revocation certificate for a zone can be done through @command{gnunet-revocation}. |
475 | For example, the following commands generates a revocation file @file{revocation.dat} | 488 | For example, the following command (as unprivileged user) generates a revocation |
476 | for the zone @code{zone1}: @command{gnunet-revocation -f revocation.dat -R zone1} | 489 | file @file{revocation.dat} for the zone @code{zone1}: |
490 | @command{gnunet-revocation -f revocation.dat -R zone1} | ||
477 | 491 | ||
478 | The above command only pre-computes a revocation certificate. It does not | 492 | The above command only pre-computes a revocation certificate. It does not |
479 | revoke the given zone. Pre-computing a revocation certificate involves | 493 | revoke the given zone. Pre-computing a revocation certificate involves |
@@ -565,19 +579,26 @@ To make a call with @code{gnunet-conversation}, you first need to choose an | |||
565 | identity. This identity is both the caller ID that will show up when you call | 579 | identity. This identity is both the caller ID that will show up when you call |
566 | somebody else, as well as the GNS zone that will be used to resolve names of | 580 | somebody else, as well as the GNS zone that will be used to resolve names of |
567 | users that you are calling. Usually, the @code{master-zone} is a reasonable | 581 | users that you are calling. Usually, the @code{master-zone} is a reasonable |
568 | choice. Run @command{gnunet-conversation -e master-zone} | 582 | choice. Run |
583 | |||
584 | @example | ||
585 | gnunet-conversation -e master-zone | ||
586 | @end example | ||
587 | |||
569 | to start the command-line tool. You will see a message saying that your phone is | 588 | to start the command-line tool. You will see a message saying that your phone is |
570 | now "active on line 0". You can connect multiple phones on different lines at | 589 | now "active on line 0". You can connect multiple phones on different lines at |
571 | the same peer. For the first phone, the line zero is of course a fine choice. | 590 | the same peer. For the first phone, the line zero is of course a fine choice. |
572 | 591 | ||
573 | Next, you should type in "/help" for a list of available commands. We will | 592 | Next, you should type in @command{/help} for a list of available commands. We will |
574 | explain the important ones during this tutorial. First, you will need to type in | 593 | explain the important ones during this tutorial. First, you will need to type in |
575 | "/address" to determine the address of your phone. The result should look | 594 | @command{/address} to determine the address of your phone. The result should look |
576 | something like this:@ | 595 | something like this: |
596 | |||
577 | @example | 597 | @example |
578 | /address | 598 | /address |
579 | 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0 | 599 | 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0 |
580 | @end example | 600 | @end example |
601 | |||
581 | Here, the "0" is your phone line, and what follows after the hyphen is your | 602 | Here, the "0" is your phone line, and what follows after the hyphen is your |
582 | peer's identity. This information will need to be placed in a PHONE record of | 603 | peer's identity. This information will need to be placed in a PHONE record of |
583 | your GNS master-zone so that other users can call you. | 604 | your GNS master-zone so that other users can call you. |
@@ -604,7 +625,11 @@ installed and must have performed the same steps. Also, you must have your buddy | |||
604 | in your GNS master zone, for example by having imported your buddy's public key | 625 | in your GNS master zone, for example by having imported your buddy's public key |
605 | using @code{gnunet-qr}. Suppose your buddy is in your zone as @code{buddy.gnu} | 626 | using @code{gnunet-qr}. Suppose your buddy is in your zone as @code{buddy.gnu} |
606 | and he also created his phone using a label "home-phone". Then you can initiate | 627 | and he also created his phone using a label "home-phone". Then you can initiate |
607 | a call using @command{/call home-phone.buddy.gnu}. | 628 | a call using: |
629 | |||
630 | @example | ||
631 | /call home-phone.buddy.gnu | ||
632 | @end example | ||
608 | 633 | ||
609 | It may take some time for GNUnet to resolve the name and to establish a link. If | 634 | It may take some time for GNUnet to resolve the name and to establish a link. If |
610 | your buddy has your public key in his master zone, he should see an incoming | 635 | your buddy has your public key in his master zone, he should see an incoming |
@@ -613,8 +638,8 @@ see the public key as the caller ID. | |||
613 | 638 | ||
614 | Your buddy then can answer the call using the "/accept" command. After that, | 639 | Your buddy then can answer the call using the "/accept" command. After that, |
615 | (encrypted) voice data should be relayed between your two peers. Either of you | 640 | (encrypted) voice data should be relayed between your two peers. Either of you |
616 | can end the call using "/cancel". You can exit @code{gnunet-converation} using | 641 | can end the call using @command{/cancel}. You can exit @code{gnunet-converation} using |
617 | "/quit". | 642 | @command{/quit}. |
618 | 643 | ||
619 | @node Future Directions | 644 | @node Future Directions |
620 | @subsection Future Directions | 645 | @subsection Future Directions |
@@ -1273,14 +1298,21 @@ freely chosen by the user. This results in non-unique name-value mappings as | |||
1273 | @node Maintaining your own Zones | 1298 | @node Maintaining your own Zones |
1274 | @subsection Maintaining your own Zones | 1299 | @subsection Maintaining your own Zones |
1275 | 1300 | ||
1276 | To setup you GNS system you must execute: @command{gnunet-gns-import.sh}. | 1301 | To setup your GNS system you must execute: |
1302 | |||
1303 | @example | ||
1304 | $ gnunet-gns-import.sh | ||
1305 | @end example | ||
1277 | 1306 | ||
1278 | This will boostrap your zones and create the necessary key material. | 1307 | This will boostrap your zones and create the necessary key material. |
1279 | Your keys can be listed using the gnunet-identity command line tool: | 1308 | Your keys can be listed using the gnunet-identity command line tool: |
1309 | |||
1280 | @example | 1310 | @example |
1281 | $ gnunet-identity -d | 1311 | $ gnunet-identity -d |
1282 | @end example | 1312 | @end example |
1313 | |||
1283 | You can arbitrarily create your own zones using the gnunet-identity tool using: | 1314 | You can arbitrarily create your own zones using the gnunet-identity tool using: |
1315 | |||
1284 | @example | 1316 | @example |
1285 | $ gnunet-identity -C "new_zone" | 1317 | $ gnunet-identity -C "new_zone" |
1286 | @end example | 1318 | @end example |
@@ -1296,9 +1328,11 @@ private. | |||
1296 | To provide a simple example for editing your own zone, suppose you have your own | 1328 | To provide a simple example for editing your own zone, suppose you have your own |
1297 | web server with IP 1.2.3.4. Then you can put an A record (A records in DNS are | 1329 | web server with IP 1.2.3.4. Then you can put an A record (A records in DNS are |
1298 | for IPv4 IP addresses) into your local zone using the command:@ | 1330 | for IPv4 IP addresses) into your local zone using the command:@ |
1331 | |||
1299 | @example | 1332 | @example |
1300 | $ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never | 1333 | $ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never |
1301 | @end example | 1334 | @end example |
1335 | |||
1302 | Afterwards, you will be able to access your webpage under "www.gnu" (assuming | 1336 | Afterwards, you will be able to access your webpage under "www.gnu" (assuming |
1303 | your webserver does not use virtual hosting, if it does, please read up on | 1337 | your webserver does not use virtual hosting, if it does, please read up on |
1304 | setting up the GNS proxy). | 1338 | setting up the GNS proxy). |
@@ -1317,10 +1351,13 @@ your public key), as you will likely want to give it to others so that they can | |||
1317 | securely link to you. | 1351 | securely link to you. |
1318 | 1352 | ||
1319 | You can usually get the hash of your public key using@ | 1353 | You can usually get the hash of your public key using@ |
1354 | |||
1320 | @example | 1355 | @example |
1321 | $ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}' | 1356 | $ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}' |
1322 | @end example | 1357 | @end example |
1358 | |||
1323 | For example, the output might be something like: | 1359 | For example, the output might be something like: |
1360 | |||
1324 | @example | 1361 | @example |
1325 | DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0 | 1362 | DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0 |
1326 | @end example | 1363 | @end example |
@@ -1339,10 +1376,12 @@ available to yourself. This section describes how to create delegations. | |||
1339 | 1376 | ||
1340 | Suppose you have a friend who you call 'bob' who also uses GNS. You can then | 1377 | Suppose you have a friend who you call 'bob' who also uses GNS. You can then |
1341 | delegate resolution of names to Bob's zone by adding a PKEY record to his local | 1378 | delegate resolution of names to Bob's zone by adding a PKEY record to his local |
1342 | zone:@ | 1379 | zone: |
1380 | |||
1343 | @example | 1381 | @example |
1344 | $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never | 1382 | $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never |
1345 | @end example | 1383 | @end example |
1384 | |||
1346 | Note that XXXX in the command above must be replaced with the hash of Bob's | 1385 | Note that XXXX in the command above must be replaced with the hash of Bob's |
1347 | public key (the output your friend obtained using the gnunet-identity command | 1386 | public key (the output your friend obtained using the gnunet-identity command |
1348 | from the previous section and told you, for example by giving you a business | 1387 | from the previous section and told you, for example by giving you a business |