doc/man/gnunet-search.1

   1 .\" This file is part of GNUnet.
   2 .\" Copyright (C) 2001-2019 GNUnet e.V.
   3 .\"
   4 .\" Permission is granted to copy, distribute and/or modify this document
   5 .\" under the terms of the GNU Free Documentation License, Version 1.3 or
   6 .\" any later version published by the Free Software Foundation; with no
   7 .\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
   8 .\" copy of the license is included in the file
   9 .\" FDL-1.3.
  10 .\"
  11 .\" A copy of the license is also available from the Free Software
  12 .\" Foundation Web site at http://www.gnu.org/licenses/fdl.html}.
  13 .\"
  14 .\" Alternately, this document is also available under the General
  15 .\" Public License, version 3 or later, as published by the Free Software
  16 .\" Foundation.  A copy of the license is included in the file
  17 .\" GPL3.
  18 .\"
  19 .\" A copy of the license is also available from the Free Software
  20 .\" Foundation Web site at http://www.gnu.org/licenses/gpl.html
  21 .\"
  22 .\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later
  23 .\"
  24 .Dd February 25, 2012
  25 .Dt GNUNET-SEARCH 1
  26 .Os
  27 .Sh NAME
  28 .Nm gnunet-search
  29 .Nd
  30 a command line interface to search for content on GNUnet
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
  34 .Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
  35 .Op Fl h | \-help
  36 .Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
  37 .Op Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
  38 .Op Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
  39 .Op Fl n | \-no-network
  40 .Op Fl N Ar VALUE | Fl \-results= Ns Ar VALUE
  41 .Op Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
  42 .Op Fl v | \-version
  43 .Op Fl V | \-verbose
  44 .Ao KEYWORD Ac Ao +KEYWORD Ac | Ao Ar URI Ac Ao Ar +URI Ac
  45 .Sh DESCRIPTION
  46 Search for content on GNUnet.
  47 The keywords are case-sensitive.
  48 .Nm
  49 can be used both for a search in the global namespace as well as for searching a private subspace.
  50 The options are as follows:
  51 .Bl -tag -width indent
  52 .It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
  53 This option can be used to specify additional anonymity constraints.
  54 The default is 1.
  55 If set to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key.
  56 This will allow other users to download the file as fast as possible, including using non-anonymous methods (discovery via DHT and CADET transfer).
  57 If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity).
  58 However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time discovery your identity.
  59 You can gain better privacy by specifying a higher level of anonymity (using values above 1).
  60 This tells FS that it must hide your own requests in equivalent-looking cover traffic.
  61 This should confound an adversaries traffic analysis, increasing the time and effort it would take to discover your identity.
  62 However, it also can significantly reduce performance, as your requests will be delayed until sufficient cover traffic is available.
  63 The specific numeric value (for anonymity levels above 1) is simple:
  64 Given an anonymity level L (above 1), each request FS makes on your behalf must be hidden in L-1 equivalent requests of cover traffic (traffic your peer routes for others) in the same time-period.
  65 The time-period is twice the average delay by which GNUnet artificially delays traffic.
  66 Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1.
  67 .It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
  68 Use the configuration file
  69 .Ar FILENAME
  70 (default:
  71 .Pa ~/.config/gnunet.conf )
  72 .It Fl h | \-help
  73 Print the help page.
  74 .It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
  75 Change the loglevel.
  76 Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG.
  77 .It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
  78 Write logs to
  79 .Ar FILENAME .
  80 .It Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
  81 Writes a GNUnet directory containing all of the search results to
  82 .Ar FILENAME .
  83 .It Fl n | \-no-network
  84 Only search locally, do not forward requests to other peers.
  85 .It Fl N Ar VALUE | Fl \-results= Ns Ar VALUE
  86 Automatically terminate the search after receiving
  87 .Ar VALUE
  88 results.
  89 .It Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
  90 Automatically timeout search after
  91 .Ar DELAY .
  92 The value given must be a number followed by a space and a time unit, for example "500 ms".
  93 Note that the quotes are required on the shell.
  94 Otherwise the search runs until gnunet-search is aborted with CTRL\-C.
  95 .It Fl v | \-version
  96 print the version number
  97 .It Fl V | \-verbose
  98 print meta data from search results as well
  99 .El
 100 You can run gnunet-search with an URI instead of a keyword.
 101 The URI can have the format for a namespace search or for a keyword search.
 102 For a namespace search, the format is
 103 .Pp
 104 .Dl gnunet://fs/sks/NAMESPACE/IDENTIFIER
 105 .Pp
 106 For a keyword search, use
 107 .Pp
 108 .Dl gnunet://fs/ksk/KEYWORD[+KEYWORD]*
 109 .Pp
 110 If the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly.
 111 .sp
 112 If multiple keywords are passed, gnunet-search will look for content matching any of the keywords.
 113 The prefix "+" makes a keyword mandatory.
 114 .Sh FILES
 115 .Pa ~/.config/gnunet.conf
 116 GNUnet configuration file; specifies the default value for the timeout
 117 .Sh EXAMPLES
 118 .Dl $ gnunet-search "Das Kapital"
 119 .Pp
 120 Searches for content matching the keyword "Das Kapital".
 121 .Pp
 122 .Dl $ gnunet-search +Das +Kapital
 123 .Pp
 124 Searches for content matching both mandatory keywords "Das" and "Kapital".
 125 .sp
 126 Search results are printed by gnunet-search like this:
 127 .Pp
 128 .ad l
 129         gnunet-download -o "COPYING" gnunet://fs/chk/HASH1.HASH2.SIZE
 130
 131                 Description: The GNU General Public License
 132
 133                 Mime-type: text/plain
 134 .ad b
 135
 136 The first line contains the command to run to download the file.
 137 The suggested filename in the example is COPYING.
 138 The GNUnet URI consists of the key and query hash of the file and finally the size of the file.
 139 After the command to download the file, GNUnet will print meta-data about the file as advertised in the search result.
 140 The meta-data here is the description ("The GNU General Public License") and the mime-type ("text-plain").
 141 See the options for
 142 .Xr gnunet-publish 1
 143 on how to supply meta-data by hand.
 144 .Sh SEE ALSO
 145 .Xr gnunet-download 1 ,
 146 .Xr gnunet-fs-gtk 1 ,
 147 .Xr gnunet-publish 1 ,
 148 .Xr gnunet.conf 5
 149 .sp
 150 The full documentation for gnunet is maintained as a Texinfo manual.
 151 If the
 152 .Xr info 1
 153 and gnunet programs are properly installed at your site, the command
 154 .Pp
 155 .Dl info gnunet
 156 .Pp
 157 should give you access to the complete handbook,
 158 .Pp
 159 .Dl info gnunet-c-tutorial
 160 .Pp
 161 will give you access to a tutorial for developers.
 162 .sp
 163 Depending on your installation, this information is also available in
 164 .Xr gnunet 7 and
 165 .Xr gnunet-c-tutorial 7 .
 166 .\".Sh HISTORY
 167 .\"gnunet-search first appeared in GNUnet 0.9.6.
 168 .\".Sh AUTHORS
 169 .Sh BUGS
 170 Report bugs by using
 171 .Lk https://bugs.gnunet.org
 172 or by sending electronic mail to
 173 .Aq Mt gnunet-developers@gnu.org .