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 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 ses
sion. 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 com
mands and variable names in this version. Commands can be abbre
viated, 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 re
sults, 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 in
put and output streams to a unix-domain socket. It is provided to
enable scripts and other clients to communicate with mutella ser
vent 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 connec
tions, the list of searches, or the last displayed list of re
sults. 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 da
ta that you may accidentally operate on information generated in
the wrong list. Future versions may make these identifiers glob
al 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. Ev
erything 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 de
scription 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 de
tailed 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 cur
rent status of the client and its activities. If executed with
out 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 visi
ble 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 connec
tions 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 es
timates for that particular host connection, and the time that
connection has been operational for. Each connection is num
bered; 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. Ac
tually 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 con
nections 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 successful
ly, 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 disconnect
ed.
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 list
ing of all current searches, remove searches with delete , or
flush out current results with the clear command.
Note that searches are continuous operations - search re
quests 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 re
sults - 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 re
sults, 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 use
ful 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 fil
tered 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 num
bers 1, 2, 5, 8, 9, and 10. Another example might be "delete 1-"
which would delete all the searches listed by the last list com
mand.
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, re
ports a nonzero "hits" in its results.
The results for one or more specific searches can be re
quested by using the results command,. One or more search IDs
taken from the output of the list command may be provided as op
tional 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 down
load that file.
results [pattern ...] or [ID ...]
This command displays the results of currently active
searches. Without arguments, this command will display all re
sults collected by the search subsystem. The output of the com
mand 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 num
ber 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 specif
ic 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 re
quested file from any hosts providing that file for an unlimited
amount of time. The download will complete only when the trans
fer is successful or stopped with the stop or kill transfer com
mands.
Upon download start, Mutella generates the search for al
ternative 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 con
nect 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 al
ready, 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 sys
tem to assist in configuration.
set [variable] [value]
This command is used to access the application's many op
tions 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 vari
able name, but without a value, it will display the current set
tings 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 com
mand 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 suc
cessful completion of any download.
library This command provides a list of all currently
shared files. This command is most useful when testing the ef
fects of filters which can be set in mutella's preferences to de
termine what files can be shared. It also reports search popu
larity of the files and the number of upload requests for each
file.
load filename
Loads and executes a script file containing com
mands 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 syn
tax, 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 us
er 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 porta
bility 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 pe
riods 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 re
liable parameter.

SEE ALSO

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

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 spe
cific commands at startup.
POSIX May 15, 2002

POSIX

Copyright © 2010-2025 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout