Gnut Manual: Advanced Usage |
4. Advanced Usage
4.1 Invocation
Gnut has a variety of command line arguments that can be used in special circumstances. They are listed below, with a short description of each.
- -l range Sets the initial logging level to the value of #. This specifies how much information Gnut displays at runtime, which is useful for debugging purposes, or to examine your network traffic in detail. The higher the level, the more information you get. Beware, though: A high log level may flood your screen. (You can type between the lines.)
- -c file Specify a script to run at startup. This will bypass any ~/.gnutrc you may have.
- -p num Start gnut listening on TCP port num.
- -i [IP/interface] IP (or interface) to broadcast as belonging to us.
- -d Daemon mode, never ask for input at the console.
- -x Exit after having run any scripts.
- -v Output version information and exit.
- -h Display a usage message and exit.
4.2 Run-Time Commands
Overview
Gnut is a command line interface. That means you have to give it commands. Commands in gnut are a single word followed by optional arguments. All commands can be abbreviated to the point that they are still unique.
Notation
Brackets are used in the regular expression sense. Thus [abc] means
use either a, b, or c. Textual arguments are indicated with less than
and greater than signs, for example
7 | Just a single number |
4-6 | Range of numbers |
2,6,5 | Comma-delimited list |
1-4,17,7-10 | Any combination thereof |
List of Commands
info [hqnsct] - Display various information.
h - Host
q - Query
n - Network
s - Local Shares
c - Connections
t - Transfers
open host - Open outgoing connection to
find string - Search the Gnutella network for. This is a keyword based search, and nearly every client specifies this as a boolean AND search with all non-alphanumeric characters ignored.
search string - Synonym for find.
find or search with no argument displays results.
monitor - Turn on the search monitor.
update - Send out ping packets to all connected hosts. If configuration variable update_clear is set, then the current host list is discarded as well.
response regexp - Show the current query responses which match the given regular expression. The results are sorted according to the sort_order configuration variable.
get range - Start downloading files referenced by %%. If more downloads are requested than allowed by max_uploads, then the downloads are queued.
push range - Same as get, however only a push connection is attempted.
stop range - Stop the transfers referenced by %%.
clear range - Removes finished transfers from the transfer list.
kill range - Terminate the gnutella connections referenced by %%.
kill w - Terminate the gnutella connection with the worst dropped-duplicate packets statistic.
hosts range - Displays the current host catcher, this can result in a lot of information!
limit num range - Limit the transfers referenced by %% to bytes per second.
log num - Set the current log level to #.
share paths - Takes a ":" delimited list of paths to share. (";" on Win32)
scan - Rescans the files in the share paths.
play range - Runs the program set in play_prog with the URL of queries %% as arguments.
set key val - Sets a configuration value. See Section 4.3.
set key - Displays a configuration value. See Section 4.3.
sleep num - Do nothing for num seconds.
quit - Quit gnut.
4.3 Configuration Variables
Nearly every aspect of gnut can be configured using it's built in configuration system. All configuration variables can be considered to either be numeric, or alphanumeric. If you enter non-numeric characters into a numeric variable, it will just be treated as a zero.
Follows is a list of all the available configuration variables, along with a short description of how it affects gnut's operation. In most cases, each variable only controls one small aspect of gnut, allowing for a wide variety of possible configurations.
User Interface
auto_clear - Boolean, if set to 1, transfers are removed from the transfer list after completion without user intervention.
beep_on_first - Boolean, if set to 1, an audible tone is emitted after the first search result of a new query is received (but only if wait_after_find is also set).
beep_on_all - Boolean, if set to 1, an audible tone is emitted whenever the number of search results goes up (but only if wait_after_find is also set).
download_path - String, directory where downloads should be stored.
munge - Boolean, if set to 1, large numbers are displayed with unit postfixes.
packet_stats - Boolean, if set to 1, a large amount of interesting statistics are shown in the connection information list.
stats_format - Boolean, defaults to 0. If set to 1, the connection stats will be in the same format as Windows Gnutella 0.56 (one line per connection). The three numbers (e.g. "2407,4260,850") give packets sent, received and dropped. "Dropped" packets are duplicates that have been seen before; a large number means that two of your connections (this one and one other) are connected to each other by another, short route. See the autokill_thres option.
paginate - Boolean, if set to 1, gnut will stop for user input after a screen-full of information has been displayed. This allows for easy viewing of long lists.
play_prog - String, the program to be used to stream media files.
sort_order - String, series of characters indicating what fields should be sorted on when using the response command. A sort string has the following format:
"?[+-]?[+-]..." ? is a single character from the following set: s = size p = speed e = extension + indicates asecending order, - indicates descending order For Ex: "e+s-" sorts by extension, followed by size in descending order.
verbose - Boolean, if set to 1, the user is immediately notified of when downloads start, when they succeed, and when they are enqueued.
wait_after_find - Boolean, if set to 1, the find command displays a pretty little indicator showing how many results have come in. Otherwise they just come in the background.
Paths
download_path - String, the directory where downloaded files are written.
share_paths - String, directories where scanning for uploadable files occurs. Setting this variable has the same effect as the share command.
Limits
Numerical limits, as well as bandwidth limits are supported for transfers and connections. The following variables control this operation.
default_download_cap - Numeric, all new downloads are initially limited to this many bytes per second.
default_upload_cap - Numeric, all new uploads are initially limited to this many bytes.
global_bandwidth_cap - Numeric, the sum of all upload and download bandwidths is limited to this.
max_downloads - Numeric, maximum number of simultaneous downloads to allow. Any more than this are queued.
download_timeout - Numeric, defaults to 3600. This is the number of seconds a download connection will wait before "giving up". Some Gnutella hosts make you wait before connecting if they have reached their max_downloads limit (Others allow the connection but wait before sending the data). Prior to version 0.4.8, the timeout was 10 but you couldn't adjust it.
max_incoming - Numeric, the gnutella protocol requires that clients connect to other clients. This allows you to limit the number of other clients connected to yourself.
max_uploads - Numeric, the maximum number of outgoing file transfers allowed at any one time. New requests are denied after this number is reached.
Password Protection
Gnut can form password protected mini-networks. The password is negotiated with each other gnutella servant that is connected to.
password - String, phrase to use for authentication with remote hosts.
password_required - Boolean, if set all incoming gnutella connections will be verified against the password.
Network and Performance Settings
These pertain to the gnutella network and protocol, and most users will have no need to mess with them.
autokill_thres - Numeric. Defaults to 10. This is a percentage from 1 to 100 (set to 0 to disable autokill). With autokill enabled, gnut will periodically scan the connection list for connections that have at least this percentage of duplicate packets. It only kills one at a time, and the frequency of checking is 16 minutes divided by the number of connections. If you have 4 connections, gnut will check once every 4 minutes; if you have 8 it checks once every 2 minutes, and if you have 16 it checks once per minute.
The effect of autokill is to gradually move the connections around until they're connected to different points as "far" from each other as possible. When your connections are "far" from each other you get a greater coverage of the Gnutellanet as a whole, which improves search results; you also get fewer duplicate packets, which improves efficiency.
hidden - Boolean, if set, the client will not respond to pings, and thus will not end up in any other client's host catcher.
local_port - Numeric, read-only, the port to which gnut is bound. If you wish to change this, you have to use the command-line option.
redirect - Boolean, when set, behavior when the maximum number of incoming connections is reached changes. Instead of ignoring all new connections, the oldest one is dropped and new connections are never refused. This can be used to set up a high availability entry point into the gnutella network.
speed - Numeric, speed to broadcast us as over the network. This is mostly meaningless.
ttl - Numeric, the TTL to use for new packets, and to limit routed packets to.
HTML interface
If you point your web browser to a gnut servant on the correct port, it has the ability to show a list of the shared files. You can also search the gnutella network through this interface. That way you could set up a gnut server that you can use from any web browser, and not necessarily be at your computer.
html_enable - Boolean, if set to 1, the html interface is enabled.
html_template - String, path to an optional html template file. See section 4.5.
Caching
As of gnut 0.3.27, caching of frequently requested files is supported. Gnut will watch all gnutella connections for query responses, and randomly download files into a local cache. This is intended to help distribute the load of highly requested files across many computers.
cache_path - String, set to the directory where you want cached files to be stored.
cache_refresh - Numeric, number of seconds between updates to the cache.
cache_size - Numeric, maximum number of kilobytes to allow the cache to grow.
4.4 Configuration File
Gnut is capable of executing files consisting of gnut commands. Upon startup it defaults to loading the file ~/.gnutrc (Win32 users can put this file in the current working directory). The actual name of the file can be set as a command-line option. All the commands are executed before any user input is requested.
4.5 Web Access
You can access a list of all files shared by a Gnut servant by
creating a connection to them from within a web browser. To test it
for yourself, just enter something like http://127.0.0.1:5634
(if 5634
is your Gnut port) in your browser's address bar (127.0.0.1 is a special
address that means "connect to my own computer"). A list of all your
shared files should come up. By giving your IP address to others, you
can let others access your files over the web. They can also search
the gnutellaNet through your servant by clicking on "Refresh Response
List." Nifty, eh?
Gnut can use a template file for this interface. It is specified in
the html_template configuration variable. This file is a standard HTML
file, except that you embed the comment <!-- gnut -->
where you want
the gnut specific stuff to go.