From a07991f9be04ede254b6e4991c7cfda44bd53700 Mon Sep 17 00:00:00 2001 From: ng0 Date: Sun, 21 Apr 2019 20:08:52 +0000 Subject: manpages. --- doc/man/gnunet-directory.1 | 184 ++++++++++++++++++------------- doc/man/gnunet-download.1 | 25 ++--- doc/man/gnunet-identity.1 | 180 +++++++++++++++++------------- doc/man/gnunet-namestore-fcfsd.1 | 158 ++++++++++++++++---------- doc/man/gnunet-namestore.1 | 232 ++++++++++++++++++++++----------------- doc/man/gnunet-nat-auto.1 | 155 ++++++++++++++++---------- doc/man/gnunet-nat-server.1 | 170 ++++++++++++++++------------ doc/man/gnunet-publish.1 | 152 +++++++++++++++++-------- doc/man/gnunet-search.1 | 54 ++++++--- 9 files changed, 797 insertions(+), 513 deletions(-) (limited to 'doc') diff --git a/doc/man/gnunet-directory.1 b/doc/man/gnunet-directory.1 index c08eca46d..e4be45b28 100644 --- a/doc/man/gnunet-directory.1 +++ b/doc/man/gnunet-directory.1 @@ -1,83 +1,109 @@ -.TH GNUNET-DIRECTORY "1" "February 25, 2012" "GNUnet" -.SH NAME -gnunet\-directory \- display directories -.SH SYNOPSIS -.B gnunet\-directory -[\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. -.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) -.TP -\fB\-h\fR, \fB\-\-help\fR -print help page -.TP -\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 -.SH NOTES +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd February 25, 2012 +.Dt GNUNET-DIRECTORY 1 +.Os +.Sh NAME +.Nm gnunet-directory +.Nd +display directories +.Sh SYNOPSIS +.Nm +.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +.Op Fl h | \-help +.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +.Op Fl v | \-version +.Ao Ar FILENAME Ac +.Sh DESCRIPTION +.Nm +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. +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +Configuration file to use. +This option is useless, since gnunet-directory does not really depend on any configuration options. +.It Fl h | \-help +Print the help page. +.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +Change the loglevel. +Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. +.It Fl v | \-version +Print the version number. +.El +.Ss 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. -.PP -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. -.PP -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. -.PP -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 BUGS -Report bugs by using mantis or by sending -electronic mail to -.SH SEE ALSO -\fBgnunet\-fs\-gtk\fP(1), \fBgnunet\-publish\fP(1), -\fBgnunet\-search\fP(1), \fBgnunet\-download\fP(1) -The full documentation for -.B gnunet -is maintained as a Texinfo manual. -If the -.B info +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. +.Pp +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. +.Pp +At the moment, directories can be created by +.Xr gnunet-fs-gtk 1 , and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr gnunet-publish 1 . +Just like ordinary files, a directory can be published in a namespace. +.Pp +GNUnet directories use the (unregistered) mimetype "application/gnunet-directory". +They can show up among normal search results. +The directory file can be downloaded to disk by +.Xr gnunet-download 1 +for later processing or be handled more directly by +.Xr gnunet-fs-gtk 1 . +.\".Sh EXAMPLES +.Sh SEE ALSO +.Xr gnunet-download 1 , +.Xr gnunet-fs-gtk 1 , +.Xr gnunet-publish 1 , +.Xr gnunet-search 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. +If the +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-download.1 b/doc/man/gnunet-download.1 index f278694c3..1c7776ff1 100644 --- a/doc/man/gnunet-download.1 +++ b/doc/man/gnunet-download.1 @@ -22,24 +22,23 @@ a command line interface for downloading files from GNUnet .Ao Ar GNUNET_URI Ac .Sh DESCRIPTION Download files from GNUnet. +The options are as follows: .Bl -tag -width Ds .It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL -This option can be used to specify additional anonymity constraints. The default is 1. +This option can be used to specify additional anonymity constraints. +The default is 1. 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 (discovery via DHT and CADET 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 discovery your identity. You can gain better privacy by specifying a higher level of anonymity (using values above 1). -This tells FS that it must hide your own requests in equivalent\-looking cover traffic. -This should confound an adversaries traffic analysis, increasing the time and effort it would -take to discover your identity. However, it also can significantly reduce performance, as -your requests will be delayed until sufficient cover traffic is available. The specific -numeric value (for anonymity levels above 1) is simple: -Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L-1 equivalent -requests of cover traffic (traffic your peer routes for others) in the same time\-period. -The time\-period is twice the average delay by which GNUnet artificially delays traffic. -Note that regardless of the anonymity level you choose, peers that cache content in the -network always use anonymity level 1. +This tells FS that it must hide your own requests in equivalent-looking cover traffic. +This should confound an adversaries traffic analysis, increasing the time and effort it would take to discover your identity. +However, it also can significantly reduce performance, as your requests will be delayed until sufficient cover traffic is available. +The specific numeric value (for anonymity levels above 1) is simple: +Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L-1 equivalent requests of cover traffic (traffic your peer routes for others) in the same time-period. +The time-period is twice the average delay by which GNUnet artificially delays traffic. +Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. .It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME Use config file (default: .Pa ~/.config/gnunet.conf Ns ) @@ -89,9 +88,9 @@ must end in '.gnd' \(em 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". .It Fl v | \-version -print the version number +Print the version number. .It Fl V | \-verbose -print progress information +Print progress information. .El .Ss NOTES The GNUNET_URI is typically obtained from diff --git a/doc/man/gnunet-identity.1 b/doc/man/gnunet-identity.1 index ca4acfebe..79004bab5 100644 --- a/doc/man/gnunet-identity.1 +++ b/doc/man/gnunet-identity.1 @@ -1,80 +1,112 @@ -.TH GNUNET-IDENTITY "1" "September 5, 2013" "GNUnet" -.SH NAME -gnunet\-identity \- create, delete or list egos -.SH SYNOPSIS -.B gnunet\-identity -[options] -.SH DESCRIPTION -.PP -gnunet\-identity is a tool for managing egos. +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd +.Dt GNUNET-IDENTITY "1" "September 5, 2013" "GNUnet" +.Os +.Sh NAME +.Nm gnunet-identity +.Nd +create, delete or list egos +.Sh SYNOPSIS +.Nm +.Op Fl C Ar NAME | Fl \-create= Ns Ar NAME +.Op Fl D Ar NAME | Fl \-delete= Ns Ar NAME +.Op Fl e Ar NAME | Fl \-ego= Ns Ar NAME +.Op Fl h | \-help +.Op Fl d | \-display +.Op Fl m | \-monitor +.Op Fl s Ar SUBSYSTEM | Fl \-set= Ns Ar SUBSYSTEM +.Sh DESCRIPTION +.Nm +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. -.PP -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). -.PP -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. -.TP -\fB\-D NAME\fR, \fB\-\-delete=NAME\fR -Delete the ego with the given NAME. -.TP -\fB\-e NAME\fR, \fB\-\-ego=NAME\fR +It is identical to a public-private ECC key pair. +.Pp +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). +.Pp +Creating a new ego requires using the +.Fl 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. +The options are as follows: +.Bl -tag -width Ds +.It Fl C Ar NAME | Fl \-create= Ns Ar NAME +Creates a new ego with the given +.Ar NAME . +.It Fl D Ar NAME | Fl \-delete= Ns Ar NAME +Delete the ego with the given +.Ar NAME . +.It Fl e Ar NAME | Fl \-ego= Ns Ar NAME 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. -.TP -\fB\-d\fR, \fB\-\-display\fR -display all of our egos -.TP -\fB\-m\fR, \fB\-\-monitor\fR +Needs to be used together with option +.Fl s . +.It Fl h | \-help +Print the help page. +.It d | \-display +Display all of our egos. +.It m | \-monitor 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. -.SH FILES -.TP -~/.local/share/gnunet/identity/egos -Directory where the egos are stored (by default) -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to -.SH SEE ALSO -\fBgnunet\-gns\fP(1), \fBgnunet\-namestore\fP(1) -The full documentation for -.B gnunet -is maintained as a Texinfo manual. +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 "". +.It Fl s Ar SUBSYSTEM | Fl \-set= Ns Ar SUBSYSTEM +Perform "set" operation for the specified +.Ar SUBSYSTEM +with the respective ego. +Needs to be used together with option +.Fl e . +After this, the given SUBSYSTEM will use the ego with the specified NAME. +This will fail if +.Ar NAME +does not yet exist. +.El +.Sh FILES +.Pa ~/.local/share/gnunet/identity/egos +Directory where the egos are stored by default +.\".Sh EXAMPLES +.Sh SEE ALSO +.Xr gnunet-gns 1 , +.Xr gnunet-namestore 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-namestore-fcfsd.1 b/doc/man/gnunet-namestore-fcfsd.1 index c1eca224f..cbfe39719 100644 --- a/doc/man/gnunet-namestore-fcfsd.1 +++ b/doc/man/gnunet-namestore-fcfsd.1 @@ -1,66 +1,104 @@ -.TH GNUNET-NAMESTORE-FCFSD 1 "September 5, 2013" "GNUnet" -.SH NAME -gnunet\-namestore-fcfsd \- HTTP server for GNU Name System First-Come-First-Served name registration -.SH SYNOPSIS -.B gnunet\-namestore-fcfsd -.RI [ options ] -.SH DESCRIPTION -Most users will not want to run an FCFS\-zone and thus will not need -this program. -.PP -\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". -.PP -It is possible to manage gnunet\-gns\-fcfsd using -gnunet\-(service\-arm) by starting the daemon using "gnunet\-arm \-i -fcfsd" or by setting "IMMEDIATE_START=YES" in the "fcfds" section of your -configuration and the "-z ZONE" in as the "OPTION". -.PP -An FCFS\-zone is run at http://gnunet.org/fcfs/. GNS users are -encouraged to register their zone with the gnunet.org FCFS authority. -.PP -If you want to run your own FCFS registrar, you need to first create a -pseudonym (using "gnunet\-identity \-C NAME"), and use it with the -"-z" option. After that, you can start the FCFSD service (possibly using -gnunet\-arm). -.SH OPTIONS -.IP "\-c FILENAME, \-\-config=FILENAME" +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd September 5, 2013 +.Dt GNUNET-NAMESTORE-FCFSD 1 +.Os +.Sh NAME +.Nm gnunet-namestore-fcfsd +.Nd +HTTP server for GNU Name System First-Come-First-Served name registration +.Sh SYNOPSIS +.Nm +.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +.Op Fl h | \-help +.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +.Op Fl v | \-version +.Op Fl z Ar EGO | \-zone= Ns Ar EGO +.Sh DESCRIPTION +Most users will not want to run an FCFS-zone and thus will not need this program. +.Pp +.Nm +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". +.Pp +It is possible to manage gnunet-gns-fcfsd using gnunet-(service-arm) by starting the daemon using "gnunet-arm -i fcfsd" or by setting "IMMEDIATE_START=YES" in the "fcfds" section of your configuration and the "-z ZONE" in as the "OPTION". +.Pp +An FCFS-zone is run at +.Lk http://gnunet.org/fcfs/ . +GNS users are encouraged to register their zone with the gnunet.org FCFS authority. +.Pp +If you want to run your own FCFS registrar, you need to first create a pseudonym (using "gnunet-identity -C NAME"), and use it with the +.Fl z +option. +After that, you can start the FCFSD service (possibly using +.Xr gnunet-arm 1 Ns ). +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME Use the configuration file FILENAME. -.IP "\-h, \-\-help" +.It Fl h | \-help Print short help on options. -.IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and -ERROR. -.IP "\-v, \-\-version" +.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +Use LOGLEVEL for logging. +Valid values are DEBUG, INFO, WARNING and ERROR. +.It Fl v | \-version Print GNUnet version number. -.IP "\-z EGO, \-\-zone=EGO" -Specifies for which EGO should FCFSD manage the zone. -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to -.SH SEE ALSO -gnunet\-identity(1), gnunet\-gns(1), gnunet\-gns\-proxy(1) -.PP -The full documentation for -.B gnunet -is maintained as a Texinfo manual. +.It Fl z Ar EGO | \-zone= Ns Ar EGO +Specifies for which +.Ar EGO +FCFSD should manage the zone. +.El +.\".Sh EXAMPLES +.\".Sh FILES +.Sh SEE ALSO +.Xr gnunet-identity 1 , +.Xr gnunet-gns 1 , +.Xr gnunet-gns-proxy 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-namestore.1 b/doc/man/gnunet-namestore.1 index 6a824cc47..6a399c360 100644 --- a/doc/man/gnunet-namestore.1 +++ b/doc/man/gnunet-namestore.1 @@ -1,104 +1,138 @@ -.TH GNUNET\-NAMESTORE 1 "April 15, 2014" "GNUnet" - -.SH NAME -gnunet\-namestore \- manipulate GNU Name System (GNS) zone data - -.SH SYNOPSIS -.B gnunet\-namestore -.RI [ options ] -z ZONEFILE -.br - -.SH DESCRIPTION -\fBgnunet\-namestore\fP can be used to manipulate records in a GNS zone. - -.SH OPTIONS -.IP "\-a, \-\-add" -Desired operation is adding a record -.IP "\-c FILENAME, \-\-config=FILENAME" +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd April 15, 2014 +.Dt GNUNET-NAMESTORE 1 +.Os +.Sh NAME +.Nm gnunet-namestore +.Nd +manipulate GNU Name System (GNS) zone data +.Sh SYNOPSIS +.Nm +.Op Fl a | \-add +.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +.Op Fl d | \-delete +.Op Fl D | \-display +.Op Fl e Ar TIME | Fl \-expiration= Ns Ar TIME +.Op Fl h | \-help +.Op Fl i Ar NICKNAME | Fl \-nick= Ns Ar NICKNAME +.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +.Op Fl m | \-monitor +.Op Fl n Ar NAME | Fl \-name= Ns Ar NAME +.Op Fl p | \-public +.Op Fl r Ar PKEY | Fl \-reverse= Ns Ar PKEY +.Op Fl R Ar RECORDLINE | Fl \-replace= Ns Ar RECORDLINE +.Op Fl s | \-shadow +.Op Fl t Ar TYPE | Fl \-type= Ns Ar TYPE +.Op Fl u Ar URI | Fl \-uri= Ns Ar URI +.Op Fl v | \-version +.Op Fl V Ar VALUE | Fl \-value= Ns Ar VALUE +.Op Fl z Ar EGO | Fl \-zone= Ns Ar EGO +.Sh DESCRIPTION +.Nm +can be used to manipulate records in a GNS zone. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl a | \-add +Desired operation is adding a record. +.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME Use the configuration file FILENAME. -.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. -.IP "\-D, \-\-display" -Desired operation is listing of matching records -.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). -.IP "\-h, \-\-help" +.It Fl 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. +.It Fl D | \-display +Desired operation is listing of matching records. +.It Fl e Ar TIME | Fl \-expiration= Ns Ar 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). +.It Fl h | \-help Print short help on options. -.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. -.IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and -ERROR. -.IP "\-m, \-\-monitor" -Monitor changes to the zone on an ongoing basis (in contrast to \-D, -which merely displays the current records) -.IP "\-n NAME, \-\-name=NAME" -Label or name of the record to add/delete/display -.IP "\-p, \-\-public" -Create a record that is public (shared with other users that know the -label) -.IP "\-r PKEY, \-\-reverse=PKEY" -Determine our GNS name for the given public key (reverse lookup of the -PKEY) in the given zone. -.IP "\-R RECORDLINE, \-\-replace=RECORDLINE" -Sets record set to values given in RECORDLINE. This option can be specified multiple -times to provide multiple records for the record set. Existing records under the -same label will be deleted. The format for the RECORDLINE is -"TTL TYPE FLAGS VALUE" where TTL is the time to live in seconds (unit must not -be given explicitly, seconds is always implied), TYPE is the -DNS/GNS record type, FLAGS is "(N)ORMAL", "(S)HADOW" or "(P)UBLIC". The VALUE -follows the usual human-readable value format(s) of DNS/GNS. -.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. -.IP "\-t TYPE, \-\-type=TYPE" -Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", -"PKEY", "MX" etc.) -.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 -.IP "\-v, \-\-version" +.It Fl i Ar NICKNAME | Fl \-nick= Ns Ar 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. +.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL +Use LOGLEVEL for logging. +Valid values are DEBUG, INFO, WARNING and ERROR. +.It Fl m | \-monitor +Monitor changes to the zone on an ongoing basis (in contrast to \-D, which merely displays the current records). +.It Fl n Ar NAME | Fl \-name= Ns Ar NAME +Label or name of the record to add/delete/display. +.It Fl p | \-public +Create a record that is public (shared with other users that know the label). +.It Fl r Ar PKEY | Fl \-reverse= Ns Ar PKEY +Determine our GNS name for the given public key (reverse lookup of the PKEY) in the given zone. +.It Fl R Ar RECORDLINE | Fl \-replace= Ns Ar RECORDLINE +Sets record set to values given in RECORDLINE. +This option can be specified multiple times to provide multiple records for the record set. +Existing records under the same label will be deleted. +The format for the RECORDLINE is "TTL TYPE FLAGS VALUE" where TTL is the time to live in seconds (unit must not be given explicitly, seconds is always implied), TYPE is the DNS/GNS record type, FLAGS is "(N)ORMAL", "(S)HADOW" or "(P)UBLIC". +The VALUE follows the usual human-readable value format(s) of DNS/GNS. +.It Fl 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. +.It Fl t Ar TYPE | Fl \-type= Ns Ar TYPE +Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", "PKEY", "MX" etc.). +.It Fl u Ar URI | Fl \-uri= Ns Ar 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 +.It Fl v | \-version Print GNUnet version number. -.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. -.IP "\-z EGO, \-\-zone=EGO" -Specifies the name of the ego controlling the private key for the zone -(mandatory option) - - -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to -.SH SEE ALSO -\fBgnunet\-gns\fP(1), \fBgnunet\-namestore\-gtk\fP(1) -The full documentation for -.B gnunet -is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.It Fl V Ar VALUE | Fl \-value= Ns Ar 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. +.It Fl z Ar EGO | Fl \-zone= Ns Ar EGO +Specifies the name of the ego controlling the private key for the zone (mandatory option). +.El +.\".Sh EXAMPLES +.\".Sh FILES +.Sh SEE ALSO +.Xr gnunet-gns 1 , +.Xr gnunet-namestore-gtk 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. +If the +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-nat-auto.1 b/doc/man/gnunet-nat-auto.1 index efd4b5df1..405020e37 100644 --- a/doc/man/gnunet-nat-auto.1 +++ b/doc/man/gnunet-nat-auto.1 @@ -1,67 +1,106 @@ -.TH GNUNET-NAT-AUTO 1 "January 6, 2017" "GNUnet" -.SH NAME -gnunet\-nat\-auto \- autoconfigure and test NAT traversal -.SH SYNOPSIS -.B gnunet\-nat\-auto -.RI [ options ] -.SH DESCRIPTION -This tool allows testing various NAT traversal functions, as well -as attempting auto\-configuration. -.SH OPTIONS -.IP "\-a, \-\-auto" -Attempt auto\-configuration for NAT traversal. -.IP "\-c FILENAME, \-\-config=FILENAME" -Use the configuration file FILENAME. -.IP "\-S NAME, \-\-section=NAME" -Name of the configuration section with details about the configuration -to test. For example "transport-tcp". -.IP "\-t, \-\-tcp" +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd January 6, 2017 +.Dt GNUNET-NAT-AUTO 1 +.Sh NAME +.Nm gnunet-nat-auto +.Nd +autoconfigure and test NAT traversal +.Sh SYNOPSIS +.Nm +.Op Fl a | \-auto +.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +.Op Fl S Ar NAME | Fl \-section= Ns Ar NAME +.Op Fl t | \-tcp +.Op Fl u | \-udp +.Op Fl w | \-write +.Sh DESCRIPTION +.Nm +allows testing various NAT traversal functions, as well as attempting auto-configuration. +The options are as follows: +.Bl -tag -width Ds +.It Fl a | \-auto +Attempt auto-configuration for NAT traversal. +.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +Use the configuration file +.Ar FILENAME . +.It Fl S Ar NAME | Fl \-section= Ns Ar NAME +Name of the configuration section with details about the configuration to test. +For example "transport-tcp". +.It Fl t | \-tcp Use TCP. -.IP "\-u, \-\-udp" +.It Fl u | \-udp Use UDP. -.IP "\-w, \-\-write" -Write configuration to configuration file, useful in combination with -autoconfiguration (\-a). -.SH EXAMPLES -.PP -\fBAutomatic configuration:\fR -.TP -# gnunet\-nat\-auto \-aw +.It Fl w | \-write +Write configuration to configuration file, useful in combination with auto-configuration +.Pq Fl a . +.El +.Sh EXAMPLES +.Ss Automatic configuration: +.Pp +.Dl # gnunet-nat-auto -aw +.Pp Probe and write result to configuration -.PP -\fBTest configuration:\fR -.TP -# gnunet\-nat\-auto -t \-S transport-tcp +.Ss Test configuration: +.Pp +.Pp +.Dl # gnunet-nat-auto -t -S transport-tcp +.Pp Test TCP configuration -.TP -# gnunet\-nat\-auto -t \-S transport-http +.Pp +.Dl # gnunet-nat-auto -t -S transport-http +.Pp Test HTTP configuration -.TP -# gnunet\-nat\-auto -u \-S transport-udp +.Pp +.Dl # gnunet-nat-auto -u -S transport-udp +.Pp Test UDP configuration -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to -.SH SEE ALSO -gnunet\-transport(1) gnunet\-nat(1) -.PP -The full documentation for -.B gnunet -is maintained as a Texinfo manual. +.\".Sh FILES +.Sh SEE ALSO +.Xr gnunet-nat 1 , +.Xr gnunet-transport 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-nat-server.1 b/doc/man/gnunet-nat-server.1 index 8cb995f7c..b8462d9da 100644 --- a/doc/man/gnunet-nat-server.1 +++ b/doc/man/gnunet-nat-server.1 @@ -1,71 +1,105 @@ -.TH GNUNET-NAT-SERVER 1 "February 25, 2012" "GNUnet" -.SH NAME -gnunet\-nat\-server \- help GNUnet setup test network setup with NAT -.SH SYNOPSIS -.B gnunet\-nat\-server -.RI [ options ] -.RI PORT -.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. -.PP -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). -.PP -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. -.PP -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. -.PP -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 -.IP "\-c FILENAME, \-\-config=FILENAME" -Use the configuration file FILENAME. -.SH BUGS -Report bugs by using Mantis or by sending -electronic mail to -.SH SEE ALSO -gnunet\-transport(1) -.PP -The full documentation for -.B gnunet -is maintained as a Texinfo manual. +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" +.Dd February 25, 2012 +.Dt GNUNET-NAT-SERVER 1 +.Os +.Sh NAME +.Nm gnunet-nat-server +.Nd +help GNUnet setup test network setup with NAT +.Sh SYNOPSIS +.Nm +.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +.Op Fl d | \-daemonize +.Op Fl h | \-help +.Op Fl L Ar FILENAME | Fl \-logfile= Ns Ar FILENAME +.Op Fl v | \-version +.Ao Ar PORT Ac +.Sh DESCRIPTION +Running a gnunet-nat-server is similar to running a hostlist server: it is a special service to the community with special requirements and no benefit to those running the service. +.Pp +This program will listen on the specified +.Ar 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). +.Pp +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. +.Pp +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. +.Pp +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. +.Pp +Normal GNUnet end-users should not concern themselves with gnunet-nat-server. +In fact, distributions are encouraged to consider not shipping it at all. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME +Use the configuration file +.Ar FILENAME . +.It Fl d | \-daemonize +Daemonize gnunet-nat-server (detach from terminal). +.It Fl h | \-help +Print the help page. +.It Fl L Ar LOGLEVEL | Fl \-log= Ns Ar LOGLEVEL +Configure logging to use +.Ar LOGLEVEL . +.It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME +Configure logging to write logs to +.Ar FILENAME . +.It Fl v | \-version +Print the GNUnet version. +.El +.\".Sh EXAMPLES +.Sh SEE ALSO +.Xr gnunet-transport 1 +.sp +The full documentation for gnunet is maintained as a Texinfo manual. If the -.B info -and -.B gnunet -programs are properly installed at your site, the command -.IP -.B info gnunet -.PP +.Xr info 1 +and gnunet programs are properly installed at your site, the command +.Pp +.Dl info gnunet +.Pp should give you access to the complete handbook, -.IP -.B info gnunet-c-tutorial -.PP +.Pp +.Dl info gnunet-c-tutorial +.Pp will give you access to a tutorial for developers. -.PP -Depending on your installation, this information is also -available in -\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). +.sp +Depending on your installation, this information is also available in +.Xr gnunet 7 and +.Xr gnunet-c-tutorial 7 . +.\".Sh HISTORY +.\".Sh AUTHORS +.Sh BUGS +Report bugs by using +.Lk https://bugs.gnunet.org +or by sending electronic mail to +.Aq Mt gnunet-developers@gnu.org . diff --git a/doc/man/gnunet-publish.1 b/doc/man/gnunet-publish.1 index b003f27e0..c41e34a8c 100644 --- a/doc/man/gnunet-publish.1 +++ b/doc/man/gnunet-publish.1 @@ -45,7 +45,7 @@ a command line interface for publishing new content into GNUnet .Op Fl P Ar NAME | Fl \-pseudonym= Ns Ar NAME .Op Fl r Ar LEVEL | Fl \-replication= Ns Ar LEVEL .Op Fl s | \-simulate-only -.Op Fl t Ar ID, \-this= Ns Ar ID +.Op Fl t Ar ID | Fl \-this= Ns Ar ID .Op Fl u Ar URI | Fl \-uri= Ns Ar URI .Op Fl v | \-version .Op Fl V | \-verbose @@ -125,25 +125,24 @@ However, indexing only works if the indexed file can be read (using the same abs 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. -.Sh OPTIONS +.Pp +The options are as follows: .Bl -tag -width Ds .It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL -This option can be used to specify additional anonymity constraints. The default is 1. +This option can be used to specify additional anonymity constraints. +The default is 1. 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 (discovery via DHT and CADET 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 discovery your identity. You can gain better privacy by specifying a higher level of anonymity (using values above 1). -This tells FS that it must hide your own requests in equivalent\-looking cover traffic. -This should confound an adversaries traffic analysis, increasing the time and effort it would -take to discover your identity. However, it also can significantly reduce performance, as -your requests will be delayed until sufficient cover traffic is available. The specific -numeric value (for anonymity levels above 1) is simple: -Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L\-1 equivalent -requests of cover traffic (traffic your peer routes for others) in the same time\-period. -The time\-period is twice the average delay by which GNUnet artificially delays traffic. -Note that regardless of the anonymity level you choose, peers that cache content in the -network always use anonymity level 1. +This tells FS that it must hide your own requests in equivalent-looking cover traffic. +This should confound an adversaries traffic analysis, increasing the time and effort it would take to discover your identity. +However, it also can significantly reduce performance, as your requests will be delayed until sufficient cover traffic is available. +The specific numeric value (for anonymity levels above 1) is simple: +Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L-1 equivalent requests of cover traffic (traffic your peer routes for others) in the same time-period. +The time-period is twice the average delay by which GNUnet artificially delays traffic. +Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. .It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME Use alternate config file FILENAME. If this option is not specified, the default is @@ -174,12 +173,20 @@ 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. +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. .It Fl N Ar ID | Fl \-next= Ns Ar ID 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 is only valid together with the +.Fl 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. +Note that specifying +.Fl i +and +.Fl N +without +.Fl t +is not allowed. .It Fl p Ar PRIORITY | Fl \-prio= Ns Ar PRIORITY Executive summary: You probably don't need it. Set the priority of the published content (default: 365). @@ -187,8 +194,9 @@ If the local database is full, GNUnet will discard the content with the lowest r 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. .It Fl P Ar NAME | Fl \-pseudonym= Ns Ar NAME -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. +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 +.Xr gnunet-identity 1 . .It Fl r Ar LEVEL | Fl \-replication= Ns Ar LEVEL 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. @@ -197,70 +205,122 @@ Note that pushing content LEVEL times into the network does not guarantee that t .It Fl s | \-simulate-only 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. -.It Fl t Ar ID, \-this= Ns Ar ID +.It Fl t Ar ID | Fl \-this= Ns Ar ID Specifies the identifier under which the file is to be published under a pseudonym. -This option is only valid together with the\ \-P option. +This option is only valid together with the +.Fl P +option. .It Fl u Ar URI | Fl \-uri= Ns Ar URI 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. +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. .It Fl v | \-version Print the version number. .It Fl V | \-verbose 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. +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. .El .Sh EXAMPLES .Ss BASIC EXAMPLES -Index a file COPYING: +Index a file +.Pa COPYING : .Pp .Dl gnunet-publish COPYING .Pp -Publish a file COPYING: +Publish a file +.Pa COPYING : .Pp -.Dl gnunet\-publish \-n COPYING +.Dl gnunet-publish -n COPYING .Pp -Index a file COPYING with the keywords \fBgpl\fR and \fBtest\fR +Index a file +.Pa COPYING +with the keywords +.Ar gpl +and +.Ar test : .Pp -.Dl gnunet\-publish \-k gpl \-k test COPYING +.Dl gnunet-publish -k gpl -k test COPYING .Pp -Index a file COPYING with description "GNU License", mime-type "text/plain" and keywords \fBgpl\fR and \fBtest\fR +Index a file +.Pa COPYING +with description +.Ar "GNU License" , +mime-type +.Ar "text/plain" +and keywords +.Ar gpl +and +.Ar test: .Pp -.Dl gnunet\-publish \-m "description:GNU License" \-k gpl \-k test \-m "mimetype:text/plain" COPYING +.Dl gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING .Ss USING DIRECTORIES -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 +.Pa COPYING +and +.Pa AUTHORS +with keyword +.Ar test +and build a directory containing the two files. +Make the directory itself available under keyword +.Ar gnu +and disable keyword extraction using libextractor: .Pp -.Dl mkdir gnu ; mv COPYING AUTHORS gnu/ ; gnunet\-publish \-k test \-k gnu \-D gnu/ +.Dl mkdir gnu ; mv COPYING AUTHORS gnu/ ; gnunet-publish -k test -k gnu -D gnu/ .Pp -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). +Neatly publish an image gallery in +.Pa kittendir/ +and its subdirs with keyword +.Ar kittens +for the directory but no keywords for the individual files or subdirs +.Pq Fl n . Force description for all files. .Pp -.Dl gnunet\-publish \-n \-m "description:Kitten collection" \-k kittens kittendir/ +.Dl gnunet-publish -n -m "description:Kitten collection" -k kittens kittendir/ .Ss SECURE PUBLISHING WITH NAMESPACES -Publish file COPYING with pseudonym RIAA-2 (\-P) and with identifier \fBgpl\fR (\-t) and no updates. +Publish file COPYING with pseudonym RIAA-2 +.Pq Fl P +and with identifier \fBgpl\fR +.Pq Fl t +and no updates. .Pp -.Dl gnunet\-publish \-P RIAA-2 \-t gpl COPYING +.Dl gnunet-publish -P RIAA-2 -t gpl COPYING .Pp -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 +.Pa /home/ogg +and build a matching directory structure. +Publish the top-level directory into the namespace under the pseudonym +.Ar RIAA-2 +.Pq Fl P +under identifier +.Ar 'MUSIC' +.Pq Fl t +and promise to provide an update with identifier +.Ar 'VIDEOS' +.Pq Fl N : .Pp -.Dl gnunet\-publish \-P RIAA-2 \-t MUSIC \-N VIDEOS /home/ogg +.Dl gnunet-publish -P RIAA-2 -t MUSIC -N VIDEOS /home/ogg .Pp -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. +Recursively publish +.Pq Fl n +/var/lib/mysql and build a matching directory structure, but disable the use of libextractor to extract keywords +.Pq Fl n . +Print the file identifiers +.Pq Fl 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: +Thus only people that have been told the secret file identifiers printed with the +.Fl V +option can retrieve the (secret?) files: .Pp -.Dl gnunet\-publish \-nV /var/lib/mysql +.Dl gnunet-publish -nV /var/lib/mysql .Pp Create a namespace entry 'root' in namespace MPAA-1 and announce that the next update will be called 'next': .Pp -.Dl gnunet\-publish \-P MPAA-1 \-t root \-N next noise.mp3 +.Dl gnunet-publish -P MPAA-1 -t root -N next noise.mp3 .Pp Update the previous entry, do not allow any future updates: .Pp -.Dl gnunet\-publish \-P MPAA-1 \-t next noise_updated.mp3 +.Dl gnunet-publish -P MPAA-1 -t next noise_updated.mp3 .Sh FILES .Pa ~/.config/gnunet.conf GNUnet configuration file @@ -271,7 +331,7 @@ GNUnet configuration file .Xr gnunet-fs-gtk 1 , .Xr gnunet-identity 1 , .Xr gnunet-search 1 , -.Xr gnunet.conf 5 , +.Xr gnunet.conf 5 .sp The full documentation for gnunet is maintained as a Texinfo manual. If the diff --git a/doc/man/gnunet-search.1 b/doc/man/gnunet-search.1 index 58e16ea7b..484bfca24 100644 --- a/doc/man/gnunet-search.1 +++ b/doc/man/gnunet-search.1 @@ -1,3 +1,26 @@ +.\" This file is part of GNUnet. +.\" Copyright (C) 2001-2019 GNUnet e.V. +.\" +.\" Permission is granted to copy, distribute and/or modify this document +.\" under the terms of the GNU Free Documentation License, Version 1.3 or +.\" any later version published by the Free Software Foundation; with no +.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +.\" copy of the license is included in the file +.\" ``FDL-1.3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. +.\" +.\" Alternately, this document is also available under the General +.\" Public License, version 3 or later, as published by the Free Software +.\" Foundation. A copy of the license is included in the file +.\" ``GPL3''. +.\" +.\" A copy of the license is also available from the Free Software +.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. +.\" +.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later +.\" .Dd February 25, 2012 .Dt GNUNET-SEARCH 1 .Os @@ -24,27 +47,26 @@ Search for content on GNUnet. The keywords are case-sensitive. .Nm can be used both for a search in the global namespace as well as for searching a private subspace. -.Sh OPTIONS +The options are as follows: .Bl -tag -width Ds .It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL -This option can be used to specify additional anonymity constraints. The default is 1. +This option can be used to specify additional anonymity constraints. +The default is 1. 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 (discovery via DHT and CADET 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 discovery your identity. You can gain better privacy by specifying a higher level of anonymity (using values above 1). -This tells FS that it must hide your own requests in equivalent\-looking cover traffic. -This should confound an adversaries traffic analysis, increasing the time and effort it would -take to discover your identity. However, it also can significantly reduce performance, as -your requests will be delayed until sufficient cover traffic is available. The specific -numeric value (for anonymity levels above 1) is simple: -Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L\-1 equivalent -requests of cover traffic (traffic your peer routes for others) in the same time\-period. -The time\-period is twice the average delay by which GNUnet artificially delays traffic. -Note that regardless of the anonymity level you choose, peers that cache content in the -network always use anonymity level 1. +This tells FS that it must hide your own requests in equivalent-looking cover traffic. +This should confound an adversaries traffic analysis, increasing the time and effort it would take to discover your identity. +However, it also can significantly reduce performance, as your requests will be delayed until sufficient cover traffic is available. +The specific numeric value (for anonymity levels above 1) is simple: +Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L-1 equivalent requests of cover traffic (traffic your peer routes for others) in the same time-period. +The time-period is twice the average delay by which GNUnet artificially delays traffic. +Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. .It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME -use config file (defaults: ~/.config/gnunet.conf) +Use the configuration file FILENAME (default: +.Pa ~/.config/gnunet.conf ) .It Fl h | \-help print help page .It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL @@ -62,13 +84,13 @@ Automatically terminate the search after receiving VALUE results. 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. +Otherwise the search runs until gnunet-search is aborted with CTRL\-C. .It Fl v | \-version print the version number .It Fl V | \-verbose print meta data from search results as well .El -You can run gnunet\-search with an URI instead of a keyword. +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 .Pp @@ -108,7 +130,7 @@ Search results are printed by gnunet\-search like this: 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). +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 SEE ALSO .Xr gnunet-fs-gtk 1 , .Xr gnunet\-publish 1 , -- cgit v1.2.3