MUTELLA - unix/linux Gnutella-net client
========================================
http://mutella.sourceforge.net

Well, yet another Gnutella clone. Initially I wrote it for myself suddenly
I've noticed that it's not bad at all... Still it is far from being ideal
though.

General information about Gnutella network can be found at
http://www.gnutella.co.uk
http://www.gnutella.wego.com
http://www.gnutelliums.com
http://www.gnutellaforums.com/

The INSTALL document describes how to build mutella. If you are running a
reasonably recent (less than a year old) release of Linux, it will amount
to the following steps:
  # unpack the tarfile, this will create a directory "mutella-X.X"
  # go into the directory that was just produced
  ./configure  # or 'sh ./configure'
               # do not forget --prefix=... if you want mutella
               # to be installed in the place other than /usr/local
  make         # or 'gmake' on some systems, like BSD or Solaris
  make install # if you want to binary, manual pahes and WEB-ui
               # template in a public directories like /usr/local/xxx 

Compiled? Installed? Ready to rock! See "Usage" for the tips. Or just start
your client and get connected to the gnutella network.


CVS
===

If you've downloaded a CVS version it is necessary to produce the configure
script and makefiles. Recent GNU Autoconf/Automake tools are required for
this step. A small script called 'bootstrap' is provided to automate this
process.


USAGE
=====

The situation with the lack of documentation is slowly improving. Starting
from version 0.4 mutella ships with the manual page, containing detailed
description of program functionality. However, this page may display
incorrectly if your man-subsytem makes use of the older version of GNU
groff. For that reason and also to save people from reading long and
precise description, we provide major usage tips here. This description
is certainly incomplete and mey be slightly out of date, but hopefully
is sufficient to help one to get started.

As for the version 0.4.4 mutella provides built-in support for two types
of user interfaces: text mode UI and HTTP UI. The text mode UI can be
started in both the interactive terminal mode and in the Unix socket mode.

By default only the terminal and the socket user interfaces are enabled.
The built-in HTTP interface is disabled in order to guaranty the highest
security for the default configuration. The procedure of activation of the
remote interface is briefly described in the HTTP-interface section.

Mutella supports the following command-line options:

  -n, --no-ui     Do not start libreadline-based interactive
                  user interface. Note that 'termrc' script
                  will not be executed.
  -d, --daemon    Start without interactive user interface
                  and fork to the background. Note that 'termrc'
                  script will not be executed.
  -c [file],
  --config=[file] Use alternative configuration file.
  -h, --help      Print this message and exit.

When executed without command line options Mutella performs certain
initialisation steps and comes up with a prompt '>'. Now you can type in
commands. 'help' or '?' without parameters lists all supported commands.
Type 'help <command>' to see some details on the command usage.

TIP: Many mutella's users find 'screen' system command to be extremely
useful to run mutella 24/7 independent of for example X session. Consult
screen(1) manual page.

TEXT MODE USER INTERFACE
========================

The most useful text-mode comands commands are:

find <list of keywords separated by spaces>
       this adds new query to the search list. additionally you can specify
       minimum size of the file with 'min:XXXX' or exact size with
       'size:XXXX' where XXXX is the size specification. K, M and G
       suffixes are accepted. When issued without parameters performs
       'list' command.

list <keywords> [-auto] [-empty]
       displays current query list. When keyword(s) is/are specified lists
       only searches which contain all given keywords. Optional parameter
       '-auto' suppressed automatically generated searches like searches
       for the alternative locations for the files you attempt to download
       or searches for broken downloads and partial files. Use '-empty' to
       suppress output of searches with no hits.

ls <keywords> [-auto]
       synonym for 'list -empty'.

results <keywords> | <number_list>
       displays the results of the query(s). Queries can be selected by the
       numeric IDs given by previous 'list' command or by the set of
       keywords. Accepts numeric ranges like 1-5,7,21- and so on.

get <number_list>
       retrieve the file, or the set of files for the result Ids given.

info
       displays various bits of information concerning current status of the
       client and the net.

stop <numer_list>
       stops a transfer (upload or download) for given ID(s). When stopping
       the download partial file remains on the disc.

open <host> [port]
       opens Gnutella-net connection to the given host. When 'port' is
       ommited 6346 is assumed.

close <number_list>
       closes the Gnutella-net connection by numeric ID(s).

set <Variable> [new_value]
       sets or displays values of the various parameters.

scan
       rescans the shared directory

The behaviour of Mutella to great degree depends on the multitude of options,
also referred here as properties, parameters or variables. You can access
these by the `set' command. Use `help' command with a property name as a
parameter to see the description of the respective option.
E.g. `help MaxUploads' will produce few lines of text describing the
MaxUploads variable. Currently all variables are documented to some
degree, but still I will mention few of them here.

important variables:
--------------------
BandwidthTransfer  maximum network bandwidth given to all uploads together
DownloadPath       where to put files
ForceIP            IP to display to the network (if behind firewall)
ForcePort          port to display to the network
DynDnsFirewall     symbolic name of your firewall if it's IP is dynamic
MaxConnections     maximum Gnutella-net connections. set according to your
                   bandwidth. In most cases values between 6 and 20 make
                   sense. 15 connections I normally use result in 15-
                   60Kbyte per second of connection-related bandwidth
                   consumption
MinConnections     minimum number of connections to maintain. recommended
                   value is 4.
MaxUploads         maximum number of uploads.
SharePath          path to your shared files. curently only single
                   Directory is supported, but you can use symbolic links
                   inside it to share files for example from different
                   partitions.
TerminalLines      number of lines in your terminal window.
TreminalColumns    width of the terminal window in characters.
Paginate           Boolean variable controls whether to stop between
                   terminal pages

When client is started, before '>' is displayed optional start-up script
can be executed. Default location of the script is $HOME/.mutella/termrc
(used to be $HOME/.mutella_termrc in the earlier versions). Syntax is
similar to the interactive mode commands described above.

NOTES ON UNIX SOCKET INTERFACE
==============================

Mutella can also be almost fully controlled via the local Unix socket.
The degree of this control, however, may be adjusted via several options.
Be sure so set the access rights in the socket and the directory, where
the socket is located (default is ~/.mutella) to protect your mutella
from the other users of your computer.

In order to facilitate access to the socket interface a small program,
called 'mutella_sio' is provided, which enables to redirect the standard
input and output streams to the socket. 'mutella_sio' may be either part
of the unix pipe or executed independantly. In the later case it redirects
the terminal input to mutella and prints the output in the terminal. This
to certain degree simulates the 'interactive' mode, however, the advanced
features, like color, paged output or command history are not available.

The main destination of the socket UI is to enable the automated time
based control of mutella's options, such as bandwidth settings. This
is acheaved via addition of the respective calls of 'mutella_sio' to the
user's crontab file.    

HTTP INTERFACE
==============

Since version 0.3.9b mutella provides built-in template-based HTTP
interface. The default location of the template files is
'/usr/local/share/mutella/remote/template/'.
The access to the remote interface is disabled by default in order to
ensure that high security and privacy traditionally provided by mutella
is maintained. To enable http-ui one has to:
1. Set remote username/password via 'RemoteUser' and 'RemotePass' variables
2. Set 'RemoteEnable' to 'true'
3. Set 'AllowedRemoteNet' to something appropriate if http-ui is supposed
   to be used from somewhere else. The default is 'localhost only' that is
   '127.0.0.1/32'. To enable any IP to use the HTTP interface set
   'AllowedRemoteNet' to '0.0.0.0/0'.

To connect to the http interface type 'http://localhost:6346/remote' in
your favourite browser (this implies that your client is listening on port
6346; check 'LocalPort' if this does not work).

TIP: if you set 'AllowedRemoteNet' to your private class-C subnet like
'192.168.1.0/24' it is important to realise that the 'localhost' is no
longer allowed to use the UI. The workaround is to use the host name instead
of the 'localhost' in the browther.

For troubleshooting is it helpfull to check HTTP access log file located at
'~/.mutella/htaccess.log' The logging facility may be switched off by setting
'RemoteLogAccess' to 'false'

NOTE: The template pages for the remote interface are installed to
<prefix>/share/mutella/remote/template by default. The place where mutella
looks for the template is controlled by 'RemoteTemplatePath' variable.
This variable will point to the correct location if you have installed
mutella using 'make install' or as a binary package. Othervise you have to
adjust 'RemoteTemplatePath' to point ot the correct directory on your file
system. Mutella's built-in HTTP server does not allow '..' path elements and
does not build directory indexes for security reasons.

For a comprehensive reference or the guide for creating/modifying templtes
it would be usefull to see README.HTTP-UI when it is written.

List of relevant Mutella variables
----------------------------------

RemoteEnable         Enable/Disable http-ui. Default is 'false'
RemoteLogAccess      Log http-ui access. Default is 'true'. Access is logged
                     to ~/.mutella/htaccess.log
AllowedRemoteNet     The subnet, allowed to use http-ui. Default is
                     localhost (127.0.0.1/32). Setting it to 0.0.0.0/0
                     enables access from any IP
RemoteDir            Http path to http-ui. Default is "/remote". If changed
                     requires restart to have an effect
RemoteTemplatePath   Disk path to the http template
RemoteUser           User name for the http authentification. Default is
                     empty. Stored as clear text
RemotePass           Password for the http authentification. Default is
                     empty. Stored as clear text. If you are CERTAIN you
                     want to disable authorisation set RemotePass to
                     no_password


Good files for everybody!
Hope mutella works fine for you.

Max Zaitsev
mailto:maksik@gmx.co.uk

