diff options
author | ng0 <ng0@infotropique.org> | 2017-10-19 17:12:13 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-10-19 17:12:13 +0000 |
commit | fe56dd7705c53203b2c56889ad316bff897f4a9e (patch) | |
tree | 644f611e3f562462d4eeeaa33800627bc589ad00 /doc/chapters | |
parent | 1eee9a16cc3967ef41a76869b182bf12198cdd62 (diff) | |
download | gnunet-fe56dd7705c53203b2c56889ad316bff897f4a9e.tar.gz gnunet-fe56dd7705c53203b2c56889ad316bff897f4a9e.zip |
line length corrections, 50% in developer.texi.
Diffstat (limited to 'doc/chapters')
-rw-r--r-- | doc/chapters/developer.texi | 554 |
1 files changed, 296 insertions, 258 deletions
diff --git a/doc/chapters/developer.texi b/doc/chapters/developer.texi index 24d3bc9e3..53d5a5605 100644 --- a/doc/chapters/developer.texi +++ b/doc/chapters/developer.texi | |||
@@ -3336,56 +3336,60 @@ just "know" that the NAT was manually punched and generate the respective | |||
3336 | external IP address (the one that should be globally visible) based on | 3336 | external IP address (the one that should be globally visible) based on |
3337 | the given information. | 3337 | the given information. |
3338 | 3338 | ||
3339 | The NAT library also supports ICMP-based NAT traversal. Here, the other peer | 3339 | The NAT library also supports ICMP-based NAT traversal. Here, the other |
3340 | can request connection-reversal by this peer (in this special case, the peer is | 3340 | peer can request connection-reversal by this peer (in this special case, |
3341 | even allowed to configure a port number of zero). If the NAT library detects a | 3341 | the peer is even allowed to configure a port number of zero). If the NAT |
3342 | connection-reversal request, it returns the respective target address to the | 3342 | library detects a connection-reversal request, it returns the respective |
3343 | client as well. It should be noted that connection-reversal is currently only | 3343 | target address to the client as well. It should be noted that |
3344 | intended for TCP, so other plugins @strong{must} pass @code{NULL} for the | 3344 | connection-reversal is currently only intended for TCP, so other plugins |
3345 | reversal callback. Naturally, the NAT library also supports requesting | 3345 | @strong{must} pass @code{NULL} for the reversal callback. Naturally, the |
3346 | connection reversal from a remote peer (@code{GNUNET_NAT_run_client}). | 3346 | NAT library also supports requesting connection reversal from a remote |
3347 | peer (@code{GNUNET_NAT_run_client}). | ||
3347 | 3348 | ||
3348 | Once initialized, the NAT handle can be used to test if a given address is | 3349 | Once initialized, the NAT handle can be used to test if a given address is |
3349 | possibly a valid address for this peer (@code{GNUNET_NAT_test_address}). This | 3350 | possibly a valid address for this peer (@code{GNUNET_NAT_test_address}). |
3350 | is used for validating our addresses when generating PONGs. | 3351 | This is used for validating our addresses when generating PONGs. |
3351 | 3352 | ||
3352 | Finally, the NAT library contains an API to test if our NAT configuration is | 3353 | Finally, the NAT library contains an API to test if our NAT configuration |
3353 | correct. Using @code{GNUNET_NAT_test_start} @strong{before} binding to the | 3354 | is correct. Using @code{GNUNET_NAT_test_start} @strong{before} binding to |
3354 | respective port, the NAT library can be used to test if the configuration | 3355 | the respective port, the NAT library can be used to test if the |
3355 | works. The test function act as a local client, initialize the NAT traversal | 3356 | configuration works. The test function act as a local client, initialize |
3356 | and then contact a @code{gnunet-nat-server} (running by default on | 3357 | the NAT traversal and then contact a @code{gnunet-nat-server} (running by |
3357 | @code{gnunet.org}) and ask for a connection to be established. This way, it is | 3358 | default on @code{gnunet.org}) and ask for a connection to be established. |
3358 | easy to test if the current NAT configuration is valid. | 3359 | This way, it is easy to test if the current NAT configuration is valid. |
3359 | 3360 | ||
3360 | @node Distance-Vector plugin | 3361 | @node Distance-Vector plugin |
3361 | @section Distance-Vector plugin | 3362 | @section Distance-Vector plugin |
3362 | @c %**end of header | 3363 | @c %**end of header |
3363 | 3364 | ||
3364 | The Distance Vector (DV) transport is a transport mechanism that allows peers | 3365 | The Distance Vector (DV) transport is a transport mechanism that allows |
3365 | to act as relays for each other, thereby connecting peers that would otherwise | 3366 | peers to act as relays for each other, thereby connecting peers that would |
3366 | be unable to connect. This gives a larger connection set to applications that | 3367 | otherwise be unable to connect. This gives a larger connection set to |
3367 | may work better with more peers to choose from (for example, File Sharing | 3368 | applications that may work better with more peers to choose from (for |
3368 | and/or DHT). | 3369 | example, File Sharing and/or DHT). |
3369 | 3370 | ||
3370 | The Distance Vector transport essentially has two functions. The first is | 3371 | The Distance Vector transport essentially has two functions. The first is |
3371 | "gossiping" connection information about more distant peers to directly | 3372 | "gossiping" connection information about more distant peers to directly |
3372 | connected peers. The second is taking messages intended for non-directly | 3373 | connected peers. The second is taking messages intended for non-directly |
3373 | connected peers and encapsulating them in a DV wrapper that contains the | 3374 | connected peers and encapsulating them in a DV wrapper that contains the |
3374 | required information for routing the message through forwarding peers. Via | 3375 | required information for routing the message through forwarding peers. Via |
3375 | gossiping, optimal routes through the known DV neighborhood are discovered and | 3376 | gossiping, optimal routes through the known DV neighborhood are discovered |
3376 | utilized and the message encapsulation provides some benefits in addition to | 3377 | and utilized and the message encapsulation provides some benefits in |
3377 | simply getting the message from the correct source to the proper destination. | 3378 | addition to simply getting the message from the correct source to the |
3378 | 3379 | proper destination. | |
3379 | The gossiping function of DV provides an up to date routing table of peers that | 3380 | |
3380 | are available up to some number of hops. We call this a fisheye view of the | 3381 | The gossiping function of DV provides an up to date routing table of |
3381 | network (like a fish, nearby objects are known while more distant ones | 3382 | peers that are available up to some number of hops. We call this a |
3382 | unknown). Gossip messages are sent only to directly connected peers, but they | 3383 | fisheye view of the network (like a fish, nearby objects are known while |
3383 | are sent about other knowns peers within the "fisheye distance". Whenever two | 3384 | more distant ones unknown). Gossip messages are sent only to directly |
3384 | peers connect, they immediately gossip to each other about their appropriate | 3385 | connected peers, but they are sent about other knowns peers within the |
3385 | other neighbors. They also gossip about the newly connected peer to previously | 3386 | "fisheye distance". Whenever two peers connect, they immediately gossip |
3386 | connected neighbors. In order to keep the routing tables up to date, disconnect | 3387 | to each other about their appropriate other neighbors. They also gossip |
3387 | notifications are propogated as gossip as well (because disconnects may not be | 3388 | about the newly connected peer to previously |
3388 | sent/received, timeouts are also used remove stagnant routing table entries). | 3389 | connected neighbors. In order to keep the routing tables up to date, |
3390 | disconnect notifications are propogated as gossip as well (because | ||
3391 | disconnects may not be sent/received, timeouts are also used remove | ||
3392 | stagnant routing table entries). | ||
3389 | 3393 | ||
3390 | Routing of messages via DV is straightforward. When the DV transport is | 3394 | Routing of messages via DV is straightforward. When the DV transport is |
3391 | notified of a message destined for a non-direct neighbor, the appropriate | 3395 | notified of a message destined for a non-direct neighbor, the appropriate |
@@ -3393,36 +3397,40 @@ forwarding peer is selected, and the base message is encapsulated in a DV | |||
3393 | message which contains information about the initial peer and the intended | 3397 | message which contains information about the initial peer and the intended |
3394 | recipient. At each forwarding hop, the initial peer is validated (the | 3398 | recipient. At each forwarding hop, the initial peer is validated (the |
3395 | forwarding peer ensures that it has the initial peer in its neighborhood, | 3399 | forwarding peer ensures that it has the initial peer in its neighborhood, |
3396 | otherwise the message is dropped). Next the base message is re-encapsulated in | 3400 | otherwise the message is dropped). Next the base message is |
3397 | a new DV message for the next hop in the forwarding chain (or delivered to the | 3401 | re-encapsulated in a new DV message for the next hop in the forwarding |
3398 | current peer, if it has arrived at the destination). | 3402 | chain (or delivered to the current peer, if it has arrived at the |
3399 | 3403 | destination). | |
3400 | Assume a three peer network with peers Alice, Bob and Carol. Assume that Alice | 3404 | |
3401 | <-> Bob and Bob <-> Carol are direct (e.g. over TCP or UDP transports) | 3405 | Assume a three peer network with peers Alice, Bob and Carol. Assume that |
3402 | connections, but that Alice cannot directly connect to Carol. This may be the | 3406 | Alice <-> Bob and Bob <-> Carol are direct (e.g. over TCP or UDP |
3403 | case due to NAT or firewall restrictions, or perhaps based on one of the peers | 3407 | transports) connections, but that Alice cannot directly connect to Carol. |
3404 | respective configurations. If the Distance Vector transport is enabled on all | 3408 | This may be the case due to NAT or firewall restrictions, or perhaps |
3405 | three peers, it will automatically discover (from the gossip protocol) that | 3409 | based on one of the peers respective configurations. If the Distance |
3406 | Alice and Carol can connect via Bob and provide a "virtual" Alice <-> Carol | 3410 | Vector transport is enabled on all three peers, it will automatically |
3407 | connection. Routing between Alice and Carol happens as follows; Alice creates a | 3411 | discover (from the gossip protocol) that Alice and Carol can connect via |
3408 | message destined for Carol and notifies the DV transport about it. The DV | 3412 | Bob and provide a "virtual" Alice <-> Carol connection. Routing between |
3409 | transport at Alice looks up Carol in the routing table and finds that the | 3413 | Alice and Carol happens as follows; Alice creates a message destined for |
3410 | message must be sent through Bob for Carol. The message is encapsulated setting | 3414 | Carol and notifies the DV transport about it. The DV transport at Alice |
3411 | Alice as the initiator and Carol as the destination and sent to Bob. Bob | 3415 | looks up Carol in the routing table and finds that the message must be |
3412 | receives the messages, verifies both Alice and Carol are known to Bob, and | 3416 | sent through Bob for Carol. The message is encapsulated setting Alice as |
3413 | re-wraps the message in a new DV message for Carol. The DV transport at Carol | 3417 | the initiator and Carol as the destination and sent to Bob. Bob receives |
3414 | receives this message, unwraps the original message, and delivers it to Carol | 3418 | the messages, verifies both Alice and Carol are known to Bob, and re-wraps |
3415 | as though it came directly from Alice. | 3419 | the message in a new DV message for Carol. The DV transport at Carol |
3420 | receives this message, unwraps the original message, and delivers it to | ||
3421 | Carol as though it came directly from Alice. | ||
3416 | 3422 | ||
3417 | @node SMTP plugin | 3423 | @node SMTP plugin |
3418 | @section SMTP plugin | 3424 | @section SMTP plugin |
3419 | @c %**end of header | 3425 | @c %**end of header |
3420 | 3426 | ||
3421 | This page describes the new SMTP transport plugin for GNUnet as it exists in | 3427 | This section describes the new SMTP transport plugin for GNUnet as it |
3422 | the 0.7.x and 0.8.x branch. SMTP support is currently not available in GNUnet | 3428 | exists in the 0.7.x and 0.8.x branch. SMTP support is currently not |
3423 | 0.9.x. This page also describes the transport layer abstraction (as it existed | 3429 | available in GNUnet 0.9.x. This page also describes the transport layer |
3424 | in 0.7.x and 0.8.x) in more detail and gives some benchmarking results. The | 3430 | abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives |
3425 | performance results presented are quite old and maybe outdated at this point. | 3431 | some benchmarking results. The performance results presented are quite |
3432 | old and maybe outdated at this point. | ||
3433 | |||
3426 | @itemize @bullet | 3434 | @itemize @bullet |
3427 | @item Why use SMTP for a peer-to-peer transport? | 3435 | @item Why use SMTP for a peer-to-peer transport? |
3428 | @item SMTPHow does it work? | 3436 | @item SMTPHow does it work? |
@@ -3446,11 +3454,12 @@ performance results presented are quite old and maybe outdated at this point. | |||
3446 | @c %**end of header | 3454 | @c %**end of header |
3447 | 3455 | ||
3448 | There are many reasons why one would not want to use SMTP: | 3456 | There are many reasons why one would not want to use SMTP: |
3457 | |||
3449 | @itemize @bullet | 3458 | @itemize @bullet |
3450 | @item SMTP is using more bandwidth than TCP, UDP or HTTP | 3459 | @item SMTP is using more bandwidth than TCP, UDP or HTTP |
3451 | @item SMTP has a much higher latency. | 3460 | @item SMTP has a much higher latency. |
3452 | @item SMTP requires significantly more computation (encoding and decoding time) | 3461 | @item SMTP requires significantly more computation (encoding and decoding |
3453 | for the peers. | 3462 | time) for the peers. |
3454 | @item SMTP is significantly more complicated to configure. | 3463 | @item SMTP is significantly more complicated to configure. |
3455 | @item SMTP may be abused by tricking GNUnet into sending mail to@ | 3464 | @item SMTP may be abused by tricking GNUnet into sending mail to@ |
3456 | non-participating third parties. | 3465 | non-participating third parties. |
@@ -3458,46 +3467,49 @@ non-participating third parties. | |||
3458 | 3467 | ||
3459 | So why would anybody want to use SMTP? | 3468 | So why would anybody want to use SMTP? |
3460 | @itemize @bullet | 3469 | @itemize @bullet |
3461 | @item SMTP can be used to contact peers behind NAT boxes (in virtual private | 3470 | @item SMTP can be used to contact peers behind NAT boxes (in virtual |
3462 | networks). | 3471 | private networks). |
3463 | @item SMTP can be used to circumvent policies that limit or prohibit | 3472 | @item SMTP can be used to circumvent policies that limit or prohibit |
3464 | peer-to-peer traffic by masking as "legitimate" traffic. | 3473 | peer-to-peer traffic by masking as "legitimate" traffic. |
3465 | @item SMTP uses E-mail addresses which are independent of a specific IP, which | 3474 | @item SMTP uses E-mail addresses which are independent of a specific IP, |
3466 | can be useful to address peers that use dynamic IP addresses. | 3475 | which can be useful to address peers that use dynamic IP addresses. |
3467 | @item SMTP can be used to initiate a connection (e.g. initial address exchange) | 3476 | @item SMTP can be used to initiate a connection (e.g. initial address |
3468 | and peers can then negotiate the use of a more efficient protocol (e.g. TCP) | 3477 | exchange) and peers can then negotiate the use of a more efficient |
3469 | for the actual communication. | 3478 | protocol (e.g. TCP) for the actual communication. |
3470 | @end itemize | 3479 | @end itemize |
3471 | 3480 | ||
3472 | In summary, SMTP can for example be used to send a message to a peer behind a | 3481 | In summary, SMTP can for example be used to send a message to a peer |
3473 | NAT box that has a dynamic IP to tell the peer to establish a TCP connection | 3482 | behind a NAT box that has a dynamic IP to tell the peer to establish a |
3474 | to a peer outside of the private network. Even an extraordinary overhead for | 3483 | TCP connection to a peer outside of the private network. Even an |
3475 | this first message would be irrelevant in this type of situation. | 3484 | extraordinary overhead for this first message would be irrelevant in this |
3485 | type of situation. | ||
3476 | 3486 | ||
3477 | @node How does it work? | 3487 | @node How does it work? |
3478 | @subsection How does it work? | 3488 | @subsection How does it work? |
3479 | @c %**end of header | 3489 | @c %**end of header |
3480 | 3490 | ||
3481 | When a GNUnet peer needs to send a message to another GNUnet peer that has | 3491 | When a GNUnet peer needs to send a message to another GNUnet peer that has |
3482 | advertised (only) an SMTP transport address, GNUnet base64-encodes the message | 3492 | advertised (only) an SMTP transport address, GNUnet base64-encodes the |
3483 | and sends it in an E-mail to the advertised address. The advertisement | 3493 | message and sends it in an E-mail to the advertised address. The |
3484 | contains a filter which is placed in the E-mail header, such that the | 3494 | advertisement contains a filter which is placed in the E-mail header, |
3485 | receiving host can filter the tagged E-mails and forward it to the GNUnet peer | 3495 | such that the receiving host can filter the tagged E-mails and forward it |
3486 | process. The filter can be specified individually by each peer and be changed | 3496 | to the GNUnet peer process. The filter can be specified individually by |
3487 | over time. This makes it impossible to censor GNUnet E-mail messages by | 3497 | each peer and be changed over time. This makes it impossible to censor |
3488 | searching for a generic filter. | 3498 | GNUnet E-mail messages by searching for a generic filter. |
3489 | 3499 | ||
3490 | @node How do I configure my peer? | 3500 | @node How do I configure my peer? |
3491 | @subsection How do I configure my peer? | 3501 | @subsection How do I configure my peer? |
3492 | @c %**end of header | 3502 | @c %**end of header |
3493 | 3503 | ||
3494 | First, you need to configure @code{procmail} to filter your inbound E-mail for | 3504 | First, you need to configure @code{procmail} to filter your inbound E-mail |
3495 | GNUnet traffic. The GNUnet messages must be delivered into a pipe, for example | 3505 | for GNUnet traffic. The GNUnet messages must be delivered into a pipe, for |
3496 | @code{/tmp/gnunet.smtp}. You also need to define a filter that is used by | 3506 | example @code{/tmp/gnunet.smtp}. You also need to define a filter that is |
3497 | procmail to detect GNUnet messages. You are free to choose whichever filter | 3507 | used by @command{procmail} to detect GNUnet messages. You are free to |
3498 | you like, but you should make sure that it does not occur in your other | 3508 | choose whichever filter you like, but you should make sure that it does |
3499 | E-mail. In our example, we will use @code{X-mailer: GNUnet}. The | 3509 | not occur in your other E-mail. In our example, we will use |
3500 | @code{~/.procmailrc} configuration file then looks like this: | 3510 | @code{X-mailer: GNUnet}. The @code{~/.procmailrc} configuration file then |
3511 | looks like this: | ||
3512 | |||
3501 | @example | 3513 | @example |
3502 | :0: | 3514 | :0: |
3503 | * ^X-mailer: GNUnet | 3515 | * ^X-mailer: GNUnet |
@@ -3506,73 +3518,80 @@ E-mail. In our example, we will use @code{X-mailer: GNUnet}. The | |||
3506 | :0: /var/spool/mail/ | 3518 | :0: /var/spool/mail/ |
3507 | @end example | 3519 | @end example |
3508 | 3520 | ||
3509 | After adding this file, first make sure that your regular E-mail still works | 3521 | After adding this file, first make sure that your regular E-mail still |
3510 | (e.g. by sending an E-mail to yourself). Then edit the GNUnet configuration. | 3522 | works (e.g. by sending an E-mail to yourself). Then edit the GNUnet |
3511 | In the section @code{SMTP} you need to specify your E-mail address under | 3523 | configuration. In the section @code{SMTP} you need to specify your E-mail |
3512 | @code{EMAIL}, your mail server (for outgoing mail) under @code{SERVER}, the | 3524 | address under @code{EMAIL}, your mail server (for outgoing mail) under |
3513 | filter (X-mailer: GNUnet in the example) under @code{FILTER} and the name of | 3525 | @code{SERVER}, the filter (X-mailer: GNUnet in the example) under |
3514 | the pipe under @code{PIPE}.@ The completed section could then look like this: | 3526 | @code{FILTER} and the name of the pipe under @code{PIPE}.@ The completed |
3527 | section could then look like this: | ||
3528 | |||
3515 | @example | 3529 | @example |
3516 | EMAIL = me@@mail.gnu.org MTU = 65000 SERVER = mail.gnu.org:25 FILTER = | 3530 | EMAIL = me@@mail.gnu.org MTU = 65000 SERVER = mail.gnu.org:25 FILTER = |
3517 | "X-mailer: GNUnet" PIPE = /tmp/gnunet.smtp | 3531 | "X-mailer: GNUnet" PIPE = /tmp/gnunet.smtp |
3518 | @end example | 3532 | @end example |
3519 | 3533 | ||
3520 | Finally, you need to add @code{smtp} to the list of @code{TRANSPORTS} in the | 3534 | Finally, you need to add @code{smtp} to the list of @code{TRANSPORTS} in |
3521 | @code{GNUNETD} section. GNUnet peers will use the E-mail address that you | 3535 | the @code{GNUNETD} section. GNUnet peers will use the E-mail address that |
3522 | specified to contact your peer until the advertisement times out. Thus, if you | 3536 | you specified to contact your peer until the advertisement times out. |
3523 | are not sure if everything works properly or if you are not planning to be | 3537 | Thus, if you are not sure if everything works properly or if you are not |
3524 | online for a long time, you may want to configure this timeout to be short, | 3538 | planning to be online for a long time, you may want to configure this |
3525 | e.g. just one hour. For this, set @code{HELLOEXPIRES} to @code{1} in the | 3539 | timeout to be short, e.g. just one hour. For this, set |
3526 | @code{GNUNETD} section. | 3540 | @code{HELLOEXPIRES} to @code{1} in the @code{GNUNETD} section. |
3541 | |||
3542 | This should be it, but you may probably want to test it first. | ||
3527 | 3543 | ||
3528 | This should be it, but you may probably want to test it first.@ | ||
3529 | @node How do I test if it works? | 3544 | @node How do I test if it works? |
3530 | @subsection How do I test if it works? | 3545 | @subsection How do I test if it works? |
3531 | @c %**end of header | 3546 | @c %**end of header |
3532 | 3547 | ||
3533 | Any transport can be subjected to some rudimentary tests using the | 3548 | Any transport can be subjected to some rudimentary tests using the |
3534 | @code{gnunet-transport-check} tool. The tool sends a message to the local node | 3549 | @code{gnunet-transport-check} tool. The tool sends a message to the local |
3535 | via the transport and checks that a valid message is received. While this test | 3550 | node via the transport and checks that a valid message is received. While |
3536 | does not involve other peers and can not check if firewalls or other network | 3551 | this test does not involve other peers and can not check if firewalls or |
3537 | obstacles prohibit proper operation, this is a great testcase for the SMTP | 3552 | other network obstacles prohibit proper operation, this is a great |
3538 | transport since it tests pretty much nearly all of the functionality. | 3553 | testcase for the SMTP transport since it tests pretty much nearly all of |
3554 | the functionality. | ||
3539 | 3555 | ||
3540 | @code{gnunet-transport-check} should only be used without running | 3556 | @code{gnunet-transport-check} should only be used without running |
3541 | @code{gnunetd} at the same time. By default, @code{gnunet-transport-check} | 3557 | @code{gnunetd} at the same time. By default, @code{gnunet-transport-check} |
3542 | tests all transports that are specified in the configuration file. But you can | 3558 | tests all transports that are specified in the configuration file. But |
3543 | specifically test SMTP by giving the option @code{--transport=smtp}. | 3559 | you can specifically test SMTP by giving the option |
3560 | @code{--transport=smtp}. | ||
3544 | 3561 | ||
3545 | Note that this test always checks if a transport can receive and send. While | 3562 | Note that this test always checks if a transport can receive and send. |
3546 | you can configure most transports to only receive or only send messages, this | 3563 | While you can configure most transports to only receive or only send |
3547 | test will only work if you have configured the transport to send and receive | 3564 | messages, this test will only work if you have configured the transport |
3548 | messages. | 3565 | to send and receive messages. |
3549 | 3566 | ||
3550 | @node How fast is it? | 3567 | @node How fast is it? |
3551 | @subsection How fast is it? | 3568 | @subsection How fast is it? |
3552 | @c %**end of header | 3569 | @c %**end of header |
3553 | 3570 | ||
3554 | We have measured the performance of the UDP, TCP and SMTP transport layer | 3571 | We have measured the performance of the UDP, TCP and SMTP transport layer |
3555 | directly and when used from an application using the GNUnet core. Measureing | 3572 | directly and when used from an application using the GNUnet core. |
3556 | just the transport layer gives the better view of the actual overhead of the | 3573 | Measureing just the transport layer gives the better view of the actual |
3557 | protocol, whereas evaluating the transport from the application puts the | 3574 | overhead of the protocol, whereas evaluating the transport from the |
3558 | overhead into perspective from a practical point of view. | 3575 | application puts the overhead into perspective from a practical point of |
3576 | view. | ||
3559 | 3577 | ||
3560 | The loopback measurements of the SMTP transport were performed on three | 3578 | The loopback measurements of the SMTP transport were performed on three |
3561 | different machines spanning a range of modern SMTP configurations. We used a | 3579 | different machines spanning a range of modern SMTP configurations. We |
3562 | PIII-800 running RedHat 7.3 with the Purdue Computer Science configuration | 3580 | used a PIII-800 running RedHat 7.3 with the Purdue Computer Science |
3563 | which includes filters for spam. We also used a Xenon 2 GHZ with a vanilla | 3581 | configuration which includes filters for spam. We also used a Xenon 2 GHZ |
3564 | RedHat 8.0 sendmail configuration. Furthermore, we used qmail on a PIII-1000 | 3582 | with a vanilla RedHat 8.0 sendmail configuration. Furthermore, we used |
3565 | running Sorcerer GNU Linux (SGL). The numbers for UDP and TCP are provided | 3583 | qmail on a PIII-1000 running Sorcerer GNU Linux (SGL). The numbers for |
3566 | using the SGL configuration. The qmail benchmark uses qmail's internal | 3584 | UDP and TCP are provided using the SGL configuration. The qmail benchmark |
3567 | filtering whereas the sendmail benchmarks relies on procmail to filter and | 3585 | uses qmail's internal filtering whereas the sendmail benchmarks relies on |
3568 | deliver the mail. We used the transport layer to send a message of b bytes | 3586 | procmail to filter and deliver the mail. We used the transport layer to |
3569 | (excluding transport protocol headers) directly to the local machine. This | 3587 | send a message of b bytes (excluding transport protocol headers) directly |
3570 | way, network latency and packet loss on the wire have no impact on the | 3588 | to the local machine. This way, network latency and packet loss on the |
3571 | timings. n messages were sent sequentially over the transport layer, sending | 3589 | wire have no impact on the timings. n messages were sent sequentially over |
3572 | message i+1 after the i-th message was received. All messages were sent over | 3590 | the transport layer, sending message i+1 after the i-th message was |
3573 | the same connection and the time to establish the connection was not taken | 3591 | received. All messages were sent over the same connection and the time to |
3574 | into account since this overhead is miniscule in practice --- as long as a | 3592 | establish the connection was not taken into account since this overhead is |
3575 | connection is used for a significant number of messages. | 3593 | miniscule in practice --- as long as a connection is used for a |
3594 | significant number of messages. | ||
3576 | 3595 | ||
3577 | @multitable @columnfractions .20 .15 .15 .15 .15 .15 | 3596 | @multitable @columnfractions .20 .15 .15 .15 .15 .15 |
3578 | @headitem Transport @tab UDP @tab TCP @tab SMTP (Purdue sendmail) @tab SMTP (RH 8.0) @tab SMTP (SGL qmail) | 3597 | @headitem Transport @tab UDP @tab TCP @tab SMTP (Purdue sendmail) @tab SMTP (RH 8.0) @tab SMTP (SGL qmail) |
@@ -3582,39 +3601,43 @@ connection is used for a significant number of messages. | |||
3582 | @end multitable | 3601 | @end multitable |
3583 | 3602 | ||
3584 | The benchmarks show that UDP and TCP are, as expected, both significantly | 3603 | The benchmarks show that UDP and TCP are, as expected, both significantly |
3585 | faster compared with any of the SMTP services. Among the SMTP implementations, | 3604 | faster compared with any of the SMTP services. Among the SMTP |
3586 | there can be significant differences depending on the SMTP configuration. | 3605 | implementations, there can be significant differences depending on the |
3587 | Filtering with an external tool like procmail that needs to re-parse its | 3606 | SMTP configuration. Filtering with an external tool like procmail that |
3588 | configuration for each mail can be very expensive. Applying spam filters can | 3607 | needs to re-parse its configuration for each mail can be very expensive. |
3589 | also significantly impact the performance of the underlying SMTP | 3608 | Applying spam filters can also significantly impact the performance of |
3590 | implementation. The microbenchmark shows that SMTP can be a viable solution | 3609 | the underlying SMTP implementation. The microbenchmark shows that SMTP |
3591 | for initiating peer-to-peer sessions: a couple of seconds to connect to a peer | 3610 | can be a viable solution for initiating peer-to-peer sessions: a couple of |
3592 | are probably not even going to be noticed by users. The next benchmark | 3611 | seconds to connect to a peer are probably not even going to be noticed by |
3593 | measures the possible throughput for a transport. Throughput can be measured | 3612 | users. The next benchmark measures the possible throughput for a |
3594 | by sending multiple messages in parallel and measuring packet loss. Note that | 3613 | transport. Throughput can be measured by sending multiple messages in |
3595 | not only UDP but also the TCP transport can actually loose messages since the | 3614 | parallel and measuring packet loss. Note that not only UDP but also the |
3596 | TCP implementation drops messages if the @code{write} to the socket would | 3615 | TCP transport can actually loose messages since the TCP implementation |
3597 | block. While the SMTP protocol never drops messages itself, it is often so | 3616 | drops messages if the @code{write} to the socket would block. While the |
3617 | SMTP protocol never drops messages itself, it is often so | ||
3598 | slow that only a fraction of the messages can be sent and received in the | 3618 | slow that only a fraction of the messages can be sent and received in the |
3599 | given time-bounds. For this benchmark we report the message loss after | 3619 | given time-bounds. For this benchmark we report the message loss after |
3600 | allowing t time for sending m messages. If messages were not sent (or | 3620 | allowing t time for sending m messages. If messages were not sent (or |
3601 | received) after an overall timeout of t, they were considered lost. The | 3621 | received) after an overall timeout of t, they were considered lost. The |
3602 | benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0 with | 3622 | benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0 |
3603 | sendmail. The machines were connected with a direct 100 MBit ethernet | 3623 | with sendmail. The machines were connected with a direct 100 MBit ethernet |
3604 | connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the throughput | 3624 | connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the |
3605 | for messages of size 1,200 octects is 2,343 kbps, 3,310 kbps and 6 kbps for | 3625 | throughput for messages of size 1,200 octects is 2,343 kbps, 3,310 kbps |
3606 | UDP, TCP and SMTP respectively. The high per-message overhead of SMTP can be | 3626 | and 6 kbps for UDP, TCP and SMTP respectively. The high per-message |
3607 | improved by increasing the MTU, for example, an MTU of 12,000 octets improves | 3627 | overhead of SMTP can be improved by increasing the MTU, for example, an |
3608 | the throughput to 13 kbps as figure smtp-MTUs shows. Our research paper) has | 3628 | MTU of 12,000 octets improves the throughput to 13 kbps as figure |
3609 | some more details on the benchmarking results. | 3629 | smtp-MTUs shows. Our research paper) has some more details on the |
3630 | benchmarking results. | ||
3610 | 3631 | ||
3611 | @node Bluetooth plugin | 3632 | @node Bluetooth plugin |
3612 | @section Bluetooth plugin | 3633 | @section Bluetooth plugin |
3613 | @c %**end of header | 3634 | @c %**end of header |
3614 | 3635 | ||
3615 | This page describes the new Bluetooth transport plugin for GNUnet. The plugin | 3636 | This page describes the new Bluetooth transport plugin for GNUnet. The |
3616 | is still in the testing stage so don't expect it to work perfectly. If you | 3637 | plugin is still in the testing stage so don't expect it to work |
3617 | have any questions or problems just post them here or ask on the IRC channel. | 3638 | perfectly. If you have any questions or problems just post them here or |
3639 | ask on the IRC channel. | ||
3640 | |||
3618 | @itemize @bullet | 3641 | @itemize @bullet |
3619 | @item What do I need to use the Bluetooth plugin transport? | 3642 | @item What do I need to use the Bluetooth plugin transport? |
3620 | @item BluetoothHow does it work? | 3643 | @item BluetoothHow does it work? |
@@ -3638,52 +3661,56 @@ have any questions or problems just post them here or ask on the IRC channel. | |||
3638 | @subsection What do I need to use the Bluetooth plugin transport? | 3661 | @subsection What do I need to use the Bluetooth plugin transport? |
3639 | @c %**end of header | 3662 | @c %**end of header |
3640 | 3663 | ||
3641 | If you are a Linux user and you want to use the Bluetooth transport plugin you | 3664 | If you are a Linux user and you want to use the Bluetooth transport plugin |
3642 | should install the BlueZ development libraries (if they aren't already | 3665 | you should install the BlueZ development libraries (if they aren't already |
3643 | installed). For instructions about how to install the libraries you should | 3666 | installed). For instructions about how to install the libraries you should |
3644 | check out the BlueZ site (@uref{http://www.bluez.org/, http://www.bluez.org}). | 3667 | check out the BlueZ site |
3645 | If you don't know if you have the necesarry libraries, don't worry, just run | 3668 | (@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if |
3646 | the GNUnet configure script and you will be able to see a notification at the | 3669 | you have the necesarry libraries, don't worry, just run the GNUnet |
3647 | end which will warn you if you don't have the necessary libraries. | 3670 | configure script and you will be able to see a notification at the end |
3671 | which will warn you if you don't have the necessary libraries. | ||
3648 | 3672 | ||
3649 | If you are a Windows user you should have installed the | 3673 | If you are a Windows user you should have installed the |
3650 | @emph{MinGW}/@emph{MSys2} with the latest updates (especially the | 3674 | @emph{MinGW}/@emph{MSys2} with the latest updates (especially the |
3651 | @emph{ws2bth} header). If this is your first build of GNUnet on Windows you | 3675 | @emph{ws2bth} header). If this is your first build of GNUnet on Windows |
3652 | should check out the SBuild repository. It will semi-automatically assembles a | 3676 | you should check out the SBuild repository. It will semi-automatically |
3653 | @emph{MinGW}/@emph{MSys2} installation with a lot of extra packages which are | 3677 | assembles a @emph{MinGW}/@emph{MSys2} installation with a lot of extra |
3654 | needed for the GNUnet build. So this will ease your work!@ Finally you just | 3678 | packages which are needed for the GNUnet build. So this will ease your |
3655 | have to be sure that you have the correct drivers for your Bluetooth device | 3679 | work!@ Finally you just have to be sure that you have the correct drivers |
3656 | installed and that your device is on and in a discoverable mode. The Windows | 3680 | for your Bluetooth device installed and that your device is on and in a |
3657 | Bluetooth Stack supports only the RFCOMM protocol so we cannot turn on your | 3681 | discoverable mode. The Windows Bluetooth Stack supports only the RFCOMM |
3658 | device programatically! | 3682 | protocol so we cannot turn on your device programatically! |
3659 | 3683 | ||
3684 | @c FIXME: Change to unique title | ||
3660 | @node How does it work2? | 3685 | @node How does it work2? |
3661 | @subsection How does it work2? | 3686 | @subsection How does it work2? |
3662 | @c %**end of header | 3687 | @c %**end of header |
3663 | 3688 | ||
3664 | The Bluetooth transport plugin uses virtually the same code as the WLAN plugin | 3689 | The Bluetooth transport plugin uses virtually the same code as the WLAN |
3665 | and only the helper binary is different. The helper takes a single argument, | 3690 | plugin and only the helper binary is different. The helper takes a single |
3666 | which represents the interface name and is specified in the configuration | 3691 | argument, which represents the interface name and is specified in the |
3667 | file. Here are the basic steps that are followed by the helper binary used on | 3692 | configuration file. Here are the basic steps that are followed by the |
3668 | Linux: | 3693 | helper binary used on Linux: |
3669 | 3694 | ||
3670 | @itemize @bullet | 3695 | @itemize @bullet |
3671 | @item it verifies if the name corresponds to a Bluetooth interface name | 3696 | @item it verifies if the name corresponds to a Bluetooth interface name |
3672 | @item it verifies if the iterface is up (if it is not, it tries to bring it up) | 3697 | @item it verifies if the iterface is up (if it is not, it tries to bring |
3673 | @item it tries to enable the page and inquiry scan in order to make the device | 3698 | it up) |
3674 | discoverable and to accept incoming connection requests | 3699 | @item it tries to enable the page and inquiry scan in order to make the |
3700 | device discoverable and to accept incoming connection requests | ||
3675 | @emph{The above operations require root access so you should start the | 3701 | @emph{The above operations require root access so you should start the |
3676 | transport plugin with root privileges.} | 3702 | transport plugin with root privileges.} |
3677 | @item it finds an available port number and registers a SDP service which will | 3703 | @item it finds an available port number and registers a SDP service which |
3678 | be used to find out on which port number is the server listening on and switch | 3704 | will be used to find out on which port number is the server listening on |
3679 | the socket in listening mode | 3705 | and switch the socket in listening mode |
3680 | @item it sends a HELLO message with its address | 3706 | @item it sends a HELLO message with its address |
3681 | @item finally it forwards traffic from the reading sockets to the STDOUT and | 3707 | @item finally it forwards traffic from the reading sockets to the STDOUT |
3682 | from the STDIN to the writing socket | 3708 | and from the STDIN to the writing socket |
3683 | @end itemize | 3709 | @end itemize |
3684 | 3710 | ||
3685 | Once in a while the device will make an inquiry scan to discover the nearby | 3711 | Once in a while the device will make an inquiry scan to discover the |
3686 | devices and it will send them randomly HELLO messages for peer discovery. | 3712 | nearby devices and it will send them randomly HELLO messages for peer |
3713 | discovery. | ||
3687 | 3714 | ||
3688 | @node What possible errors should I be aware of? | 3715 | @node What possible errors should I be aware of? |
3689 | @subsection What possible errors should I be aware of? | 3716 | @subsection What possible errors should I be aware of? |
@@ -3693,43 +3720,47 @@ devices and it will send them randomly HELLO messages for peer discovery. | |||
3693 | 3720 | ||
3694 | Well there are many ways in which things could go wrong but I will try to | 3721 | Well there are many ways in which things could go wrong but I will try to |
3695 | present some tools that you could use to debug and some scenarios. | 3722 | present some tools that you could use to debug and some scenarios. |
3723 | |||
3696 | @itemize @bullet | 3724 | @itemize @bullet |
3697 | 3725 | ||
3698 | @item @code{bluetoothd -n -d} : use this command to enable logging in the | 3726 | @item @code{bluetoothd -n -d} : use this command to enable logging in the |
3699 | foreground and to print the logging messages | 3727 | foreground and to print the logging messages |
3700 | 3728 | ||
3701 | @item @code{hciconfig}: can be used to configure the Bluetooth devices. If you | 3729 | @item @code{hciconfig}: can be used to configure the Bluetooth devices. |
3702 | run it without any arguments it will print information about the state of the | 3730 | If you run it without any arguments it will print information about the |
3703 | interfaces. So if you receive an error that the device couldn't be brought up | 3731 | state of the interfaces. So if you receive an error that the device |
3704 | you should try to bring it manually and to see if it works (use @code{hciconfig | 3732 | couldn't be brought up you should try to bring it manually and to see if |
3705 | -a hciX up}). If you can't and the Bluetooth address has the form | 3733 | it works (use @code{hciconfig -a hciX up}). If you can't and the |
3706 | 00:00:00:00:00:00 it means that there is something wrong with the D-Bus daemon | 3734 | Bluetooth address has the form 00:00:00:00:00:00 it means that there is |
3707 | or with the Bluetooth daemon. Use @code{bluetoothd} tool to see the logs | 3735 | something wrong with the D-Bus daemon or with the Bluetooth daemon. Use |
3708 | 3736 | @code{bluetoothd} tool to see the logs | |
3709 | @item @code{sdptool} can be used to control and interogate SDP servers. If you | 3737 | |
3710 | encounter problems regarding the SDP server (like the SDP server is down) you | 3738 | @item @code{sdptool} can be used to control and interogate SDP servers. |
3711 | should check out if the D-Bus daemon is running correctly and to see if the | 3739 | If you encounter problems regarding the SDP server (like the SDP server is |
3712 | Bluetooth daemon started correctly(use @code{bluetoothd} tool). Also, sometimes | 3740 | down) you should check out if the D-Bus daemon is running correctly and to |
3713 | the SDP service could work but somehow the device couldn't register his | 3741 | see if the Bluetooth daemon started correctly(use @code{bluetoothd} tool). |
3714 | service. Use @code{sdptool browse [dev-address]} to see if the service is | 3742 | Also, sometimes the SDP service could work but somehow the device couldn't |
3715 | registered. There should be a service with the name of the interface and GNUnet | 3743 | register his service. Use @code{sdptool browse [dev-address]} to see if |
3716 | as provider. | 3744 | the service is registered. There should be a service with the name of the |
3717 | 3745 | interface and GNUnet as provider. | |
3718 | @item @code{hcitool} : another useful tool which can be used to configure the | 3746 | |
3719 | device and to send some particular commands to it. | 3747 | @item @code{hcitool} : another useful tool which can be used to configure |
3748 | the device and to send some particular commands to it. | ||
3720 | 3749 | ||
3721 | @item @code{hcidump} : could be used for low level debugging | 3750 | @item @code{hcidump} : could be used for low level debugging |
3722 | @end itemize | 3751 | @end itemize |
3723 | 3752 | ||
3753 | @c FIXME: A more unique name | ||
3724 | @node How do I configure my peer2? | 3754 | @node How do I configure my peer2? |
3725 | @subsection How do I configure my peer2? | 3755 | @subsection How do I configure my peer2? |
3726 | @c %**end of header | 3756 | @c %**end of header |
3727 | 3757 | ||
3728 | On Linux, you just have to be sure that the interface name corresponds to the | 3758 | On Linux, you just have to be sure that the interface name corresponds to |
3729 | one that you want to use. Use the @code{hciconfig} tool to check that. By | 3759 | the one that you want to use. Use the @code{hciconfig} tool to check that. |
3730 | default it is set to hci0 but you can change it. | 3760 | By default it is set to hci0 but you can change it. |
3731 | 3761 | ||
3732 | A basic configuration looks like this: | 3762 | A basic configuration looks like this: |
3763 | |||
3733 | @example | 3764 | @example |
3734 | [transport-bluetooth] | 3765 | [transport-bluetooth] |
3735 | # Name of the interface (typically hciX) | 3766 | # Name of the interface (typically hciX) |
@@ -3738,19 +3769,20 @@ INTERFACE = hci0 | |||
3738 | TESTMODE = 0 TESTING_IGNORE_KEYS = ACCEPT_FROM; | 3769 | TESTMODE = 0 TESTING_IGNORE_KEYS = ACCEPT_FROM; |
3739 | @end example | 3770 | @end example |
3740 | 3771 | ||
3772 | In order to use the Bluetooth transport plugin when the transport service | ||
3773 | is started, you must add the plugin name to the default transport service | ||
3774 | plugins list. For example: | ||
3741 | 3775 | ||
3742 | In order to use the Bluetooth transport plugin when the transport service is | ||
3743 | started, you must add the plugin name to the default transport service plugins | ||
3744 | list. For example: | ||
3745 | @example | 3776 | @example |
3746 | [transport] ... PLUGINS = dns bluetooth ... | 3777 | [transport] ... PLUGINS = dns bluetooth ... |
3747 | @end example | 3778 | @end example |
3748 | 3779 | ||
3749 | If you want to use only the Bluetooth plugin set @emph{PLUGINS = bluetooth} | 3780 | If you want to use only the Bluetooth plugin set |
3781 | @emph{PLUGINS = bluetooth} | ||
3750 | 3782 | ||
3751 | On Windows, you cannot specify which device to use. The only thing that you | 3783 | On Windows, you cannot specify which device to use. The only thing that |
3752 | should do is to add @emph{bluetooth} on the plugins list of the transport | 3784 | you should do is to add @emph{bluetooth} on the plugins list of the |
3753 | service. | 3785 | transport service. |
3754 | 3786 | ||
3755 | @node How can I test it? | 3787 | @node How can I test it? |
3756 | @subsection How can I test it? | 3788 | @subsection How can I test it? |
@@ -3758,42 +3790,46 @@ service. | |||
3758 | 3790 | ||
3759 | If you have two Bluetooth devices on the same machine which use Linux you | 3791 | If you have two Bluetooth devices on the same machine which use Linux you |
3760 | must: | 3792 | must: |
3793 | |||
3761 | @itemize @bullet | 3794 | @itemize @bullet |
3762 | 3795 | ||
3763 | @item create two different file configuration (one which will use the first | 3796 | @item create two different file configuration (one which will use the |
3764 | interface (@emph{hci0}) and the other which will use the second interface | 3797 | first interface (@emph{hci0}) and the other which will use the second |
3765 | (@emph{hci1})). Let's name them @emph{peer1.conf} and @emph{peer2.conf}. | 3798 | interface (@emph{hci1})). Let's name them @emph{peer1.conf} and |
3799 | @emph{peer2.conf}. | ||
3766 | 3800 | ||
3767 | @item run @emph{gnunet-peerinfo -c peerX.conf -s} in order to generate the | 3801 | @item run @emph{gnunet-peerinfo -c peerX.conf -s} in order to generate the |
3768 | peers private keys. The @strong{X} must be replace with 1 or 2. | 3802 | peers private keys. The @strong{X} must be replace with 1 or 2. |
3769 | 3803 | ||
3770 | @item run @emph{gnunet-arm -c peerX.conf -s -i=transport} in order to start the | 3804 | @item run @emph{gnunet-arm -c peerX.conf -s -i=transport} in order to |
3771 | transport service. (Make sure that you have "bluetooth" on the transport | 3805 | start the transport service. (Make sure that you have "bluetooth" on the |
3772 | plugins list if the Bluetooth transport service doesn't start.) | 3806 | transport plugins list if the Bluetooth transport service doesn't start.) |
3807 | |||
3808 | @item run @emph{gnunet-peerinfo -c peer1.conf -s} to get the first peer's | ||
3809 | ID. If you already know your peer ID (you saved it from the first | ||
3810 | command), this can be skipped. | ||
3773 | 3811 | ||
3774 | @item run @emph{gnunet-peerinfo -c peer1.conf -s} to get the first peer's ID. | 3812 | @item run @emph{gnunet-transport -c peer2.conf -p=PEER1_ID -s} to start |
3775 | If you already know your peer ID (you saved it from the first command), this | 3813 | sending data for benchmarking to the other peer. |
3776 | can be skipped. | ||
3777 | 3814 | ||
3778 | @item run @emph{gnunet-transport -c peer2.conf -p=PEER1_ID -s} to start sending | ||
3779 | data for benchmarking to the other peer. | ||
3780 | @end itemize | 3815 | @end itemize |
3781 | 3816 | ||
3782 | 3817 | ||
3783 | This scenario will try to connect the second peer to the first one and then | 3818 | This scenario will try to connect the second peer to the first one and |
3784 | start sending data for benchmarking. | 3819 | then start sending data for benchmarking. |
3785 | 3820 | ||
3786 | On Windows you cannot test the plugin functionality using two Bluetooth devices | 3821 | On Windows you cannot test the plugin functionality using two Bluetooth |
3787 | from the same machine because after you install the drivers there will occur | 3822 | devices from the same machine because after you install the drivers there |
3788 | some conflicts between the Bluetooth stacks. (At least that is what happend on | 3823 | will occur some conflicts between the Bluetooth stacks. (At least that is |
3789 | my machine : I wasn't able to use the Bluesoleil stack and the WINDCOMM one in | 3824 | what happend on my machine : I wasn't able to use the Bluesoleil stack and |
3790 | the same time). | 3825 | the WINDCOMM one in the same time). |
3791 | 3826 | ||
3792 | If you have two different machines and your configuration files are good you | 3827 | If you have two different machines and your configuration files are good |
3793 | can use the same scenario presented on the begining of this section. | 3828 | you can use the same scenario presented on the begining of this section. |
3794 | 3829 | ||
3795 | Another way to test the plugin functionality is to create your own application | 3830 | Another way to test the plugin functionality is to create your own |
3796 | which will use the GNUnet framework with the Bluetooth transport service. | 3831 | application which will use the GNUnet framework with the Bluetooth |
3832 | transport service. | ||
3797 | 3833 | ||
3798 | @node The implementation of the Bluetooth transport plugin | 3834 | @node The implementation of the Bluetooth transport plugin |
3799 | @subsection The implementation of the Bluetooth transport plugin | 3835 | @subsection The implementation of the Bluetooth transport plugin |
@@ -3801,12 +3837,13 @@ which will use the GNUnet framework with the Bluetooth transport service. | |||
3801 | 3837 | ||
3802 | This page describes the implementation of the Bluetooth transport plugin. | 3838 | This page describes the implementation of the Bluetooth transport plugin. |
3803 | 3839 | ||
3804 | First I want to remind you that the Bluetooth transport plugin uses virtually | 3840 | First I want to remind you that the Bluetooth transport plugin uses |
3805 | the same code as the WLAN plugin and only the helper binary is different. Also | 3841 | virtually the same code as the WLAN plugin and only the helper binary is |
3806 | the scope of the helper binary from the Bluetooth transport plugin is the same | 3842 | different. Also the scope of the helper binary from the Bluetooth |
3807 | as the one used for the wlan transport plugin: it acceses the interface and | 3843 | transport plugin is the same as the one used for the wlan transport |
3808 | then it forwards traffic in both directions between the Bluetooth interface | 3844 | plugin: it acceses the interface and then it forwards traffic in both |
3809 | and stdin/stdout of the process involved. | 3845 | directions between the Bluetooth interface and stdin/stdout of the |
3846 | process involved. | ||
3810 | 3847 | ||
3811 | The Bluetooth plugin transport could be used both on Linux and Windows | 3848 | The Bluetooth plugin transport could be used both on Linux and Windows |
3812 | platforms. | 3849 | platforms. |
@@ -3834,9 +3871,9 @@ platforms. | |||
3834 | 3871 | ||
3835 | In order to implement the plugin functionality on Linux I used the BlueZ | 3872 | In order to implement the plugin functionality on Linux I used the BlueZ |
3836 | stack. For the communication with the other devices I used the RFCOMM | 3873 | stack. For the communication with the other devices I used the RFCOMM |
3837 | protocol. Also I used the HCI protocol to gain some control over the device. | 3874 | protocol. Also I used the HCI protocol to gain some control over the |
3838 | The helper binary takes a single argument (the name of the Bluetooth | 3875 | device. The helper binary takes a single argument (the name of the |
3839 | interface) and is separated in two stages: | 3876 | Bluetooth interface) and is separated in two stages: |
3840 | 3877 | ||
3841 | @c %** 'THE INITIALIZATION' should be in bigger letters or stand out, not | 3878 | @c %** 'THE INITIALIZATION' should be in bigger letters or stand out, not |
3842 | @c %** starting a new section? | 3879 | @c %** starting a new section? |
@@ -3844,17 +3881,17 @@ interface) and is separated in two stages: | |||
3844 | @subsubsection THE INITIALIZATION | 3881 | @subsubsection THE INITIALIZATION |
3845 | 3882 | ||
3846 | @itemize @bullet | 3883 | @itemize @bullet |
3847 | @item first, it checks if we have root privilegies (@emph{Remember that we need | 3884 | @item first, it checks if we have root privilegies |
3848 | to have root privilegies in order to be able to bring the interface up if it is | 3885 | (@emph{Remember that we need to have root privilegies in order to be able |
3849 | down or to change its state.}). | 3886 | to bring the interface up if it is down or to change its state.}). |
3850 | 3887 | ||
3851 | @item second, it verifies if the interface with the given name exists. | 3888 | @item second, it verifies if the interface with the given name exists. |
3852 | 3889 | ||
3853 | @strong{If the interface with that name exists and it is a Bluetooth | 3890 | @strong{If the interface with that name exists and it is a Bluetooth |
3854 | interface:} | 3891 | interface:} |
3855 | 3892 | ||
3856 | @item it creates a RFCOMM socket which will be used for listening and call the | 3893 | @item it creates a RFCOMM socket which will be used for listening and call |
3857 | @emph{open_device} method | 3894 | the @emph{open_device} method |
3858 | 3895 | ||
3859 | On the @emph{open_device} method: | 3896 | On the @emph{open_device} method: |
3860 | @itemize @bullet | 3897 | @itemize @bullet |
@@ -3866,14 +3903,14 @@ On the @emph{open_device} method: | |||
3866 | discoverable | 3903 | discoverable |
3867 | @item closes the HCI socket and binds the RFCOMM one | 3904 | @item closes the HCI socket and binds the RFCOMM one |
3868 | @item switches the RFCOMM socket in listening mode | 3905 | @item switches the RFCOMM socket in listening mode |
3869 | @item registers the SDP service (the service will be used by the other devices | 3906 | @item registers the SDP service (the service will be used by the other |
3870 | to get the port on which this device is listening on) | 3907 | devices to get the port on which this device is listening on) |
3871 | @end itemize | 3908 | @end itemize |
3872 | 3909 | ||
3873 | @item drops the root privilegies | 3910 | @item drops the root privilegies |
3874 | 3911 | ||
3875 | @strong{If the interface is not a Bluetooth interface the helper exits with a | 3912 | @strong{If the interface is not a Bluetooth interface the helper exits |
3876 | suitable error} | 3913 | with a suitable error} |
3877 | @end itemize | 3914 | @end itemize |
3878 | 3915 | ||
3879 | @c %** Same as for @node entry above | 3916 | @c %** Same as for @node entry above |
@@ -3882,9 +3919,10 @@ suitable error} | |||
3882 | 3919 | ||
3883 | The helper binary uses a list where it saves all the connected neighbour | 3920 | The helper binary uses a list where it saves all the connected neighbour |
3884 | devices (@emph{neighbours.devices}) and two buffers (@emph{write_pout} and | 3921 | devices (@emph{neighbours.devices}) and two buffers (@emph{write_pout} and |
3885 | @emph{write_std}). The first message which is send is a control message with | 3922 | @emph{write_std}). The first message which is send is a control message |
3886 | the device's MAC address in order to announce the peer presence to the | 3923 | with the device's MAC address in order to announce the peer presence to |
3887 | neighbours. Here are a short description of what happens in the main loop: | 3924 | the neighbours. Here are a short description of what happens in the main |
3925 | loop: | ||
3888 | 3926 | ||
3889 | @itemize @bullet | 3927 | @itemize @bullet |
3890 | @item Every time when it receives something from the STDIN it processes the | 3928 | @item Every time when it receives something from the STDIN it processes the |