From c3c9fef22fa6e4657c3fc862bad365b440ee2305 Mon Sep 17 00:00:00 2001 From: Nils Gillmann Date: Fri, 4 May 2018 19:57:38 +0000 Subject: [PATCH] Follow-up commit to format most of the other man pages code. Signed-off-by: Nils Gillmann --- doc/man/gnunet-arm.1 | 28 ++- doc/man/gnunet-ats.1 | 3 +- doc/man/gnunet-auto-share.1 | 60 +++++- doc/man/gnunet-bcd.1 | 7 +- doc/man/gnunet-config.1 | 10 +- doc/man/gnunet-conversation-test.1 | 9 +- doc/man/gnunet-conversation.1 | 10 +- doc/man/gnunet-core.1 | 7 +- doc/man/gnunet-datastore.1 | 5 +- doc/man/gnunet-directory.1 | 39 +++- doc/man/gnunet-dns2gns.1 | 8 +- doc/man/gnunet-download-manager.1 | 12 +- doc/man/gnunet-download.1 | 100 ++++++++-- doc/man/gnunet-ecc.1 | 22 ++- doc/man/gnunet-fs.1 | 21 +- doc/man/gnunet-gns-proxy.1 | 18 +- doc/man/gnunet-gns.1 | 25 +-- doc/man/gnunet-identity.1 | 45 +++-- doc/man/gnunet-namecache.1 | 6 +- doc/man/gnunet-namestore-fcfsd.1 | 32 ++- doc/man/gnunet-namestore.1 | 44 +++-- doc/man/gnunet-nat-auto.1 | 6 +- doc/man/gnunet-nat-server.1 | 43 ++++- doc/man/gnunet-nat.1 | 31 ++- doc/man/gnunet-peerinfo.1 | 4 +- doc/man/gnunet-publish.1 | 279 ++++++++++++++++++++------- doc/man/gnunet-qr.1 | 3 +- doc/man/gnunet-resolver.1 | 3 +- doc/man/gnunet-revocation.1 | 38 +++- doc/man/gnunet-scalarproduct.1 | 40 +++- doc/man/gnunet-scrypt.1 | 3 +- doc/man/gnunet-search.1 | 73 +++++-- doc/man/gnunet-statistics.1 | 18 +- doc/man/gnunet-testbed-profiler.1 | 4 +- doc/man/gnunet-testing-run-service.1 | 12 +- doc/man/gnunet-transport.1 | 15 +- doc/man/gnunet-unindex.1 | 5 +- doc/man/gnunet-uri.1 | 6 +- doc/man/gnunet-vpn.1 | 30 ++- doc/man/gnunet-zoneimport.1 | 50 +++-- 40 files changed, 900 insertions(+), 274 deletions(-) diff --git a/doc/man/gnunet-arm.1 b/doc/man/gnunet-arm.1 index b591f0ad7..099978f24 100644 --- a/doc/man/gnunet-arm.1 +++ b/doc/man/gnunet-arm.1 @@ -9,7 +9,10 @@ gnunet\-arm \- control GNUnet services .br .SH DESCRIPTION -\fBgnunet\-arm\fP can be used to start or stop GNUnet services, including the ARM service itself. The ARM service is a supervisor for GNUnet's service processes. ARM starts services on-demand or as configured and re-starts them if they crash. +\fBgnunet\-arm\fP can be used to start or stop GNUnet services, including +the ARM service itself. The ARM service is a supervisor for GNUnet's +service processes. ARM starts services on-demand or as configured and +re-starts them if they crash. .SH OPTIONS .B @@ -17,7 +20,8 @@ gnunet\-arm \- control GNUnet services Use the configuration file FILENAME. .B .IP "\-e, \-\-end" -Shutdown all GNUnet services (including ARM itself). Running "gnunet-arm \-e" is the usual way to shutdown a GNUnet peer. +Shutdown all GNUnet services (including ARM itself). Running +"gnunet-arm \-e" is the usual way to shutdown a GNUnet peer. .B .IP "\-h, \-\-help" Print short help on options. @@ -26,16 +30,25 @@ Print short help on options. Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. .B .IP "\-i SERVICE, \-\-init=SERVICE" -Starts the specified SERVICE if it is not already running. More specifically, this makes the service behave as if it were in the default services list. +Starts the specified SERVICE if it is not already running. More specifically, +this makes the service behave as if it were in the default services list. .B .IP "\-k SERVICE, \-\-kill=SERVICE" -Stop the specified SERVICE if it is running. While this will kill the service right now, the service may be restarted immediately if other services depend on it (service is then started 'on-demand'). If the service used to be a 'default' service, its default-service status will be revoked. If the service was not a default service, it will just be (temporarily) stopped, but could be re-started on-demand at any time. +Stop the specified SERVICE if it is running. While this will kill the service +right now, the service may be restarted immediately if other services depend +on it (service is then started 'on-demand'). If the service used to be a 'default' +service, its default-service status will be revoked. If the +service was not a default service, it will just be (temporarily) stopped, +but could be re-started on-demand at any time. .B .IP "\-m, \-\-monitor" -Monitor service activity of ARM. In this mode, the command will not terminate until the user presses CTRL-C. +Monitor service activity of ARM. In this mode, the command will not terminate +until the user presses CTRL-C. .B .IP "\-s, \-\-start" -Start all GNUnet default services on this system (and also ARM). Naturally, if a service is demanded by a default service, it will then also be started. Running "gnunet-arm \-s" is the usual way to start a GNUnet peer. +Start all GNUnet default services on this system (and also ARM). Naturally, +if a service is demanded by a default service, it will then also be started. +Running "gnunet-arm \-s" is the usual way to start a GNUnet peer. .B .IP "\-I, \-\-info" List all running services. @@ -45,7 +58,8 @@ Print GNUnet version number. .SH BUGS -Report bugs by using Mantis or by sending electronic mail to +Report bugs by using Mantis or by sending +electronic mail to .SH SEE ALSO gnunet\-config(1), gnunet\-setup(1) diff --git a/doc/man/gnunet-ats.1 b/doc/man/gnunet-ats.1 index e0546f53e..cac55e79f 100644 --- a/doc/man/gnunet-ats.1 +++ b/doc/man/gnunet-ats.1 @@ -62,7 +62,8 @@ Print verbose output (include ATS address properties) Print GNUnet version number. .SH BUGS -Report bugs by using Mantis or by sending electronic mail to +Report bugs by using Mantis or by sending +electronic mail to .SH SEE ALSO gnunet\-transport(1) diff --git a/doc/man/gnunet-auto-share.1 b/doc/man/gnunet-auto-share.1 index dd3d93611..f655f6ccd 100644 --- a/doc/man/gnunet-auto-share.1 +++ b/doc/man/gnunet-auto-share.1 @@ -6,13 +6,22 @@ gnunet\-auto\-share \- a command line tool to automatically share an entire dire [\fIOPTIONS\fR] DIRNAME .SH DESCRIPTION .PP -In order to share files with other GNUnet users, the files must first be made available to GNUnet. This tool can be used to automatically share all files from a certain directory. The program will periodically scan the directory for changes and publish files that are new or that changed on GNUnet. Which files have already been shared is remembered in a ".auto-share" file in the shared directory. You can run the tool by hand or automatically by adding the respective options to your configuration. gnunet\-auto\-share has many options in common with gnunet\-publish, but can only be used to index files. +In order to share files with other GNUnet users, the files must first be made +available to GNUnet. This tool can be used to automatically share all files +from a certain directory. The program will periodically scan the directory +for changes and publish files that are new or that changed on GNUnet. +Which files have already been shared is remembered in a ".auto-share" file +in the shared directory. You can run the tool by hand or automatically by +adding the respective options to your configuration. gnunet\-auto\-share +has many options in common with gnunet\-publish, but can only be used to +index files. .PP You can use automatic meta\-data extraction (based on libextractor). .PP \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR -Use alternate config file (if this option is not specified, the default is ~/.config/gnunet.conf). +Use alternate config file (if this option is not specified, the +default is ~/.config/gnunet.conf). .TP \fB\-D\fR, \fB\-\-disable\-extractor\fR @@ -31,11 +40,20 @@ ERROR, WARNING, INFO and DEBUG. \fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR Executive summary: You probably don't need it. -Set the priority of the published content (default: 365). If the local database is full, GNUnet will discard the content with the lowest ranking. Note that ranks change over time depending on popularity. The default should be high enough to preserve the locally published content in favor of content that migrates from other peers. +Set the priority of the published content (default: 365). If the local +database is full, GNUnet will discard the content with the lowest ranking. +Note that ranks change over time depending on popularity. The default +should be high enough to preserve the locally published content in favor +of content that migrates from other peers. .TP \fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR -Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet will push each block (for the file) LEVEL times to other peers before doing normal "random" replication of all content. This option can be used to push some content out into the network harder. Note that pushing content LEVEL times into the network does not guarantee that there will actually be LEVEL replicas. +Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet +will push each block (for the file) LEVEL times to other peers before doing +normal "random" replication of all content. This option can be used to push +some content out into the network harder. Note that pushing content LEVEL +times into the network does not guarantee that there will actually be LEVEL +replicas. .TP \fB\-v\fR, \fB\-\-version\fR @@ -43,16 +61,38 @@ Print the version number. .TP \fB\-V\fR, \fB\-\-verbose\fR -Be verbose. Using this option causes gnunet\-publish to print progress information and at the end the file identification that can be used to download the file from GNUnet. +Be verbose. Using this option causes gnunet\-publish to print progress +information and at the end the file identification that can be used to download +the file from GNUnet. .SH SETTING ANONYMITY LEVEL -The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key. This will allow other users to download the file as fast as possible, including using non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. - -The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of data in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. - -The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. +The \fB\-a\fR option can be used to specify additional anonymity constraints. +If set to 0, GNUnet will publish the file non-anonymously and in fact sign +the advertisement for the file using your peer's private key. This will +allow other users to download the file as fast as possible, including using +non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), +you use the standard anonymous routing algorithm (which does not explicitly +leak your identity). However, a powerful adversary may still be able to +perform traffic analysis (statistics) to over time infer data about your +identity. You can gain better privacy by specifying a higher level of +anonymity, which increases the amount of cover traffic your own traffic will +get, at the expense of performance. Note that regardless of the anonymity +level you choose, peers that cache content in the network always use anonymity +level 1. + +The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity +is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" +traffic can be from the local user, leaving 'v-1' bytes of cover traffic per +byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign +peers (using anonymous routing), it may originate n/(v-1) bytes of data in +the same time\-period. The time\-period is twice the average delay that +GNUnet defers forwarded queries. + +The default is 1 and this should be fine for most users. Also notice that if +you choose very large values, you may end up having no throughput at all, +especially if many of your fellow GNUnet\-peers all do the same. .SH EXAMPLES diff --git a/doc/man/gnunet-bcd.1 b/doc/man/gnunet-bcd.1 index 3f695c072..f23196687 100644 --- a/doc/man/gnunet-bcd.1 +++ b/doc/man/gnunet-bcd.1 @@ -9,7 +9,12 @@ gnunet\-bcd \- run HTTP server to create GNS business cards .br .SH DESCRIPTION -\fBgnunet\-bcd\fP can be used to create an business card with a QR code containing the public key of a zone from the GNU Name System. gnunet\-bcd requires LaTeX (pdflatex) with various packages to be installed. If it does not work for you, try installing the full TeXLive distribution first (i.e. "apt-get install texlive-full"). +\fBgnunet\-bcd\fP can be used to create an business card with a QR code +containing the public key of a zone from the GNU Name System. +gnunet\-bcd requires LaTeX (pdflatex) with various packages to be +installed. If it does not work for you, try installing the full +TeXLive distribution first, for example using the package\-manager +apt: "apt-get install texlive-full". .SH OPTIONS .B diff --git a/doc/man/gnunet-config.1 b/doc/man/gnunet-config.1 index d309e7fa0..74839ee0e 100644 --- a/doc/man/gnunet-config.1 +++ b/doc/man/gnunet-config.1 @@ -14,7 +14,8 @@ gnunet\-config \- manipulate GNUnet configuration files .SH OPTIONS .B .IP "\-f, \-\-filename" -When accessing a specific option using \-s and \-o, perform expansions as if the value represents a filename. +When accessing a specific option using \-s and \-o, perform expansions as if the +value represents a filename. .B .IP "\-s SECTION, \-\-section=SECTION" Which configuration section should be accessed or edited. Required option. @@ -26,10 +27,13 @@ List available configuration sections for use with \-\-section. Consider differences to defaults only. .B .IP "\-o OPTION, \-\-option=OPTION" -Which configuration option should be accessed or edited. Required to set a value. If not given, all values of a given section will be printed in the format "OPTION = VALUE". +Which configuration option should be accessed or edited. Required to set a value. +If not given, all values of a given section will be printed in the +format "OPTION = VALUE". .B .IP "\-V VALUE, \-\-value VALUE" -Configuration value to store in the given section under the given option. Must only be given together with \-s and \-o options. +Configuration value to store in the given section under the given option. +Must only be given together with \-s and \-o options. .B .IP "\-c FILENAME, \-\-config=FILENAME" Use the configuration file FILENAME. diff --git a/doc/man/gnunet-conversation-test.1 b/doc/man/gnunet-conversation-test.1 index fa1b8d855..3cda104df 100644 --- a/doc/man/gnunet-conversation-test.1 +++ b/doc/man/gnunet-conversation-test.1 @@ -9,9 +9,14 @@ gnunet\-conversation\-test \- check your speaker and microphone settings .br .SH DESCRIPTION -\fBgnunet\-conversation\-test\fP can be used to check your speaker and microphone settings. It will record you for five seconds and then play the recording back to you. If this fails, you might want to use the \fBpavucontrol\fP tool to check which microphone or speaker were assigned to GNUnet by PulseAudio (you may have more than one set of microphones or speakers known to your computer). +\fBgnunet\-conversation\-test\fP can be used to check your speaker and microphone +settings. It will record you for five seconds and then play the recording back +to you. If this fails, you might want to use the \fBpavucontrol\fP tool to +check which microphone or speaker were assigned to GNUnet by PulseAudio (you +may have more than one set of microphones or speakers known to your computer). -You can use gnunet\-conversation\-test without having a peer running on your computer. +You can use gnunet\-conversation\-test without having a peer running on your +computer. .SH OPTIONS .B diff --git a/doc/man/gnunet-conversation.1 b/doc/man/gnunet-conversation.1 index 912d2a17e..ae2523f82 100644 --- a/doc/man/gnunet-conversation.1 +++ b/doc/man/gnunet-conversation.1 @@ -9,7 +9,11 @@ gnunet\-conversation \- have a conversation with your peers .br .SH DESCRIPTION -\fBgnunet\-conversation\fP can be used to have a conversation with other GNUnet users. You can make calls and receive incoming calls. You need to setup an ego using gnunet\-identity first. For others to be able to call you, you must add a PHONE record to your zone in the GNU Name System (using gnunet\-namestore). gnunet\-conversation has an interactive help system via the /help command. +\fBgnunet\-conversation\fP can be used to have a conversation with other GNUnet +users. You can make calls and receive incoming calls. You need to setup an +ego using gnunet\-identity first. For others to be able to call you, you must +add a PHONE record to your zone in the GNU Name System (using gnunet\-namestore). +gnunet\-conversation has an interactive help system via the /help command. .SH OPTIONS .B @@ -26,7 +30,9 @@ Print short help on options. Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. .B .IP "\-p LINE, \-\-phone=LINE" -Optional argument that can be used to specify the phone LINE to be used with the conversation service. The default LINE is zero, which should be fine for most users. +Optional argument that can be used to specify the phone LINE to be used with +the conversation service. The default LINE is zero, which should be fine +for most users. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-core.1 b/doc/man/gnunet-core.1 index e2ada055a..2ed3df880 100644 --- a/doc/man/gnunet-core.1 +++ b/doc/man/gnunet-core.1 @@ -8,7 +8,9 @@ gnunet\-core \- monitor CORE subsystem .SH DESCRIPTION .PP -gnunet\-core is a tool to access various functions of GNUnet's core subsystem from the command\-line. The only function right now is to monitor the status of peers known to the CORE service. +gnunet\-core is a tool to access various functions of GNUnet's core subsystem +from the command\-line. The only function right now is to monitor the status +of peers known to the CORE service. .TP \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR @@ -21,7 +23,8 @@ print help page Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. .TP \fB\-m\fR, \fB\-\-monitor\fR -in monitor mode, gnunet\-core will continuously print the connection status, instead of giving just a snapshot +in monitor mode, gnunet\-core will continuously print the connection status, +instead of giving just a snapshot .TP \fB\-v\fR, \fB\-\-version\fR print the version number diff --git a/doc/man/gnunet-datastore.1 b/doc/man/gnunet-datastore.1 index 1605006b3..6bba7fb47 100644 --- a/doc/man/gnunet-datastore.1 +++ b/doc/man/gnunet-datastore.1 @@ -8,7 +8,10 @@ gnunet\-datastore \- dump or insert (restore) GNUnet datastore databases .SH DESCRIPTION .PP -gnunet\-datastore can be used to backup and restore or merge GNUnet datastores. This is useful if a datastore is to be migrated between SQL databases, i.e. from sqlite to postgres or vice versa. gnunet\-datastore will dump the entire contents of the database or insert a dump file into the database. +gnunet\-datastore can be used to backup and restore or merge GNUnet datastores. +This is useful if a datastore is to be migrated between SQL databases, i.e. +from sqlite to postgres or vice versa. gnunet\-datastore will dump the +entire contents of the database or insert a dump file into the database. .TP \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR diff --git a/doc/man/gnunet-directory.1 b/doc/man/gnunet-directory.1 index 373e171f1..9a44be244 100644 --- a/doc/man/gnunet-directory.1 +++ b/doc/man/gnunet-directory.1 @@ -7,10 +7,14 @@ gnunet\-directory \- display directories [\fIOPTIONS\fR] (FILENAME)* .SH DESCRIPTION .PP -gnunet\-directory lists the contents of one or more GNUnet directories. A GNUnet directory is a binary file that contains a list of GNUnet file\-sharing URIs and meta data. The names of the directory files must be passed as command\-line arguments to gnunet\-directory. +gnunet\-directory lists the contents of one or more GNUnet directories. +A GNUnet directory is a binary file that contains a list of GNUnet +file\-sharing URIs and meta data. The names of the directory files must +be passed as command\-line arguments to gnunet\-directory. .TP \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR -configuration file to use (useless option since gnunet\-directory does not really depend on any configuration options) +configuration file to use (useless option since gnunet\-directory does not +really depend on any configuration options) .TP \fB\-h\fR, \fB\-\-help\fR print help page @@ -21,13 +25,36 @@ Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and \fB\-v\fR, \fB\-\-version\fR print the version number .SH NOTES -A GNUnet directory is a file containing a list of GNUnet URIs and meta data. The keys can point to files, other directories or files in namespaces. In other words, a GNUnet directory is similar to UNIX directories. The difference to tar and zip is that GNUnet directory does not contain the actual files (except if they are really small, in which case they may be inlined), just symbolic (links), similar to directories with symbolic links in UNIX filesystems. The benefit is that the individual files can be retrieved separately (if desired) and if some of the files are inserted to another node in GNUnet, this just increases their availability but does not produce useless duplicates (for example, it is a better idea to publish a collection of pictures or compressed sound files using a GNUnet directory instead of processing them with archivers such as tar or zip first). Directories can contain arbitrary meta data for each file. +A GNUnet directory is a file containing a list of GNUnet URIs and meta data. +The keys can point to files, other directories or files in namespaces. In other +words, a GNUnet directory is similar to UNIX directories. The difference to tar +and zip is that GNUnet directory does not contain the actual files (except if +they are really small, in which case they may be inlined), just symbolic (links), +similar to directories with symbolic links in UNIX filesystems. The benefit is +that the individual files can be retrieved separately (if desired) and if some +of the files are inserted to another node in GNUnet, this just increases their +availability but does not produce useless duplicates (for example, it is a +better idea to publish a collection of pictures or compressed sound files +using a GNUnet directory instead of processing them with archivers such as +tar or zip first). Directories can contain arbitrary meta data for each file. -If a directory has missing blocks (for example, some blocks failed to download), GNUnet is typically able to retrieve information about other files in the directory. Files in a GNUnet directory have no particular order; the GNUnet code that generates a directory can reorder the entries in order to better fit the information about files into blocks of 32k. Respecting 32k boundaries where possible makes it easier for gnunet\-directory (and other tools) to recover information from partially downloaded directory files. +If a directory has missing blocks (for example, some blocks failed to download), +GNUnet is typically able to retrieve information about other files in the +directory. Files in a GNUnet directory have no particular order; the GNUnet +code that generates a directory can reorder the entries in order to better +fit the information about files into blocks of 32k. Respecting 32k boundaries +where possible makes it easier for gnunet\-directory (and other tools) to +recover information from partially downloaded directory files. -At the moment, directories can be created by \fBgnunet\-fs\-gtk\fP and \fBgnunet\-publish\fP. Just like ordinary files, a directory can be published in a namespace. +At the moment, directories can be created by \fBgnunet\-fs\-gtk\fP +and \fBgnunet\-publish\fP. Just like ordinary files, a directory can be +published in a namespace. -GNUnet directories use the (unregistered) mimetype \fBapplication/gnunet\-directory\fP. They can show up among normal search results. The directory file can be downloaded to disk by \fBgnunet\-download\fP(1) for later processing or be handled more directly by \fBgnunet\-fs\-gtk\fP(1). +GNUnet directories use the (unregistered) +mimetype \fBapplication/gnunet\-directory\fP. They can show up among normal +search results. The directory file can be downloaded to disk +by \fBgnunet\-download\fP(1) for later processing or be handled more directly +by \fBgnunet\-fs\-gtk\fP(1). .SH "REPORTING BUGS" Report bugs by using mantis or by sending electronic mail to diff --git a/doc/man/gnunet-dns2gns.1 b/doc/man/gnunet-dns2gns.1 index 04fcb7f53..e04901062 100644 --- a/doc/man/gnunet-dns2gns.1 +++ b/doc/man/gnunet-dns2gns.1 @@ -9,9 +9,13 @@ gnunet\-dns2gns \- run a DNS-to-GNS proxy .br .SH DESCRIPTION -Most users will not want to run an DNS to GNS proxy/gateway and thus will not need this program. +Most users will not want to run an DNS to GNS proxy/gateway and thus will not +need this program. -\fBgnunet\-dns2gns\fP runs a DNS resolver which delegates requests GNS if the TLD matches one configured for GNS. All other requests are forwarded to DNS. This DNS proxy is useful for enabling non-personalized GNS\-resolution to an entire network or to offer GNS\-resolution to DNS users. +\fBgnunet\-dns2gns\fP runs a DNS resolver which delegates requests GNS if +the TLD matches one configured for GNS. All other requests are forwarded +to DNS. This DNS proxy is useful for enabling non-personalized +GNS\-resolution to an entire network or to offer GNS\-resolution to DNS users. .SH OPTIONS .B diff --git a/doc/man/gnunet-download-manager.1 b/doc/man/gnunet-download-manager.1 index 844f81084..ec1f7538a 100644 --- a/doc/man/gnunet-download-manager.1 +++ b/doc/man/gnunet-download-manager.1 @@ -9,13 +9,19 @@ gnunet-download-manager \- manage downloads across sessions .br .SH DESCRIPTION -\fBgnunet\-download\-manager\fP is a script that can be used to track download sessions. It makes the process of resuming downloads after a system reboot easier. A typical use is to define an alias (depending on your shell) of the form +\fBgnunet\-download\-manager\fP is a script that can be used to track +download sessions. It makes the process of resuming downloads after a +system reboot easier. A typical use is to define an alias (depending +on your shell) of the form $ alias gnunet\-download='gnunet\-download\-manager.scm download' -Other commands for the download manager include resume (resumes all downloads), status (show status of pending downloads), killall (abort all downloads), settings (for configuration) and help (print help text). +Other commands for the download manager include resume (resumes all +downloads), status (show status of pending downloads), killall (abort +all downloads), settings (for configuration) and help (print help text). -gnunet\-download\-manager is a scheme script and will only work if guile is available. +gnunet\-download\-manager is a scheme script and will only work if Guile +is available. .SH BUGS Report bugs by using mantis or by sending electronic mail to diff --git a/doc/man/gnunet-download.1 b/doc/man/gnunet-download.1 index 759b3a964..824c2414d 100644 --- a/doc/man/gnunet-download.1 +++ b/doc/man/gnunet-download.1 @@ -18,7 +18,12 @@ use config file (defaults: ~/.config/gnunet.conf) .TP \fB\-D, \fB\-\-delete\-incomplete\fR -causes gnunet\-download to delete incomplete downloads when aborted with CTRL\-C. Note that complete files that are part of an incomplete recursive download will not be deleted even with this option. Without this option, terminating gnunet\-download with a signal will cause incomplete downloads to stay on disk. If gnunet\-download runs to (normal) completion finishing the download, this option has no effect. +causes gnunet\-download to delete incomplete downloads when aborted with +CTRL\-C. Note that complete files that are part of an incomplete recursive +download will not be deleted even with this option. Without this option, +terminating gnunet\-download with a signal will cause incomplete +downloads to stay on disk. If gnunet\-download runs to (normal) completion +finishing the download, this option has no effect. .TP \fB\-h\fR, \fB\-\-help\fR @@ -35,19 +40,49 @@ Only search locally, do not forward requests to other peers. .TP \fB\-o \fIFILENAME\fR, \fB\-\-output=FILENAME\fR -write the file to FILENAME. Hint: when recursively downloading a directory, append a '/' to the end of the FILENAME to create a directory of that name. If no FILENAME is specified, gnunet\-download constructs a temporary ID from the URI of the file. The final filename is constructed based on meta\-data extracted using libextractor (if available). +write the file to FILENAME. Hint: when recursively downloading a directory, +append a '/' to the end of the FILENAME to create a directory of that name. +If no FILENAME is specified, gnunet\-download constructs a temporary ID from +the URI of the file. The final filename is constructed based on meta\-data +extracted using libextractor (if available). .TP \fB\-p \fIDOWNLOADS\fR, \fB\-\-parallelism=DOWNLOADS\fR -set the maximum number of parallel downloads that is allowed. More parallel downloads can, to some extent, improve the overall time to download content. However, parallel downloads also take more memory (see also option \-r which can be used to limit memory utilization) and more sockets. This option is used to limit the number of files that are downloaded in parallel (\-r can be used to limit the number of blocks that are concurrently requested). As a result, the value only matters for recursive downloads. The default value is 32. +set the maximum number of parallel downloads that is allowed. More parallel +downloads can, to some extent, improve the overall time to download content. +However, parallel downloads also take more memory (see also option \-r which +can be used to limit memory utilization) and more sockets. This option is +used to limit the number of files that are downloaded in parallel (\-r can +be used to limit the number of blocks that are concurrently requested). +As a result, the value only matters for recursive downloads. +The default value is 32. .TP \fB\-r \fIREQUESTS\fR, \fB\-\-request-parallelism=REQUESTS\fR -set the maximum number of parallel requests that is allowed. If multiple files are downloaded, gnunet\-download will not run them in parallel if this would cause the number of pending requests to possibly exceed the given value. This is useful since, for example, downloading dozens of multi\-gigabyte files in parallel could exhaust memory resources and would hardly improve performance. Note that the limit only applies to this specific process and that other download activities by other processes are not included in this limit. Consider raising this limit for large recursive downloads with many large files if memory and network bandwidth are not fully utilized and if the parallelism limit (\-p option) is not reached. This option also only matters for recursive downloads. The default value is 4092. +set the maximum number of parallel requests that is allowed. If multiple +files are downloaded, gnunet\-download will not run them in parallel if +this would cause the number of pending requests to possibly exceed the +given value. This is useful since, for example, downloading dozens of +multi\-gigabyte files in parallel could exhaust memory resources and would +hardly improve performance. Note that the limit only applies to this +specific process and that other download activities by other processes +are not included in this limit. Consider raising this limit for large +recursive downloads with many large files if memory and network +bandwidth are not fully utilized and if the parallelism limit (\-p option) +is not reached. This option also only matters for recursive downloads. +The default value is 4092. .TP \fB\-R\fR, \fB\-\-recursive\fR -download directories recursively (and in parallel). Note that the URI must belong to a GNUnet directory and that the filename given to "\-o" must end in '.gnd' \-\- otherwise, you will receive an error. You may want to use "DIRNAME/.gnd" for the filename, this way a directory "DIRNAME/" will be created, and GNUnet's internal directory information will be stored in "DIRNAME/.gnd". However, it is also possible to specify "DIRNAME.gnd", in which case the files from the directory will end up in "DIRNAME/", while GNUnet's directory meta data will be in "DIRNAME.gnd". +download directories recursively (and in parallel). Note that the URI +must belong to a GNUnet directory and that the filename given to "\-o" +must end in '.gnd' \-\- otherwise, you will receive an error. You may +want to use "DIRNAME/.gnd" for the filename, this way a directory +"DIRNAME/" will be created, and GNUnet's internal directory +information will be stored in "DIRNAME/.gnd". However, it is also +possible to specify "DIRNAME.gnd", in which case the files from the +directory will end up in "DIRNAME/", while GNUnet's directory meta +data will be in "DIRNAME.gnd". .TP \fB\-v\fR, \fB\-\-version\fR @@ -58,18 +93,55 @@ print the version number print progress information .SH NOTES -The GNUNET_URI is typically obtained from gnunet\-search. gnunet\-fs\-gtk can also be used instead of gnunet\-download. -If you ever have to abort a download, you can at any time continue it by re\-issuing gnunet\-download with the same filename. In that case GNUnet will not download blocks again that are already present. GNUnet's file\-encoding will ensure file integrity, even if the existing file was not downloaded from GNUnet in the first place. Temporary information will be appended to the target file until the download is completed. +The GNUNET_URI is typically obtained from +gnunet\-search. gnunet\-fs\-gtk can also be used instead of +gnunet\-download. If you ever have to abort a download, you can at +any time continue it by re\-issuing gnunet\-download with the same +filename. In that case GNUnet will not download blocks again that are +already present. GNUnet's file\-encoding will ensure file integrity, +even if the existing file was not downloaded from GNUnet in the first +place. Temporary information will be appended to the target file until +the download is completed. .SH SETTING ANONYMITY LEVEL -The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods. If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that your download performance is not only determined by your own anonymity level, but also by the anonymity level of the peers publishing the file. So even if you download with anonymity level 0, the peers publishing the data might be sharing with a higher anonymity level, which in this case will determine performance. Also, peers that cache content in the network always use anonymity level 1. - -This option can be used to limit requests further than that. In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries. This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency. So set it only if you really believe you need it. - -The definition of ANONYMITY\-RECEIVE is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of queries in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. - -The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. +The \fB\-a\fR option can be used to specify additional anonymity +constraints. If set to 0, GNUnet will try to download the file as fast +as possible, including using non-anonymous methods. If you set it to +1 (default), you use the standard anonymous routing algorithm (which +does not explicitly leak your identity). However, a powerful +adversary may still be able to perform traffic analysis (statistics) +to over time infer data about your identity. You can gain better +privacy by specifying a higher level of anonymity, which increases the +amount of cover traffic your own traffic will get, at the expense of +performance. Note that your download performance is not only +determined by your own anonymity level, but also by the anonymity +level of the peers publishing the file. So even if you download with +anonymity level 0, the peers publishing the data might be sharing with +a higher anonymity level, which in this case will determine +performance. Also, peers that cache content in the network always use +anonymity level 1. + +This option can be used to limit requests further than that. In +particular, you can require GNUnet to receive certain amounts of +traffic from other peers before sending your queries. This way, you +can gain very high levels of anonymity \- at the expense of much more +traffic and much higher latency. So set it only if you really believe +you need it. + +The definition of ANONYMITY\-RECEIVE is the following. 0 means no +anonymity is required. Otherwise a value of 'v' means that 1 out of v +bytes of "anonymous" traffic can be from the local user, leaving 'v-1' +bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n +bytes of messages from foreign peers (using anonymous routing), it may +originate n/(v-1) bytes of queries in the same time\-period. The +time\-period is twice the average delay that GNUnet defers forwarded +queries. + +The default is 1 and this should be fine for most users. Also notice +that if you choose very large values, you may end up having no +throughput at all, especially if many of your fellow GNUnet\-peers all +do the same. .SH FILES .TP diff --git a/doc/man/gnunet-ecc.1 b/doc/man/gnunet-ecc.1 index 910687f1f..22a3c5d44 100644 --- a/doc/man/gnunet-ecc.1 +++ b/doc/man/gnunet-ecc.1 @@ -9,21 +9,30 @@ gnunet\-ecc \- manipulate GNUnet ECC key files .br .SH DESCRIPTION -\fBgnunet\-ecc\fP can be used to create an ECC private key and to print the corresponding public key. You must specify a filename containing an ECC private key in GNUnet format as an argument. If the file does not exist, gnunet\-ecc will create a key. This may then take a while. If the option \-p is given, the corresponding public key will be printed to the console. +\fBgnunet\-ecc\fP can be used to create an ECC private key and to +print the corresponding public key. You must specify a filename +containing an ECC private key in GNUnet format as an argument. If the +file does not exist, gnunet\-ecc will create a key. This may then +take a while. If the option \-p is given, the corresponding public +key will be printed to the console. .SH OPTIONS .B .IP "\-g COUNT, \-\-generate-keys=COUNT" -Create COUNT public-private key pairs and write them to FILENAME. Used for creating a file for testing. +Create COUNT public-private key pairs and write them to FILENAME. +Used for creating a file for testing. .B .IP "\-p, \-\-print-public-key" -Print the corresponding public key to stdout. This is the value used for PKEY records in GNS. +Print the corresponding public key to stdout. This is the value used +for PKEY records in GNS. .B .IP "\-P, \-\-print-private-key" -Print the corresponding private key to stdout. This is the value used for PKEY records in GNS. +Print the corresponding private key to stdout. This is the value used +for PKEY records in GNS. .B .IP "\-x, \-\-print-hex" -Print the corresponding public key to stdout in HEX format. Useful for comparing to Ed25519 keys in X.509 tools. +Print the corresponding public key to stdout in HEX format. Useful +for comparing to Ed25519 keys in X.509 tools. .B .IP "\-c FILENAME, \-\-config=FILENAME" Use the configuration file FILENAME. @@ -32,7 +41,8 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-fs.1 b/doc/man/gnunet-fs.1 index 65f104d61..dfdaabbdb 100644 --- a/doc/man/gnunet-fs.1 +++ b/doc/man/gnunet-fs.1 @@ -8,7 +8,11 @@ gnunet\-fs \- measure and control the fs subsystem .SH DESCRIPTION .PP -gnunet\-fs is a tool to access various functions of GNUnet's fs subsystem from the command\-line. Most of these are not expected to be useful for end-users. gnunet\-fs can currently only be used to obtain a list of indexed files. Other functions should be added in the near future. +gnunet\-fs is a tool to access various functions of GNUnet's fs +subsystem from the command\-line. Most of these are not expected to +be useful for end-users. gnunet\-fs can currently only be used to +obtain a list of indexed files. Other functions should be added in +the near future. .TP \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR @@ -17,17 +21,16 @@ configuration file to use \fB\-h\fR, \fB\-\-help\fR print help page .TP -\fB\-i\fR, \fB\-\-list-indexed\fR -print information about files that are currently indexed by file-sharing +\fB\-i\fR, \fB\-\-list-indexed\fR print information about files that +are currently indexed by file-sharing .TP -\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=LOGLEVEL\fR -Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. +\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=LOGLEVEL\fR Change the +loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and +DEBUG. .TP -\fB\-v\fR, \fB\-\-version\fR -print the version number +\fB\-v\fR, \fB\-\-version\fR print the version number .TP -\fB\-V\fR, \fB\-\-verbose\fR -be verbose +\fB\-V\fR, \fB\-\-verbose\fR be verbose .SH BUGS diff --git a/doc/man/gnunet-gns-proxy.1 b/doc/man/gnunet-gns-proxy.1 index 9b9f603bd..96e9911a2 100644 --- a/doc/man/gnunet-gns-proxy.1 +++ b/doc/man/gnunet-gns-proxy.1 @@ -9,9 +9,15 @@ gnunet\-gns\-proxy \- run a client side GNS SOCKS proxy .br .SH DESCRIPTION -Most users will want to run this SOCKS proxy. It can be used in combination with browsers that support the SOCKS 4a protocol. +Most users will want to run this SOCKS proxy. It can be used in +combination with browsers that support the SOCKS 4a protocol. -The proxy will perform SSL authentication of GNS names and rewrite GNS enabled HTML content. To assert the validity of GNS names a local root CA certificate has to be generated that is used by the proxy. Thus "gnunet-gns-proxy-setup-ca" should be executed before the first launch of this proxy or the \-\-authority switch is used to specify an appropriate CA certificate that is already trusted by the browser. +The proxy will perform SSL authentication of GNS names and rewrite GNS +enabled HTML content. To assert the validity of GNS names a local root +CA certificate has to be generated that is used by the proxy. Thus +"gnunet-gns-proxy-setup-ca" should be executed before the first launch +of this proxy or the \-\-authority switch is used to specify an +appropriate CA certificate that is already trusted by the browser. .SH OPTIONS .B @@ -19,7 +25,10 @@ The proxy will perform SSL authentication of GNS names and rewrite GNS enabled H Use the configuration file FILENAME. .B .IP "\-a AUTHORITY, \-\-authority=AUTHORITY" -Path to a PEM CA file that contains the certificate and private key of the CA to use to assert the validity of GNS names. The default port is specified in the configuration file for the gns service under "[gns-proxy]" PROXY_CACERT. +Path to a PEM CA file that contains the certificate and private key of +the CA to use to assert the validity of GNS names. The default port is +specified in the configuration file for the gns service under +"[gns-proxy]" PROXY_CACERT. .B .IP "\-p PORT, \-\-port=PORT" The port this proxy should listen on. Default is 7777. @@ -28,7 +37,8 @@ The port this proxy should listen on. Default is 7777. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-gns.1 b/doc/man/gnunet-gns.1 index 4d52cfa97..9466dae03 100644 --- a/doc/man/gnunet-gns.1 +++ b/doc/man/gnunet-gns.1 @@ -9,7 +9,8 @@ gnunet\-gns \- Access to GNU Name System .br .SH DESCRIPTION -\fBgnunet\-gns\fP can be used to lookup and process GNU Name Service names. +\fBgnunet\-gns\fP can be used to lookup and process GNU Name Service +names. .SH OPTIONS .B @@ -17,24 +18,24 @@ gnunet\-gns \- Access to GNU Name System Use the configuration file FILENAME. .B .IP "\-r, \-\-raw" -No unneeded output. -This is a quiet mode where only important information is displayed. -For example a lookup for an IP address will only yield the IP address, no -descriptive text. +No unneeded output. This is a quiet mode where only important +information is displayed. For example a lookup for an IP address will +only yield the IP address, no descriptive text. .B .IP "\-h, \-\-help" Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-u NAME, \-\-lookup=NAME" -Name to lookup. -Resolve the specified name using the GNU Name System. +Name to lookup. Resolve the specified name using the GNU Name System. .B .IP "\-t TYPE, \-\-type=TYPE" -Resource Record Type (TYPE) to look for. -Supported TYPE's are: A, AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA, MX, LEHO, VPN, REV, PTR, TXT +Resource Record Type (TYPE) to look for. Supported TYPE's are: A, +AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA, MX, LEHO, VPN, REV, PTR, +TXT Defaults to "A". .B @@ -44,8 +45,8 @@ Print GNUnet version number. .SH RETURN VALUE -gnunet\-gns will return 0 on success, 1 on internal failures, 2 on launch failures, -3 if the given name is not configured to use GNS. +gnunet\-gns will return 0 on success, 1 on internal failures, 2 on +launch failures, 3 if the given name is not configured to use GNS. .SH BUGS diff --git a/doc/man/gnunet-identity.1 b/doc/man/gnunet-identity.1 index 50efa74d4..37cf85f45 100644 --- a/doc/man/gnunet-identity.1 +++ b/doc/man/gnunet-identity.1 @@ -6,39 +6,50 @@ gnunet\-identity \- create, delete or list egos [options] .SH DESCRIPTION .PP -gnunet\-identity is a tool for managing egos. An ego is the persona that controls a namespace. It is identical to a public\-private ECC key pair. +gnunet\-identity is a tool for managing egos. An ego is the persona +that controls a namespace. It is identical to a public\-private ECC +key pair. -gnunet\-identity can be used to list all of the egos that were created locally, to create new egos, and to delete existing egos (the namespace will continue to exist, but it will be impossible to add additional data to it). +gnunet\-identity can be used to list all of the egos that were created +locally, to create new egos, and to delete existing egos (the +namespace will continue to exist, but it will be impossible to add +additional data to it). -Creating a new ego requires using the \-C option together with an identifier (name) that is to be used for the new ego. This identifier is only used locally for this peer and not shared with other peers. +Creating a new ego requires using the \-C option together with an +identifier (name) that is to be used for the new ego. This identifier +is only used locally for this peer and not shared with other peers. .TP -\fB\-C NAME\fR, \fB\-\-create=NAME\fR -Creates a new ego with the given NAME. +\fB\-C NAME\fR, \fB\-\-create=NAME\fR Creates a new ego with the given +NAME. .TP -\fB\-D NAME\fR, \fB\-\-delete=NAME\fR -Delete the ego with the given NAME. +\fB\-D NAME\fR, \fB\-\-delete=NAME\fR Delete the ego with the given +NAME. .TP -\fB\-e NAME\fR, \fB\-\-ego=NAME\fR -Perform "set" operation with the respective ego. Needs to be used together with option \-s. +\fB\-e NAME\fR, \fB\-\-ego=NAME\fR Perform "set" operation with the +respective ego. Needs to be used together with option \-s. .TP -\fB\-h\fR, \fB\-\-help\fR -Print help page. +\fB\-h\fR, \fB\-\-help\fR Print help page. .TP -\fB\-d\fR, \fB\-\-display\fR -display all of our egos +\fB\-d\fR, \fB\-\-display\fR display all of our egos .TP -\fB\-m\fR, \fB\-\-monitor\fR -run in monitor mode, listing all ouf our egos until CTRL-C is pressed. Each ego is listed together with a unique pointer value; if egos are renamed, that pointer value remains the same; if egos are deleted, they are listed one more time with a name of "". +\fB\-m\fR, \fB\-\-monitor\fR run in monitor mode, listing all ouf our +egos until CTRL-C is pressed. Each ego is listed together with a +unique pointer value; if egos are renamed, that pointer value remains +the same; if egos are deleted, they are listed one more time with a +name of "". .TP -\fB\-s SUBSYSTEM\fR, \fB\-\-set=SUBSYSTEM\fR -Perform "set" operation for the specified SUBSYSTEM with the respective ego. Needs to be used together with option \-e. After this, the given SUBSYSTEM will use the ego with the specified NAME. This will fail if NAME does not yet exist. +\fB\-s SUBSYSTEM\fR, \fB\-\-set=SUBSYSTEM\fR Perform "set" operation +for the specified SUBSYSTEM with the respective ego. Needs to be used +together with option \-e. After this, the given SUBSYSTEM will use +the ego with the specified NAME. This will fail if NAME does not yet +exist. .SH FILES diff --git a/doc/man/gnunet-namecache.1 b/doc/man/gnunet-namecache.1 index ec2e602b8..ffc315b32 100644 --- a/doc/man/gnunet-namecache.1 +++ b/doc/man/gnunet-namecache.1 @@ -9,7 +9,8 @@ gnunet\-namecache \- inspect namecache .br .SH DESCRIPTION -\fBgnunet\-namecache\fP can be used to inspect values in the namecache. +\fBgnunet\-namecache\fP can be used to inspect values in the +namecache. .SH OPTIONS .B @@ -20,7 +21,8 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-n NAME, \-\-name=NAME" Name (label) of the record to display (mandatory option) diff --git a/doc/man/gnunet-namestore-fcfsd.1 b/doc/man/gnunet-namestore-fcfsd.1 index 8039e796f..6b13c3db4 100644 --- a/doc/man/gnunet-namestore-fcfsd.1 +++ b/doc/man/gnunet-namestore-fcfsd.1 @@ -9,13 +9,28 @@ gnunet\-namestore-fcfsd \- HTTP server for GNU Name System First-Come-First-Serv .br .SH DESCRIPTION -Most users will not want to run an FCFS\-zone and thus will not need this program. - -\fBgnunet\-gns-fcfsd\fP runs a web server where users can register names to be mapped to their GNS zone. Names are made available on a First Come First Served basis (hence fcfs). Registered names do not expire. The HTTP server is run on the port that is specified in the configuration file in section "[fcfsd]" under the name "HTTPPORT". The key of the zone in which the names are registered must be specified under the name "ZONEKEY" in the same section. It is possible to manage gnunet\-gns\-fcfsd using gnunet\-(service\-arm) by starting the daemon using "gnunet\-arm \-i fcfsd" or by setting "FORCESTART=YES" in the "fcfds" section of your configuration. - -An FCFS\-zone is run at http://gnunet.org/fcfs/. GNS users are encouraged to register their zone with the gnunet.org FCFS authority. - -If you want to run your own FCFS registrar, you need to first create a pseudonym (using "gnunet\-identity \-C NAME"), and then assign it to be used for the "fcfsd" service using "gnunet\-identity \-e NAME \-s fcfsd". After that, you can start the FCFSD service (possibly using gnunet\-arm). +Most users will not want to run an FCFS\-zone and thus will not need +this program. + +\fBgnunet\-gns-fcfsd\fP runs a web server where users can register +names to be mapped to their GNS zone. Names are made available on a +First Come First Served basis (hence fcfs). Registered names do not +expire. The HTTP server is run on the port that is specified in the +configuration file in section "[fcfsd]" under the name "HTTPPORT". +The key of the zone in which the names are registered must be +specified under the name "ZONEKEY" in the same section. It is +possible to manage gnunet\-gns\-fcfsd using gnunet\-(service\-arm) by +starting the daemon using "gnunet\-arm \-i fcfsd" or by setting +"FORCESTART=YES" in the "fcfds" section of your configuration. + +An FCFS\-zone is run at http://gnunet.org/fcfs/. GNS users are +encouraged to register their zone with the gnunet.org FCFS authority. + +If you want to run your own FCFS registrar, you need to first create a +pseudonym (using "gnunet\-identity \-C NAME"), and then assign it to +be used for the "fcfsd" service using "gnunet\-identity \-e NAME \-s +fcfsd". After that, you can start the FCFSD service (possibly using +gnunet\-arm). .SH OPTIONS .B @@ -26,7 +41,8 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-namestore.1 b/doc/man/gnunet-namestore.1 index 1811031ad..006c8593b 100644 --- a/doc/man/gnunet-namestore.1 +++ b/doc/man/gnunet-namestore.1 @@ -20,52 +20,72 @@ Desired operation is adding a record Use the configuration file FILENAME. .B .IP "\-d, \-\-delete" -Desired operation is deleting records under the given name that match the specified type (\-t) and value (\-V). If type or value are not specified, it means that all types (or values) should be assumed to match (and possibly multiple or all values under the given label will be deleted). Specifying a label (\-n) is mandatory. Note that matching by expiration time or flags is (currently) not supported. +Desired operation is deleting records under the given name that match +the specified type (\-t) and value (\-V). If type or value are not +specified, it means that all types (or values) should be assumed to +match (and possibly multiple or all values under the given label will +be deleted). Specifying a label (\-n) is mandatory. Note that +matching by expiration time or flags is (currently) not supported. .B .IP "\-D, \-\-display" Desired operation is listing of matching records .B .IP "\-e TIME, \-\-expiration=TIME" -Specifies expiration time of record to add; format is relative time, i.e "1 h" or "7 d 30 m". Supported units are "ms", "s", "min" or "minutes", "h" (hours), "d" (days) and "a" (years). +Specifies expiration time of record to add; format is relative time, +i.e "1 h" or "7 d 30 m". Supported units are "ms", "s", "min" or +"minutes", "h" (hours), "d" (days) and "a" (years). .B .IP "\-h, \-\-help" Print short help on options. .B .IP "\-i NICKNAME, \-\-nick=NICKNAME" -Set the desired NICKNAME for the zone. The nickname will be included in all (public) records and used as the suggested name for this zone. +Set the desired NICKNAME for the zone. The nickname will be included +in all (public) records and used as the suggested name for this zone. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-m, \-\-monitor" -Monitor changes to the zone on an ongoing basis (in contrast to \-D, which merely displays the current records) +Monitor changes to the zone on an ongoing basis (in contrast to \-D, +which merely displays the current records) .B .IP "\-n NAME, \-\-name=NAME" Label or name of the record to add/delete/display .B .IP "\-p, \-\-public" -Create a record that is public (shared with other users that know the label) +Create a record that is public (shared with other users that know the +label) .B .IP "\-r PKEY, \-\-reverse=PKEY" -Determine our GNS name for the given public key (reverse lookup of the PKEY) in the given zone. +Determine our GNS name for the given public key (reverse lookup of the +PKEY) in the given zone. .B .IP "\-s, \-\-shadow" -Create a record that is a shadow record. Shadow records are only used once all other records of the same type under the same label have expired. +Create a record that is a shadow record. Shadow records are only used +once all other records of the same type under the same label have +expired. .B .IP "\-t TYPE, \-\-type=TYPE" -Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", "PKEY", "MX" etc.) +Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", +"PKEY", "MX" etc.) .B .IP "\-u URI, \-\-uri=URI" -Add PKEY record from gnunet://gns/-URI to our zone; the record type is always PKEY, if no expiration is given FOREVER is used +Add PKEY record from gnunet://gns/-URI to our zone; the record type is +always PKEY, if no expiration is given FOREVER is used .B .IP "\-v, \-\-version" Print GNUnet version number. .B .IP "\-V VALUE, \-\-value=VALUE" -Value to store or remove from the GNS zone. Specific format depends on the record type. A records expect a dotted decimal IPv4 address, AAAA records an IPv6 address, PKEY a public key in GNUnet's printable format, and CNAME and NS records should be a domain name. +Value to store or remove from the GNS zone. Specific format depends +on the record type. A records expect a dotted decimal IPv4 address, +AAAA records an IPv6 address, PKEY a public key in GNUnet's printable +format, and CNAME and NS records should be a domain name. .B .IP "\-z EGO, \-\-zone=EGO" -Specifies the name of the ego controlling the private key for the zone (mandatory option) +Specifies the name of the ego controlling the private key for the zone +(mandatory option) .SH BUGS diff --git a/doc/man/gnunet-nat-auto.1 b/doc/man/gnunet-nat-auto.1 index 249d54da4..3a2631391 100644 --- a/doc/man/gnunet-nat-auto.1 +++ b/doc/man/gnunet-nat-auto.1 @@ -24,7 +24,8 @@ Use the configuration file FILENAME. .B .IP "\-S NAME, \-\-section=NAME" -Name of the configuration section with details about the configuration to test. For example "transport-tcp". +Name of the configuration section with details about the configuration +to test. For example "transport-tcp". .IP "\-t, \-\-tcp" Use TCP. @@ -35,7 +36,8 @@ Use UDP. .B .IP "\-w, \-\-write" -Write configuration to configuration file, useful in combination with autoconfiguration (\-a). +Write configuration to configuration file, useful in combination with +autoconfiguration (\-a). .SH EXAMPLES .PP diff --git a/doc/man/gnunet-nat-server.1 b/doc/man/gnunet-nat-server.1 index dcf856e1c..3d79d5bc5 100644 --- a/doc/man/gnunet-nat-server.1 +++ b/doc/man/gnunet-nat-server.1 @@ -11,15 +11,40 @@ gnunet\-nat\-server \- help GNUnet setup test network setup with NAT .SH DESCRIPTION -Normal GNUnet end-users should not concern themselves with gnunet\-nat\-server. In fact, distributions are encouraged to consider not shipping it at all. Running gnunet\-nat\-server's is similar to running hostlist servers: it is a special service to the community with special requirements and no benefit to those running the service. - -This program will listen on the specified PORT for incoming requests to test a peer's network connectivity. Incoming requests can ask it to connect to a given IPv4 address (and port) using TCP or UDP and to send a 2-byte test message using the specified address. The program can also be asked to send a "fake" ICMP response message to a given IPv4 address (for autonomous NAT traversal \-\-\- see the description in the respective research paper). - -The idea is that gnunet\-nat\-server will be run on some trusted hosts with unrestricted connectivity to allow GNUnet users to test their network configuration. As written, the code allows any user on the Internet to cause the gnunet\-nat\-server to send 2-bytes of arbitrary data to any TCP or UDP port at any address. We believe that this is generally harmless. - -When running gnunet\-nat\-server, make sure to use a configuration that disables most NAT options but enables 'enable_nat_client' and sets 'internal_address' to the global IP address of your local host. Also, the gnunet\-helper\-nat\-client should be installed locally and run with root privileges (SUID), otherwise the gnunet\-nat\-server will not work properly. - -Note that gnunet\-nat\-server could be run via gnunet\-arm but typically is not. Also, the name of the host and port that gnunet\-nat\-server is run on should be specified in the NATSERVER option in the [setup] section of the configuration file of hosts that are supposed to autoconfigure with this server. +Normal GNUnet end-users should not concern themselves with +gnunet\-nat\-server. In fact, distributions are encouraged to +consider not shipping it at all. Running gnunet\-nat\-server's is +similar to running hostlist servers: it is a special service to the +community with special requirements and no benefit to those running +the service. + +This program will listen on the specified PORT for incoming requests +to test a peer's network connectivity. Incoming requests can ask it +to connect to a given IPv4 address (and port) using TCP or UDP and to +send a 2-byte test message using the specified address. The program +can also be asked to send a "fake" ICMP response message to a given +IPv4 address (for autonomous NAT traversal \-\-\- see the description +in the respective research paper). + +The idea is that gnunet\-nat\-server will be run on some trusted hosts +with unrestricted connectivity to allow GNUnet users to test their +network configuration. As written, the code allows any user on the +Internet to cause the gnunet\-nat\-server to send 2-bytes of arbitrary +data to any TCP or UDP port at any address. We believe that this is +generally harmless. + +When running gnunet\-nat\-server, make sure to use a configuration +that disables most NAT options but enables 'enable_nat_client' and +sets 'internal_address' to the global IP address of your local host. +Also, the gnunet\-helper\-nat\-client should be installed locally and +run with root privileges (SUID), otherwise the gnunet\-nat\-server +will not work properly. + +Note that gnunet\-nat\-server could be run via gnunet\-arm but +typically is not. Also, the name of the host and port that +gnunet\-nat\-server is run on should be specified in the NATSERVER +option in the [setup] section of the configuration file of hosts that +are supposed to autoconfigure with this server. .SH OPTIONS diff --git a/doc/man/gnunet-nat.1 b/doc/man/gnunet-nat.1 index 0a9053444..fe9d8af3e 100644 --- a/doc/man/gnunet-nat.1 +++ b/doc/man/gnunet-nat.1 @@ -33,7 +33,8 @@ Assuming we are listening at ADDRESS for connection reversal requests. .B .IP "\-r ADDRESS, \-\-remote=ADDRESS" -Ask the peer at ADDRESS for connection reversal, using the local address for the target address of the reversal. +Ask the peer at ADDRESS for connection reversal, using the local +address for the target address of the reversal. .B .IP "\-S NAME, \-\-section=NAME" @@ -41,7 +42,9 @@ Name of section in configuration file to use for additional options. .B .IP "\-s, \-\-stun" -Enable processing of STUN requests. Will try to read UDP packets from the bind address and handle the packets if they are STUN packets. Will only work with UDP. +Enable processing of STUN requests. Will try to read UDP packets from +the bind address and handle the packets if they are STUN packets. Will +only work with UDP. .B .IP "\-t, \-\-tcp" @@ -53,38 +56,46 @@ Use UDP. .B .IP "\-W, \-\-watch" -Watch for connection reversal requests. +Watch for connection reversal requests. .SH EXAMPLES .PP \fBBasic examples\fR -We are bound to "0.0.0.0:8080" on UDP and want to obtain all applicable IP addresses: +We are bound to "0.0.0.0:8080" on UDP and want to obtain all +applicable IP addresses: # gnunet-nat -i 0.0.0.0:8080 -u -We are bound to "::0" on port 8080 on TCP and want to obtain all applicable IP addresses: +We are bound to "::0" on port 8080 on TCP and want to obtain all +applicable IP addresses: # gnunet-nat -i '[::0]':8080 -t -We are bound to "127.0.0.1:8080" on UDP and want to obtain all applicable IP addresses: +We are bound to "127.0.0.1:8080" on UDP and want to obtain all +applicable IP addresses: # gnunet-nat -i 127.0.0.1:8080 -u \fBICMP-based NAT traversal:\fR -Watch for connection reversal request (you must be bound to NAT range or to wildcard, 0.0.0.0), only works for IPv4: +Watch for connection reversal request (you must be bound to NAT range +or to wildcard, 0.0.0.0), only works for IPv4: # gnunet-nat -Wt -i 192.168.178.12:8080 -Initiate connection reversal request from peer at external IPv4 address 1.2.3.4, while we are running ourselves at 2.3.4.5:8080 (must use IPv4 addresses): +Initiate connection reversal request from peer at external IPv4 +address 1.2.3.4, while we are running ourselves at 2.3.4.5:8080 (must +use IPv4 addresses): # gnunet-nat -t -r 1.2.3.4:8080 -i 2.3.4.5:8080 -Initiate connection reversal request from peer at external IPv4 address 1.2.3.4, and let the kernel fill in whatever IPv4 address we happen to have: +Initiate connection reversal request from peer at external IPv4 +address 1.2.3.4, and let the kernel fill in whatever IPv4 address we +happen to have: - # gnunet-nat -t -r 1.2.3.4:8080 -i 0.0.0.0:8080 + # gnunet-nat -t -r 1.2.3.4:8080 -i 0.0.0.0:8080 \fBManual hole punching:\fR diff --git a/doc/man/gnunet-peerinfo.1 b/doc/man/gnunet-peerinfo.1 index 6d89f461a..cfb34c36a 100644 --- a/doc/man/gnunet-peerinfo.1 +++ b/doc/man/gnunet-peerinfo.1 @@ -42,7 +42,9 @@ Add given HELLO uri to the database Do not print anything but the peer identities .B .IP "\-s, \-\-self" -Print only our own identity (together with "\-q", this is the exact line that other peers would have to put in to their friends file in order to consider this peer one of their friends in F2F mode). +Print only our own identity (together with "\-q", this is the exact +line that other peers would have to put in to their friends file in +order to consider this peer one of their friends in F2F mode). .B .IP "\-v, \-\-version" Print the version number diff --git a/doc/man/gnunet-publish.1 b/doc/man/gnunet-publish.1 index 53a8a6563..28ee163e2 100644 --- a/doc/man/gnunet-publish.1 +++ b/doc/man/gnunet-publish.1 @@ -6,108 +6,235 @@ gnunet\-publish \- a command line interface for publishing new content into GNUn [\fIOPTIONS\fR] FILENAME .SH DESCRIPTION .PP -In order to share files with other GNUnet users, the files must first be made available to GNUnet. GNUnet does not automatically share all files from a certain directory (however, you can do this with the gnunet\-auto\-share tool). In fact, even files that are downloaded are not automatically shared. +In order to share files with other GNUnet users, the files must first +be made available to GNUnet. GNUnet does not automatically share all +files from a certain directory (however, you can do this with the +gnunet\-auto\-share tool). In fact, even files that are downloaded +are not automatically shared. .PP -In order to start sharing files, the files must be added either using gnunet\-publish or a graphical interface such as gnunet\-fs\-gtk. The command line tool gnunet\-publish is more useful if many files are supposed to be added. gnunet\-publish can automatically publish batches of files, recursively publish directories, create directories that can be browsed within GNUnet and publish file lists in a namespace. When run on a directory, gnunet\-publish will always recursively publish all of the files in the directory. +In order to start sharing files, the files must be added either using +gnunet\-publish or a graphical interface such as gnunet\-fs\-gtk. The +command line tool gnunet\-publish is more useful if many files are +supposed to be added. gnunet\-publish can automatically publish +batches of files, recursively publish directories, create directories +that can be browsed within GNUnet and publish file lists in a +namespace. When run on a directory, gnunet\-publish will always +recursively publish all of the files in the directory. .PP -gnunet\-publish can automatically extract keywords from the files that are shared. Users that want to download files from GNUnet use keywords to search for the appropriate content. You can disable keyword extraction with the \-D option. You can manually add keywords using the \-k option. The keywords are case\-sensitive. +gnunet\-publish can automatically extract keywords from the files that +are shared. Users that want to download files from GNUnet use +keywords to search for the appropriate content. You can disable +keyword extraction with the \-D option. You can manually add keywords +using the \-k option. The keywords are case\-sensitive. .PP -In addition to searching for files by keyword, GNUnet allows organizing files into directories. With directories, the user only needs to find the directory in order to be able to download any of the files listed in the directory. Directories can contain pointers to other directories. +In addition to searching for files by keyword, GNUnet allows +organizing files into directories. With directories, the user only +needs to find the directory in order to be able to download any of the +files listed in the directory. Directories can contain pointers to +other directories. .PP -With gnunet\-publish, it is easy to create new directories simultaneously when adding the files. Simply pass the name of a directory instead of a file. +With gnunet\-publish, it is easy to create new directories +simultaneously when adding the files. Simply pass the name of a +directory instead of a file. .PP -Since keywords can be spammed (any user can add any content under any keyword), GNUnet supports namespaces. A namespace is a subset of the searchspace into which only the holder of a certain pseudonym can add content. Any GNUnet user can create any number of pseudonyms using \fBgnunet\-pseudonym\fR. Pseudonyms are stored in the user's GNUnet directory. While pseudonyms are locally identified with an arbitrary string that the user selects when the pseudonym is created, the namespace is globally known only under the hash of the public key of the pseudonym. Since only the owner of the pseudonym can add content to the namespace, it is impossible for other users to pollute the namespace. gnunet\-publish automatically publishes the top\-directory (or the only file if only one file is specified) into the namespace if a pseudonym is specified. +Since keywords can be spammed (any user can add any content under any +keyword), GNUnet supports namespaces. A namespace is a subset of the +searchspace into which only the holder of a certain pseudonym can add +content. Any GNUnet user can create any number of pseudonyms using +\fBgnunet\-pseudonym\fR. Pseudonyms are stored in the user's GNUnet +directory. While pseudonyms are locally identified with an arbitrary +string that the user selects when the pseudonym is created, the +namespace is globally known only under the hash of the public key of +the pseudonym. Since only the owner of the pseudonym can add content +to the namespace, it is impossible for other users to pollute the +namespace. gnunet\-publish automatically publishes the top\-directory +(or the only file if only one file is specified) into the namespace if +a pseudonym is specified. .PP -It is possible to update content in GNUnet if that content was placed and obtained from a particular namespace. Updates are only possible for content in namespaces since this is the only way to assure that a malicious party can not supply counterfeited updates. Note that an update with GNUnet does not make the old content unavailable, GNUnet merely allows the publisher to point users to more recent versions. You can use the \-N option to specify the future identifier of an update. When using this option, a GNUnet client that finds the current (\-t) identifier will automatically begin a search for the update (\-N) identifier. If you later publish an update under the (\-N) identifier, both results will be given to the user. +It is possible to update content in GNUnet if that content was placed +and obtained from a particular namespace. Updates are only possible +for content in namespaces since this is the only way to assure that a +malicious party can not supply counterfeited updates. Note that an +update with GNUnet does not make the old content unavailable, GNUnet +merely allows the publisher to point users to more recent +versions. You can use the \-N option to specify the future identifier +of an update. When using this option, a GNUnet client that finds the +current (\-t) identifier will automatically begin a search for the +update (\-N) identifier. If you later publish an update under the +(\-N) identifier, both results will be given to the user. .PP -You can use automatic meta\-data extraction (based on libextractor) or the command\-line option \-m to specify meta-data. For the \-m option you need to use the form keyword\-type:value. For example, use "\-m os:Linux" to specify that the operating system is Linux. Common meta\-data types are "author", "title" , "mimetype", "filename", "language", "subject" and "keywords". A full list can be obtained from the extract tool using the option \-\-list. The meta\-data is used to help users in searching for files on the network. The keywords are case\-sensitive. +You can use automatic meta\-data extraction (based on libextractor) or +the command\-line option \-m to specify meta-data. For the \-m option +you need to use the form keyword\-type:value. For example, use "\-m +os:Linux" to specify that the operating system is Linux. Common +meta\-data types are "author", "title" , "mimetype", "filename", +"language", "subject" and "keywords". A full list can be obtained +from the extract tool using the option \-\-list. The meta\-data is +used to help users in searching for files on the network. The +keywords are case\-sensitive. .PP -GNUnet supports two styles of publishing files on the network. Publishing a file means that a copy of the file is made in the local (!) database of the node. Indexing a file means that an index is added to the local (!) database with symbolic links to the file itself. The links will use the SHA-512 hash of the entire file as the filename. Indexing is generally significantly more efficient and the default choice. However, indexing only works if the indexed file can be read (using the same absolute path) by gnunet-service-fs. If this is not the case, indexing will fail (and gnunet\-publish will automatically revert to publishing instead). Regardless of which method is used to publish the file, the file will be slowly (depending on how often it is requested and on how much bandwidth is available) dispersed into the network. If you publish or index a file and then leave the network, it will almost always NOT be available anymore. - -\fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR -Use alternate config file (if this option is not specified, the default is ~/.config/gnunet.conf). +GNUnet supports two styles of publishing files on the +network. Publishing a file means that a copy of the file is made in +the local (!) database of the node. Indexing a file means that an +index is added to the local (!) database with symbolic links to the +file itself. The links will use the SHA-512 hash of the entire file +as the filename. Indexing is generally significantly more efficient +and the default choice. However, indexing only works if the indexed +file can be read (using the same absolute path) by gnunet-service-fs. +If this is not the case, indexing will fail (and gnunet\-publish will +automatically revert to publishing instead). Regardless of which +method is used to publish the file, the file will be slowly (depending +on how often it is requested and on how much bandwidth is available) +dispersed into the network. If you publish or index a file and then +leave the network, it will almost always NOT be available anymore. + +\fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR Use alternate config +file (if this option is not specified, the default is +~/.config/gnunet.conf). .TP -\fB\-D\fR, \fB\-\-disable\-extractor\fR -Disable use of GNU libextractor for finding additional keywords and metadata. +\fB\-D\fR, \fB\-\-disable\-extractor\fR Disable use of GNU +libextractor for finding additional keywords and metadata. .TP -\fB\-d\fR, \fB\-\-disable\-creation\-time\fR -Disable use of creation time timestamp in metadata. Useful to make created directories deterministic and to avoid leaking information about the time at which a file was made available. +\fB\-d\fR, \fB\-\-disable\-creation\-time\fR Disable use of creation +time timestamp in metadata. Useful to make created directories +deterministic and to avoid leaking information about the time at which +a file was made available. .TP -\fB\-e\fR, \fB\-\-extract\fR -Print the list of keywords that will be used for each file given the current options. Do not perform any indexing or publishing. +\fB\-e\fR, \fB\-\-extract\fR Print the list of keywords that will be +used for each file given the current options. Do not perform any +indexing or publishing. .TP -\fB\-h\fR, \fB\-\-help\fR -Print a brief help page with all the options. +\fB\-h\fR, \fB\-\-help\fR Print a brief help page with all the +options. .TP -\fB\-k \fIKEYWORD\fR, \fB\-\-key=KEYWORD\fR -additional key to index the content with (to add multiple keys, specify multiple times). Each additional key is case\-sensitive. Can be specified multiple times. The keyword is only applied to the top\-level file or directory. +\fB\-k \fIKEYWORD\fR, \fB\-\-key=KEYWORD\fR additional key to index +the content with (to add multiple keys, specify multiple times). Each +additional key is case\-sensitive. Can be specified multiple times. +The keyword is only applied to the top\-level file or directory. .TP -\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR -Change the loglevel. Possible values for LOGLEVEL are -ERROR, WARNING, INFO and DEBUG. +\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR Change the +loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and +DEBUG. .TP -\fB\-m \fITYPE:VALUE\fR, \fB\-\-meta=\fITYPE:VALUE\fR -For the main file (or directory), set the metadata of the given TYPE to the given VALUE. Note that this will not add the respective VALUE to the set of keywords under which the file can be found. +\fB\-m \fITYPE:VALUE\fR, \fB\-\-meta=\fITYPE:VALUE\fR For the main +file (or directory), set the metadata of the given TYPE to the given +VALUE. Note that this will not add the respective VALUE to the set of +keywords under which the file can be found. .TP -\fB\-n\fR, \fB\-\-noindex\fR -Executive summary: You probably don't need it. - -Do not index, full publishing. Note that directories, information for keyword search, namespace search and indexing data are always published (even without this option). With this option, every block of the actual files is stored in encrypted form in the block database of the local peer. While this adds security if the local node is compromised (the adversary snags your machine), it is significantly less efficient compared to on\-demand encryption and is definitely not recommended for large files. +\fB\-n\fR, \fB\-\-noindex\fR Executive summary: You probably don't +need it. + +Do not index, full publishing. Note that directories, information for +keyword search, namespace search and indexing data are always +published (even without this option). With this option, every block +of the actual files is stored in encrypted form in the block database +of the local peer. While this adds security if the local node is +compromised (the adversary snags your machine), it is significantly +less efficient compared to on\-demand encryption and is definitely not +recommended for large files. .TP -\fB\-N \fIID\fR, \fB\-\-next=\fIID\fR -Specifies the next identifier of a future version of the file to be published under the same pseudonym. This option is only valid together with the \-P option. This option can be used to specify what the identifier of an updated version will look like. Note that specifying \-i and \-N without \-t is not allowed. +\fB\-N \fIID\fR, \fB\-\-next=\fIID\fR Specifies the next identifier of +a future version of the file to be published under the same pseudonym. +This option is only valid together with the \-P option. This option +can be used to specify what the identifier of an updated version will +look like. Note that specifying \-i and \-N without \-t is not +allowed. .TP -\fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR -Executive summary: You probably don't need it. +\fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR Executive summary: +You probably don't need it. -Set the priority of the published content (default: 365). If the local database is full, GNUnet will discard the content with the lowest ranking. Note that ranks change over time depending on popularity. The default should be high enough to preserve the locally published content in favor of content that migrates from other peers. +Set the priority of the published content (default: 365). If the +local database is full, GNUnet will discard the content with the +lowest ranking. Note that ranks change over time depending on +popularity. The default should be high enough to preserve the locally +published content in favor of content that migrates from other peers. .TP -\fB\-P \fINAME\fR, \fB\-\-pseudonym=\fINAME\fR -For the top\-level directory or file, places the file into the namespace identified by the pseudonym NAME. NAME must be a valid pseudonym managed by gnunet\-identity. +\fB\-P \fINAME\fR, \fB\-\-pseudonym=\fINAME\fR For the top\-level +directory or file, places the file into the namespace identified by +the pseudonym NAME. NAME must be a valid pseudonym managed by +gnunet\-identity. .TP -\fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR -Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet will push each block (for the file) LEVEL times to other peers before doing normal "random" replication of all content. This option can be used to push some content out into the network harder. Note that pushing content LEVEL times into the network does not guarantee that there will actually be LEVEL replicas. +\fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR Set the desired +replication level. If CONTENT_PUSHING is set to YES, GNUnet will push +each block (for the file) LEVEL times to other peers before doing +normal "random" replication of all content. This option can be used +to push some content out into the network harder. Note that pushing +content LEVEL times into the network does not guarantee that there +will actually be LEVEL replicas. .TP -\fB\-s\fR, \fB\-\-simulate-only\fR -When this option is used, gnunet\-publish will not actually publish the file but just simulate what would be done. This can be used to compute the GNUnet URI for a file without actually sharing it. +\fB\-s\fR, \fB\-\-simulate-only\fR When this option is used, +gnunet\-publish will not actually publish the file but just simulate +what would be done. This can be used to compute the GNUnet URI for a +file without actually sharing it. .TP -\fB\-t \fIID\fR, \fB\-\-this=\fIID\fR -Specifies the identifier under which the file is to be published under a pseudonym. This option is only valid together with the\ \-P option. +\fB\-t \fIID\fR, \fB\-\-this=\fIID\fR Specifies the identifier under +which the file is to be published under a pseudonym. This option is +only valid together with the\ \-P option. .TP -\fB\-u \fIURI\fR, \fB\-\-uri=\fIURI\fR -This option can be used to specify the URI of a file instead of a filename (this is the only case where the otherwise mandatory filename argument must be omitted). Instead of publishing a file or directory and using the corresponding URI, gnunet\-publish will use this URI and perform the selected namespace or keyword operations. This can be used to add additional keywords to a file that has already been shared or to add files to a namespace for which the URI is known but the content is not locally available. +\fB\-u \fIURI\fR, \fB\-\-uri=\fIURI\fR This option can be used to +specify the URI of a file instead of a filename (this is the only case +where the otherwise mandatory filename argument must be omitted). +Instead of publishing a file or directory and using the corresponding +URI, gnunet\-publish will use this URI and perform the selected +namespace or keyword operations. This can be used to add additional +keywords to a file that has already been shared or to add files to a +namespace for which the URI is known but the content is not locally +available. .TP -\fB\-v\fR, \fB\-\-version\fR -Print the version number. +\fB\-v\fR, \fB\-\-version\fR Print the version number. .TP -\fB\-V\fR, \fB\-\-verbose\fR -Be verbose. Using this option causes gnunet\-publish to print progress information and at the end the file identification that can be used to download the file from GNUnet. +\fB\-V\fR, \fB\-\-verbose\fR Be verbose. Using this option causes +gnunet\-publish to print progress information and at the end the file +identification that can be used to download the file from GNUnet. .SH SETTING ANONYMITY LEVEL -The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key. This will allow other users to download the file as fast as possible, including using non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. - -The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of data in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. - -The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. +The \fB\-a\fR option can be used to specify additional anonymity +constraints. If set to 0, GNUnet will publish the file non-anonymously +and in fact sign the advertisement for the file using your peer's +private key. This will allow other users to download the file as fast +as possible, including using non-anonymous methods (DHT, direct +transfer). If you set it to 1 (default), you use the standard +anonymous routing algorithm (which does not explicitly leak your +identity). However, a powerful adversary may still be able to perform +traffic analysis (statistics) to over time infer data about your +identity. You can gain better privacy by specifying a higher level of +anonymity, which increases the amount of cover traffic your own +traffic will get, at the expense of performance. Note that regardless +of the anonymity level you choose, peers that cache content in the +network always use anonymity level 1. + +The definition of the ANONYMITY LEVEL is the following. 0 means no +anonymity is required. Otherwise a value of 'v' means that 1 out of v +bytes of "anonymous" traffic can be from the local user, leaving 'v-1' +bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n +bytes of messages from foreign peers (using anonymous routing), it may +originate n/(v-1) bytes of data in the same time\-period. The +time\-period is twice the average delay that GNUnet defers forwarded +queries. + +The default is 1 and this should be fine for most users. Also notice +that if you choose very large values, you may end up having no +throughput at all, especially if many of your fellow GNUnet\-peers all +do the same. .SH EXAMPLES @@ -127,37 +254,55 @@ Index a file COPYING with the keywords \fBgpl\fR and \fBtest\fR: # gnunet\-publish \-k gpl \-k test COPYING -Index a file COPYING with description "GNU License", mime-type "text/plain" and keywords \fBgpl\fR and \fBtest\fR: +Index a file COPYING with description "GNU License", mime-type +"text/plain" and keywords \fBgpl\fR and \fBtest\fR: - # gnunet\-publish \-m "description:GNU License" \-k gpl \-k test \-m "mimetype:text/plain" COPYING + # gnunet\-publish \-m "description:GNU License" \-k gpl \-k test \-m + "mimetype:text/plain" COPYING \fBUsing directories\fR -Index the files COPYING and AUTHORS with keyword \fBtest\fR and build a directory containing the two files. Make the directory itself available under keyword \fBgnu\fR and disable keyword extraction using libextractor: +Index the files COPYING and AUTHORS with keyword \fBtest\fR and build +a directory containing the two files. Make the directory itself +available under keyword \fBgnu\fR and disable keyword extraction using +libextractor: - # mkdir gnu - # mv COPYING AUTHORS gnu/ - # gnunet\-publish \-k test \-k gnu \-D gnu/ + # mkdir gnu mv COPYING AUTHORS gnu/ gnunet\-publish \-k test \-k gnu + # \-D gnu/ -Neatly publish an image gallery in \fBkittendir/\fR and its subdirs with keyword \fBkittens\fR for the directory but no keywords for the individual files or subdirs (\-n). Force description for all files: +Neatly publish an image gallery in \fBkittendir/\fR and its subdirs +with keyword \fBkittens\fR for the directory but no keywords for the +individual files or subdirs (\-n). Force description for all files: - # gnunet\-publish \-n \-m "description:Kitten collection" \-k kittens kittendir/ + # gnunet\-publish \-n \-m "description:Kitten collection" \-k kittens + kittendir/ \fBSecure publishing with namespaces\fR -Publish file COPYING with pseudonym RIAA-2 (\-P) and with identifier \fBgpl\fR (\-t) and no updates: +Publish file COPYING with pseudonym RIAA-2 (\-P) and with identifier +\fBgpl\fR (\-t) and no updates: # gnunet\-publish \-P RIAA-2 \-t gpl COPYING -Recursively index /home/ogg and build a matching directory structure. Publish the top\-level directory into the namespace under the pseudonym RIAA\-2 (\-P) under identifier 'MUSIC' (\-t) and promise to provide an update with identifier 'VIDEOS' (\-N): +Recursively index /home/ogg and build a matching directory +structure. Publish the top\-level directory into the namespace under +the pseudonym RIAA\-2 (\-P) under identifier 'MUSIC' (\-t) and promise +to provide an update with identifier 'VIDEOS' (\-N): # gnunet\-publish \-P RIAA-2 \-t MUSIC \-N VIDEOS /home/ogg -Recursively publish (\-n) /var/lib/mysql and build a matching directory structure, but disable the use of libextractor to extract keywords (\-n). Print the file identifiers (\-V) that can be used to retrieve the files. This will store a copy of the MySQL database in GNUnet but without adding any keywords to search for it. Thus only people that have been told the secret file identifiers printed with the \-V option can retrieve the (secret?) files: +Recursively publish (\-n) /var/lib/mysql and build a matching +directory structure, but disable the use of libextractor to extract +keywords (\-n). Print the file identifiers (\-V) that can be used to +retrieve the files. This will store a copy of the MySQL database in +GNUnet but without adding any keywords to search for it. Thus only +people that have been told the secret file identifiers printed with +the \-V option can retrieve the (secret?) files: # gnunet\-publish \-nV /var/lib/mysql -Create a namespace entry 'root' in namespace MPAA-1 and announce that the next update will be called 'next': +Create a namespace entry 'root' in namespace MPAA-1 and announce that +the next update will be called 'next': # gnunet\-publish \-P MPAA-1 \-t root \-N next noise.mp3 diff --git a/doc/man/gnunet-qr.1 b/doc/man/gnunet-qr.1 index 6c3261d02..f1baf85ac 100644 --- a/doc/man/gnunet-qr.1 +++ b/doc/man/gnunet-qr.1 @@ -9,7 +9,8 @@ gnunet\-qr \- Scan a QR code using a video device and import. .br .SH DESCRIPTION -\fBgnunet\-qr\fP is a command line tool to scan a QR code using a video device and import. +\fBgnunet\-qr\fP is a command line tool to scan a QR code using a +video device and import. .SH OPTIONS .B diff --git a/doc/man/gnunet-resolver.1 b/doc/man/gnunet-resolver.1 index 0c314bc66..7e16932ac 100644 --- a/doc/man/gnunet-resolver.1 +++ b/doc/man/gnunet-resolver.1 @@ -20,7 +20,8 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-l LOGFILE, \-\-logfile=LOGFILE" Configure logging to write logs to LOGFILE. diff --git a/doc/man/gnunet-revocation.1 b/doc/man/gnunet-revocation.1 index 9043c286e..017b019fd 100644 --- a/doc/man/gnunet-revocation.1 +++ b/doc/man/gnunet-revocation.1 @@ -9,21 +9,48 @@ gnunet\-revocation \- revoke private keys (of egos) in GNUnet .br .SH DESCRIPTION -\fBgnunet\-revocation\fP can be used to verify if a key has been revoked, to create a revocation certificate for later revocation, to instantly revoke a key and to use a pre-generated revocation certificate to revoke a key. Upon successful revocation, all peers will be informed about the invalidity of the key. As this is an expensive operation, GNUnet requires the issuer of the revocation to perform an expensive proof-of-work computation before he will be allowed to perform the revocation. gnunet\-revocation will perform this computation. The computation can be performed ahead of time, with the resulting revocation certificate being stored in a file for later "instant" use. gnunet\-revocation also makes is possible to resume the pre-calculation of a revocation --- simply abort a running proof-of-work calculation with CTRL-C, and the existing revocation certificate file will contain the status of the computation. Note that performing a revocation proof-of-work is deliberately VERY expensive. Depending on your CPU, the calculation can take days or weeks. +\fBgnunet\-revocation\fP can be used to verify if a key has been +revoked, to create a revocation certificate for later revocation, to +instantly revoke a key and to use a pre-generated revocation +certificate to revoke a key. Upon successful revocation, all peers +will be informed about the invalidity of the key. As this is an +expensive operation, GNUnet requires the issuer of the revocation to +perform an expensive proof-of-work computation before he will be +allowed to perform the revocation. gnunet\-revocation will perform +this computation. The computation can be performed ahead of time, +with the resulting revocation certificate being stored in a file for +later "instant" use. gnunet\-revocation also makes is possible to +resume the pre-calculation of a revocation --- simply abort a running +proof-of-work calculation with CTRL-C, and the existing revocation +certificate file will contain the status of the computation. Note +that performing a revocation proof-of-work is deliberately VERY +expensive. Depending on your CPU, the calculation can take days or +weeks. .SH OPTIONS .B .IP "\-t KEY, \-\-test=KEY" -Check if the given KEY (ASCII\-encoded public key required) has been revoked. +Check if the given KEY (ASCII\-encoded public key required) has been +revoked. .B .IP "\-R NAME, \-\-revoke=NAME" Calculate or perform revocation for the ego with the given NAME. .B .IP "\-p, \-\-perform" -Actually perform the revocation as soon as possible (do not just generate a revocation certificate, use it). Must be supplied to actually perform the revocation. +Actually perform the revocation as soon as possible (do not just +generate a revocation certificate, use it). Must be supplied to +actually perform the revocation. .B .IP "\-f NAME, \-\-filename=NAME" -Use NAME as the name of the file that is to contain the revocation certificate. Intermediate computation results will be stored here, as well as the final revocation certificate. When used together with \-p, this file will be inspected to see if it contains a valid certificate for instant revocation, in which case the revocation can be performed instantly. If the given file contains anything (a valid certificate, with or without the completed proof-of-work) there is no need to supply the "\-R" option or to still have the private key of the ego to perform the revocation. +Use NAME as the name of the file that is to contain the revocation +certificate. Intermediate computation results will be stored here, as +well as the final revocation certificate. When used together with +\-p, this file will be inspected to see if it contains a valid +certificate for instant revocation, in which case the revocation can +be performed instantly. If the given file contains anything (a valid +certificate, with or without the completed proof-of-work) there is no +need to supply the "\-R" option or to still have the private key of +the ego to perform the revocation. .B .IP "\-c FILENAME, \-\-config=FILENAME" Use the configuration file FILENAME. @@ -32,7 +59,8 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. +Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and +ERROR. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-scalarproduct.1 b/doc/man/gnunet-scalarproduct.1 index 73081e2ed..0159e1eb9 100644 --- a/doc/man/gnunet-scalarproduct.1 +++ b/doc/man/gnunet-scalarproduct.1 @@ -9,7 +9,8 @@ gnunet\-vectorproduct \- compute a vectorproduct .br .SH DESCRIPTION -\fBgnunet-vectorproduct\fP enables you to compute a vectorproduct across two peers \fBAlice\fP and \fBBob\fP. +\fBgnunet-vectorproduct\fP enables you to compute a vectorproduct +across two peers \fBAlice\fP and \fBBob\fP. A client can issue one of two messages to its service: .TS @@ -23,30 +24,51 @@ Elements to support a peer in computing a vectorproduct (\fBBob\fP) T} .TE -Both requests must share the same SID, which can be an arbitrary string identifying the session. SIDs should be unique, however it is sufficient to guarantee the uniqueness of the tupel element count and session ID. +Both requests must share the same SID, which can be an arbitrary +string identifying the session. SIDs should be unique, however it is +sufficient to guarantee the uniqueness of the tupel element count and +session ID. -\fBAlice\fP\'s client must supply the ASCII encoded peer ID of bob\'s service, it will internally be checked by the client for validity. Invalid values here result in the client or the service failing the session. +\fBAlice\fP\'s client must supply the ASCII encoded peer ID of bob\'s +service, it will internally be checked by the client for +validity. Invalid values here result in the client or the service +failing the session. -Elements are handed over as signed decimal integers, the element count supplied by \fBAlice\fP and \fBBob\fP must match. \fBAlice\fP can also supply a mask for these values to her service, which allows partial vector products to be computed across the vector. Elements can be masked by setting their the corresponding mask element to zero, any other value means the element will not be masked. \fBAlice\fP\'s client will also mask all 0-values to avoid information leakage to \fBBob\fP. +Elements are handed over as signed decimal integers, the element count +supplied by \fBAlice\fP and \fBBob\fP must match. \fBAlice\fP can also +supply a mask for these values to her service, which allows partial +vector products to be computed across the vector. Elements can be +masked by setting their the corresponding mask element to zero, any +other value means the element will not be masked. \fBAlice\fP\'s +client will also mask all 0-values to avoid information leakage to +\fBBob\fP. -The protocol by definition relies on \fBAlice\fP and \fBBob\fP being benign, thus \fBBob\fP can arbitrarily falsify his information. Both peers collaborate to achieve a correct result. +The protocol by definition relies on \fBAlice\fP and \fBBob\fP being +benign, thus \fBBob\fP can arbitrarily falsify his information. Both +peers collaborate to achieve a correct result. .SH OPTIONS .B .IP "\-e ELEMENTS, \-\-elements=ELEMENTS" -The element-vector the vectorproduct should be computed over in signed decimal form, eg: \"42,1,-3,3,7\". Zero value elements will be automatically masked. +The element-vector the vectorproduct should be computed over in signed +decimal form, eg: \"42,1,-3,3,7\". Zero value elements will be automatically masked. .B .IP "\-m MASK, \-\-mask=MASK" -Elements in the vector can be masked. There must be at least two elements left in the vector to compute a vectorproduct. Non-Zero values indicate an element is not maskes. +Elements in the vector can be masked. There must be at least two +elements left in the vector to compute a vectorproduct. Non-Zero +values indicate an element is not maskes. .B .IP "\-k KEY, \-\-key=KEY" -The session key, a shared string of arbitrary length from which the SID will be generated +The session key, a shared string of arbitrary length from which the +SID will be generated .B .IP "\-c FILENAME, \-\-config=FILENAME" Use the configuration file FILENAME. .B .IP "\-p PEERID, \-\-peer=PEERID" -The remote peer\'s ASCII-armored gnunet-peer ID as output by gnunet-peerinfo. If this option is not given, the peer will take the \fBBob\fP\'s role. +The remote peer\'s ASCII-armored gnunet-peer ID as output by +gnunet-peerinfo. If this option is not given, the peer will take the +\fBBob\fP\'s role. .B .IP "\-h, \-\-help" Print short help on options. diff --git a/doc/man/gnunet-scrypt.1 b/doc/man/gnunet-scrypt.1 index 3b11ca52e..147b18fbe 100644 --- a/doc/man/gnunet-scrypt.1 +++ b/doc/man/gnunet-scrypt.1 @@ -9,7 +9,8 @@ gnunet\-scrypt \- Manipulate GNUnet proof of work files. .br .SH DESCRIPTION -\fBgnunet\-scrypt\fP is a command line tool to manipulate GNUnet proof of work files. +\fBgnunet\-scrypt\fP is a command line tool to manipulate GNUnet proof +of work files. .SH OPTIONS .B diff --git a/doc/man/gnunet-search.1 b/doc/man/gnunet-search.1 index 7f30812e0..1e0973b63 100644 --- a/doc/man/gnunet-search.1 +++ b/doc/man/gnunet-search.1 @@ -9,17 +9,49 @@ gnunet\-search \- a command line interface to search for content on GNUnet [\fIOPTIONS\fR] [+]\fIURI\fR .SH DESCRIPTION .PP -Search for content on GNUnet. The keywords are case\-sensitive. gnunet\-search can be used both for a search in the global namespace as well as for searching a private subspace. +Search for content on GNUnet. The keywords are case\-sensitive. +gnunet\-search can be used both for a search in the global namespace +as well as for searching a private subspace. .TP \fB\-a \fILEVEL\fR, \fB\-\-anonymity=\fILEVEL\fR -The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods. If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that your download performance is not only determined by your own anonymity level, but also by the anonymity level of the peers publishing the file. So even if you download with anonymity level 0, the peers publishing the data might be sharing with a higher anonymity level, which in this case will determine performance. Also, peers that cache content in the network always use anonymity level 1. - -This option can be used to limit requests further than that. In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries. This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency. So set it only if you really believe you need it. - -The definition of ANONYMITY\-RECEIVE is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of queries in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. - -The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. +The \fB\-a\fR option can be used to specify additional anonymity +constraints. If set to 0, GNUnet will try to download the file as fast +as possible, including using non-anonymous methods. If you set it to +1 (default), you use the standard anonymous routing algorithm (which +does not explicitly leak your identity). However, a powerful +adversary may still be able to perform traffic analysis (statistics) +to over time infer data about your identity. You can gain better +privacy by specifying a higher level of anonymity, which increases the +amount of cover traffic your own traffic will get, at the expense of +performance. Note that your download performance is not only +determined by your own anonymity level, but also by the anonymity +level of the peers publishing the file. So even if you download with +anonymity level 0, the peers publishing the data might be sharing with +a higher anonymity level, which in this case will determine +performance. Also, peers that cache content in the network always use +anonymity level 1. + +This option can be used to limit requests further than that. In +particular, you can require GNUnet to receive certain amounts of +traffic from other peers before sending your queries. This way, you +can gain very high levels of anonymity \- at the expense of much more +traffic and much higher latency. So set it only if you really believe +you need it. + +The definition of ANONYMITY\-RECEIVE is the following. 0 means no +anonymity is required. Otherwise a value of 'v' means that 1 out of v +bytes of "anonymous" traffic can be from the local user, leaving 'v-1' +bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n +bytes of messages from foreign peers (using anonymous routing), it may +originate n/(v-1) bytes of queries in the same time\-period. The +time\-period is twice the average delay that GNUnet defers forwarded +queries. + +The default is 1 and this should be fine for most users. Also notice +that if you choose very large values, you may end up having no +throughput at all, especially if many of your fellow GNUnet\-peers all +do the same. .TP \fB\-c \fIFILENAME\fR, \fB\-\-config=\fIFILENAME\fR @@ -48,7 +80,10 @@ automatically terminate the search after receiving VALUE results. .TP \fB\-t \fIDELAY\fR, \fB\-\-timeout=\fIDELAY\fR -Automatically timeout search after DELAY. The value given must be a number followed by a space and a time unit, for example "500 ms". Note that the quotes are required on the shell. Otherwise the search runs until gnunet\-search is aborted with CTRL\-C. +Automatically timeout search after DELAY. The value given must be a +number followed by a space and a time unit, for example "500 ms". +Note that the quotes are required on the shell. Otherwise the search +runs until gnunet\-search is aborted with CTRL\-C. .TP \fB\-v\fR, \fB\-\-version\fR @@ -59,9 +94,17 @@ print the version number print meta data from search results as well .SH NOTES -You can run gnunet\-search with an URI instead of a keyword. The URI can have the format for a namespace search or for a keyword search. For a namespace search, the format is gnunet://fs/sks/NAMESPACE/IDENTIFIER. For a keyword search, use gnunet://fs/ksk/KEYWORD[+KEYWORD]*. If the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly. +You can run gnunet\-search with an URI instead of a keyword. The URI +can have the format for a namespace search or for a keyword search. +For a namespace search, the format is +gnunet://fs/sks/NAMESPACE/IDENTIFIER. For a keyword search, use +gnunet://fs/ksk/KEYWORD[+KEYWORD]*. If the format does not correspond +to a GNUnet URI, GNUnet will automatically assume that keywords are +supplied directly. -If multiple keywords are passed, gnunet-search will look for content matching any of the keywords. The prefix "+" makes a keyword mandatory. +If multiple keywords are passed, gnunet-search will look for content +matching any of the keywords. The prefix "+" makes a keyword +mandatory. # gnunet\-search "Das Kapital" @@ -81,7 +124,13 @@ Search results are printed by gnunet\-search like this: Mime-type: text/plain .ad b -The first line contains the command to run to download the file. The suggested filename in the example is COPYING. The GNUnet URI consists of the key and query hash of the file and finally the size of the file. After the command to download the file GNUnet will print meta\-data about the file as advertised in the search result, here "The GNU General Public License" and the mime\-type (see the options for gnunet\-publish on how to supply meta-data by hand). +The first line contains the command to run to download the file. The +suggested filename in the example is COPYING. The GNUnet URI consists +of the key and query hash of the file and finally the size of the +file. After the command to download the file GNUnet will print +meta\-data about the file as advertised in the search result, here +"The GNU General Public License" and the mime\-type (see the options +for gnunet\-publish on how to supply meta-data by hand). .SH FILES .TP diff --git a/doc/man/gnunet-statistics.1 b/doc/man/gnunet-statistics.1 index e6c744f12..36f445a09 100644 --- a/doc/man/gnunet-statistics.1 +++ b/doc/man/gnunet-statistics.1 @@ -10,8 +10,11 @@ gnunet\-statistics \- Display statistics about your GNUnet system .br .SH DESCRIPTION -\fBgnunet\-statistics\fP is used to display detailed information about various aspect of GNUnet's operation. This tool only works if the "statistics" service is available. -gnunet\-statistics can be used to set a value by giving the options \-n, \-s and also a VALUE. +\fBgnunet\-statistics\fP is used to display detailed information about +various aspect of GNUnet's operation. This tool only works if the +"statistics" service is available. +gnunet\-statistics can be used to set a value by giving the options +\-n, \-s and also a VALUE. .SH OPTIONS .B @@ -25,13 +28,18 @@ Print short help on options. Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. .B .IP "\-n NAME, \-\-name=NAME" -Each statistic has a name that is unique with in its subsystem. With this option, the output can be restricted to statistics that have a particular name. +Each statistic has a name that is unique with in its subsystem. With +this option, the output can be restricted to statistics that have a +particular name. .B .IP "\-p, \-\-persistent" -When setting a value, make the value persistent. If the value used to be persistent and this flag is not given, it will be marked as non\-persistent. +When setting a value, make the value persistent. If the value used to +be persistent and this flag is not given, it will be marked as +non\-persistent. .B .IP "\-s SUBSYSTEM, \-\-subsystem=SUBSYSTEM" -Statistics are kept for various subsystems. With this option, the output can be restricted to a particular subsystem only. +Statistics are kept for various subsystems. With this option, the +output can be restricted to a particular subsystem only. .B .IP "\-v, \-\-version" Print GNUnet version number. diff --git a/doc/man/gnunet-testbed-profiler.1 b/doc/man/gnunet-testbed-profiler.1 index 3911085f2..bc7092e68 100644 --- a/doc/man/gnunet-testbed-profiler.1 +++ b/doc/man/gnunet-testbed-profiler.1 @@ -32,7 +32,9 @@ Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. Configure logging to write logs to LOGFILE. .B .IP "\-n, \-\-non\-interactive" -Run profiler in non-interactive mode where upon testbed setup the profiler does not wait for a keystroke but continues to run until a termination signal is received. +Run profiler in non-interactive mode where upon testbed setup the +profiler does not wait for a keystroke but continues to run until a +termination signal is received. .B .IP "\-p COUNT, \-\-num\-peers=COUNT" Create COUNT number of peers. diff --git a/doc/man/gnunet-testing-run-service.1 b/doc/man/gnunet-testing-run-service.1 index 7df698225..a6a29d953 100644 --- a/doc/man/gnunet-testing-run-service.1 +++ b/doc/man/gnunet-testing-run-service.1 @@ -9,11 +9,17 @@ gnunet\-testing\-run\-service \- Command line tool to start a service for testin .br .SH DESCRIPTION -\fBgnunet\-testing\-run\-service\fP is a command line tool to start a service for testing. It starts a peer, running only the service specified on the command line, outputs the path to the temporary configuration file to stdout. +\fBgnunet\-testing\-run\-service\fP is a command line tool to start a +service for testing. It starts a peer, running only the service +specified on the command line, outputs the path to the temporary +configuration file to stdout. -The peer will run until this program is killed, or stdin is closed. When reading the character 'r' from stdin, the running service is restarted with the same configuration. +The peer will run until this program is killed, or stdin is +closed. When reading the character 'r' from stdin, the running service +is restarted with the same configuration. -This executable is intended to be used by gnunet-java, in order to reliably start and stop services for test cases. +This executable is intended to be used by gnunet-java, in order to +reliably start and stop services for test cases. .SH OPTIONS .B diff --git a/doc/man/gnunet-transport.1 b/doc/man/gnunet-transport.1 index 1680f9cf7..3a81c54fe 100644 --- a/doc/man/gnunet-transport.1 +++ b/doc/man/gnunet-transport.1 @@ -8,11 +8,17 @@ gnunet\-transport \- measure and control the transport subsystem .SH DESCRIPTION .PP -gnunet\-transport is a tool to access various functions of GNUnet's transport subsystem from the command\-line. Most of these are not expected to be useful for end-users. gnunet\-transport can be used to evaluate the performance of the transports, force a peer to connect to another peer (if possible). Other functions should be added in the near future. +gnunet\-transport is a tool to access various functions of GNUnet's +transport subsystem from the command\-line. Most of these are not +expected to be useful for end-users. gnunet\-transport can be used to +evaluate the performance of the transports, force a peer to connect to +another peer (if possible). Other functions should be added in the +near future. .TP \fB\-b\fR, \fB\-\-benchmark\fR -measure how fast we are receiving data (from all connections). On exit, the data rate will be reported. Runs until aborted with CTRL-C. +measure how fast we are receiving data (from all connections). On +exit, the data rate will be reported. Runs until aborted with CTRL-C. .TP \fB\-D\fR, \fB\-\-disconnect\fR force disconnection from a peer (used in conjunction with \-p). @@ -46,7 +52,10 @@ the peer identity to connect to or monitor monitor session state of transport plugins .TP \fB\-s\fR, \fB\-\-send\fR -transmit (dummy) traffic as quickly as possible to the peer specified with the \-p option. The rate will still be limited by the quota(s) determined by the peers (ATS subsystem). Will run until CTRL\-C is pressed or until the connection to the other peer is disrupted. +transmit (dummy) traffic as quickly as possible to the peer specified +with the \-p option. The rate will still be limited by the quota(s) +determined by the peers (ATS subsystem). Will run until CTRL\-C is +pressed or until the connection to the other peer is disrupted. .TP \fB\-v\fR, \fB\-\-version\fR print the version number diff --git a/doc/man/gnunet-unindex.1 b/doc/man/gnunet-unindex.1 index b3a1de6e3..cf095cc49 100644 --- a/doc/man/gnunet-unindex.1 +++ b/doc/man/gnunet-unindex.1 @@ -25,7 +25,10 @@ print the version number \fB\-V\fR, \fB\-\-verbose\fR be verbose .SH NOTES -You can only unindex files that you indexed and that you still have available locally in full. You should use gnunet\-unindex on files that you indexed (not inserted) and that you are going to delete or move locally. +You can only unindex files that you indexed and that you still have +available locally in full. You should use gnunet\-unindex on files +that you indexed (not inserted) and that you are going to delete or +move locally. .TP .SH FILES .TP diff --git a/doc/man/gnunet-uri.1 b/doc/man/gnunet-uri.1 index 9eac68a6d..ac8ccf374 100644 --- a/doc/man/gnunet-uri.1 +++ b/doc/man/gnunet-uri.1 @@ -9,7 +9,11 @@ gnunet\-uri \- invoke default handler for GNUnet URIs .br .SH DESCRIPTION -\fBgnunet\-uri\fP can be used to invoke the correct tool to handle a GNUnet URI. GNUnet URIs have the format "gnunet://SUBSYSTEM/DETAILS" and thus the specific tool to handle the URI depends on the subsystem. gnunet\-uri will determine the correct tool (by looking for SUBSYSTEM in the configuration section "uri") and invoke it. +\fBgnunet\-uri\fP can be used to invoke the correct tool to handle a +GNUnet URI. GNUnet URIs have the format "gnunet://SUBSYSTEM/DETAILS" +and thus the specific tool to handle the URI depends on the subsystem. +gnunet\-uri will determine the correct tool (by looking for SUBSYSTEM +in the configuration section "uri") and invoke it. .SH OPTIONS .B diff --git a/doc/man/gnunet-vpn.1 b/doc/man/gnunet-vpn.1 index 68a5905d8..6b1b11f7b 100644 --- a/doc/man/gnunet-vpn.1 +++ b/doc/man/gnunet-vpn.1 @@ -9,9 +9,20 @@ gnunet\-vpn \- manually setup a GNUnet VPN tunnel .br .SH DESCRIPTION -\fBgnunet\-vpn\fP can be used to manually setup a VPN tunnel via the GNUnet network. There are two main types of tunnels. Tunnels to an exit node which routes the traffic to the global Internet, and tunnels to a node that runs a service only within GNUnet. Depending on the type of tunnel, gnunet\-vpn takes different options. The "\-i" option is required for tunnels to an exit node, whereas the "\-p" and "\-s" options in conjunction with either "\-u" or "\-t" are required for tunnels to services. For exit tunnels, both UDP and TCP traffic will be redirected. For service tunnels, either UDP ("\-u") or TCP ("\-t") traffic will be redirected. +\fBgnunet\-vpn\fP can be used to manually setup a VPN tunnel via the +GNUnet network. There are two main types of tunnels. Tunnels to an +exit node which routes the traffic to the global Internet, and tunnels +to a node that runs a service only within GNUnet. Depending on the +type of tunnel, gnunet\-vpn takes different options. The "\-i" option +is required for tunnels to an exit node, whereas the "\-p" and "\-s" +options in conjunction with either "\-u" or "\-t" are required for +tunnels to services. For exit tunnels, both UDP and TCP traffic will +be redirected. For service tunnels, either UDP ("\-u") or TCP ("\-t") +traffic will be redirected. -The tool will display the IP address for this end of the tunnel. The address can be displayed as soon as it has been allocated, or only after ("\-a") the tunnel has been created. +The tool will display the IP address for this end of the tunnel. The +address can be displayed as soon as it has been allocated, or only +after ("\-a") the tunnel has been created. .SH OPTIONS .B @@ -25,22 +36,29 @@ Desired IP address on this end of the tunnel should be an IPv6 address. Use the configuration file FILENAME. .B .IP "\-d TIME, \-\-duration TIME" -The mapping should be established for TIME. The value given must be a number followed by a space and a time unit, for example "500 ms". Note that the quotes are required on the shell. Default is 5 minutes. +The mapping should be established for TIME. The value given must be a +number followed by a space and a time unit, for example "500 ms". +Note that the quotes are required on the shell. Default is 5 minutes. .B .IP "\-h, \-\-help" Print short help on options. .B .IP "\-i IP, \-\-ip IP" -Tunnel should be to an exit node and connect to the given IPv4 or IPv6 IP address. Note that you can specify an IPv6 address as the target here, even in combination with "\-4" (4to6) and similarly you can specify an IPv4 address in combination with "\-6" (6to4). +Tunnel should be to an exit node and connect to the given IPv4 or IPv6 +IP address. Note that you can specify an IPv6 address as the target +here, even in combination with "\-4" (4to6) and similarly you can +specify an IPv4 address in combination with "\-6" (6to4). .B .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. .B .IP "\-p PEERID, \-\-peer=PEERID" -Name of the peer offering the service to connect to. Cannot be used in conjunction with "\-i", requires "\-s". +Name of the peer offering the service to connect to. Cannot be used +in conjunction with "\-i", requires "\-s". .B .IP "\-s NAME, \-\-service=NAME" -Name of the service running on the target peer. Cannot be used in conjunction with "\-i", requires "\-p". +Name of the service running on the target peer. Cannot be used in +conjunction with "\-i", requires "\-p". .B .IP "\-t, \-\-tcp" Service runs TCP. Either "\-t" or "\-u" must be specified when using "\-s". diff --git a/doc/man/gnunet-zoneimport.1 b/doc/man/gnunet-zoneimport.1 index 06b3a6bcf..bcfa7b734 100644 --- a/doc/man/gnunet-zoneimport.1 +++ b/doc/man/gnunet-zoneimport.1 @@ -8,17 +8,37 @@ gnunet\-zoneimport \- import DNS zone into GNS zone .br .SH DESCRIPTION -\fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from stdin and issues DNS queries for each of the domain names given. It then checks if a local ego with a name matching the domain exists. Specifically, if the domain name is "example.fr", it will check if an ego "fr" exists, while for a domain "example.com.fr" it will look for an ego called "com.fr"). If so, it will convert the DNS records into GNS records (in particular converting NS records and glue records to GNS2DNS records) and add them to the namestore under the label ("example" in the examples above). - -The arguments given to gnunet\-zoneimport is a list of IP addresses of DNS servers to query. - -gnunet\-zoneimport will usually never terminate: it will check when DNS records expire, and re-issue requests when the old DNS records have expired so that GNS always has the latest data. - -gnunet\-zoneimport will issue many DNS queries in parallel, but is rate-limited in various ways, so most DNS servers should easily handle the load. gnunet\-zoneimport will perform a limited number of retries if queries fail. - -gnunet\-zoneimport operates incrementally. It will check if the namestore already has (non-expired) records stored for a given name in the respective zone and not issue those requests again. Thus, it is fine to restart gnunet\-zoneimport whenever the list of domain names changes. - -Finally, gnunet\-zoneimport keeps information for each domain name in memory. This consumes about 200 bytes per domain name, or 1 GB for 5 million labels. +\fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from +stdin and issues DNS queries for each of the domain names given. It +then checks if a local ego with a name matching the domain +exists. Specifically, if the domain name is "example.fr", it will +check if an ego "fr" exists, while for a domain "example.com.fr" it +will look for an ego called "com.fr"). If so, it will convert the DNS +records into GNS records (in particular converting NS records and glue +records to GNS2DNS records) and add them to the namestore under the +label ("example" in the examples above). + +The arguments given to gnunet\-zoneimport is a list of IP addresses of +DNS servers to query. + +gnunet\-zoneimport will usually never terminate: it will check when +DNS records expire, and re-issue requests when the old DNS records +have expired so that GNS always has the latest data. + +gnunet\-zoneimport will issue many DNS queries in parallel, but is +rate-limited in various ways, so most DNS servers should easily handle +the load. gnunet\-zoneimport will perform a limited number of retries +if queries fail. + +gnunet\-zoneimport operates incrementally. It will check if the +namestore already has (non-expired) records stored for a given name in +the respective zone and not issue those requests again. Thus, it is +fine to restart gnunet\-zoneimport whenever the list of domain names +changes. + +Finally, gnunet\-zoneimport keeps information for each domain name in +memory. This consumes about 200 bytes per domain name, or 1 GB for 5 +million labels. .SH OPTIONS .B @@ -29,7 +49,13 @@ Use the configuration file FILENAME. Print short help on options. .B .IP "\-s MAPSIZE, \-\-size=MAPSIZE" -Specifies the size (in number of entries) to use for the main hash map. The value provided should be at least twice the number of domain names that will be given to the tool. This option is required for very large zones where the number of records encountered is too large for the automatic growth mechanism to work (that one is limited to at most 16 MB allocations for security reasons). Do not worry about this unless you are importing millions of domain names from a zone. +Specifies the size (in number of entries) to use for the main hash +map. The value provided should be at least twice the number of domain +names that will be given to the tool. This option is required for very +large zones where the number of records encountered is too large for +the automatic growth mechanism to work (that one is limited to at most +16 MB allocations for security reasons). Do not worry about this +unless you are importing millions of domain names from a zone. .SH NOTES -- 2.25.1