--- name: "mutella" section: "1" platform: "linux" package: "mutella" version: "0.4.5-5" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/mutella" --- # mutella(1) A command line and HTTP-based Gnutella servent ## 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 platforms and 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 communicate 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 receive 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 partial 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 pointed 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 replacement for **poll**() for systems only supporting **select**() ## LIMITATIONS - **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. - **Mutella** is dependent on the availability of GNU readline version 4.2. - 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)](/screen/1.md), [pipe(2)](/pipe/2.md), [readline(3)](/readline/3.md), [cron(8)](/cron/8.md), [crontab(1)](/crontab/1.md) ## TODO - Explain concepts and special features better, including auto-search, auto-get, and other search-time options. - Add a TIPS section (and mention the extreme usefulness of "screen" when used with Mutella to keep long-term sessions - Mention the ./mutella/termrc scripts for performing specific commands at startup.