
-------------------------------------------------------------------------------
                          gtk-gnutella shell interface
-------------------------------------------------------------------------------
Date: 2002-12-17
Author: Richard Eckart
$Id: shell.txt 13096 2007-03-15 17:12:47Z 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<enter>" 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 "gtk-gnutella --shell" this "HELO" is sent automagically.

  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 <query>
    Creates a new search for <query>. 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 <ip> [port]
    Try to connect to given <ip>. [port] is optional. If no [port] is given
    the default gnutella port 6346 is used.

  - node drop <ip> [port]
    Disconnect the node with the given <ip> and port. [port] is optional. If
    no [port] is given, all nodes with the given <ip> are disconnected.

  - print <property>
    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 <property> <value>
    Set the value of <property> to <value>.
    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 <property>
    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 [<regex>]
    Lists the names of all core properties. An optional regex pattern can
    be used to show only certain properties.

  - download add <magnet>|<HTTP URL>
    Initiates a download. The command accepts magnet links and URLs starting
    with "http://".

Notes:
------

  The property "remote_shell_timeout" controls after how many seconds a
  idle shell session is terminated. The default is 60 seconds. You can
  disable this timeout by setting the property to zero.

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.

