From 5e4dc39b85856222643520b8c8908384d548a0db Mon Sep 17 00:00:00 2001 From: ng0 Date: Sat, 20 Apr 2019 13:51:18 +0000 Subject: gnunet-download.1 --- doc/man/gnunet-download.1 | 278 ++++++++++++++++++++++------------------------ 1 file changed, 130 insertions(+), 148 deletions(-) (limited to 'doc') 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 or by sending electronic -mail to -.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 . -- cgit v1.2.3