1GTK-GNUTELLA(1)                      1.2.0                     GTK-GNUTELLA(1)
2
3
4

NAME

6       gtk-gnutella - A Gnutella client for Gtk+
7

SYNOPSIS

9       gtk-gnutella
10

DESCRIPTION

12       gtk-gnutella  is  a  GTK+  Gnutella  client  for Unix. It supports both
13       searching and sharing with the 0.6 version of the Gnutella protocol and
14       includes  support for numerous protocol improvements and additions that
15       have been added to the Gnutella network since.
16
17       The Gnutella network allows users to search for files and to  advertise
18       files  shared locally, but is not handling file transfers which is done
19       through HTTP.  The addition of  Gnutella-specific  HTTP  headers  makes
20       each  Gnutella  client  a  powerful  file swarmer where even firewalled
21       hosts can contribute.
22
23       Great care has been devoted into making  gtk-gnutella  powerful,  effi‐
24       cient and reliable.
25

OPTIONS

27       All  the options can be abbreviated as long as the supplied name is not
28       ambiguous.
29
30       --cleanup
31              For developers mostly: this requests a final memory cleanup  se‐
32              quence  at  exit  time  in  an attempt to be able to spot memory
33              leaks by looking at all the remaining allocated blocks,  letting
34              the  developpers  figuring  out,  perhaps,  why  they  were  not
35              cleaned-up properly.
36
37       --compile-info
38              Tell gtk-gnutella to output a list of variables describing  com‐
39              pile-time  configuration  information that was gathered when the
40              program was built.
41
42       --daemonize
43              This options causes gtk-gnutella to become a daemon. It detaches
44              from  the  terminal  (if started from one) and forks itself into
45              the background. It also changes it working directory to the root
46              directory  i.e.,  "/" so that it doesn't block a mount point for
47              example. This is mainly meant for headless mode but you can also
48              use it if the Gtk+ GUI is enabled.
49
50              For  example,  if  you do not start gtk-gnutella from a terminal
51              but from a window manager menu, there's  little  reason  to  not
52              daemonize  gtk-gnutella. Thus you might want to add the --daemo‐
53              nize option in this case.
54
55              Please note that when gtk-gnutella is started as  a  daemon  all
56              output  which  is normally send to the standard output and stan‐
57              dard error output (usually your terminal or a  common  log  file
58              such  as  ~/.xsession-errors), is sent to /dev/null. The options
59              --log-stderr and --log-stdout can be used to redirect log output
60              in this case.
61
62       --exec-on-crash path
63              Execute command specified in path when gtk-gnutella crashes.
64
65       --geometry
66              This option can be used to force the main window of the GUI to a
67              certain location on your screen and/or give  it  certain  dimen‐
68              sions.
69
70              For  example,  the  following  would  position the window in the
71              lower right corner with a width of 800 pixels and  a  height  of
72              600 pixels:
73
74                  gtk-gnutella --geometry 800x600-0-0
75
76              Note  that  none  of this can be guaranteed, your window manager
77              has the last word on this. This option is a traditional command-
78              line switch supported by most X11 applications.
79
80       --help Show a summary of all supported options.
81
82       --log-stderr , --log-stdout
83              These  options  allow  you to log everything which is written to
84              stderr respectively stdout to some files. A  typical  use  would
85              look like this:
86
87                 gtk-gnutella --daemonize  \
88                      --log-stderr ~/logs/gtkg.stderr \
89                      --log-stdout ~/logs/gtkg.stdout
90
91              Redirecting  these  log messages also works without --daemonize.
92              Of course, log files can become large and you might want to  ar‐
93              chive them or delete them periodically. After moving or deleting
94              the log files, you can send gtk-gnutella a SIGHUP signal to cre‐
95              ate new log files.
96
97       --log-supervise
98              Redirects the logs for the supervisor process.
99
100       --minimized
101              Launches  gtk-gnutella with a minimized main window. Recommended
102              when starting gtk-gnutella in the background on login.
103
104       --no-dbus
105              Disable notifications of gtk-gnutella events to D-BUS.
106
107       --no-expire
108              Disable GUI popups when gtk-gnutella has expired.  This  is  not
109              the  default  behaviour  because  we  wish  to  keep the network
110              healthy by having recent versions running, but at the same  time
111              we  understand  not everyone can or wants to upgrade in a timely
112              manner.
113
114       --no-restart
115              Prevents gtk-gnutella from auto-restarting itself when  crashing
116              on a platform where core dumps are not possible or disabled.
117
118       --no-supervise
119              Prevents  gtk-gnutella  from starting a supervising process that
120              will monitor the main process and automatically  restart  a  new
121              instance when the previous one exits abnormally.
122
123       --no-xshm
124              Disable  MIT  shared  memory  extension, when running with the X
125              graphical user-interface.
126
127       --pause-on-crash
128              Pause the process on crash, so that a debugger may  be  attached
129              to inspect the current state for instance.
130
131       --ping This  option  allows  you  to check whether gtk-gnutella is cur‐
132              rently running. This option returns with  a  success  code  when
133              gtk-gnutella is already running, and with a failure code when it
134              is not.
135
136              This allows you to use the following code to start  gtk-gnutella
137              from  a  cron  job  or window manager menu and avoid starting it
138              twice:
139
140                  gtk-gnutella --ping || gtk-gnutella
141
142       --restart-on-crash
143              Asks gtk-gnutella to auto-restart itself  after  crashing  on  a
144              platform where core dumps are allowed.
145
146              Regardless  of  core  dumping  options, --no-restart will always
147              prevent a restart whilst --restart-on-crash will always  request
148              one  if  possible.   It is not allowed to supply both options at
149              the same time.
150
151       --resume-session
152              Requests that the previous session  be  continued.   This  means
153              that searches launched for the duration of the session only will
154              not expire, that seeded files will continue to  be  seeded,  and
155              that all the other aspects persisted during the previous session
156              will be restored (current tab for instance).
157
158       --shell
159              When this option is  used  to  connect  to  an  already  running
160              gtk-gnutella  process  over  a  local  unix  domain socket. This
161              socket is located at "$GTK_GNUTELLA_DIR/ipc/socket",  thus  nor‐
162              mally  "~/.gtk-gnutella/ipc/socket". The socket is only accessi‐
163              ble by the  user  running  gtk-gnutella  which  is  enforced  by
164              filesystem  permissions.  The socket is in a dedicated directory
165              because apparently not all systems honor the access  permissions
166              on sockets as seen through the filesystem.
167
168              You can disable this feature by setting the property "enable_lo‐
169              cal_socket" to FALSE. It is  recommendable  to  use  this  local
170              socket whenever possible instead of the TCP socket to access the
171              shell interface remotely. The reason is that the  authentication
172              token  is passed non-encrypted over the network and everyone who
173              can sniff the network is able to connect to  the  remote  shell.
174              This  may  not  matter over the loopback interface or a LAN, but
175              it's a bad idea to use this over the Internet.
176
177       --topless
178              Starts gtk-gnutella without the graphical user-interface.
179
180       --use-poll
181              For developers mostly: this requests that I/O  polling  be  done
182              exclusively  through the poll() interface instead of more modern
183              and efficient epoll() or kqueue() system calls.
184
185       --version
186              Show the user-agent string used on the  Gnutella  network  which
187              also holds the version information.
188

GETTING STARTED

190       When  gtk-gnutella  is  first  started, it will attempt to connect to a
191       well-known hosts server for some hosts to connect to.  If  you  know  a
192       host you want to connect to, you can enter it in the box on the Gnutel‐
193       laNet tab and push  the  Add  button.  When  first  connecting  to  the
194       gnutella  network,  it can take some time to establish a stable connec‐
195       tion. Be patient.
196

SEARCHING

198       To search files just type your query in the search box at  the  top  of
199       the  screen.  All  searches, both active and inactive, are shown in the
200       sidebar.
201
202       You can have multiple searches running at once. To start another search
203       while  the  first one is running, simply enter another search term into
204       the edit box at the top of the window.
205
206       To stop a particular search and remove its tab from the search  window,
207       select  the  search by clicking on its tab and click the "Close search"
208       button. If you want to clear the list for a particular search, but want
209       to  continue  to see new files that are received for this search, click
210       the "Clear results" button.
211
212       It is possible to apply filtering to search results  using  the  filter
213       editor.  Click  on "Edit filters" to access the editor. Use of the fil‐
214       tering editor goes beyond the scope of this man page, but  there  is  a
215       tutorial on this topic on the gtk-gnutella homepage.
216
217       When  you find a file that you want to download, select the file in the
218       list and click "Download selected". This file will  be  placed  in  the
219       download  queue.  On  the  downloads  view  you  can watch the download
220       progress of the file(s) you are downloading.
221
222       It is also possible to select a bunch of files for downloading at once.
223       By holding down the control or shift keys while clicking files, you can
224       select several files and then click "Download selected" to put them all
225       in the download queue at once.
226

CONFIGURATION

228       Most of the configuration can be done via the "Preferences" window that
229       can be accesed using the "File -> Preferences" menu-option.   You  will
230       find  several  tabs there, each tab regrouping common information.  But
231       some specific information pertaining to downloads or searches  are  di‐
232       rectly available on the "Downloads" and "Uploads" panes.
233
234       If  you  linger your mouse over each configuration parameter, a tooltip
235       window will popup explaining the meaning of that  parameter.   You  may
236       have  to press "Enter" after a text input, or move the focus to another
237       parameter to validate your entry.  Items configured  via  spin  buttons
238       normally take effect immediately, unless you type text instead of using
239       the spin buttons.
240

FILES

242       $GTK_GNUTELLA_DIR/config_gnet
243              Per-user configuration file, for  core  settings.  This  can  be
244              edited  when  the  program is not running, but it is best to use
245              the GUI to change configuration variables.   gtk-gnutella  saves
246              this file every time the program is exited normally.
247
248       $GTK_GNUTELLA_DIR/config_gui
249              GUI configuration.  It is best to not edit this file.
250
251       $GTK_GNUTELLA_DIR/dmesh
252              This is where the download mesh is persisted.  You don't need to
253              worry about this.
254
255       $GTK_GNUTELLA_DIR/dmesh_ban
256              This is where  temporarily  banned  download  mesh  entries  are
257              stored.
258
259       $GTK_GNUTELLA_DIR/done.namesize
260              This file holds the name and size of files completely downloaded
261              by gtk-gnutella and which will now be ignored.
262
263       $GTK_GNUTELLA_DIR/done.sha1
264              This file holds the  SHA1  of  files  completely  downloaded  by
265              gtk-gnutella and which will now be ignored.
266
267       $GTK_GNUTELLA_DIR/downloads
268              This  is where the download queue is persisted.  Only the direct
269              downloads (i.e. non-pushed) can be saved, since they don't  need
270              routing information.
271
272       $GTK_GNUTELLA_DIR/hosts
273              This  is  the  host cache. This is saved by gtk-gnutella on exit
274              and should not be edited by hand.
275
276       $GTK_GNUTELLA_DIR/searches.xml
277              This is where the open searches and all the search  filters  are
278              saved.
279
280       $GTK_GNUTELLA_DIR/sha1_cache
281              This is where the cache of all the computed SHA1 is stored.
282
283       $GTK_GNUTELLA_DIR/tth_cache
284              This is the directory under which all the computed TTH trees are
285              stored.  These files are binary data.
286
287       $GTK_GNUTELLA_DIR/upload_stats
288              This file keeps track of the upload statistics.
289

ENVIRONMENT

291       gtk-gnutella searches GTK_GNUTELLA_DIR for configuration files. If this
292       variable  is not set, HOME is used instead. If HOME is not set, then no
293       configuration information will be saved when gtk-gnutella exits.
294

MAILING LISTS

296       There  are  a  couple  of  mailing   lists   for   gtk-gnutella.    See
297       http://sourceforge.net/mail/?group_id=4467 for more info.
298

BUGS

300       gtk-gnutella  is  production-quality software, but still has minor bugs
301       and incomplete or missing features.  But which software doesn't for its
302       authors?
303
304       There are probably other missing features that should be listed here.
305
306       A  list  of  known bugs might be available at the gtk-gnutella web site
307       (see below.)
308

SEE ALSO

310       Additional information about gtk-gnutella and the  latest  version  are
311       available at http://gtk-gnutella.sourceforge.net/
312
313       Additional    information    about    gnutella    is    available    at
314       http://www.the-gdf.org/          http://www.infoanarchy.org/en/Gnutella
315       http://rfc-gnutella.sourceforge.net/
316

AUTHORS

318       Yann  Grossel  wrote  the  original gtk-gnutella which was running as a
319       Gnutella 0.4 client in 2000.
320
321       Raphael Manfredi <Raphael_Manfredi@pobox.com> is the current maintainer
322       and project leader (since version 0.14, released early September 2001).
323       For support, please contact the developer list, which can be reached at
324       <gtk-gnutella-devel@lists.sourceforge.net>.
325
326       For a full list of contributors, open the "About" menu.
327
328       Brian St. Pierre <bstpierre@bstpierre.org> wrote the initial version of
329       this manpage.
330
332       gtk-gnutella is Copyright (c) 2000, Yann Grossel, with additional copy‐
333       rights held by other contributors 2000-2020
334
335       License to use and copy gtk-gnutella is given under the  terms  of  the
336       GNU  General Public License (GPL), version 2. Please see the file COPY‐
337       ING in the distribution for complete information.
338
339       This manual page can also be redistributed under the same conditions as
340       gtk-gnutella itself.
341
342
343
344Version                            July 2020                   GTK-GNUTELLA(1)
Impressum