diff options
author | ng0 <ng0@n0.is> | 2019-04-03 11:19:30 +0000 |
---|---|---|
committer | ng0 <ng0@n0.is> | 2019-04-03 11:19:30 +0000 |
commit | 56b6543511d41f44a05b6966293e45a8f0c39712 (patch) | |
tree | c089c24308a38afffb1cf1b4e727b307470ea373 /doc/man | |
parent | fcac585424151f1c8d28905040cc7791e3ee05fa (diff) | |
download | gnunet-56b6543511d41f44a05b6966293e45a8f0c39712.tar.gz gnunet-56b6543511d41f44a05b6966293e45a8f0c39712.zip |
man: search (update)
Diffstat (limited to 'doc/man')
-rw-r--r-- | doc/man/gnunet-search.1 | 268 |
1 files changed, 127 insertions, 141 deletions
diff --git a/doc/man/gnunet-search.1 b/doc/man/gnunet-search.1 index af72d369d..c1bb7c1e4 100644 --- a/doc/man/gnunet-search.1 +++ b/doc/man/gnunet-search.1 | |||
@@ -1,121 +1,108 @@ | |||
1 | .TH GNUNET-SEARCH "1" "February 25, 2012" "0.9.6" "GNUnet" | 1 | .Dd February 25, 2012 |
2 | .SH NAME | 2 | .Dt GNUNET-SEARCH 1 |
3 | gnunet\-search \- a command line interface to search for content on GNUnet | 3 | .Os |
4 | .SH SYNOPSIS | 4 | .Sh NAME |
5 | .B gnunet\-search | 5 | .Nm gnunet-search |
6 | [\fIOPTIONS\fR] [+]\fIKEYWORD\fR [[+]\fIKEYWORD\fR]* | 6 | .Nd |
7 | 7 | a command line interface to search for content on GNUnet | |
8 | .B gnunet\-search | 8 | .Sh SYNOPSIS |
9 | [\fIOPTIONS\fR] [+]\fIURI\fR | 9 | .Nm |
10 | .SH DESCRIPTION | 10 | .Op Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL |
11 | .PP | 11 | .Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME |
12 | Search for content on GNUnet. The keywords are case\-sensitive. | 12 | .Op Fl h | \-help |
13 | gnunet\-search can be used both for a search in the global namespace | 13 | .Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL |
14 | as well as for searching a private subspace. | 14 | .Op Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME |
15 | .TP | 15 | .Op Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME |
16 | \fB\-a \fILEVEL\fR, \fB\-\-anonymity=\fILEVEL\fR | 16 | .Op Fl n | \-no-network |
17 | 17 | .Op Fl N Ar VALUE | Fl \-results= Ns Ar VALUE | |
18 | The \fB\-a\fR option can be used to specify additional anonymity | 18 | .Op Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY |
19 | constraints. If set to 0, GNUnet will try to download the file as fast | 19 | .Op Fl v | \-version |
20 | as possible, including using non-anonymous methods. If you set it to | 20 | .Op Fl V | \-verbose |
21 | 1 (default), you use the standard anonymous routing algorithm (which | 21 | .Ao KEYWORD Ac Ao +KEYWORD Ac | Ao Ar URI Ac Ao Ar +URI Ac |
22 | does not explicitly leak your identity). However, a powerful | 22 | .Sh DESCRIPTION |
23 | adversary may still be able to perform traffic analysis (statistics) | 23 | Search for content on GNUnet. |
24 | to over time infer data about your identity. You can gain better | 24 | The keywords are case-sensitive. |
25 | privacy by specifying a higher level of anonymity, which increases the | 25 | .Nm |
26 | amount of cover traffic your own traffic will get, at the expense of | 26 | can be used both for a search in the global namespace as well as for searching a private subspace. |
27 | performance. Note that your download performance is not only | 27 | .Bl -tag -width Ds |
28 | determined by your own anonymity level, but also by the anonymity | 28 | .It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL |
29 | level of the peers publishing the file. So even if you download with | 29 | The \fB\-a\fR option can be used to specify additional anonymity constraints. |
30 | anonymity level 0, the peers publishing the data might be sharing with | 30 | If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods. |
31 | a higher anonymity level, which in this case will determine | 31 | If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). |
32 | performance. Also, peers that cache content in the network always use | 32 | However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. |
33 | anonymity level 1. | 33 | 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. |
34 | 34 | 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. | |
35 | This option can be used to limit requests further than that. In | 35 | 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. |
36 | particular, you can require GNUnet to receive certain amounts of | 36 | Also, peers that cache content in the network always use anonymity level 1. |
37 | traffic from other peers before sending your queries. This way, you | 37 | .sp |
38 | can gain very high levels of anonymity \- at the expense of much more | 38 | This option can be used to limit requests further than that. |
39 | traffic and much higher latency. So set it only if you really believe | 39 | In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries. |
40 | you need it. | 40 | This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency. |
41 | 41 | So set it only if you really believe you need it. | |
42 | The definition of ANONYMITY\-RECEIVE is the following. 0 means no | 42 | .sp |
43 | anonymity is required. Otherwise a value of 'v' means that 1 out of v | 43 | The definition of ANONYMITY\-RECEIVE is the following. |
44 | bytes of "anonymous" traffic can be from the local user, leaving 'v-1' | 44 | 0 means no anonymity is required. |
45 | bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n | 45 | 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. |
46 | bytes of messages from foreign peers (using anonymous routing), it may | 46 | 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. |
47 | originate n/(v-1) bytes of queries in the same time\-period. The | 47 | The time\-period is twice the average delay that GNUnet defers forwarded queries. |
48 | time\-period is twice the average delay that GNUnet defers forwarded | 48 | .sp |
49 | queries. | 49 | The default is 1 and this should be fine for most users. |
50 | 50 | 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. | |
51 | The default is 1 and this should be fine for most users. Also notice | 51 | .It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME |
52 | that if you choose very large values, you may end up having no | ||
53 | throughput at all, especially if many of your fellow GNUnet\-peers all | ||
54 | do the same. | ||
55 | |||
56 | .TP | ||
57 | \fB\-c \fIFILENAME\fR, \fB\-\-config=\fIFILENAME\fR | ||
58 | use config file (defaults: ~/.config/gnunet.conf) | 52 | use config file (defaults: ~/.config/gnunet.conf) |
59 | 53 | .It Fl h | \-help | |
60 | .TP | ||
61 | \fB\-h\fR, \fB\-\-help\fR | ||
62 | print help page | 54 | print help page |
63 | 55 | .It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL | |
64 | .TP | 56 | Change the loglevel. |
65 | \fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR | 57 | Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. |
66 | Change the loglevel. Possible values for LOGLEVEL are | 58 | .It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME |
67 | ERROR, WARNING, INFO and DEBUG. | 59 | Write logs to FILENAME. |
68 | 60 | .It Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME | |
69 | .TP | ||
70 | \fB\-o \fIFILENAME\fR, \fB\-\-output=\fIFILENAME\fR | ||
71 | Writes a GNUnet directory containing all of the search results to FILENAME. | 61 | Writes a GNUnet directory containing all of the search results to FILENAME. |
72 | 62 | .It Fl n | \-no-network | |
73 | .TP | ||
74 | \fB\-n\fR, \fB\-\-no-network\fR | ||
75 | Only search locally, do not forward requests to other peers. | 63 | Only search locally, do not forward requests to other peers. |
76 | 64 | .It Fl N Ar VALUE | Fl \-results= Ns Ar VALUE | |
77 | .TP | 65 | Automatically terminate the search after receiving VALUE results. |
78 | \fB\-N \fIVALUE\fR, \fB\-\-results=\fIVALUE\fR | 66 | .It Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY |
79 | automatically terminate the search after receiving VALUE results. | 67 | Automatically timeout search after DELAY. |
80 | 68 | The value given must be a number followed by a space and a time unit, for example "500 ms". | |
81 | .TP | 69 | Note that the quotes are required on the shell. |
82 | \fB\-t \fIDELAY\fR, \fB\-\-timeout=\fIDELAY\fR | 70 | Otherwise the search runs until gnunet\-search is aborted with CTRL\-C. |
83 | Automatically timeout search after DELAY. The value given must be a | 71 | .It Fl v | \-version |
84 | number followed by a space and a time unit, for example "500 ms". | ||
85 | Note that the quotes are required on the shell. Otherwise the search | ||
86 | runs until gnunet\-search is aborted with CTRL\-C. | ||
87 | |||
88 | .TP | ||
89 | \fB\-v\fR, \fB\-\-version\fR | ||
90 | print the version number | 72 | print the version number |
91 | 73 | .It Fl V | \-verbose | |
92 | .TP | ||
93 | \fB\-V\fR, \fB\-\-verbose\fR | ||
94 | print meta data from search results as well | 74 | print meta data from search results as well |
95 | .SH NOTES | 75 | .El |
96 | 76 | You can run gnunet\-search with an URI instead of a keyword. | |
97 | You can run gnunet\-search with an URI instead of a keyword. The URI | 77 | The URI can have the format for a namespace search or for a keyword search. |
98 | can have the format for a namespace search or for a keyword search. | ||
99 | For a namespace search, the format is | 78 | For a namespace search, the format is |
100 | gnunet://fs/sks/NAMESPACE/IDENTIFIER. For a keyword search, use | 79 | .Pp |
101 | gnunet://fs/ksk/KEYWORD[+KEYWORD]*. If the format does not correspond | 80 | .Dl gnunet://fs/sks/NAMESPACE/IDENTIFIER |
102 | to a GNUnet URI, GNUnet will automatically assume that keywords are | 81 | .Pp |
103 | supplied directly. | 82 | For a keyword search, use |
104 | 83 | .Pp | |
84 | .Dl gnunet://fs/ksk/KEYWORD[+KEYWORD]* | ||
85 | .Pp | ||
86 | If the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly. | ||
87 | .sp | ||
105 | If multiple keywords are passed, gnunet-search will look for content | 88 | If multiple keywords are passed, gnunet-search will look for content |
106 | matching any of the keywords. The prefix "+" makes a keyword | 89 | matching any of the keywords. |
107 | mandatory. | 90 | The prefix "+" makes a keyword mandatory. |
108 | 91 | .Sh FILES | |
109 | # gnunet\-search "Das Kapital" | 92 | .Pa ~/.config/gnunet.conf |
110 | 93 | GNUnet configuration file; specifies the default value for the timeout | |
111 | searches for content matching the keyword "Das Kapital". Whereas | 94 | .Sh EXAMPLES |
112 | 95 | .Pp | |
113 | # gnunet\-search +Das +Kapital | 96 | .Dl $ gnunet\-search "Das Kapital" |
114 | 97 | .Pp | |
98 | Searches for content matching the keyword "Das Kapital". | ||
99 | .Pp | ||
100 | .Dl $ gnunet\-search +Das +Kapital | ||
101 | .Pp | ||
115 | Searches for content matching both mandatory keywords "Das" and "Kapital". | 102 | Searches for content matching both mandatory keywords "Das" and "Kapital". |
116 | 103 | .sp | |
117 | Search results are printed by gnunet\-search like this: | 104 | Search results are printed by gnunet\-search like this: |
118 | .P | 105 | .Pp |
119 | .ad l | 106 | .ad l |
120 | gnunet\-download \-o "COPYING" gnunet://fs/chk/HASH1.HASH2.SIZE | 107 | gnunet\-download \-o "COPYING" gnunet://fs/chk/HASH1.HASH2.SIZE |
121 | 108 | ||
@@ -124,38 +111,37 @@ Search results are printed by gnunet\-search like this: | |||
124 | Mime-type: text/plain | 111 | Mime-type: text/plain |
125 | .ad b | 112 | .ad b |
126 | 113 | ||
127 | The first line contains the command to run to download the file. The | 114 | The first line contains the command to run to download the file. |
128 | suggested filename in the example is COPYING. The GNUnet URI consists | 115 | The suggested filename in the example is COPYING. |
129 | of the key and query hash of the file and finally the size of the | 116 | The GNUnet URI consists of the key and query hash of the file and finally the size of the file. |
130 | file. After the command to download the file GNUnet will print | 117 | 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). |
131 | meta\-data about the file as advertised in the search result, here | 118 | .Sh SEE ALSO |
132 | "The GNU General Public License" and the mime\-type (see the options | 119 | .Xr gnunet-fs-gtk 1 , |
133 | for gnunet\-publish on how to supply meta-data by hand). | 120 | .Xr gnunet\-publish 1 , |
134 | 121 | .Xr gnunet\-download 1 , | |
135 | .SH FILES | 122 | .Xr gnunet.conf 5 |
136 | .TP | 123 | .sp |
137 | ~/.config/gnunet.conf | 124 | The full documentation for gnunet is maintained as a Texinfo manual. |
138 | GNUnet configuration file; specifies the default value for the timeout | 125 | If the |
139 | .SH "REPORTING BUGS" | 126 | .Xr info 1 |
140 | Report bugs to <https://bugs.gnunet.org/> or by sending electronic mail to <gnunet\-developers@gnu.org> | 127 | and gnunet programs are properly installed at your site, the command |
141 | .SH "SEE ALSO" | 128 | .Pp |
142 | \fBgnunet\-fs\-gtk\fP(1), \fBgnunet\-publish\fP(1), \fBgnunet\-download\fP(1), \fBgnunet.conf\fP(5), | 129 | .Dl info gnunet |
143 | The full documentation for | 130 | .Pp |
144 | .B gnunet | ||
145 | is maintained as a Texinfo manual. If the | ||
146 | .B info | ||
147 | and | ||
148 | .B gnunet | ||
149 | programs are properly installed at your site, the command | ||
150 | .IP | ||
151 | .B info gnunet | ||
152 | .PP | ||
153 | should give you access to the complete handbook, | 131 | should give you access to the complete handbook, |
154 | .IP | 132 | .Pp |
155 | .B info gnunet-c-tutorial | 133 | .Dl info gnunet-c-tutorial |
156 | .PP | 134 | .Pp |
157 | will give you access to a tutorial for developers. | 135 | will give you access to a tutorial for developers. |
158 | .PP | 136 | .sp |
159 | Depending on your installation, this information is also | 137 | Depending on your installation, this information is also available in |
160 | available in | 138 | .Xr gnunet 7 and |
161 | \fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). | 139 | .Xr gnunet-c-tutorial 7 . |
140 | .\".Sh HISTORY | ||
141 | .\"gnunet-search first appeared in GNUnet 0.9.6. | ||
142 | .\".Sh AUTHORS | ||
143 | .Sh BUGS | ||
144 | Report bugs by using | ||
145 | .Lk https://bugs.gnunet.org | ||
146 | or by sending electronic mail to | ||
147 | .Aq Mt gnunet-developers@gnu.org . | ||