GTK-GNUTELLA(1)

📦
version 1.3.1 · 3 versions
, in fedora 43, fedora 44, nixos 26.05

💖 GTK-GNUTELLA 💖

okay bestie, sit down, grab a boba 🧋 — this is the manual page for gtk-gnutella, version 1.2.0, section 1 of the manual. it's giving classic Unix manpage but make it cute. no cap, every single flag is in here, so read the whole thing 💅

✨ NAME ✨

gtk-gnutella — a Gnutella client for Gtk+ 🦋

✨ SYNOPSIS ✨

gtk-gnutella

✨ DESCRIPTION ✨

so gtk-gnutella is a GTK+ Gnutella client for Unix. she supports both searching and sharing with the 0.6 version of the Gnutella protocol, and on top of that she's got support for a whole bunch of protocol improvements and additions that got bolted onto the Gnutella network after that. iconic behaviour honestly 👑

the Gnutella network lets users search for files and advertise files shared locally, but here's the tea — it is not handling file transfers, that part is done through HTTP. the addition of Gnutella-specific HTTP headers makes each Gnutella client a powerful file swarmer where even firewalled hosts can contribute. literally everyone eats 🔥

and like, great care has been devoted into making gtk-gnutella powerful, efficient and reliable. she did that. periodt.

✨ OPTIONS ✨

first things first: all the options can be abbreviated, as long as the name you supply is not ambiguous. slay 🎀

  • --cleanup — for developers mostly: this requests a final memory cleanup sequence at exit time, in an attempt to be able to spot memory leaks by looking at all the remaining allocated blocks, letting the developers figure out, perhaps, why they were not cleaned up properly. detective mode fr 🔍
  • --compile-info — tells gtk-gnutella to output a list of variables describing the compile-time configuration information that was gathered when the program was built.
  • --daemonize — this option causes gtk-gnutella to become a daemon. she detaches from the terminal (if started from one) and forks herself into the background. she also changes her working directory to the root directory, i.e. "/", so that she doesn't block a mount point for example. this is mainly meant for headless mode, but you can also use it if the Gtk+ GUI is enabled.

for example, if you do not start gtk-gnutella from a terminal but from a window manager menu, there's little reason to not daemonize gtk-gnutella. thus you might want to add the --daemonize option in this case.

⚠️ please note that when gtk-gnutella is started as a daemon, all output which is normally sent to the standard output and standard error output (usually your terminal or a common log file such as ~/.xsession-errors) is sent to /dev/null. the options --log-stderr and --log-stdout can be used to redirect log output in this case. so like, don't be surprised when your logs ghost you 👻
  • --exec-on-crash path — execute the command specified in path when gtk-gnutella crashes. 💀
  • --geometry — this option can be used to force the main window of the GUI to a certain location on your screen and/or give it certain dimensions.

for example, the following would position the window in the lower right corner with a width of 800 pixels and a height of 600 pixels:

gtk-gnutella --geometry 800x600-0-0
note that none of this can be guaranteed — your window manager has the last word on this. it's a traditional command-line switch supported by most X11 applications, so it's giving old-school 🫶
  • --help — show a summary of all supported options. your bestie when you're lost 🙈
  • --log-stderr, --log-stdout — these options allow you to log everything which is written to stderr respectively stdout to some files. a typical use would look like this:
   gtk-gnutella --daemonize  \
        --log-stderr ~/logs/gtkg.stderr \
        --log-stdout ~/logs/gtkg.stdout

redirecting these log messages also works without --daemonize. of course, log files can become large and you might want to archive them or delete them periodically. after moving or deleting the log files, you can send gtk-gnutella a SIGHUP signal to create new log files. ✨

  • --log-supervise — redirects the logs for the supervisor process.
  • --minimized — launches gtk-gnutella with a minimized main window. recommended when starting gtk-gnutella in the background on login. lowkey respectful of your screen real estate 🌸
  • --no-dbus — disable notifications of gtk-gnutella events to D-BUS.
  • --no-expire — disable GUI popups when gtk-gnutella has expired. this is not the default behaviour because we wish to keep the network healthy by having recent versions running, but at the same time we understand not everyone can or wants to upgrade in a timely manner. no pressure bestie 💜
  • --no-restart — prevents gtk-gnutella from auto-restarting itself when crashing on a platform where core dumps are not possible or disabled.
  • --no-supervise — prevents gtk-gnutella from starting a supervising process that will monitor the main process and automatically restart a new instance when the previous one exits abnormally.
  • --no-xshm — disable the MIT shared memory extension, when running with the X graphical user-interface.
  • --pause-on-crash — pause the process on crash, so that a debugger may be attached to inspect the current state for instance. hit the pause button, bestie ⏸️
  • --ping — this option allows you to check whether gtk-gnutella is currently running. it returns with a success code when gtk-gnutella is already running, and with a failure code when it is not.

this allows you to use the following code to start gtk-gnutella from a cron job or window manager menu and avoid starting it twice:

gtk-gnutella --ping || gtk-gnutella
  • --restart-on-crash — asks gtk-gnutella to auto-restart itself after crashing on a platform where core dumps are allowed.

regardless of core dumping options, --no-restart will always prevent a restart whilst --restart-on-crash will always request one if possible. it is not allowed to supply both options at the same time. pick a lane 🚫

  • --resume-session — requests that the previous session be continued. this means that searches launched for the duration of the session only will not expire, that seeded files will continue to be seeded, and that all the other aspects persisted during the previous session will be restored (current tab for instance). we love a comeback queen 👑
  • --shell — when this option is used to connect to an already running gtk-gnutella process over a local unix domain socket. this socket is located at "$GTK_GNUTELLA_DIR/ipc/socket", thus normally "~/.gtk-gnutella/ipc/socket". the socket is only accessible by the user running gtk-gnutella, which is enforced by filesystem permissions. the socket is in a dedicated directory because apparently not all systems honor the access permissions on sockets as seen through the filesystem.

you can disable this feature by setting the property "enable_local_socket" to FALSE. it is recommendable to use this local socket whenever possible instead of the TCP socket to access the shell interface remotely. the reason is that the authentication token is passed non-encrypted over the network and everyone who can sniff the network is able to connect to the remote shell.

🚨 this may not matter over the loopback interface or a LAN, but it's a bad idea to use this over the Internet. fr fr, don't do it.
  • --topless — starts gtk-gnutella without the graphical user-interface. (yes that's the real name. iconic.) 💅
  • --use-poll — for developers mostly: this requests that I/O polling be done exclusively through the poll() interface instead of the more modern and efficient epoll() or kqueue() system calls.
  • --version — show the user-agent string used on the Gnutella network, which also holds the version information. 🎀

🌈 GETTING STARTED 🌈

when gtk-gnutella is first started, she will attempt to connect to a well-known hosts server for some hosts to connect to. if you know a host you want to connect to, you can enter it in the box on the GnutellaNet tab and push the Add button. when first connecting to the Gnutella network, it can take some time to establish a stable connection. be patient bestie, good things take a sec 🧚

🔍 SEARCHING 🔍

to search files, just type your query in the search box at the top of the screen. all searches, both active and inactive, are shown in the sidebar.

you can have multiple searches running at once. to start another search while the first one is running, simply enter another search term into the edit box at the top of the window. multitasking queen 👑

to stop a particular search and remove its tab from the search window, select the search by clicking on its tab and click the "Close search" button. if you want to clear the list for a particular search but want to continue to see new files that are received for this search, click the "Clear results" button.

it is possible to apply filtering to search results using the filter editor. click on "Edit filters" to access the editor. use of the filtering editor goes beyond the scope of this man page, but there is a tutorial on this topic on the gtk-gnutella homepage.

when you find a file that you want to download, select the file in the list and click "Download selected". this file will be placed in the download queue. on the downloads view you can watch the download progress of the file(s) you are downloading.

it is also possible to select a bunch of files for downloading at once. by holding down the control or shift keys while clicking files, you can select several files and then click "Download selected" to put them all in the download queue at once. bulk behaviour, we love it ✨

🎀 CONFIGURATION 🎀

most of the configuration can be done via the "Preferences" window, which can be accessed using the "File -> Preferences" menu-option. you will find several tabs there, each tab regrouping common information. but some specific information pertaining to downloads or searches is directly available on the "Downloads" and "Uploads" panes.

if you linger your mouse over each configuration parameter, a tooltip window will popup explaining the meaning of that parameter. you may have to press "Enter" after a text input, or move the focus to another parameter to validate your entry. items configured via spin buttons normally take effect immediately, unless you type text instead of using the spin buttons. 🦋

📁 FILES 💖

okay bestie, this is where all ur stuff lives. every single one of these is inside $GTK_GNUTELLA_DIR — that's the home base, the main character directory 💅

  • $GTK_GNUTELLA_DIR/config_gnet — the per-user config file for core settings. you can hand-edit this while the program isn't running, but honestly? just use the GUI to change config vars, it's so much nicer. gtk-gnutella rewrites this file every single time the program exits normally, so any sneaky edits you made get overwritten. no cap.
  • $GTK_GNUTELLA_DIR/config_gui — the GUI configuration. bestie, please do not edit this one. it's best to just leave it alone fr fr.
  • $GTK_GNUTELLA_DIR/dmesh — this is where the download mesh gets persisted. you literally don't need to worry about this one, it's not ur business 🙈
  • $GTK_GNUTELLA_DIR/dmesh_ban — where the temporarily banned download mesh entries are stored. the naughty corner, basically 😭
  • $GTK_GNUTELLA_DIR/done.namesize — holds the name and size of files that got completely downloaded by gtk-gnutella and which will now be ignored.
  • $GTK_GNUTELLA_DIR/done.sha1 — holds the SHA1 of files completely downloaded by gtk-gnutella that will now be ignored. same energy, different hash ✨
  • $GTK_GNUTELLA_DIR/downloads — this is where the download queue is persisted. lowkey important detail: only the direct downloads (i.e. non-pushed ones) can be saved, since they don't need routing information.
  • $GTK_GNUTELLA_DIR/hosts — the host cache. gtk-gnutella saves this on exit and you should not edit it by hand. hands off, bestie 🙅
  • $GTK_GNUTELLA_DIR/searches.xml — where the open searches and all the search filters get saved. ur whole search history vibe, preserved 🌸
  • $GTK_GNUTELLA_DIR/sha1_cache — where the cache of all the computed SHA1 lives.
  • $GTK_GNUTELLA_DIR/tth_cache — the directory under which all the computed TTH trees are stored. heads up: these files are binary data, so don't go opening them in a text editor expecting cute little words, okay? 💀
  • $GTK_GNUTELLA_DIR/upload_stats — this file keeps track of the upload statistics. the receipts, basically 📊

🌈 ENVIRONMENT 🌈

gtk-gnutella goes looking for configuration files in GTK_GNUTELLA_DIR. if that variable isn't set, it uses HOME instead. and if HOME isn't set either? then no configuration information will be saved when gtk-gnutella exits. like, nothing. gone. the void. so maybe set ur env vars, bestie 😭

💌 MAILING LISTS 💌

there are a couple of mailing lists for gtk-gnutella. see http://sourceforge.net/mail/?group_id=4467 for more info. come hang out, the group chat is open 🫶

💀 BUGS 💀

gtk-gnutella is production-quality software, bestie — it's iconic, it ate — but it still has minor bugs and incomplete or missing features. but honestly, which software doesn't, for its authors? 😌

there are probably other missing features that should be listed here. (yes, the manpage is self-aware. we love a humble queen.)

a list of known bugs might be available at the gtk-gnutella web site (see below).

👀 SEE ALSO 👀

additional info about gtk-gnutella and the latest version are available at http://gtk-gnutella.sourceforge.net/

additional info about gnutella is available at http://www.the-gdf.org/ http://www.infoanarchy.org/en/Gnutella http://rfc-gnutella.sourceforge.net/

👑 AUTHORS 👑

Yann Grossel wrote the original gtk-gnutella, which was running as a Gnutella 0.4 client in 2000. an OG, a legend, the blueprint fr fr ✨

Raphael Manfredi <Raphael_Manfredi@pobox.com> is the current maintainer and project leader (since version 0.14, released early September 2001). for support, please contact the developer list, which can be reached at <gtk-gnutella-devel@lists.sourceforge.net>.

for a full list of contributors, open the "About" menu. (yes, go click it, they deserve the recognition 💅)

Brian St. Pierre <bstpierre@bstpierre.org> wrote the initial version of this manpage. thank u brian, the documentation would simply not exist without u 🫶

gtk-gnutella is Copyright (c) 2000, Yann Grossel, with additional copyrights held by other contributors 2000-2020

license to use and copy gtk-gnutella is given under the terms of the GNU General Public License (GPL), version 2. please see the file COPYING in the distribution for complete information.

this manual page can also be redistributed under the same conditions as gtk-gnutella itself.

and that's the whole page, bestie 💖 this is Version from July 2020, section GTK-GNUTELLA(1) — the manual page, the moment, the icon. now go download something and slay 💅✨🦋

📦 where this page comes from