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 inter-
     active prompt to the user, and accepts commands and provides feedback and
     information to that interactive session.  The interactive session sup-
     ports 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 ).

     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.

     rmutella 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 appropri-
     ate 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 com-
     mands 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 generat-
     ed 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 ter-
     minal 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 pro-
     vide 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 com-
       mand.

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

       When invoked with a specific variable it displays a detailed descrip-
       tion 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 informa-
     tion and statistics about the operation of Gnutella and the user's visi-
     ble 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 informa-
       tion.  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 net-
         work 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 dis-
         plays, 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 connec-
         tion 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 num-
         bered, and can be stopped using the stop command.

       downloads
         Displays all currently active downloads.  For each download, informa-
         tion 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, how-
         ever, 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 ad-
       ditional/future Gnutella-net connections.  When the client is in opera-
       tional 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 ar-
       gument 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 net-
     work.  Users may define new searches using find , list subsets or specif-
     ic types of the current searches and get a listing of all current search-
     es, remove searches with delete , or flush out current results with the
     clear command.

     Note that searches are continuous operations - search requests are per-
     formed 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 pos-
     sible 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 contain-
         ing "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 re-
       sults as the list command.
       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 to delete searches from the list,
       to clear results, or to list the results of one or more searches.

       When a pattern is provided, only searches matching the specified pat-
       tern 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 down-
