Gnut Manual: Advanced Usage

Next Previous Contents



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 #. See the Debugging portion of section 4.3 below.

-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. See section 4.4.4 for more about daemon mode.

-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 italics, for example arg. The # sign is used to indicate a scalar number. "range" is used to indicate a list and/or range of numbers. These ranges can be specified in several ways. 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 [ctud] - Display list of current connections. The letters are:
     c - GnutellaNet connections
     t - file transfers in progress (both upload and download)
     u - upload transfers in progress
     d - download transfers in progress

The format of info c is controlled by the setting of stats_format (see below).

For transfers (info t, info u, info d) it displays IP address of host at other end of transfer, percent complete, bytes complete / total bytes, bytes per second, ETA (estimated time until it will be complete), TID (an internal ID number), Type, State, and requested full pathname.

The "Type" is always IN, OUT, PUSH IN or PUSH OUT. The "State" is one of the following:

CONN, CON1, CON2, CON3 or CON4 - connection opening at the socket level (usually waiting for the select(2) kernel routine to time out). The numbers indicate which line of code set the state (look at the source code if you really care)
NEGOT - Gnutella greetings being sent
UP - normal state when a connection is fully open
CLEAN - closed by other end, waiting to be closed at this end
DONE - transfer finished normally, waiting to be closed by this end
ERR - an error occurred, waiting to be closed by this end
QUEUED - too many connections already open (due to max_uploads or max_downloads and will enter CONN once another connection finishes
RETRY - a download that couldn't connect and is waiting a few seconds to try again (according to auto_download_retry)

info [hqns] - Display other types of information.
     h - Number of hosts, number of files they're sharing, and total size of those shared files
     n - GnutellaNet statistics: packets received and sent, number of unique packet GUIDs in memory, total Gnutellanet bytes received and sent so far
     q - queries received and replies sent
     s - number and total size of shared files on this machine

open host:port - Open outgoing connection to a host.

find string - Search the Gnutella network for string. The string you supply is is sent as-is to the network. Nearly every Gnutella node (servent) specifies this as a boolean AND search with all non-alphanumeric characters ignored and ignoring upper/lower case. If you want to force all results to be boolean AND matches, set the strict_search configuration variable. If you want to force non-alphanumeric characters to be ignored, simply leave all non-alphanumeric characters out of your search string.

If you have set the multi_enable variable, you can perform more than one find at the same time; this also enables the list and lclear commands.

search string - Synonym for find.

find or search with no argument displays results.

list - Shows all searches currently going on (if multi_enable is set). You can remove searches and their results from the list with the lclear command.

lclear id - Clear a search and its associated results. The id is a number shown in the output of the list command.

lclear string - You can also clear a search by giving the text that was used to issue the search.

forget range - Eliminate some search results from the list shown by the response command. You won't see those search results again until you start a new search, or (if multi_enable is set) clear all searches with lclear. This is useful for manually filtering out files that are not of interest to you.

If you set the auto_forget option, gnut will automatically forget every file you get or push. This is useful to people who only want to try each file once. By eliminating the files you've tried from the list, it lets you more easily see what you have not yet tried to download.

forget keywords - The forget command can also be issued with alphanumeric keywords. It eliminates search results that match the given keywords. Case is ignored, and all keywords must match for an item to be eliminated.

Usually it is better to add more keywords to your initial search, but when that is not possible, forget is a useful alternative. For example, a search for apple pie might get a lot of results for apple rhubarb pie. You cannot do a Gnutella search for "apple and pie without rhubarb", but you can accomplish almost the same thing by searching for apple pie, then after the results come in type forget rhubarb.

forget = number - The forget command with an '=' sign and the number of an item in the search reply list will forget all items in the search reply list that have exactly the same combination of words, letters and/or numbers. Case is ignored and all symbols and whitespace is ignored. For example, if item number 7 in the list shown by response is apple pie.txt, then forget = 7 will remove any items called apple pie.txt, or Pie Apple.txt, apple_pie.TXT, etc.

forget s number - forget with 's' and the number of an item in the search reply list will forget all items in the search reply list that have exactly the same size as the specified item. This is sometimes useful for filtering out things that you don't want, in situations where the file size is a likely indication of whether two files are identical. Such is often the case with files containing images, music, and video.

monitor keywords - Monitor incoming search queries. If arguments are supplied, they are used for a boolean AND match (ignoring case) before displaying search queries. So, for example, monitor fred jpg will only display search queries that contain both 'fred' and 'jpg'.

mreply keywords - Monitor replies to search queries that others have issued. While monitor lets you see what people are searching for, mreply lets you find out what's actually available on the network. As with monitor, arguments can be given to specify a boolean AND match (ignoring case) before displaying filenames.

mpush keywords - Monitor push requests issued by others. While mreply lets you see what files are available on the network, mpush lets you find out which of those files are actually in demand. NOTE: Push requests are kind of rare, and gnut cannot always identify the file being requested. So, you won't see much when you use mpush. Try it sometime when you can let it run for an hour or two.

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 range. If more downloads are requested than allowed by max_uploads, then the downloads are queued. The auto_download_retry flag affects the behavior of get, see below.

push range - Same as get, however only a push connection is attempted.

stop [gpd|u] 0 - Stop the transfers referenced by range, or all zero-data transfers if 0 is specified in place of range, or all transfers if no range is given, optionally with a category letter g, p, d, or u.

The letters are:
     g: all 'get' downloads
     p: all 'push' downloads
     c: downloads to file cache (see section 4.4.2)
     d: all downloads
     u: uploads (both normal and pushed)

The special range 0 tells gnut to stop only those transfers which have transferred 0 bytes. 0 combined with another number or number range(s) does different things depending on where the 0 is placed. 0 doesn't affect any numbers that come before it; it places the zero-data restriction on any numbers that come after it, and if it comes last or appears without any other numbers, 0 causes all zero-data transfers to be affected.

A letter can be combined with 0 and/or numbers, but you can only use one letter.

Here are some examples to make all that a bit clearer:

     stop - Stop all file transfers in both directions

     stop d - Stop all downloads of both types (get and push)

     stop 0 - Stop all transfers (both upload and download) that have not yet transferred any data

     stop g 0 - Stop all 'get' downloads that have not yet transferred any data

     stop p 5-10 - Stop all 'push' downloads whose numbers are from 5 to 10

     stop 0,4-6 - Stop transfers that have transferred no data but only if they're numbered 4 through 6.

     stop 4-6,0 - Stop transfers 4 through 6, and then also stop any other transfers that have not transferred any bytes yet. Notice the difference between this and the previous example!

     stop u 4-6,0 - Same as previous example but only affects uploads.

     stop 1-3,0,6-8 - Stop transfers 1 through 3, then stop zero-byte transfers numbered 6 through 8.

     stop d 1-3,0,6-8 - Same as previous example but only affects downloads.

Note that if you use a number range (like '4-6'), the numbers you give come from the info command. You must type an info, info t, info d or info u command first to display the numbers -- gnut doesn't assign numbers until you type the info command. So, any new transfers that have started since you last did an info command will not be affected by the number range because they don't have numbers until you display them with the info command.

clear range - Removes finished transfers from the transfer list. If no range is given, all completed transfers will be removed. You can also set the auto_clear variable to make this automatic. Range numbers work the same way as for the 'stop' command.

last - If a download fails, it's usually because the server is busy. you can sometimes see an error message by typing this command -- it shows any text (up to 1024 characters) sent back by a server before refusing a download. See also the verbose configuration setting.

kill range - Terminate the GnutellaNet connections referenced by range. Numbers in range refer to the numbers shown in the info c command.

kill w - Terminate the gnutella connection with the worst dropped-duplicate packets statistic.

blacklist args - Add one or more hosts, port numbers, subnets, or search reply strings to the blacklist. All Gnutella nodes on the blacklist, and all query replies that match the blacklist will be ignored. Used properly, this can eliminate lots of spam. (See also the search_extensions and strict_search variables)

Syntax of the arguments is:

blacklist [ host hostname [subnet bits]] [search string] [ all | ping | search | incoming | outgoing | http ]

The many forms of the blacklist command are best explained by example:
blacklist host 1.2.3.4 all Blacklists one host: All queries, replies, connection attempts, etc. from that host will be ignored.
blacklist host 1.2.3.4 incoming Prevents incoming connections from one host, but other activity (searches, etc) involving that host is still allowed.
blacklist host 1.2.3.1 subnet 8 Blacklists everyone from 1.2.3.1 to 1.2.3.255 (the "8" refers to the last 8 bits of the IP address).
blacklist search hitler Stops any search that includes "hitler" from passing through this server, and prevents such files from being added to the file cache (see section 4.4.2)

See also the save command.

hosts - Displays the current contents of the host list. WARNING: this will probably display more information than you want to see! The lines look like this:

     123.45.67.89:1011 3861 10460353203

These numbers are IP address and port, files shared, bytes shared. If you set munge, the bytes shared will be abbreviated the same way the numbers in info h are.

hosts file - Reads in a gnutella-hosts file. The filename or pathname must be resolved (that is, the special character '~' for home directory will not work).

#limit num range - Limit the transfers referenced by range to num bytes per second.

log num - Set the current log level to num. See description of log_level in the Debugging section below.

share paths - Takes a ":" delimited list of paths to share. (";" on Win32) If a pathname contains any blank spaces, it should be in quotes. This example shows how to include multiple paths with one path in quotes:

share "/dos/My Documents/Music":/home/fred/gnut/shared-files

scan - Rescans the files in the share paths.

play range - Runs the program set in play_prog with the URL of queries range as arguments. If play_prog is configured and installed properly, it will connect to, tranfer (if possible), and stream the data.

player mime_type mimetype extention extension player program - Attach a player program to the given filename extension and MIME type. This command allows you to specify different programs for each type of file that you might want to play with the play command. There are six arguments, three are always the same. Two examples are:

player mime_type image/jpeg extension jpg player ee
player mime_type image/gif89a extension gif player xv

set key val - Sets a configuration value. See Section 4.3.

set key - Displays a configuration value. See Section 4.3.

save - If you have changed configuration variables, or have blacklisted anything with the blacklist command, this command saves the settings in the appropriate files .gnutrc and .gnut_blacklist. It also saves the current host list in .gnut_hosts. WARNING: If you have any commands in .gnutrc aside from set commands, you shouldn't use save because it will overwrite .gnutrc and erase those other commands.

sleep num - Do nothing for num seconds.

cls - Clears the screen (UNIX users only)

load file - Read a file that contains gnut commands and execute them. type help load for an example.

! cmd args - Shell escape: runs a shell and sends a command to it (UNIX users only) Type help ! for examples.

eval cmd args - Evaluate shell escape: runs a shell and sends a command to it, then executes its output as gnut commands. (UNIX users only) Type help eval for an example.

The eval_echo configuration vaue determines if the commands executed by eval are printed. Of course, it can be set and cleared within an eval. Here is a script that uses this. It issues an update command and then checks the host count every 5 seconds for 10 minutes. Note the use of shell escape and echo at the end to print a message.

        #!/usr/bin/perl
        print "set eval_echo 0\n";
        print "set update_clear 1\n";
        print "update\n";
        $i = 0; $sl = 5;
        while($i < 10 * 60) {
          print "info h\n";
          print "sleep $sl\n";
          $i += $sl;
        }
        print "info h\n";
        print "! echo ---- test done ----\n";

`cmd args` - A shell command can be enclosed in back-quotes and included as part of any other gnut command. This works like eval, except that only the last line of output from the shell command is used as part of a gnut command. For example, try:

       set prompt `date` > 

quit - Quit gnut.

exit - Synonym for quit.


4.3 Configuration Variables

Nearly every aspect of gnut can be configured using its 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.

To set a value, type a command like set variable_name 1. For convenience, "-" characters are treated like "_" for variable names. To display a variable's current value, type the command without a value: set variable_name.

In most cases, each variable only controls one small aspect of gnut, allowing for a wide variety of possible configurations.

Here are the configuration variables by category:

Searching: no_rfc_1597, strict_search, search_extensions, search_min_size, multi_enable, max_responses

Search Scoring and Rating: search_min_rating, score_available, score_did_upload, score_did_receive

Downloading: auto_download_retry, retry_push, leave_turds, download_path

User Interface: prompt, auto_clear, auto_forget, beep_on_first, beep_on_all, download_path, munge, stats_format, paginate, play_prog, sort_order, verbose, wait_after_find

Paths: download_path, share_paths, follow_symlinks

Bandwidth and Connection Limits: default_download_cap, default_upload_cap, global_bandwidth_cap, max_downloads, download_timeout, max_incoming, max_uploads

Network and Performance: autokill_thres, hide_pathname, max_results, hidden, local_port, redirect, speed, ttl, http_client_headers, host_list_size

File Cache: cache_path, cache_refresh, cache_size, min_cache_size, cache_parallel (see section 4.4.2)

HTML Interface: html_enable, html_template (see section 4.4.1)

Daemon Mode: checkpoint_hosts, checkpoint_net (see section 4.4.4)

Security: password, password_required

Logging: transfer_log, search_log, search_log_all

Debugging: packet_stats, log_level, eval_echo

Alphabetical List of Configuration Variables

auto_clear - Boolean, defaults to 1. If set to 1, transfers are removed from the transfer list after completion without user intervention.

auto_download_retry - Numeric, defaults to 60. If set to any non-zero number, gnut will automatically restart any incomplete downloads, and will automatically retry any failed download connection. The interval between retries starts at 10 seconds, then gets gradually longer until it reaches whatever number you set auto_download_retry to (default is 60 seconds). If you set a negative value, it will always delay exactly that amount (for example, if you set it to -30, it will delay 30 seconds the first time and every time) Set auto_download_retry to 0 to disable auto-retry. Changes to auto_download_retry take effect after the current delay period has finished.

Please be aware that auto retry does not guarantee a file will finish transferring. Sometimes the computer with the file disconnects from the network.

auto_forget - Boolean, defaults to 0. If set to 1, gnut will automatically forget every file you get or push. See the description of the forget command in section 4.2.

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.

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).

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).

cache_path - String, set to the directory where you want cached files to be stored (see section 4.4.2). This should be a full path, like "/home/fred/gnut/cachedir".

cache_parallel - Numeric, defaults to 1. Specifies the number of parallel downloads that gnut should use for filling the file cache (see section 4.4.2). If you have a slow internet link, increasing this won't do much. When decreasing cache_parallel, the number of downloads won't go down until downloads actually complete; to make them stop sooner you'll have to stop them manually via the stop command.

cache_refresh - Numeric, number of seconds to wait before starting a new download attempt for the file cache (see section 4.4.2). For example, if you set cache_refresh to 10, gnut will try a new download every 10 seconds (but it doesn't try a new download if the cache_parallel limit has already been reached).

cache_size - Numeric, maximum number of kilobytes to allow the file cache (see section 4.4.2) to use. When the file cache directory reaches this size, the oldest files in the cache get deleted to make room for new ones.

checkpoint_hosts - Numeric, defaults to 600. Affects daemon mode only. If set to a non-zero value, gnut in daemon mode will save the host list to ~/.gnut_hosts periodically; the value tells how many seconds to wait between saves.

checkpoint_net - Numeric, defaults to 60. Affects daemon mode only. If set to a non-zero value, gnut in daemon mode will periodically check to see if your IP address has changed; the value tells how many seconds to wait between saves.

default_download_cap - Numeric, defaults to 0. If set to a nonzero value, each download is limited to this many bytes per second, unless specifically set with the limit command. Any downloads that do not currently have a limit command applying to them will immediately respond to changes in default_download_cap, unless their speed is limited by a bottleneck somewhere out in the network. See also the note in the description of global_bandwidth_cap.

default_upload_cap - Same as default_download_cap, but for uploads. See also the note in the description of global_bandwidth_cap.

download_path - String, the directory where downloaded files are written.

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.7, the timeout was 10 but you couldn't adjust it.

eval_echo - Boolean, defaults to 1. If set, the eval command prints the gnut commands it is going to execute before executing them.

follow_symlinks - Boolean, defaults to 1. If set, symlinks will be dereferenced (followed) while scanning the files in the search paths.

WARNING: You should set follow_symlinks to zero if you are sharing directories which are world-writable. The reason is that someone could put a symlink to your home directory in the shared directory, then the next time you start gnut, your gnut would be sharing your private files!

global_bandwidth_cap - Numeric, defaults to 0. If set to a nonzero value, the sum of all upload and download bandwidths is limited to this many bytes per second. Changes take effect immediately. All the limits are enforced simultaneously, with the result that the actual bandwidth used will always be less than global_bandwidth_cap, and each individual transfer will also be limited by default_upload_cap or default_download_cap or its individual limit set by the limit command. This means that your actual total bandwidth usage will usually be lower than global_bandwidth_cap. But note that the GnutellaNet connections use some bandwidth too; each one uses an average of about 1000 bytes per second in each direction. The bandwidth used by the GnutellaNet connections is controlled only by min_connections and max_incoming.

hidden - Boolean, if set, the client will not respond to pings, and thus will not end up in any other client's host catcher.

hide_pathname - Boolean, defaults to 0 (false). When set, the files you share will be shown to others as filenames, not full pathnames. This setting does not affect searches -- if they search for "abc" and the files are in a directory called "abc", the search will match. This is the way the original Windows Gnutella client worked, and most clients only show filenames.

host_list_size - Numeric, defaults to 10000. This is the maximum number of hosts gnut will remember in memory and in the .gnut_hosts file. gnut keeps this list for two reasons: to establish new GnutellaNet connections when needed, and to maintain the files and bytes totals displayed by info h. Because hosts are always joining and leaving the network, and because active hosts do not always advertise their presence or accept connection requests, it is impossible to ever get a complete list of active hosts. Therefore, when the list reaches the size specified by host_list_size, gnut just starts deleting the oldest entries in the list, and any hosts that are actually active insert themselves back in the list when they send packets. If you set host_list_size to (for example) 5000, info h will show a pretty close approximation of the 5000 hosts that have been active most recently.

If you increase host_list_size, gnut will be able to accumulate a higher total in the info h display. However, the higher total is probably misleading, because many hosts leave the network and re-join later with a different IP address, thereby appearing to be a different host. Until gnut deletes the old entry from the list, that host would be getting counted twice.

Please also note that the number of hosts you can "see" depends on both the TTL (see the ttl setting) and the number of GnutellaNet connections min_connections plus max_incoming), plus autokill_thres. See notes under those settings for more info.

html_enable - Boolean, if set to 1, the HTML interface is enabled. See section 4.4.1.

html_template - String, path to an optional HTML template file. See section 4.4.1.

http_client_headers - String, contains the extra header lines sent between the GET line and the "Range:" header (if any) when initiating a download. By changing this you can emulate a web browser or a different Gnutella client. Look at the default value (type "set http_client_headers" at the gnut prompt before it's been set to something else) to see what the syntax looks like. If setting this in your .gnutrc, do not put quotes around the string. Put "\n" everywhere you want to have a newline, including at the end. Don't put two \n's in a row. Be very careful -- if the syntax is wrong all downloads will fail.

leave_turds - Numeric, defaults to 512. Failed downloads less than this size will be automatically deleted. Set it to 0 to leave all failed downloads in place; set it to 1 to delete only zero-length turds; set it to 2000 to delete anything less than 2000 bytes. You get the idea.

If you want gnut to always delete all partial downloads, you can set leave_turds to a really high value like 2000000000 (2 billion). However, be aware that this partly defeats the purpose of auto_download_retry, because it will have to start over from 0 every time it retries.

local_port - Numeric, read-only, defaults to 5634. This is the port number for all incoming connections to gnut. Another popular port number is 6346 (used by most of the Windows clients). The number doesn't matter much unless you have firewall or gateway restrictions on port numbers. Changing local_port after gnut is running has no effect, but you can put "set local_port 12345" in your .gnutrc file or use the -p num command-line option.

NOTE: If you set local_port in the .gnutrc file, the set local_port command must occur at the beginning of the .gnutrc file. The following will not work:

open server1.foo.bar:6346  gnut will choose its own local_port here
set local_port 6346        too late

log_level - Numeric, defaults to 0. Sets the current log level. This is also set by the -l command-line option and the log command. Any nonzero value causes debugging information to be printed out. Larger numbers give more output. Anything higher than 2 is probably more output than you want to see. (However, you can type between the lines.)

max_downloads - Numeric, maximum number of simultaneous downloads to allow. Any more than this are queued.

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_incoming does not affect the number of file uploads (use max_uploads for that) and does not interfere with receiving files via the push command.

max_responses - Numeric, defaults to 1000. The maximum number of search results that gnut will keep. Please note that if you increase this a lot, your gnut will use a lot of memory (results use an average of 200 kbytes per 1000 results)

max_results - Numeric, defaults to 64. The maximum number of files that gnut will return to others doing queries. If a query matches more than this number of files, only the first matches will be returned.

max_uploads - Numeric, the maximum number of outgoing file transfers allowed at any one time. New requests are denied after this number is reached. max_uploads does not affect the number of incoming GnutellaNet connections (use max_incoming for that) and does not interfere with receiving files via the push command.

min_cache_size - Numeric, minimum size of a file (in kilobytes) required for it to be stored in the file cache (see section 4.4.2). Any files smaller than this size will not be cached.

multi_enable - Boolean, defaults to 0. If set to 1, allows multiple simultaneous searches. This involves a slightly more complicated interface because the results list has to be manually cleared to get rid of old search results. (That's why this setting is not enabled by default).

munge - Boolean, defaults to 1. If set to 1, large numbers are displayed with SI unit postfixes k, M, G and so on. Otherwise, you'll get scientific notaion. For example:

     munge = 1: Bytes Sent: 6.080M
     munge = 0: Bytes Sent: 6.08023e+06

NOTE: To comply with international standard, the SI prefixes always refer to powers of 1000, not 1024. See FAQ question 5.17.

no_rfc_1597 - Boolean, defaults to 0. If set to 1, searches will find lots of files on hosts behind firewalls that you cannot reach. See question 5.4.3 in the next section of the manual for more details. Please note that RFC 1597 is an Internet standard which all ISPs and firewalls are required to obey in order to be compatible with the Internet, so you really absolutely cannot reach certain addresses and there is no practical advantage to seeing such hosts in your results list. However, if you're just curious as to what you wouldn't be missing if you weren't behind a firewall, you can turn on this setting. Note that the setting has no effect if you are not behind a firewall yourself, because in that case all addresses are reachable to you through a PUSH connection.

packet_stats - Boolean, if set to 1, a large amount of (possibly interesting) statistics are shown in the connection information list.

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.

password - String, defaults to null. gnut can form password protected mini-networks. The password is sent to each other gnutella servant that is connected to.

password_required - Boolean, if set all incoming gnutella connections will be verified against the password.

play_prog - String, the program to be used to stream media files.

prompt - String, the text displayed each time gnut is waiting for a command. By default, this is "gnut> ". If any of the following special strings is included in prompt, they will be replaced with values as described here:
${HOSTS} The number of hosts in the host list.
${FILES} The number of files on active Gnutella servers on the network.
${SIZE} The total size (in megabytes) of files on active Gnutella servers on the network.
${MSGS_R} The total number of packets received over all connections since gnut started.
${MSGS_S} The total number of packets sent out over all connections since gnut started.
${BYTES_R} The total number of bytes received over all connections (not including downloads) since gnut started.
${BYTES_S} The total number of bytes sent out over all connections (not including uploads) since gnut started.
${QUERIES} The total number of query packets received over all connections since gnut started.
${QUERY_RESP} The total number of query replies sent since gnut started.
${NUM_SHARED} The number of files you're sharing.
${SIZE_SHARED} The total size (in kilobytes) of the files you're sharing.
${RESPONSES} The number of responses to your latest (current) find or search.
${BLACKLIST_S} The number of hosts that have been blacklisted.

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. (Note: a bug caused this to not work correctly in all versions from 0.4.7 to 0.4.20 inclusive)

results_format - String, defaults to "{f#}){N/I:P}size: {S}score {r}". This string controls the format of the search results given by the find command with no arguments, the response command, etc.

Within results_format, special letters are enclosed in curly braces. These special letters produce the actual information in the search results. The available special letters are:
# Item number in list. You need to know this number to use the get and push commands!
f Flag letter: g for files you've tried to get with get, p for files you've tried to get with push.
I Server's IP address
N File's name
n File's Gnutella refnum. This isn't very interesting but it provided because the older versions of gnut used to display it.
P Server's port number
R Rating for this file, from 0 to 4 stars. Half stars are dots "." For example, a 2 1/2-star rating will look like "**. ".
r Rating for this file in numerical form. The rating is always from 0 to 143 because when shifted right by 4 (divided by 16) you get a number from 0 to 8, which is used to pick one of the 9 star-ratings from 0 to 4 stars.
S Size of the file
s Server's speed in kbytes per second. Note that this is included in the rating, so if you display the rating you probably don't need the speed too.
/ A newline (goes to the next line)

Any characters that are not in the list, not in curly braces, or out of place (like extra braces that don't match) get printed. So, for example, if you set results_format to "{{#}} {R N}" you'll get the item number in curly braces, because the '#' has an extra left-brace and an extra right-brace.

retry_push - Numeric, defaults to 1. If set to 1, gnut will use push requests as part of its retry procedure for files that cannot be downloaded by a direct connection. If set to 2, gnut will send push requests even when the remote host's IP address makes it appear to be unreachable. If retry_push is set to 0, gnut will never issue push requests except when you explicitly start one with the push command.

score_available - Numeric, defaults to 50. Controls the number of points assigned to the "available" attribute in the scoring and rating system (see section 4.4.5).

score_did_upload - Numeric, defaults to 30. Controls the number of points assigned to the "did upload" attribute in the scoring and rating system (see section 4.4.5).

score_did_receive - Numeric, defaults to 40. Controls the number of points assigned to the "did receive" attribute in the scoring and rating system (see section 4.4.5).

search_extensions - String, contains list of filename extensions to use as a filter against search results. For example, if set to "jpg txt", only files ending in ".jpg" or ".txt" will appear in search results. If search_extensions starts with "*", it will match all search results. Putting a "*" anywhere else in search_extensions has no useful effect. This setting defaults to "*".

search_log - String, defaults to null (none). If set to a filename or pathname, gnut will add a line to the specified file each time it returns results to a search query. WARNING: If you are sharing files this will cause a lot of stuff to be logged!

search_log_all - Boolean, defaults to 0. If set, and if search_log is also set, gnut will log searches even if they don't match any of your shared files. WARNING: This will use up a lot of disk space!

search_min_rating - Numeric, defaults to 0. If set to any value from 1 to 143, it sets a minimum rating (see section 4.4.5) for files to match a search. This table shows some sample values to use:
set search_min_rating 32 1 star (*   ) or more
set search_min_rating 64 2 stars (**  ) or more
set search_min_rating 96 3 stars (*** ) or more
set search_min_rating 128 Must have 4 stars (****)
In-between values work as well. The maximum score a file can possibly have is 143 because a rating of 144 would be "41/2 stars".

search_min_size - Numeric, defaults to 0. If set to any positive number, this sets a minimum size for files to match a search. For example, if you set it to 10000, all search results less than 10000 bytes in size will be ignored. This is sometimes useful for filtering out spam and other "worthless" files.

share_paths - String, directories where scanning for uploadable files occurs. Setting this variable has the same effect as the share command. The syntax for multiple paths and quoting is similar, as shown by this example:

set share_paths "/dos/My Documents/Music":/home/fred/gnut/shared-files

sort_order - String, defaults to "s-p-". A 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:

      r = rating (0 to 4 stars)
      C = combined rating and size (see below)
      s = size
      p = speed
      e = extension
      i = IP address

      + indicates asecending order, - indicates descending order

For example: e+s- sorts by extension in increasing order, with files of the same extension sorted by size in descending order.

The special letter C combines the rating and the file size by multiplying them together. For example, a 2-megabyte file with a 2-star rating would count the same as a 1-megabyte file with a 4-star rating.

speed - Numeric, defaults to 56. Your Internet sccess speed in kbytes per second. This is important for getting accurate scores in the search response list, because most hosts send measured speeds and that speed needs to be compared to your speed to evaluate an actual predicted download speed. See section 4.4.5 for more about the scoring system.

stats_format - Boolean, defaults to 0. If set to 1, the connection stats (info c) 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.

strict_search - Boolean, defaults to 1. If set to 1, results of find or search will be filtered against the original search string, using a boolean AND match of all words in the string, ignoring case but not ignoring punctuation. This is useful because many other nodes on the Gnutella network do not use a boolean AND match, and almost all ignore punctuation. If strict_search is turned off, searches for "Mike" and "I'm Mike" will return the same matches, because most servents will ignore the ', and because the letters I and m are part of the word Mike. But with strict_search turned on, the "I'm Mike" search will only return filenames that actually contain both I'm and Mike. strict_search also guarantees that a search for "John John" will show files that have two John's in them. And, it filters out some spam (results from servers that return results even if those results don't match your search at all).

transfer_log - String, defaults to null (none). If set to a filename or pathname, gnut will add a line to the specified file each time something gets downloaded from your machine.

ttl - Numeric, defaults to 7. The TTL value to use for new GnutellaNet packets, and the limit to impose on routed packets. WARNING: If you increase your ttl too far you risk being "ignored" by your neighbors on the network, and if you set it too low you won't see many hosts. Read the section below Choosing the TTL value before changing ttl from its default value.

verbose - Numeric, defaults to 3. Controls messages that notify when uploads and/or downloads start and end. The settings are:
0 No messages
1 Print messages related to downloads.
2 Print messages related to uploads.
3 Print messages related to both downloads and uploads.

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.


4.4 Special gnut Features

4.4.1. 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.

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 "Search the GnutellaNet". So if your address and port were (for example) 12.34.56.78:9011 then they would type http://12.34.56.78:9011 in their location bar. If 12.34.56.78 were registered as a domain name "gnut.fred.foo", they could type http://gnut.fred.foo:9011

gnut can use a template file for the HTTP 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. gnut| will place its stuff into the template and serve the result as the "main page".

4.4.2. File Cache

gnut can automatically download files that are frequently requested on the network and offer them as shared files to others; this is called the file cache. If the file cache is enabled, gnut will watch all gnutella connections for query responses, and randomly download files into a local directory. Frequently requested files are more likely to be cached because they are more commonly found in the search replies. The main purpose of the file cache is to help distribute the load of highly requested files across many computers. By enabling the cache, you help other people download files that they might not otherwise be able to get. If you don't want to do this or if you don't want to deal with the extra doanload traffic and disk space, leave the cache disabled.

To enable the cache, set each of the variables cache_path, cache_refresh, and cache_size. You might also want to change min_cache_size and cache_parallel. See the descriptions of these variables in section 4.3 above.

If you are using the file cache and have the ability to play mp3 files, you might want to check out the GDJ script, described in chapter 7.

To disable the file cache, set cache_path to a null string "" or set cache_size or cache_parallel to 0. You might also wish to use stop c to stop the current file cache downloads. If you never want the file cache again, you should probably also delete the cached files in the directory that was your cache_path.

4.4.3. Configuration Files and Scripting

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.

To run a config file as a script, use the load command. Config files are just a list of commands, there is no provision for calculation, testing conditions, looping, etc. For slightly more flexibility, you can write a perl or shell script and run it with the ` or eval commands (described in section 4.2). The script will still not be able to look at gnut's output, but it can do an ls on the downloads folder to determine (for example) when the current downloads have completed. Also, to prevent runaway scripts from spamming the network, gnut imposes a limit on network activity generated by load, eval and `.

4.4.4. Daemon Mode

You can run gnut as a daemon (server-only, no command-line interface) by launching it this way:

  bash# gnut -d &
It will print the initial startup messages (such as the settings in .gnutrc) and then will print the message:
  gnut *version* Entering no output mode, have fun!
From this point on there will be no output from gnut, and it is running in the background. You can still connect to it through a web browser as described in the previous section.

Users have reported that gnut in daemon mode does not run directly under cron, but they succeeded in getting it to run inside a shell script, and the shell script runs under cron.

You can also start gnut the normal way, type some commands, and then enter daemon mode by typing control-D. However, you cannot then put gnut in the background with control-Z and log out. If you want to run gnut that way, start it up with gnut -d & or use the shell script method mentioned in the previous paragraph.

To stop a gnut daemon, use the ps command to discover its process ID:

  bash# ps aux | fgrep gnut
  USER       PID %CPU %MEM   VSZ  RSS TTY      STAT START   TIME COMMAND
  fred     20510 35.0  1.9  2856 1856 pts/2    S    23:16   0:01 gnut -d
  fred     20534  0.0  1.9  2856 1856 pts/2    R    23:17   0:00 gnut -d
  ...
(Note on your version of UNIX your ps options might have to be different) There are multiple "gnut -d" lines because gnut is multithreaded; each GnutellaNet connection and each upload and download shows up as a separate thread.

Stop the daemon with this command:

  bash# kill -SIGHUP 20534
You can use any of the gnut process IDs in the kill command.

The daemon's activity is affected by the special configuration variables checkpoint_hosts and checkpoint_net (described above).

4.4.5. The Scoring and Rating System

Beginning with gnut 0.4.27, search results are given a score which is displayed as a set of 0 to 4 stars (in increments of half a star). The score is based on attributes that are reported by the server when it reports its serach results. Here are the attributes and how they are scored:

Speed: This counts for up to 100 points. Each search result has a speed, and that speed is either measured or raw. A measured speed is the speed at which that server has actually served files; the raw speed is usually just the bandwidth of the remote user's connection. gnut divides raw speeds by 4 to make an estimate, based on the idea that if you're downloading a file from a server, you'll probably be competing with a few other users for that server's bandwidth. After calculating the measured or estimated speed, gnut assigns from 0 to 100 points based on how that speed compares to your own local speed as given by your speed configuration variable (see section 4.3). For example, if their speed is 2/3 as fast as yours, they get 67 points. A server whose measured or estimated speed is greater than your local speed gets 100 points.

Available: Servers place a limit on how many files can be downloaded simultaneously. The three possible states are "busy", "available", or "unknown". "unknown" means that the server isn't telling whether it's busy, usually because it is running old software. If it is available, the server gets a 50-point bonus, if it is unknown it gets a 25-point bonus. You can adjust this with the score_available setting (see section 4.3).

DidUpload: This attribute means that te server has successfully uploaded a file to someone else. It can be "yes", "no" or "unknown". "unknown" means that the server isn't telling whether it has done an upload, usually because it is running old software. If it is "no", that usually means the server has joined the network recently, has been around a while but has just begun sharing files, or is unable to upload due to a technical problem. Servers that have done an upload get a 30-point bonus, unknown status is worth a 15-point bonus. You can adjust this with the score_did_upload setting (see section 4.3).

DidReceive: This attribute means that te server has successfully received an incoming connection of any kind (upload, push download or GnutellaNet) and indicates that the server is not behind a firewall. The attribute can be "yes", "no" or "unknown". "unknown" means that the server isn't telling whether it has received a connection, usually because it is running old software. If it is "no", that usually means the server is behind a firewall or has joined the network recently, but it might also mean it is unable to receive connections due to a technical problem. Servers that have received a connection get a 40-point bonus, unknown status is worth a 20-point bonus. You can adjust this with the score_did_receive setting (see section 4.3).

Converting the score to stars: After the points are added up, the resulting score is compared to the maximum possible score (which is 100 + score_available + score_did_upload + score_did_receive) and generates a rating from 0 to 4 stars.

Here's an example using the normal score values. Suppose your speed is 128 kbytes per second, and a search result comes back from a server with a measured speed of 106 kbytes per second. The server is not available, it has uploaded, and its has received status is unknown. The points are added up like so:

       score  out of
         83    100   for speed (because 106 is 83% of 128)
          0     50   for "not available" status
         30     30   for "has uploaded" status
         20     40   for unknown "has received" status
       ----   ----
totals: 133    220

          rating = 4.5 x score / maximumscore
    ```````````` = 4.5 x 133 / 220
    ```````````` = 2.72, rounds down to 2.5 stars

The formula uses 4.5 rather than 4 because otherwise, anything without a perfect score would get rounded down to 31/2 stars.

gnut's actual internal representation of the star rating is an integer equal to (number of stars×32). This means the 4-star ratings go from 128 to 143, because (4.5×32 - 1) = 143.

Customizing the Scoring: You can adjust the three variables score_available, score_did_upload and score_did_receive to emphasize or de-emphasize whichever attributes you want. You can even assign negative values to make positive attributes count against the score if you so desire. Here are some examples:

To score based on speed only: Set all three settings score_available, score_did_upload and score_did_receive to 0.

To ignore speed: Set speed (the variable that indicates your local speed) to 1. All servers will then get 100 speed points because they're all considered faster than your own speed.

To make available and speed count equally much and ignore the others: set score_available to 100 and set score_did_upload and score_did_receive to 0.

To make did_receive count 10 times as much as the other 3 attributes: Set score_available and score_did_upload to 100, and score_did_receive to 1000.

4.4.6 Recording a gnut Session

If you want to run gnut and have all its output get recorded into a file while you run, use the standard UNIX command script. Type man script to learn how to use this command.


4.5 Reaching the Most Hosts (TTL and min_connections)

The TTL value controls how many nodes on the network will see your searches. In gnut it is set by the ttl setting and defaults to 7. If you decrease it, your searches return less results.

Recently, new Gnutella programs (such as BearShare and LimeWire) have begun to enforce a maximum TTL value of 7. If you set your TTL higher than 7, the other nodes on the network will reduce it to 7 when they forward your searches.

At the same time, the Gnutella network has grown to the point where it is now always well over 20,000 users. In early summer of the year 2000 there were always less than 5000 Gnutella users.

As a result of the network growth and the imposed TTL limit, it is no longer possible for users on the Gnutella network to be able to reach all the other users, or even to get a rough estimate of the number of other users, files and megabytes on the Gnutella network!

However, you can still increase the number of hosts you reach if you have a high-bandwidth connection, by increasing min_connections and leaving autokill_thres at its default setting of 10. However, increase min_connections gradually: try 6, then 8, then 12. If you increase it too much, it'll take up all your bandwidth and you won't have any bandwidth left over for uploads and downloads..


Next Previous Contents


The gnut pages are hosted by gnutelliums.com and gnutelanews.com

Permission is granted to copy, distribute and/or modify this text under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts.

Use of the gnut source code is subject to the terms and conditions of the GNU General Public License.

gnut is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

gnut is currently maintained by Robert Munafo, mrob at mrob com

Back to main gnut page