------------------------------------------------------------------------------- Gtk-Gnutella shell interface ------------------------------------------------------------------------------- Date: 2002-12-17 Author: Richard Eckart $Id: shell.txt 12284 2006-11-09 18:40:24Z cbiere $ Introduction ------------ Gtk-Gnutella supports a so-called shell interface. This feature is available locally and optionally remotely as well. At the moment, the shell has still limited use but is nonetheless sufficient for special tasks and uses. It is especially useful and important when using Gtk-Gnutella Topless. Connecting ---------- Gtk-Gnutella has a simple built-in application which can be used to access the shell over the local socket by invoking it as follows: $ gtk-gnutella --shell Type "HELO" to access the shell interface. Note, the environment variable GTK_GNUTELLA_DIR is also respected in this case. You need write-permission to the local socket located in "$GTK_GNUTELLA_DIR/ipc/socket". For security reasons, the "ipc" directory and "socket" are created so that only the user running the gtk-gnutella process can access them. To connect to the remote shell simply telnet to the gnutella port on your machine. Alternative applications are gnutls-cli (for a TLS encrypted connection) and, for example, netcat. The latter is useful for automized task using scripts because telnet cannot be used properly for such purposes. While it is possible to have multiple shells open at the same time, keep in mind that this feature is not implemented as a multi-user system. Authentication ---------------- The local shell does not require authentication because the local socket is protected by the filesystem permissions. However, in order to request access to the shell, the first sent line must be "HELO". Optional arguments are ignored for now. This means, the local socket can also be used for anything else supported over the ordinary listening TCP socket e.g., HTTP. When using the remote shell, The first thing you need to do after the connect is to authenticate. For that you need to supply the command: HELO [credential] The [credential] is stored in $GTK_GNUTELLA_DIR/auth_cookie. Gtk-Gnutella creates this file at startup and stores a random base32 value in it. The file is readable only by the owner. Commands -------- After the authentication, you can enter commands. All commands are case-insensitive but their arguments might be case-sensitive. You can use double-quotes in commands to create arguments that contain spaces. Within those quotes the "\" (backslash) is used to escape chars ('\x' -> 'x', '\"' -> '"'). This is useful if you need to have double-quotes in a quoted argument. The commands that are currently working are: - help Shows available commands. - quit Close the shell connection. - search add Creates a new search for . The query string is interpreted the same way as in the GUI. This means you can also initiate browse host requests and even magnets are handled, so even downloads can be started this way. NOTE: This command does not yet for Gtk-Gnutella Topless because large parts of the code responsible for handling searches and search results are implemented in the GUI. - node add [port] Try to connect to given . [port] is optional. If no [port] is given the default gnutella port 6346 is used. - print Print the current value of a property. Refer to gnet_props.ag and gui_props.ag to find names, descriptions, and possible values of properties. Current values are stored in ~/.gtk-gnutella/config_gnet and ~/.gtk-gnutella/config_gui so you could also look there for hints. - set Set the value of to . Boolean values are false|FALSE|0 for false and true|TRUE|!0 for true. Multichoice properties must be set with their integer values, e.g. to set configured_peermode, you should know that 0 is for leaf, 1 for legacy, 2 for ultrapeer, and 3 for auto. - whatis Print information about the property. This is the same information found in the tooltip in the gui. - shutdown Initiates a shutdown of gtk-gnutella. - nodes Displays a list of all currently connected Gnutella peers. - horizon [all] Shows the current horizon information as evaluated by the HSEP extension. An optional argument "all" shows the horizon for all connected peers supporting HSEP. Otherwise only the cumulative horizon stats are displayed. - rescan Rescans all shared directories and updates the list of shared files. This is useful when you removed or added files to the shared directories. - status Shows a short overview of the current node status. - offline Disconnects from Gnutella but keep uploads and downloads running. - online Connects to Gnutella. - props [] Lists the names of all core properties. An optional regex pattern can be used to show only certain properties. Caveats: -------- Some output might be translated but in general the shell interface is meant to be English-only. There might be character set problems because the gtk-gnutella process might be using a different locale than the shell connecting to it. Therefore, it's highly recommended, that the gtk-gnutella process is started using UTF-8 as locale encoding or ASCII if UTF-8 support is not available or desired. The output format is meant to be NNTP-like so that it is easy to parse by scripts - but this is not the case yet for all commands.