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