MUTELLA(1)                 OpenBSD Reference Manual                 MUTELLA(1)

NAME
     mutella - A command line and HTTP-based Gnutella servent

SYNOPSIS
     mutella
     mutella_sio

DESCRIPTION
     mutella is a high-performance Gnutella servent supporting v0.4 and v0.6
     of the Gnutella protocols.  It is compatible with a broad range of
     clients from other platformsand development groups, including LimeWire,
     BearShare, Morpheus, and many more.

     mutella is referred to as a servent - it is both client and server to the
     network, allowing the user to both serve files to other Gnutella network
     members and to receive files from those members. It is designed to be
     very easy to use and configure.

     mutella is designed to be very easy to use and configure.  It has only
     several very basic command line options;  instead, it provides an
     interactive prompt to the user, and accepts commands and provides
     feedback and information to that interactive session.  The interactive
     session supports command history, command line editing, and completion
     through the GNU readline library on the input line.  Command completion
     can be used to complete commands and variable names in this version.
     Commands can be abbreviated, as long a they are still unique. For
     example, the results command can be shortened to res (or even r).

     Optionally, the user may choose to interact using a web-based interface.
     A remote interface (which operates on the same interface as the Gnutella
     port) can be configured which allows the user to perform most of the
     basic and many of the complex tasks of monitoring activity, performing
     searches, viewing results, selecting results for transfer, and managing
     and viewing uploads, downloads, and event messages.  Note that, by
     default, the web interface is disabled in order to maintain high security
     standards.

     mutella_sio is a tiny program, allowing to redirect its input and output
     streams to a unix-domain socket. It is provided to enable scripts and
     other clients to comminicate with mutella servent via the unix socket. In
     particular it enables the time-based bandwidth control, if the
     appropriate commands are executed from the cron service.

   Using The Terminal Interface
     The terminal interface provided on the command line allows the user to
     operate on information displayed.  Many commands will provide a numbered
     list in its output; the command line interface remembers which numbers
     were assigned during the last listing of the output type in question,
     whether that be the list of connections, the list of searches, or the
     last displayed list of results.  Rerunning the command that generated the
     list will change the numbers which the user must use in following
     commands to the newly generated numbers.

     It is therefore important that when users attempt to close a connection,
     list, clear, or stop a search, get a from a result list, or stop or kill
     transfers in progress that they do so with the information from their
     most recent listing of those commands. This presents a known problem when
     using multiple windows in the web display, which operates on a similar
     principle.  Be aware that if you are using multiple windows to view and
     operate on data that you may accidentally operate on information
     generated in the wrong list.  Future versions may make these identifiers
     global and unique references to ensure that users do not experience this.

IMPORTANT NOTE
     This manual page may appear corrupted if your man subsystem uses GNU
     groff prior than version 1.17.

COMMANDS
     The terminal session supports a broad range of commands geared towards
     providing full operability from the terminal.  Everything which can be
     performed in the web interface (and at the moment, a good deal more) can
     be performed from the terminal in a fast and efficient manner.  The
     terminal session supports ANSI colorization to make information easier to
     locate, organize, and read.

   Online Help System Commands
     Online help is available for all commands and options in the client.  You
     can get a list of all commands by typing help or ?  Alternately, you can
     get a list of variables which can be set by typing "set", which will
     provide a grouped list of variables and their current settings to the
     user.  The commands to access the help system are

     help [context]
       When invoked without arguments, this command will display a summary of
       all commands available witha  short one-line description of each
       command.

       When invoked with a specific command it displays a more detailed
       description of that command.  Tab completion can be used to assist in
       completing command names.

       When invoked with a specific variable it displays a detailed
       description of that variable.

   Network Commands
     Network commands are used to retrieve information about the status of the
     user's network connections to the Gnutella network, and retrieve
     information and statistics about the operation of Gnutella and the user's
     visible horizon.

     info [options ...]
           Displays a broad range of information regarding current status of
           the client and its activities.  If executed without arguments, it
           will list information from all sections, as if the user had
           supplied all options to the command.  Using options will display
           only the requested information.  Multiple options may be provided.
           These options are

           network
                 Displays information about the current network horizon
                 (reachable hosts, number of hosts sharing information, and
                 vague estimates of the number of files and size of the
                 visible part of the Gnutella network to which the client is
                 currently able to reach.

           connections
                 Displays all current connections to the Gnutella network.
                 Note that these are the actual Gnutella connections used to
                 query and recieve queries from peers, and not the connections
                 used for transferring files (which appear under the transfers
                 option results).  It displays, for each connection, the host
                 and port to which the servent is connected, the horizon
                 estimates for that particular host connection, and the time
                 that connection has been operational for.  Each connection is
                 numbered; individual connections can be manually closed using
                 the close command, and new connections to specific hosts
                 manually opened using the open command to connect to specific
                 Gnutella hosts by their IP address or DNS name.

           transfers
                 Displays all current transfers in progress. Actually displays
                 results as if the user had selected both uploads and
                 downloads as options to the command.

           uploads
                 Displays each upload, or file sent to another Gnutella user.
                 Each upload lists the host and port which the file is being
                 sent to, and various transfer statistics about the file
                 transfer in progress.  The number of simultaneous uploads
                 allowed and the maximum bandwidth can be set and displayed
                 from the set command.  Each transfer is numbered, and can be
                 stopped using the stop command.

           downloads
                 Displays all currently active downloads.  For each download,
                 information concerning the remote host selected for
                 downloading and transfer statistics are provided.

                 mutella attempts to establish simultaneous connections to
                 multiple peers providing the same file, and tries to
                 determine the fastest possible transfer partner by
                 downloading a small portion of that file data from each
                 replying host.

                 Even if the download process starts successfully, mutella
                 associates with with a special kind of search, listed as
                 AUTOGET in the search list.  These searches are automatically
                 generated, and are used to find alternative locations for
                 that file.  Once transfer begins, however, new connection
                 efforts will only be performed once the current download
                 socket is disconnected.

                 To avoid slow transfers, it can be useful to set minimum
                 transfer rates; configuration of parameters are discussed
                 later.

                 As with the uploads option, each transfer is numbered, and
                 can be stopped using the stop command.  However, in addition,
                 the user may choose to kill a download transfer - this
                 results in the removal of the partial file, the removal of
                 the .Ar AUTOGET search associated with that file, and the
                 stopping of the download.

     hosts
           Displays the current content of the hosts cache, the top of the
           iceberg of our 'known universe'.  Hosts in this list may be used to
           create additional/future Gnutella-net connections.  When the client
           is in operational state, the host cache contains at least a few
           dozen entries; normally not more than 100.

     open host [port]
           Opens Gnutella-net connection to the specified host.  When the port
           argument is omitted, the default Gnutella network protocol port of
           6346 is assumed.

     close ID [...]
           Closes one or more connections corresponding to the last displayed
           list of connection IDs. The connection matching the given
           connection IDs will be taken from the last output of the info
           command.

   Search-Related Commands
     These commands are used to manage the searches in progress on the
     network.  Users may define new searches using find , list subsets or
     specific types of the current searches and get a listing of all current
     searches, remove searches with delete , or flush out current results with
     the clear command.

     Note that searches are continuous operations - search requests are
     performed periodically to refresh the list of search results.  Over time
     our visible horizon changes, and with it, new providers of the requested
     files may become available.  Clearing the search results will update
     search results to be more accurate to the current visible horizon, but it
     is safe to leave searches running for long periods of time.  Hundreds of
     searches may be run simultaneously, each with hundreds or a thousand
     possible results - judicious use of pattern matching in the list function
     can help manage long search lists.

     The commands to create and manage searches are

     find keyword ... [options]
            Adds new query to the current list of searches. All the keywords
            are matched as a boolean AND, ignoring upper/lower case.  In
            addition, the following search options may be used

            -word
                 Users may exclude specific words from searches using a '-'
                 before the word (e.g., "find hook .avi -hookers" will only
                 locate files containing "hook" and ".avi", but will exclude
                 any file containing the word "hookers".  (and we are
                 absolutely certain you've never seen that word legitimately
                 used in a man page)

            size:bytes
                 Specify the exact size of the file to locate, in bytes.

            min:bytes
                 Specify the minimum size of the file to locate, in bytes.

            max:bytes
                 Specify the maximum size of the file to locate, in bytes.

            If no parameters are provided to this command, it provides the
            same results as the list command.

     list [pattern / ID] [options]
            Displays the current list of searches. Optionally, this command
            takes a pattern as a parameter.  Each search result listed is
            numbered; that number, the search ID, may then be fed into other
            commands to perform operations on those searches, such as delete
            to delete searches from the list, clear to clear results, or
            results to list the results of one or more searches.

            When a pattern is provided, only searches matching the specified
            pattern will be listed.   This feature is most useful when the
            search list grows above 5-10 entries.

            In addition, the following options can be used

            -empty        Filter out all searches which have no results
                          ('hits').

            -auto         Filter out automatically generated search results
                          created by downloads.  Searches which will be
                          filtered out are marked as AUTOGET in the results
                          list.  These searches are automatically created by
                          downloads and partial files.

     ls     Provides the same results as if the user had typed in

     list -empty
            as an interactive command.

     delete ID [...]
            Delete one or more queries from the current list of searches.
            Numeric IDs should be taken from the last output of the list
            command.

            IDs can be given in fairly relaxed way. For example, ".Ic delete
            2,5, 1,8-10" will delete searches listed under numbers 1, 2, 5, 8,
            9, and 10.  Another example might be "delete 1-" which would
            delete all the searches listed by the last list command.

     clear ID [...]
            Clear the results of one or more queries from the current list of
            searches.  Numeric IDs should be taken from the last output of the
            list command.

            As with the delete command, search IDs to delete may be given in a
            similarly relaxed way.

   Results-Related Commands
     Once a search has located results, those results may be listed.  (The
     search entry, as reported by the list command, reports a nonzero "hits"
     in its results.

     The results for one or more specific searches can be requested by using
     the results command,.  One or more search IDs taken from the output of
     the list command may be provided as optional parameters.  Alternatively,
     a text string may be provided as a filter to limit the output only to
     those searches which match the supplied filter contents.

     Once the user has viewed the results, he may use the result ID provided
     in that list to perform a get, and attempt to download that file.

     results [pattern ...] or [ID ...]
       This command displays the results of currently active searches.
       Without arguments, this command will display all results collected by
       the search subsystem.  The output of the command can be made more
       specific using two different mechanisms: either by providing one or
       more search IDs taken from the list command, or by providing a pattern
       to match against the search strings of individual searches.

       A list of results will be provided, separating the results of each
       query and listing the number of results in each query group.  Files may
       be grouped according to name and size, the number of hosts providing
       that file listed below with host details.  A "REF" number represents
       the "reference" part of the Gnutella file transfer query (which is
       built like http://HOST:PORT/get/REF/FILE_NAME).

     get ID [...]
       Initiates download of one or more files defined by specific result IDs
       taken from the last results command.

       IDs can be given in fairly relaxed way. For example "get 10, 15, 22-25"
       will start download of the search results listed under numbers 10, 15,
       21, 22, 23, 24, 25.

       The progress of downloads can be examined with the info command.

       Once download is started, mutella will try to get the requested file
       from any hosts providing that file for an unlimited amount of time.
       The download will complete only when the transfer is successful or
       stopped with the stop or kill transfer commands.

       Upon download start, Mutella generates the search for alternative
       locations for the file.  The results, received by that search entry are
       always automatically used to update host lists for the download.  If
       the automatically generated search is deleted while the download is
       still active, it will be re-created again after a period of time.

       Upon download start or disconnection of a transferring file connection
       from the remote peer, the servent tries to connect to all the hosts in
       the download list until a successful connection is established.  If a
       host is not responding during the last 20 attempts, it is removed from
       the peer list.  If for any reason the peer list becomes empty, an
       AUTOGET search is added (if the search associated with that transfer
       exists already, it will be changed to AUTOGET status) and download
       failure is reported.  If that file appears again on the Gnutella
       horizon, the servent will automatically attempt to continue transfer.

       AUTOGET searches are also created for all partial files found in the
       download directory on the client start to allow for automatic resume of
       partial downloads between mutella sessions.

   Transfer Commands
     Transfer commands need to be provided with the ID of the transfer to
     stop; these IDs can be shown from the info command.

     stop ID [...]
                   Stops the file transfers corresponding to one or more
                   transfer IDs.  Note that this command does not remove
                   partial files from the download directory.

     kill ID [...]
                   Stops transfers corresponding to the given transfer IDs and
                   deletes appropriate patrial files in case of download.

   Application Preferences
     Application preferences are set using the set command, which allows you
     to list, set, and view the settings of all servent preferences.  Each
     variable has online help through the help system to assist in
     configuration.

     set [variable] [value]
       This command is used to access the application's many options and
       preferences. Using the command without any parameters provides an
       organised list of all options available and their current values.  When
       the command is called with a single variable name, but without a value,
       it will display the current settings of that variable.  To set a
       variable's contents, supply the value as the second parameter to the
       command.

       To clear a variable of its value, a variable can be set to "" (an empty
       string).

       Note that to disable the effects of some variables, the value is 0; for
       others, 0 has a meaning, and -1 will disable the feature.  More
       information about how a variable behaves can be found in the online
       help system by supplying the variable name as the option to the help
       command.

       All mutella options are stored in '~/.mutella/mutellarc' file.

     color [field [ANSI-code]]
       This command can be used to set the ANSI escape codes used to produce
       colors for the terminal UI.  The syntax for this command is similar to
       `set'.

       The color scheme is stored in the location ponted by the ColorScheme
       variable (the default is '~/.mutella/termclr').

   Other Commands
     Commands in this section include the ability to list all currently shared
     files, rescan for new files in the library, and performing scripting
     actions.  Also, the system command, which allows users to execute
     arbitrary shell commands, and the exit command, which allows users to
     terminate execution of the client.

     scan      Forces a rescan of the list of files present in the library
               directory and makes those files available as query responses.
               A rescan will automatically take place at the successful
               completion of any download.

     library   This command provides a list of all currently shared files.
               This command is most useful when testing the effects of filters
               which can be set in mutella's preferences to determine what
               files can be shared.  It also reports search popularity of the
               files and the number of upload requests for each file.

     load filename
               Loads and executes a script file containing commands in the
               servent's command interpreter.

     system command [arguments ...]
               Executes the shell command provided.

     ! command [arguments ...]
               Shorthand; same as "system".

     version   This command displays the current program version.

     exit      Exits the servent.

   Unix Pipes
     All commands support Unix pipes.  The output of any command can be
     redirected to the shell using standard Unix pipeline syntax, e.g.  "res
     1-3 | grep something" to grep the output of that command for specific
     result patterns.

COMMAND LINE OPTIONS
     Mutella supports the following command-line options:

     -n or --no-ui
                   Do not start libreadline-based interactive user interface.
                   Note that 'termrc' script will not be executed in this
                   case.

     -d or --daemon
                   Start without the interactive user interface and fork to
                   the background. Note that 'termrc' script will not be
                   executed in this case.

     -c file or --config=file
                   Use alternative configuration file.

     -h or --help  Print the help message and exit.

FILES
     Configuration is retained within the user's home directory; a .mutella/
     directory will be created containing a mutellarc and other app-specific
     files.

VERSION
     This manual documents mutella 0.4.4

AUTHORS
     Max Zaitsev
         Original author and maintainer.

     Gregory R. Block
         Co-maintainer and co-developer, build system, and portability changes

   Other Contributors
     Marco Herrn   Original author of this manual page.

     Greg Parker   Contribution of a one-shot replacment for poll() for
                   systems only supporting select()

LIMITATIONS
     o   mutella has a known problem with hostname translation.  Hostnames are
         resolved by gethostbyname() during connection open; this halts
         processing of the core network heartbeat, which causes the
         application (in specific circumstances) to hang for long periods of
         time.  During this, the application may refuse to report connection
         lists and similar activities which would need access to that locked
         information.

         Please ensure that autoconnect host entries are valid host entries on
         your system and can be located with nslookup if you find you are
         having problems like this.  Future versions will perform these
         activities asynchronously.

     o   Mutella is dependent on the availability of GNU readline version 4.2.

     o   Rates displayed for individual Gnutella-net connections in info do
         not reflect the bandwidth consumed and are given only for the
         reference. Total connection speed, however, is quite reliable
         parameter.

SEE ALSO
     screen(1), pipe(2), readline(3), cron(8), crontab(1)

TODO
     o   Explain concepts and special features better, including auto-search,
         auto-get, and other search-time options.

     o   Add a TIPS section (and mention the extreme usefulness of "screen"
         when used with Mutella to keep long-term sessions

     o   Mention the ./mutella/termrc scripts for performing specific commands
         at startup.

POSIX                            May 15, 2002                            POSIX
