Gnut Manual

Gnut Manual Josh Pieper May 4, 2000 This document describes what gnut is, how to use it, and gives detailed instructions for advanced users. Administrivia Where to Get

The main gnut home page is . Source package, binary releases, as well as the newest version of this document can be found there. The distribution can also be found at the under the section third party clients.

Requirements

Gnut will run under most unices which support POSIX threads. Under linux this requires that you have glibc-2.0 or greater. Win32 is supported through some simple wrappers. Readline, regular expression searching, and other niceties are supported if the compiling platform has them.

Most Recent Version

As of this writing the most recent version of gnut is 0.3.28. This changes on a regular basis, so it's always best to look at the web page for the newest version. A ChangeLog, as well as a README, are available at the web page as well.

Pre-compiled Binaries

A precompiled Win32 binary is available at the web page. A link to RPMs for i386 can also be found there. It is assumed that all other platforms have some way of compiling software, preferably with Gnu tools.

Acknowledgements

Thanks to everyone who has ever submitted a patch, or told me what they like and dislike. This document is based in part on the excellent tutorial written by Elijah . Also thanks to Erik Moeller for his great suggestions.

Introduction Gnutella

Gnutella is a distributed file sharing protocol. It has uses not dissimilar to those that other programs such as Napster, I-Mesh, and Scour provide. Despite this competition, gnutella has one strong point. It is distributed, there is no central authority, there is no forced port, and it's very hard to stop a gnutella network in action.

A gnutella client, more accurately called a servant, can connect to other clients, and accept connection from other clients. Queries and responses are then sent between the clients, so that a person is capable of searching from any node in the network, and reaching a large proportion of the other nodes throughout the world. As well as queries, other routing information is passed over these connections, this can make gnutella use quite a bit of bandwidth. Its usability for modem users has been debated.

History

The original gnutella client was created by Nullsoft, the creators of Winamp, a subsidiary of AOL/Time Warner. It was released for public beta testing, and on the same day withdrawn due to pressure from AOL. The build released on that day, 0.48, was the last one to officially come from Nullsoft. However leaked versions up until 0.56 appeared, and are reputed to come from Nullsoft.

Not long after the beta test release, many developers around the world reverse engineered the protocol used by this client, and developed other programs which were inter-operable. This is the category under which gnut falls, as well as many other clients which implement the protocol. A good place to look for other clients is the .

Gnut

Gnut is a command-line client which implements the gnutella protocol. It supports all features available in the original Nullsoft client, as well as many others. Bandwidth limiting, sorting of results, regular expression searching, are among the list. It will compile and run on a wide range of POSIX compliant (and not so compliant) systems including: SunOS, Linux, FreeBSD, HP-UX, and Win32.

Basic Usage Building Gnut

If you are not using one of the available precompile versions, you need to build Gnut from the source code. Gnut uses a standard Gnu automake/autoconf build system. First untar your distribution, cd into the directory, then do the standard:

./configure make make install

This will build gnut and install it into your default installation path.

Starting Gnut

How hard can that be, simply type gnut!

[josh@zaphod gnut]$ gnut num_columns=78 num_rows=34 131.151.189.18 gnut version 0.3.29 at your service Bound to port: 5635 gnut>

You're started, now all you have to do is enter at least one other servant's IP address. Once you have one address, gnut will find others and do its best to keep you always connected to the gnutella network. So, you'll need an IP address, a good place to look is at the , there are usually several hosts listed on the first page. Find an IP to try, then use the open command to pull it up, then use the update command to request more IP addresses.

gnut> open 216.231.59.208:8080 gnut> update

If you want to see the status of all the network connections that gnut has open at any time, you can use the info command.

gnut> info HOST STATS: Hosts: 19 Files: 2.72K Size: 9.145G NET STATS: Msg Received: 20 Msg Sent: 1 Bytes Rcvd: 740 Bytes Sent: 23 QUERY STATS: Queries: 0 Responses Sent: 0 SHARE STATS: Num Shared: 0 Size Shared: 0 CONNECTION STATS: ----------------- 1)198.109.221.88:6346 Packs: 0:0 0:0 Bytes: 0:0 TID: 7171 Type: OUT State: CONN Rate: 0:0 /sec

HOST_STATSShows information about the gnutellaNet (or rather, the parts of the gnutellaNet that are known to you). NET_STATSShows info about the infomration you send and receive over the gnutellaNet. SHARE_STATSSelf-explaining. CONNECTION_STATSReveals the hosts you are currently connected to, whether these connections are incoming or outgoing and at what speed they run at.

Sharing

If you're running gnutella, it's probably because you want to help share some files with your fellow neighbor. Sharing files is easy in gnut, all you have to do is either put them all in one directory, or make the appropriate symlinks (if on a Unix platform). Then you use the share and scan commands to share your files.

gnut> share /home/mp3:/home/movies gnut> scan Scanned 386 files and 3649352 Kbytes. gnut>

And now all your hot files can be downloaded by anyone around the world.

Searching

Searching is just as easy as sharing was. In gnut, you use the find command. It takes one argument, which is the search keyword you are looking for. It waits for you to press a key as search results come in. The results don't stop coming in when you press the key, you just lose feedback of it.

gnut> find britney spears Searching the gnutella network for: britney spears Press any key to continue 63 results received.

After you think enough responses have arrived, hit any key to end the search. You are then presented with a sorted list of the files which matched your query.

1)Britney Spears- Oops!...I Did It Again.mpg 129.142.84.183:6346 size:42.565M ref: 29 speed: 28 2)Britney Spears- Sometimes.mpg 139.142.84.183:6346 size:39.054M ref: 0 speed: 28 etc... ---more---

Let's say that you really wanted the "Sometimes" video. What you would first do is hit "q" to stop displaying results, then you would use the get command to grab the file, then the info t command to display the results of the ongoing transfer.

gnut> get 2 gnut> Download of Britney Spears- Sometimes.mpg.gnut started.

(NOTE: The file is given the extension ".gnut" until it has been completely downloaded. This way you can easily recognize incomplete files.)

gnut> info t TRANSFER_STATS: --------------- 1) 139.142.84.183:6346 2.3% 3.41K/39.054M 3.41K/sec ETA 2h10h34m TID: 15369 IN State: UP Name: Britney Spears- Sometimes.mpg TOTALS: Rate 0:3.41K /sec gnut> Download of Britney Spears- Sometimes.mpg.gnut succeeded.

And now you have Britney Spear's latest video in your current working directory. Crazy huh?

Advanced Usage 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 <#> 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 <#> Start gnut listening on TCP port #. -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.

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 <arg>. The # sign is used to indicate a scalar number. A %% is used to indicate a list and/or range of numbers. These ranges can be specified in several ways. For example:

# = Just a single number #-# = Range of number, Ex: 4-6 #,#,# = Command delimited list, Ex: 2,6,5 #-#,#,#-# = 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 <host> find <string> - Search the Gnutella network for <string>. This is a keyword based search, and nearly every client specifies this as a boolean AND search with all non-alphanumeric characters ignored. 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 %% - Start downloading files referenced by %%. If more downloads are requested than allowed by max_uploads, then the downloads are queued. push %% - Same as get, however only a push connection is attempted. stop %% - Stop the transfers referenced by %%. clear %% - Removes finished transfers from the transfer list. kill %% - Terminate the gnutella connections referenced by %%. hosts - Displays the current host catcher, this can result in a lot of information! limit # %% - Limit the transfers referenced by %% to # bytes per second. log # - 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 %% - Runs the program set in play_prog with the URL of queries %% as arguments. set <val> <key> - Sets a configuration value. See Section 4.3. sleep <#> - Do nothing for # seconds. quit - Quit gnut.

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

These pertain to the gnutella protocol, and most users will have no need to mess with them.

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.

Configuration Files

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.

Web Access

You can access a list of all files shared by a Gnut servant by creating a connection to them from withing 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. 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  where you want the gnut specific stuff to go.

F.A.Q. Will gnut run on Slackware 4.0?

No. Gnut requires glibc2.0, you need to upgrade to this before you can use it.

Does ggnut work?

No, ggnut worked a long time ago, and until some intrepid hacker fixes him, you'll have to live with the standard command-line front-end.

How do I change the port in gnut?

The port gnut listens on can only be changed on the command line. Use the -p option. For example:

gnut -p 6346

Does gnut has feature <x>?

Look in this manual, read README, if you don't see it in either place, then the answer is no.

Ideas for Advanced Use High Availability Connection Point

Gnut can be used as a publicized connection point into the main gnutella network. Just set max_incoming to somewhere around 10 or 20, and redirect to 1. It might be best not to share any files in this case as the gnutella traffic itself is liable to consume large amounts of bandwidth.

Scriptable Downloads

Using an interpreted language such as perl, gnut can be directed to automatically search and download requested files. Never again will you have to worry about when that one host you've been waiting for will get on.