#LyX 1.1 created this file. For more info see http://www.lyx.org/ \lyxformat 2.15 \textclass linuxdoc \language default \inputencoding default \fontscheme default \graphics default \paperfontsize 10 \spacing single \papersize Default \paperpackage a4 \use_geometry 0 \use_amsmath 0 \paperorientation portrait \secnumdepth 3 \tocdepth 3 \paragraph_separation skip \defskip medskip \quotes_language english \quotes_times 2 \papercolumns 1 \papersides 1 \paperpagestyle default \layout Title \added_space_top vfill \added_space_bottom vfill Gnut Manual \layout Author Josh Pieper \begin_inset LatexCommand \url{} \end_inset \begin_inset LatexCommand \htmlurl[josh@nemonet.com]{mailto:josh@nemonet.com} \end_inset \layout Date May 4, 2000 \layout Abstract This document describes what gnut is, how to use it, and gives detailed instructions for advanced users. \layout Standard \begin_inset LatexCommand \tableofcontents{} \end_inset \layout Section Administrivia \layout Subsection Where to Get \layout Standard The main gnut home page is \begin_inset LatexCommand \htmlurl[http://www.umr.edu/~jjp]{http://www.umr.edu/~jjp} \end_inset . 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 \begin_inset LatexCommand \htmlurl[Gnutella Portal]{http://gnutella.wego.com} \end_inset under the section third party clients. \layout Subsection Requirements \layout Standard 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. \layout Subsection Most Recent Version \layout Standard As of this writing the most recent version of gnut is 0.3.29. 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. \layout Subsection Pre-compiled Binaries \layout Standard 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. \layout Subsection Acknowledgements \layout Standard 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 \begin_inset LatexCommand \htmlurl[eli@panix.com]{mailto:eli@panix.com} \end_inset . Also thanks to Erik Moeller for his great suggestions. \layout Section Introduction \layout Subsection Gnutella \layout Standard 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. \layout Standard A gnutella client, more accurately called a servant, can connect to other clients, and accept connections 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 portion 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. \layout Subsection History \layout Standard 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 have come from Nullsoft. \layout Standard 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 \begin_inset LatexCommand \htmlurl[Gnutella Portal]{http://gnutella.wego.com} \end_inset . \layout Subsection Gnut \layout Standard 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. \layout Section Basic Usage \layout Subsection Building Gnut \layout Standard If you are not using one of the available precompiled 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: \layout Verbatim ./configure \newline make \newline make install \layout Standard This will build gnut and install it into your default installation path. \layout Subsection Starting Gnut \layout Standard How hard can that be, simply type gnut! \layout Verbatim [josh@zaphod gnut]$ gnut \newline num_columns=78 num_rows=34 \newline 131.151.189.18 \newline gnut version 0.3.29 at your service \newline \newline Bound to port: 5635 \newline gnut> \layout Standard 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 \begin_inset LatexCommand \htmlurl[Gnutella Portal]{http://gnutella.wego.com} \end_inset , there are usually several hosts listed on the first page. Find an IP to try, then use the \emph on open \emph default command to pull it up, then use the \emph on update \emph default command to request more IP addresses. \layout Verbatim gnut> open 216.231.59.208:8080 \newline gnut> update \layout Standard If you want to see the status of all the network connections that gnut has open at any time, you can use the \emph on info \emph default command. \layout Verbatim gnut> info \newline HOST STATS: \protected_separator Hosts: 19 \protected_separator \protected_separator \protected_separator Files: 2.72K \protected_separator \protected_separator \protected_separator Size: 9.145G \newline NET STATS: \protected_separator Msg Received: 20 \protected_separator \protected_separator \protected_separator \protected_separator Msg Sent: 1 \newline \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator Bytes Rcvd: 740 \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator Bytes Sent: 23 \newline QUERY STATS: Queries: 0 \protected_separator \protected_separator \protected_separator \protected_separator Responses Sent: 0 \newline SHARE STATS: Num Shared: 0 \protected_separator \protected_separator Size Shared: 0 \newline CONNECTION STATS: \newline ----------------- \newline 1)198.109.221.88:6346 \protected_separator Packs: \protected_separator \protected_separator \protected_separator \protected_separator 0:0 \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator 0:0 \protected_separator \protected_separator Bytes: \protected_separator \protected_separator \protected_separator \protected_separator 0:0 \newline TID: 7171 \protected_separator \protected_separator Type: OUT \protected_separator State: \protected_separator CONN \protected_separator Rate: \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator 0:0 \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator /sec \layout Description HOST_STATS Shows information about the gnutellaNet (or rather, the parts of the gnutellaNet that are known to you). \layout Description NET_STATS Shows info about the infomration you send and receive over the gnutellaNet. \layout Description SHARE_STATS Self-explaining. \layout Description CONNECTION_STATS Reveals the hosts you are currently connected to, whether these connections are incoming or outgoing and at what speed they run at. \layout Subsection Sharing \layout Standard 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 \emph on share \emph default and \emph on scan \emph default commands to share your files. \layout Verbatim gnut> share /home/mp3:/home/movies \newline gnut> scan \newline Scanned 386 files and 3649352 Kbytes. \newline gnut> \layout Standard And now all your hot files can be downloaded by anyone around the world. \layout Subsection Searching \layout Standard Searching is just as easy as sharing was. In gnut, you use the \emph on find \emph default 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. \layout Verbatim gnut> find britney spears \newline Searching the gnutella network for: britney spears \newline Press any key to continue \newline 63 results received. \layout Standard 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. \layout Verbatim 1)Britney Spears- Oops!...I Did It Again.mpg \newline 129.142.84.183:6346 \protected_separator size:42.565M \protected_separator ref: 29 \protected_separator speed: 28 \newline 2)Britney Spears- Sometimes.mpg \newline 139.142.84.183:6346 \protected_separator size:39.054M \protected_separator ref: 0 \protected_separator \protected_separator speed: 28 \newline etc... \newline ---more--- \layout Standard Let's say that you really wanted the \begin_inset Quotes eld \end_inset Sometimes \begin_inset Quotes erd \end_inset video. What you would first do is hit \begin_inset Quotes eld \end_inset q \begin_inset Quotes erd \end_inset to stop displaying results, then you would use the \emph on get \emph default command to grab the file, then the \emph on info t \emph default command to display the results of the ongoing transfer. \layout Verbatim gnut> get 2 \newline gnut> \newline Download of Britney Spears- Sometimes.mpg.gnut started. \layout Standard (NOTE: The file is given the extension \begin_inset Quotes eld \end_inset .gnut \begin_inset Quotes erd \end_inset until it has been completely downloaded. This way you can easily recognize incomplete files.) \layout Verbatim gnut> info t \newline TRANSFER_STATS: \newline --------------- \newline 1) 139.142.84.183:6346 \protected_separator 2.3% \protected_separator 3.41K/39.054M \protected_separator \protected_separator 3.41K/sec ETA 2h10h34m \newline TID: 15369 \protected_separator \protected_separator IN \protected_separator State: UP \protected_separator Name: Britney Spears- Sometimes.mpg \newline TOTALS: Rate \protected_separator \protected_separator 0:3.41K /sec \newline \newline gnut> \protected_separator \newline Download of Britney Spears- Sometimes.mpg.gnut succeeded. \layout Standard And now you have Britney Spear's latest video in your current working directory. Crazy huh? \layout Section Advanced Usage \layout Subsection Invocation \layout Standard 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. \layout Itemize \series bold -l <#> \series default 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.) \layout Itemize \series bold -c \series default Specify a script to run at startup. This will bypass any ~/.gnutrc you may have. \layout Itemize \series bold -p <#> \series default Start gnut listening on TCP port #. \layout Itemize \series bold -i [IP/interface] \series default IP (or interface) to broadcast as belonging to us. \layout Itemize \series bold -d \series default Daemon mode, never ask for input at the console. \layout Itemize \series bold -x \series default Exit after having run any scripts. \layout Itemize \series bold -v \series default Output version information and exit. \layout Itemize \series bold -h \series default Display a usage message and exit. \layout Subsection Run-Time Commands \layout Subsubsection Overview \layout Standard 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. \layout Subsubsection Notation \layout Standard 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 . 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: \layout Verbatim # \protected_separator \protected_separator \protected_separator \protected_separator = Just a single number \newline #-# \protected_separator \protected_separator \protected_separator = Range of number, Ex: 4-6 \newline #,#,# \protected_separator \protected_separator = Command delimited list, Ex: 2,6,5 \newline #-#,#,#-# = Any combination thereof \layout Subsubsection List of Commands \layout Itemize \series bold info [hqnsct] \series default - Display various information. \begin_deeper \layout Itemize h - Host \layout Itemize q - Query \layout Itemize n - Network \layout Itemize s - Local Shares \layout Itemize c - Connections \layout Itemize t - Transfers \end_deeper \layout Itemize \series bold open \emph on \emph default \series default - Open outgoing connection to \layout Itemize \series bold find \series default - 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. \layout Itemize \series bold monitor \series default - Turn on the search monitor. \layout Itemize \series bold update \series default - Send out ping packets to all connected hosts. If configuration variable update_clear is set, then the current host list is discarded as well. \layout Itemize \series bold response \series default \series bold \series default - Show the current query responses which match the given regular expression. The results are sorted according to the sort_order configuration variable. \layout Itemize \series bold get %% \series default - Start downloading files referenced by %%. If more downloads are requested than allowed by max_uploads, then the downloads are queued. \layout Itemize \series bold push %% \series default - Same as get, however only a push connection is attempted. \layout Itemize \series bold stop %% \series default - Stop the transfers referenced by %%. \layout Itemize \series bold clear %% \series default - Removes finished transfers from the transfer list. \layout Itemize \series bold kill \emph on \emph default %% \series default - Terminate the gnutella connections referenced by %%. \layout Itemize \series bold hosts \series default - Displays the current host catcher, this can result in a lot of information! \layout Itemize \series bold limit # %% \series default - Limit the transfers referenced by %% to # bytes per second. \layout Itemize \series bold log \emph on \emph default # \series default - Set the current log level to #. \layout Itemize \series bold share \emph on \emph default \series default - Takes a \begin_inset Quotes eld \end_inset : \begin_inset Quotes eld \end_inset delimited list of paths to share. ( \begin_inset Quotes eld \end_inset ; \begin_inset Quotes erd \end_inset on Win32) \layout Itemize \series bold scan \series default - Rescans the files in the share paths. \layout Itemize \series bold play %% \series default - Runs the program set in play_prog with the URL of queries %% as arguments. \layout Itemize \series bold set \series default - Sets a configuration value. See Section 4.3. \layout Itemize \series bold sleep <#> \series default - Do nothing for # seconds. \layout Itemize \series bold quit \emph on \series default \emph default - Quit gnut. \layout Subsection Configuration Variables \layout Standard 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. \layout Standard 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. \layout Subsubsection User Interface \layout Itemize \emph on auto_clear \emph default - Boolean, if set to 1, transfers are removed from the transfer list after completion without user intervention. \layout Itemize \emph on beep_on_first \emph default - Boolean, if set to 1, an audible tone is emitted after the first search result of a new query is received. \layout Itemize \emph on download_path \emph default - String, directory where downloads should be stored. \layout Itemize \emph on munge \emph default - Boolean, if set to 1, large numbers are displayed with unit postfixes. \layout Itemize \emph on packet_stats \emph default - Boolean, if set to 1, a large amount of interesting statistics are shown in the connection information list. \layout Itemize \emph on paginate \emph default - 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. \layout Itemize \emph on play_prog \emph default - String, the program to be used to stream media files. \layout Itemize \emph on sort_order \emph default - String, series of characters indicating what fields should be sorted on when using the response command. A sort string has the following format: \begin_deeper \layout Verbatim \begin_inset Quotes eld \end_inset ?[+-]?[+-]... \begin_inset Quotes erd \end_inset \newline \newline ? is a single character from the following set: \newline s = size \newline p = speed \newline e = extension \newline \newline + indicates asecending order, - indicates descending order \newline \newline For Ex: \begin_inset Quotes eld \end_inset e+s- \begin_inset Quotes eld \end_inset sorts by extension, followed by size in descending order. \end_deeper \layout Itemize \emph on verbose \emph default - Boolean, if set to 1, the user is immediately notified of when downloads start, when they succeed, and when they are enqueued. \layout Itemize \emph on wait_after_find \emph default - 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. \layout Subsubsection Paths \layout Itemize \emph on download_path \emph default - String, the directory where downloaded files are written. \layout Itemize \emph on share_paths \emph default - String, directories where scanning for uploadable files occurs. Setting this variable has the same effect as the \emph on share \emph default command. \layout Subsubsection Limits \layout Standard Numerical limits, as well as bandwidth limits are supported for transfers and connections. The following variables control this operation. \layout Itemize \emph on default_download_cap \emph default - Numeric, all new downloads are initially limited to this many bytes per second. \layout Itemize \emph on default_upload_cap \emph default - Numeric, all new uploads are initially limited to this many bytes. \layout Itemize \emph on global_bandwidth_cap \emph default - Numeric, the sum of all upload and download bandwidths is limited to this. \layout Itemize \emph on max_downloads \emph default - Numeric, maximum number of simultaneous downloads to allow. Any more than this are queued. \layout Itemize \emph on max_incoming \emph default - Numeric, the gnutella protocol requires that clients connect to other clients. This allows you to limit the number of other clients connected to yourself. \layout Itemize \emph on max_uploads \emph default - Numeric, the maximum number of outgoing file transfers allowed at any one time. New requests are denied after this number is reached. \layout Itemize \emph on min_connections \emph default - Numeric, minimum number of gnutella network connections to maintain. \layout Subsubsection Password Protection \layout Standard Gnut can form password protected mini-networks. The password is negotiated with each other gnutella servant that is connected to. \layout Itemize \emph on password \emph default - String, phrase to use for authentication with remote hosts. \layout Itemize \emph on password_required \emph default - Boolean, if set all incoming gnutella connections will be verified against the password. \layout Subsubsection Network Settings \layout Standard These pertain to the gnutella protocol, and most users will have no need to mess with them. \layout Itemize \emph on hidden \emph default - Boolean, if set, the client will not respond to pings, and thus will not end up in any other client's host catcher. \layout Itemize \emph on local_port \emph default - Numeric, read-only, the port to which gnut is bound. If you wish to change this, you have to use the command-line option. \layout Itemize \emph on redirect \emph default - 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. \layout Itemize \emph on speed \emph default - Numeric, speed to broadcast us as over the network. This is mostly meaningless. \layout Itemize \emph on ttl \emph default - Numeric, the TTL to use for new packets, and to limit routed packets to. \layout Subsubsection HTML interface \layout Standard 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. \layout Itemize \emph on html_enable \emph default - Boolean, if set to 1, the html interface is enabled. \layout Itemize \emph on html_template \emph default - String, path to an optional html template file. See section 4.5. \layout Subsubsection Caching \layout Standard 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. \layout Itemize \emph on cache_path \emph default - String, set to the directory where you want cached files to be stored. \layout Itemize \emph on cache_refresh \emph default - Numeric, number of seconds between updates to the cache. \layout Itemize \emph on cache_size \emph default - Numeric, maximum number of kilobytes to allow the cache to grow. \layout Subsection Configuration Files \layout Standard 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. \layout Subsection Web Access \layout Standard 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 \emph on http://127.0.0.1:5634 \emph default (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 \begin_inset Quotes eld \end_inset Refresh Response List. \begin_inset Quotes erd \end_inset Nifty, eh? \layout Standard Gnut can use a template file for this interface. It is specified in the \emph on html_template \emph default configuration variable. This file is a standard HTML file, except that you embed the comment where you want the gnut specific stuff to go. \layout Section F.A.Q. \layout Subsection Will gnut run on Slackware 4.0? \layout Standard No. Gnut requires glibc2.0, you need to upgrade to this before you can use it. \layout Subsection Does ggnut work? \layout Standard 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. \layout Subsection How do I change the port in gnut? \layout Standard The port gnut listens on can only be changed on the command line. Use the -p option. For example: \layout Verbatim gnut -p 6346 \layout Subsection Does gnut has feature ? \layout Standard Look in this manual, read README, if you don't see it in either place, then the answer is no. \layout Section Ideas for Advanced Use \layout Subsection High Availability Connection Point \layout Standard Gnut can be used as a publicized connection point into the main gnutella network. Just set \emph on max_incoming \emph default to somewhere around 10 or 20, and \emph on redirect \emph default 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. \layout Subsection Scriptable Downloads \layout Standard Using an interpreted language such as perl, gnut can be directed to automaticall y 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. \the_end