Show shell.txt syntax highlighted
-------------------------------------------------------------------------------
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.
See more files for this project here