summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorng0 <ng0@n0.is>2019-04-20 13:51:18 +0000
committerng0 <ng0@n0.is>2019-04-20 13:51:18 +0000
commit5e4dc39b85856222643520b8c8908384d548a0db (patch)
treeafe2c8bfafb4ad5fcc40537b9a63462ef12e1900 /doc
parente704e562dcad7262c34da0212fa4a612c5f62b5e (diff)
gnunet-download.1
Diffstat (limited to 'doc')
-rw-r--r--doc/man/gnunet-download.1278
1 files changed, 130 insertions, 148 deletions
diff --git a/doc/man/gnunet-download.1 b/doc/man/gnunet-download.1
index 064a803d0..4dd8ecb79 100644
--- a/doc/man/gnunet-download.1
+++ b/doc/man/gnunet-download.1
@@ -1,160 +1,142 @@
-.TH GNUNET-DOWNLOAD "1" "January 31, 2016" "GNUnet"
-.SH NAME
-gnunet\-download \- a command line interface for downloading files from GNUnet
-.SH SYNOPSIS
-.B gnunet\-download
-[\fIOPTIONS\fR] \-\- GNUNET_URI
-.SH DESCRIPTION
+.Dd January 31, 2016
+.Dt GNUNET-DOWNLOAD 1
+.Os
+.Sh NAME
+.Nm gnunet-download
+.Nd
+a command line interface for downloading files from GNUnet
+.Sh SYNOPSIS
+.Nm
+.Op Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
+.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
+.Op Fl D | \-delete\-incomplete
+.Op Fl h | \-help
+.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+.Op Fl n | \-no-network
+.Op Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
+.Op Fl p Ar DOWNLOADS | Fl \-parallelism= Ns Ar DOWNLOADS
+.Op Fl r Ar REQUESTS | Fl \-request-parallelism= Ns Ar REQUESTS
+.Op Fl R | \-recursive
+.Op Fl v | \-version
+.Op Fl V | \-verbose
+.Ao Ar GNUNET_URI Ac
+.Sh DESCRIPTION
Download files from GNUnet.
-.TP
-\fB\-a \fILEVEL\fR, \fB\-\-anonymity=LEVEL\fR
-set desired level of receiver anonymity. Default is 1.
-.TP
-\fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR
-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.
-.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\-n\fR, \fB\-\-no-network\fR
+.Bl -tag -width Ds
+.It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
+Set desired level of receiver anonymity.
+Default is 1.
+.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
+Use config file (default:
+.Pa ~/.config/gnunet.conf Ns )
+.It Fl D | \-delete\-incomplete
+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.
+.It Fl h | \-help
+Print 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 n | \-no-network
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).
-.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).
+.It Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
+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).
+.It Fl p Ar DOWNLOADS | Fl \-parallelism= Ns Ar DOWNLOADS
+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.
+.It Fl r Ar REQUESTS | Fl \-request-parallelism= Ns Ar REQUESTS
+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
+.Pq Fl p
+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".
-.TP
-\fB\-v\fR, \fB\-\-version\fR
+.It Fl R | \-recursive
+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".
+.It Fl v | \-version
print the version number
-.TP
-\fB\-V\fR, \fB\-\-verbose\fR
+.It Fl V | \-verbose
print progress information
-.SH NOTES
+.El
+.Ss 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.
-.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.
-.PP
-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.
-.PP
-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.
-.PP
-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
-~/.config/gnunet.conf
+.Xr gnunet-search 1 .
+.Xr gnunet-fs-gtk 1
+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.
+.Ss SETTING ANONYMITY LEVEL
+The
+.Fl a
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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
+.Pa ~/.config/gnunet.conf
GNUnet configuration file
-.SH BUGS
-Report bugs to <https://bugs.gnunet.org/> or by sending electronic
-mail to <gnunet\-developers@gnu.org>
-.SH SEE ALSO
-\fBgnunet\-fs\-gtk\fP(1), \fBgnunet\-publish\fP(1),
-\fBgnunet\-search\fP(1), \fBgnunet.conf\fP(5),
-\fBgnunet\-service\-fs\fP(1)
-.PP
-The full documentation for
-.B gnunet
-is maintained as a Texinfo manual.
+.Sh SEE ALSO
+.Xr gnunet-fs-gtk 1 ,
+.Xr gnunet-publish 1 ,
+.Xr gnunet-search 1 ,
+.Xr gnunet-service-fs 1 ,
+.Xr gnunet.conf 5
+.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 .