aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-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 @@
1.TH GNUNET-DOWNLOAD "1" "January 31, 2016" "GNUnet" 1.Dd January 31, 2016
2.SH NAME 2.Dt GNUNET-DOWNLOAD 1
3gnunet\-download \- a command line interface for downloading files from GNUnet 3.Os
4.SH SYNOPSIS 4.Sh NAME
5.B gnunet\-download 5.Nm gnunet-download
6[\fIOPTIONS\fR] \-\- GNUNET_URI 6.Nd
7.SH DESCRIPTION 7a command line interface for downloading files from GNUnet
8.Sh SYNOPSIS
9.Nm
10.Op Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
11.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
12.Op Fl D | \-delete\-incomplete
13.Op Fl h | \-help
14.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
15.Op Fl n | \-no-network
16.Op Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
17.Op Fl p Ar DOWNLOADS | Fl \-parallelism= Ns Ar DOWNLOADS
18.Op Fl r Ar REQUESTS | Fl \-request-parallelism= Ns Ar REQUESTS
19.Op Fl R | \-recursive
20.Op Fl v | \-version
21.Op Fl V | \-verbose
22.Ao Ar GNUNET_URI Ac
23.Sh DESCRIPTION
8Download files from GNUnet. 24Download files from GNUnet.
9.TP 25.Bl -tag -width Ds
10\fB\-a \fILEVEL\fR, \fB\-\-anonymity=LEVEL\fR 26.It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
11set desired level of receiver anonymity. Default is 1. 27Set desired level of receiver anonymity.
12.TP 28Default is 1.
13\fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR 29.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
14use config file (defaults: ~/.config/gnunet.conf) 30Use config file (default:
15.TP 31.Pa ~/.config/gnunet.conf Ns )
16\fB\-D, \fB\-\-delete\-incomplete\fR 32.It Fl D | \-delete\-incomplete
17causes gnunet\-download to delete incomplete downloads when aborted with 33Causes gnunet-download to delete incomplete downloads when aborted with CTRL-C.
18CTRL\-C. Note that complete files that are part of an incomplete recursive 34Note that complete files that are part of an incomplete recursive download will not be deleted even with this option.
19download will not be deleted even with this option. Without this option, 35Without this option, terminating gnunet-download with a signal will cause incomplete downloads to stay on disk.
20terminating gnunet\-download with a signal will cause incomplete 36If gnunet-download runs to (normal) completion finishing the download, this option has no effect.
21downloads to stay on disk. If gnunet\-download runs to (normal) completion 37.It Fl h | \-help
22finishing the download, this option has no effect. 38Print help page
23.TP 39.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
24\fB\-h\fR, \fB\-\-help\fR 40Change the loglevel.
25print help page 41Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG.
26.TP 42.It Fl n | \-no-network
27\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=LOGLEVEL\fR
28Change the loglevel. Possible values for LOGLEVEL are
29ERROR, WARNING, INFO and DEBUG.
30.TP
31\fB\-n\fR, \fB\-\-no-network\fR
32Only search locally, do not forward requests to other peers. 43Only search locally, do not forward requests to other peers.
33.TP 44.It Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
34\fB\-o \fIFILENAME\fR, \fB\-\-output=FILENAME\fR 45Write the file to FILENAME.
35write the file to FILENAME. Hint: when recursively downloading a directory, 46Hint: when recursively downloading a directory, append a '/' to the end of the FILENAME to create a directory of that name.
36append a '/' to the end of the FILENAME to create a directory of that name. 47If no FILENAME is specified, gnunet-download constructs a temporary ID from the URI of the file.
37If no FILENAME is specified, gnunet\-download constructs a temporary ID from 48The final filename is constructed based on meta-data extracted using libextractor (if available).
38the URI of the file. The final filename is constructed based on meta\-data 49.It Fl p Ar DOWNLOADS | Fl \-parallelism= Ns Ar DOWNLOADS
39extracted using libextractor (if available). 50Set the maximum number of parallel downloads that is allowed.
40.TP 51More parallel downloads can, to some extent, improve the overall time to download content.
41\fB\-p \fIDOWNLOADS\fR, \fB\-\-parallelism=DOWNLOADS\fR 52However, parallel downloads also take more memory (see also option \-r which can be used to limit memory utilization) and more sockets.
42set the maximum number of parallel downloads that is allowed. More parallel 53This 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).
43downloads can, to some extent, improve the overall time to download content.
44However, parallel downloads also take more memory (see also option \-r which
45can be used to limit memory utilization) and more sockets. This option is
46used to limit the number of files that are downloaded in parallel (\-r can
47be used to limit the number of blocks that are concurrently requested).
48As a result, the value only matters for recursive downloads. 54As a result, the value only matters for recursive downloads.
49The default value is 32. 55The default value is 32.
50.TP 56.It Fl r Ar REQUESTS | Fl \-request-parallelism= Ns Ar REQUESTS
51\fB\-r \fIREQUESTS\fR, \fB\-\-request-parallelism=REQUESTS\fR 57Set the maximum number of parallel requests that is allowed.
52set the maximum number of parallel requests that is allowed. If multiple 58If 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.
53files are downloaded, gnunet\-download will not run them in parallel if 59This is useful since, for example, downloading dozens of multi\-gigabyte files in parallel could exhaust memory resources and would hardly improve performance.
54this would cause the number of pending requests to possibly exceed the 60Note that the limit only applies to this specific process and that other download activities by other processes are not included in this limit.
55given value. This is useful since, for example, downloading dozens of 61Consider 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
56multi\-gigabyte files in parallel could exhaust memory resources and would 62.Pq Fl p
57hardly improve performance. Note that the limit only applies to this 63is not reached.
58specific process and that other download activities by other processes 64This option also only matters for recursive downloads.
59are not included in this limit. Consider raising this limit for large
60recursive downloads with many large files if memory and network
61bandwidth are not fully utilized and if the parallelism limit (\-p option)
62is not reached. This option also only matters for recursive downloads.
63The default value is 4092. 65The default value is 4092.
64.TP 66.It Fl R | \-recursive
65\fB\-R\fR, \fB\-\-recursive\fR 67Download directories recursively (and in parallel).
66download directories recursively (and in parallel). Note that the URI 68Note 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.
67must belong to a GNUnet directory and that the filename given to "\-o" 69You 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".
68must end in '.gnd' \-\- otherwise, you will receive an error. You may 70However, 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".
69want to use "DIRNAME/.gnd" for the filename, this way a directory 71.It Fl v | \-version
70"DIRNAME/" will be created, and GNUnet's internal directory
71information will be stored in "DIRNAME/.gnd". However, it is also
72possible to specify "DIRNAME.gnd", in which case the files from the
73directory will end up in "DIRNAME/", while GNUnet's directory meta
74data will be in "DIRNAME.gnd".
75.TP
76\fB\-v\fR, \fB\-\-version\fR
77print the version number 72print the version number
78.TP 73.It Fl V | \-verbose
79\fB\-V\fR, \fB\-\-verbose\fR
80print progress information 74print progress information
81.SH NOTES 75.El
76.Ss NOTES
82The GNUNET_URI is typically obtained from 77The GNUNET_URI is typically obtained from
83gnunet\-search. gnunet\-fs\-gtk can also be used instead of 78.Xr gnunet-search 1 .
84gnunet\-download. If you ever have to abort a download, you can at 79.Xr gnunet-fs-gtk 1
85any time continue it by re\-issuing gnunet\-download with the same 80can also be used instead of gnunet-download.
86filename. In that case GNUnet will not download blocks again that are 81If you ever have to abort a download, you can at any time continue it by re-issuing gnunet-download with the same filename.
87already present. GNUnet's file\-encoding will ensure file integrity, 82In that case GNUnet will not download blocks again that are already present.
88even if the existing file was not downloaded from GNUnet in the first 83GNUnet's file-encoding will ensure file integrity, even if the existing file was not downloaded from GNUnet in the first place.
89place. Temporary information will be appended to the target file until 84Temporary information will be appended to the target file until the download is completed.
90the download is completed. 85.Ss SETTING ANONYMITY LEVEL
91.SH SETTING ANONYMITY LEVEL 86The
92The \fB\-a\fR option can be used to specify additional anonymity 87.Fl a
93constraints. If set to 0, GNUnet will try to download the file as fast 88option can be used to specify additional anonymity constraints.
94as possible, including using non-anonymous methods. If you set it to 89If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods.
951 (default), you use the standard anonymous routing algorithm (which 90If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity).
96does not explicitly leak your identity). However, a powerful 91However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity.
97adversary may still be able to perform traffic analysis (statistics) 92You 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.
98to over time infer data about your identity. You can gain better 93Note 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.
99privacy by specifying a higher level of anonymity, which increases the 94So 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.
100amount of cover traffic your own traffic will get, at the expense of 95Also, peers that cache content in the network always use anonymity level 1.
101performance. Note that your download performance is not only 96.Pp
102determined by your own anonymity level, but also by the anonymity 97This option can be used to limit requests further than that.
103level of the peers publishing the file. So even if you download with 98In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries.
104anonymity level 0, the peers publishing the data might be sharing with 99This way, you can gain very high levels of anonymity - at the expense of much more traffic and much higher latency.
105a higher anonymity level, which in this case will determine 100So set it only if you really believe you need it.
106performance. Also, peers that cache content in the network always use 101.Pp
107anonymity level 1. 102The definition of ANONYMITY\-RECEIVE is the following.
108.PP 1030 means no anonymity is required.
109This option can be used to limit requests further than that. In 104Otherwise 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.
110particular, you can require GNUnet to receive certain amounts of 105Thus, 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.
111traffic from other peers before sending your queries. This way, you 106The time\-period is twice the average delay that GNUnet defers forwarded queries.
112can gain very high levels of anonymity \- at the expense of much more 107.Pp
113traffic and much higher latency. So set it only if you really believe 108The default is 1 and this should be fine for most users.
114you need it. 109Also 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.
115.PP 110.Sh FILES
116The definition of ANONYMITY\-RECEIVE is the following. 0 means no 111.Pa ~/.config/gnunet.conf
117anonymity is required. Otherwise a value of 'v' means that 1 out of v
118bytes of "anonymous" traffic can be from the local user, leaving 'v-1'
119bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n
120bytes of messages from foreign peers (using anonymous routing), it may
121originate n/(v-1) bytes of queries in the same time\-period. The
122time\-period is twice the average delay that GNUnet defers forwarded
123queries.
124.PP
125The default is 1 and this should be fine for most users. Also notice
126that if you choose very large values, you may end up having no
127throughput at all, especially if many of your fellow GNUnet\-peers all
128do the same.
129.SH FILES
130.TP
131~/.config/gnunet.conf
132GNUnet configuration file 112GNUnet configuration file
133.SH BUGS 113.Sh SEE ALSO
134Report bugs to <https://bugs.gnunet.org/> or by sending electronic 114.Xr gnunet-fs-gtk 1 ,
135mail to <gnunet\-developers@gnu.org> 115.Xr gnunet-publish 1 ,
136.SH SEE ALSO 116.Xr gnunet-search 1 ,
137\fBgnunet\-fs\-gtk\fP(1), \fBgnunet\-publish\fP(1), 117.Xr gnunet-service-fs 1 ,
138\fBgnunet\-search\fP(1), \fBgnunet.conf\fP(5), 118.Xr gnunet.conf 5
139\fBgnunet\-service\-fs\fP(1) 119.sp
140.PP 120The full documentation for gnunet is maintained as a Texinfo manual.
141The full documentation for
142.B gnunet
143is maintained as a Texinfo manual.
144If the 121If the
145.B info 122.Xr info 1
146and 123and gnunet programs are properly installed at your site, the command
147.B gnunet 124.Pp
148programs are properly installed at your site, the command 125.Dl info gnunet
149.IP 126.Pp
150.B info gnunet
151.PP
152should give you access to the complete handbook, 127should give you access to the complete handbook,
153.IP 128.Pp
154.B info gnunet-c-tutorial 129.Dl info gnunet-c-tutorial
155.PP 130.Pp
156will give you access to a tutorial for developers. 131will give you access to a tutorial for developers.
157.PP 132.sp
158Depending on your installation, this information is also 133Depending on your installation, this information is also available in
159available in 134.Xr gnunet 7 and
160\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). 135.Xr gnunet-c-tutorial 7 .
136.\".Sh HISTORY
137.\".Sh AUTHORS
138.Sh BUGS
139Report bugs by using
140.Lk https://bugs.gnunet.org
141or by sending electronic mail to
142.Aq Mt gnunet-developers@gnu.org .