GNUNET-SEARCH(1)

GNUNET-SEARCH 💅✨

okay bestie, listen. this is the gnunet-search page from section 1 of the General Commands Manual — like, the actual manual page, not some random blog. sit down, grab a strawberry 🍓, we're doing this.

---

✨ NAME ✨

gnunet-search — a command line interface to search for content on GNUnet 🦋

---

🌸 SYNOPSIS 🌸

gnunet-search [-a LEVEL | --anonymity=LEVEL] [-b | --bookmark-only]
              [-c FILENAME | --config=FILENAME]
              [-F FORMAT | --dir-printf=FORMAT]
              [-f FORMAT | --printf=FORMAT] [-h | --help]
              [-i FORMAT | --iter-printf=FORMAT]
              [-L LOGLEVEL | --loglevel=LOGLEVEL]
              [-l FILENAME | --logfile=FILENAME]
              [-o FILENAME | --output=FILENAME] [-n | --no-network]
              [-N VALUE | --results=VALUE] [-s | --silent]
              [-t DELAY | --timeout=DELAY] [-v | --version]
              [-V | --verbose] ⟨KEYWORD⟩ ⟨+KEYWORD⟩ | ⟨URI⟩ ⟨+URI⟩

---

💖 DESCRIPTION 💖

so the whole point of this girl is: search for content on GNUnet. that's it, that's the job. 🫶

⚠️ the keywords are case-sensitive. yes fr fr, capital letters matter, do not come crying to me.

gnunet-search can be used both for a search in the global namespace as well as for searching a private subspace. iconic duality tbh. the options are as follows:

👑 OPTIONS 👑

• -a LEVEL, --anonymity=LEVEL — this one can be used to specify additional anonymity constraints, and the default is 1. if you set it to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key 🔑. this will allow other users to download the file as fast as possible, including using non-anonymous methods (discovery via DHT and CADET transfer). if you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). however — and this is the part you need to hear — a powerful adversary may still be able to perform traffic analysis (statistics) to over time discovery your identity 😭. you can gain better privacy by specifying a higher level of anonymity (using values above 1). this tells FS that it must hide your own requests in equivalent-looking cover traffic. this should confound an adversaries traffic analysis, increasing the time and effort it would take to discover your identity. but also?? it can significantly reduce performance, as your requests will be delayed until sufficient cover traffic is available 🐌. the specific numeric value (for anonymity levels above 1) is simple: 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. the time-period is twice the average delay by which GNUnet artificially delays traffic ⏳. note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1.
• -b, --bookmark-only — do not search, print only the URI that points to the search with the given keywords 🔖.
• -c FILENAME, --config=FILENAME — use the configuration file FILENAME (default: ~/.config/gnunet.conf).
• -F FORMAT, --dir-printf=FORMAT — write the search results for directories according to FORMAT. the directives supported here are identical to those supported in the --printf argument (please refer to it for more information, bestie, it's right there). if missing, --dir-printf defaults to --printf. if --printf is missing too, --dir-printf defaults to ‘#%n:\ngnunet-download -o "%f" -R %u\n\n’ 💖.
• -f FORMAT, --printf=FORMAT — write the search results according to FORMAT, in which ‘\’ and ‘%’ directives are interpreted as follows:
  • \\ — a literal backslash (‘\’)
  • \a — an alarm bell 🔔
  • \b — a backspace
  • \e — an escape
  • \f — a form feed
  • \n — a newline
  • \r — a carriage return
  • \t — a horizontal tab
  • \v — a vertical tab
  • \0 — an ASCII NUL.
  • \N... — the character whose ASCII code is N..., expressed in octal digits
  • \xX... — the character whose ASCII code is X..., expressed in hexadecimal digits

note: the ‘\’ character followed by any other character not listed above is treated as an ordinary character, so both characters are printed. no magic, no drama.

• %% — a percent sign
• %a — the complete list of all the printable metadata properties available, displayed according to the --iter-printf argument; this specifier optionally supports metatype filtering via hash sign (e.g. ‘%2#a’ prints all embedded file names, if present — see libextractor's metatypes for the complete list of numerical identifiers) 🌈
• %f — the file's name
• %j — the first printable metadata property available, displayed according to the --iter-printf argument; this specifier optionally supports metatype filtering via hash sign (e.g. ‘%5#j’ prints a book title, if present); see libextractor's metatypes for the complete list of numerical identifiers)
• %l — the file name's length
• %m — the file's mime type
• %n — the search result number
• %s — the file's size in bytes
• %u — the file's URI

note: the ‘%’ character followed by any other character not listed above is treated as an ordinary character, so both characters are printed. same energy, different sigil 💅

if missing, --printf defaults to ‘#%n:\ngnunet-download -o "%f" %u\n\n’.

• -h, --help — print the help page 🫶.
• -i FORMAT, --iter-printf=FORMAT — when the ‘%a’ or ‘%j’ format specifiers appear in --printf or --dir-printf, list each metadata property according to FORMAT, in which the ‘\’ directives are interpreted as in --printf and --dir-printf, while the ‘%’ directives are interpreted as follows:
  • %% — a percent sign
  • %p — the property's content
  • %l — the property content's length in bytes
  • %i — the property type's unique identifier
  • %n — the property number
  • %t — the property type (available only if compiled with libextractor)
  • %w — the name of the plugin that provided the information

note: the ‘%’ character followed by any other character not listed above is treated as an ordinary character, so both characters are printed. yes, again. consistent queen ✨

if missing, --iter-printf defaults to ‘ %t: %p\n’ or ‘ MetaType #%i: %p\n’, depending on whether the program was compiled with libextractor or not 👀.

• -L LOGLEVEL, --loglevel=LOGLEVEL — change the loglevel. possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG.
• -l FILENAME, --logfile=FILENAME — write logs to FILENAME 📝.
• -o FILENAME, --output=FILENAME — writes a GNUnet directory containing all of the search results to FILENAME (e.g. ‘gnunet-search --output=commons.gnd commons’) 📁.
• -n, --no-network — only search locally, do not forward requests to other peers. introvert mode, valid 🏠.
• -N VALUE, --results=VALUE — automatically terminate the search after receiving VALUE results 🔢.
• -s, --silent — enable silent mode and do not print any result (the --output argument is required) 🤫.
• -t DELAY, --timeout=DELAY — automatically timeout search after DELAY. the value given must be a number followed by a space and a time unit, for example "500 ms". note that the quotes are required on the shell 🐚. without a unit it defaults to microseconds (1000000 = 1 second). if 0 or omitted the search runs until gnunet-search is aborted with CTRL-C ⌨️.
• -v, --version — print the version number.
• -V, --verbose — append ‘%a\n’ to the default --printf and --dir-printf arguments — ignored when these are provided by the user. so it only does anything if you didn't already pick your own format, iykyk 💜

---

🦋 uris vs keywords, bestie 🦋

it is possible to run gnunet-search with an URI instead of a keyword. the URI can have the format for a namespace search or for a keyword search. for a namespace search, the format is

gnunet://fs/sks/NAMESPACE/IDENTIFIER

for a keyword search, use

gnunet://fs/ksk/KEYWORD[+KEYWORD]*

if the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly. no cap, it just figures it out 🙈

if multiple keywords are passed, gnunet-search will look for content matching any of the keywords. the ‘+’ prefix makes a keyword mandatory 🔥

---

🎀 FILES 🎀

• ~/.config/gnunet.conf — GNUnet configuration file; specifies the default value for the timeout.

✨ EXAMPLES ✨

Okay bestie, let's get into the actual examples because this is where gnunet-search really shows off its main character energy. 💅

🌸 Example 1 🌸

$ gnunet-search 'Das Kapital'

This one searches for content that matches the keyword “Das Kapital” — like, the whole phrase as one keyword. Iconic. ✨

🌸 Example 2 🌸

$ gnunet-search Das Kapital

No quotes this time, so it searches for content matching either the keyword “Das” or the keyword “Kapital”. It's giving OR energy. 🔥

🌸 Example 3 🌸

$ gnunet-search +Das +Kapital

The plus signs make both keywords mandatory, so it searches for content matching both “Das” and “Kapital”. It's giving AND energy, periodt. 👑

---

Now, search results are printed by gnunet-search like this:

gnunet-download -o "COPYING" gnunet://fs/chk/HASH1.HASH2.SIZE

  Description: The GNU General Public License
  Mime-type: text/plain
  ...

The first line is literally the command you run to download the file. The suggested filename in this example is ‘COPYING’. The GNUnet URI is made up of the key and query hash of the file and finally the size of the file. If you passed the --verbose option, then after the download command, GNUnet will print metadata about the file as advertised in the search result. In this example the metadata is the description (“The GNU General Public License”) and the mime-type (“text-plain”). For how to supply metadata by hand, go peek at the options for gnunet-publish(1). 👑

The --printf (-f), --dir-printf (-F) and --iter-printf (-i) arguments are these powerful tools for manipulating the output printed. For instance…

🌟 Example 4 🌟

$ gnunet-search -f '%f (%s bytes)\n' commons

This will print a simple list of the results that match the “commons” keyword, with only the file name and the size printed, without any URI. So clean, so minimal, we love. ✨

Or, for instance…

🌟 Example 5 🌟

#!/bin/sh
{
  printf '<list>'
  gnunet-search -f '
  <file uri="%u">
    <filename len="%l">%f</filename>
    <size>%s</size>
    <mimetype>%m</mimetype>
    <result_id>%n</result_id>
    <metadata>%a
    </metadata>
  </file>' \
    -i '
      <property tid="%i" type="%t">
        <content len="%l">%p</content>
        <property_id>%n</property_id>
        <provided_by>%w</provided_by>
      </property>' \
    -t '2 s' commons
  printf '\n</list>\n'
} > commons.xml

This will run for two seconds and then create a file named commons.xml, containing the search results that match the “commons” keyword in XML format. It's giving structured data realness. 💖

👀 SEE ALSO 👀

Okay so you're gonna wanna check out these other pages, bestie, because they're all connected in the GNUnet cinematic universe:

• gnunet-download(1)
• gnunet-fs-gtk(1)
• gnunet-publish(1)
• gnunet.conf(5)

The full documentation for GNUnet is maintained as a Texinfo manual. If the info(1) and gnunet packages are properly installed at your site, the command

info gnunet

should give you access to the complete handbook. And

info gnunet-c-tutorial

will give you access to a tutorial for developers. Depending on your installation, this information is also available in gnunet(7) and gnunet-c-tutorial(7). Slay. 📚✨

🐛 BUGS 🐛

Found a bug? Don't be shy, report it by using https://bugs.gnunet.org or by sending electronic mail to ⟨gnunet-developers@gnu.org⟩. They'll appreciate it, fr fr. 💌

---

Okay bestie, that's the whole vibe. This page is from the Debian package, dated February 12, 2022, and it's for GNUNET-SEARCH(1). Now go search something iconic. 🫶💖