0 About this document.
1 Installing Hagelslag
1.1 Installation methods
1.2 Obtaining the source
1.3 Compiling the source

2 Using Hagelslag
2.1 The different modes.
2.2 The Commands
2.3 Command explanation
2.3.1 host
2.3.2 set
2.3.3 help
2.3.4 list
2.3.5 search
2.3.6 download
2.3.7 kill
2.3.8 share
2.3.9 scan
2.3.10 save
2.3.11 holdon
2.3.12 quit
2.3.13 version
2.3.14 continue

3. Configuring Hagelslag
3.1 Intro
3.2 The Files
3.2.1 hagelslag.conf
3.2.2 hagelslag.cid
3.2.3 hagelslag.hosts
3.2.4 hagelslag.shares

4 Feedback

5 Diehards


0 About his document

This User Manual is distributed with the tarball of hagelslag. Version 0.4
will be the first version officially having this User Manual. Future
versions are garanteed to have errors, inconsistencies etc. I like
programming better than writing documentation, and I prefer to have
something working and THEN documenting it that the other way around. In
order to keep the number of anomalies to a minimum I would like to point out
the existence of chapter 4, called Feedback.

This document describes the basics of operating hagelslag, and, if
nessicary, some related information about GNUtella.


1 Installing hagelslag


1.1 Installation methods

Currently, the only installation method is to :
1) get the source
2) compile the source
3) copy the binary to a suitable location
4) run the program

Other easier methods such a precompiled packages, such as .rpm and .deb, are
currently not available, at least not from me. Sorry.


1.2 Obtaining the source

The source can be downloaded from the project home page, located at
http://TieFighter.et.tudelft.nl/hagelslag
or by anonymous ftp from
ftp://TieFighter.et.tudelft.nl/pub/hagelslag

This is currently the only server, there are no mirrors that I know of.
Download the latest tarball, which is currently the only way hagelslag is
distributed.


1.3 Compiling the source code

If you are interested in a console client, please try the following
commands:

tar xzvf hagelslag-VERSION.tgz
(note that if you actually type 'VERSION' instead of something like 0.7 a
console client might be somewhat difficult ffor you.)
cd hagelslag/src
make all

There. copy the binary to a suitable location, such as ~/bin or
/usr/local/bin. You're ready to go!

If you are interrested in something else than this, read the README. There
you will see some explanation about the thoughts behind hagelslag and how to
compile hagelslag as a router or a daemon.

What it says it that you must change 1 line in 'Makefile'
where it say CXXFLAGS=(CONSOLE_FLAGS) you must change 'CONSOLE_FLAGS' to
'ROUTER_FLAGS' or 'DAEMON_FLAGS'. Then, instead of 'make all' do
'make clean' then 'make depend' and then either 'make hagelslagd' or 
'make hagelslagrouter'.
Copy the binary to a suitable location and your ready to rock.


2 Using hagelslag


2.1 The different modes.

Hagelslag can be run in three different modes. These modes are CONSOLE,
ROUTER and DAEMON. ROUTER is practically non-interactive, for configuration
please refer to Chapter 3. CONSOLE and DAEMON use almost exactly the same 
commands, but the way interaction is performed is different. CONSOLE mode
works in a normal console. DAEMON mode listens on a separate port to which
you must connect. Telnet will do this, or a gui. This port is by default
1414, but you can set it with the -p daemon_port option on the commandline.
i.e. hagelslagd -p 5000 will listen for your command on port 5000.
As of version 0.6, hagelslag -v will print a version string and then exit.


2.2 The Commands

Commands are the way to work with hagelslag. You put stuff in, in some cases
you get stuff back. I tried to make the feedback human-readable, yet
structured enough to be easily parsed. If you have an opinion on this
subject, refer to Chapter 4!

In order to know what kind of commands are used, it is feasable to have some
knowlegde of the workings of GNUtella. GNUtella works like this : You
connect to the network by trying to connect to people in your hosts
database. If one or more connections are made, you are connected! Files
exchanges, or, in other words, get what you want, are done by 1) searching
2) waiting for results 3) ordering the download of a result. Of course you
can share things too, so other people can search and download from you as
well.


2.3 Command explanation

Here's the list commands you may use. If a '!' is given as command, the
previous command is repeated. As of version 0.10, commands may be abbriated 
(except 'holdon'), sometimes parameters may be abbreviated too. You must enter
sufficient characters to identify the command unambigiously.

Example :
host add 1.2.3.4:5000
may be abbreviated to
h a 1.2.3.4:5000

Some parameters, most notably those of the 'set' command cannot be abbreviated.


2.3.1 host

Used to use and manipulate the hosts database.

syntax :
host add 1.2.3.4:5000
host add gnutellahosts.com

Add a host to your hosts database. The port is not required as of version 0.11,
this version also allows the use of canonical names.

host del 3
Delete host number 3 from your hosts list. You can find the numbers with 
'list hosts'

host connect 5
Try to connect to host number 5.


2.3.2 set

Used to set values to parameters.

set MAX_UPLOADS 10
Set the maximum number of uploads to 10.

set DOWNLOAD_DIR /tmp
Set the directory to which files are downloaded to /tmp

A full list of options, their possible values and their meaning is given in
section 3.2.1 as all the parameters are the same the parameters that can be
tuned in hagelslag.conf.


2.3.3 help

Used to get some help on the commands.

help
Print general help.

help list
Print help on the command list.


2.3.4 list

Used to get a list of information on a particular subject.

Possible parameters are results, downloads, uploads, connections, shares,
hosts, options, stats or queries. The parameters connections, results and
hosts require an extra parameter, a number n. See also the 'continue' command.

list results
List the first 10 results.

list results 50
Lists results 50 trough 59

list downloads
Lists all downloads, giving stats such as download status, host and download
speed.

list uploads
Lists all uploads, giving stats such as upload status, host and upload speed.

list connections 15
Lists the connections 10 through 15 with peer and status.

list shares
Lists the list of shared directories.

list hosts
Lists the first 20 entries in the hosts database.

list hosts 30
Lists hosts number 30 through 49

list options
Lists the current configuration.

list stats
Lists some statistics, currently with very unlikely values. This is a known
bug at the moment of writing.

list queries
Lists the last searches that were done by other people. This is the
equivalent of the search monitor in GNUtella.

list internals
Lists some internal statistics. Not very usefull unless you know what you're watching.

2.3.5 search

Used to find files on the GNUtella network that can be downloaded.

search speed string
or
search clear

Where speed is the minimum speed each host that responds must have, string
is the string you want to find.

search 56 Britney Spears
Search for 'Britney Spears' and ask hosts to respond only if their
connection speed is greater or equal to 56 kbs.

If you issue a new search, your old results database will be cleared if
AUTO_CLEAR_RESULTS is non-zero. A search is very bandwidth intentisive, and
results may take a while before they arrive. Retrying a search as quickly as 
possible is an efficient way to fill the GNUtella network with huge amounts of
bandwidth sucking packets. 
Besides that, as every new search means results from previous searches are 
automatically discarded, you not getting any more results either.

search clear will discard all results found so far.


2.3.6 download

Used to get a file from somebody else.

Possible parameters are start, continue or push.

download start 3
download result number 3 from the beginning of the file. Is the file already
exists, it is overwritten.

download continue 5
download result number 5. If the file exists, only the remaining bytes are
downloaded and appended to the file.

download push 11
download result number 11. Use a push only when the normal way, with start,
fails, as a push request puts a lot of strain on everybodies bandwidth.

Push downloads are used to circumvent problems with people behind firewalls
or using masquarading.


2.3.7 kill

Used to kill a connection, an upload or a download.

possible parameters are connection, upload or download.

kill connection 3
Close connection number 3.

kill upload 10
Terminate upload number 10

kill download 6
Stop download number 6

All these numbers can be found using the list command.


2.3.8 share

Used to manipulate the list of directries that you are sharing.

Possible parameters are add, del or clear.

share add /tmp
Add the /tmp directory to the list of shared directories.

share del /home/root/secret
Remove the directory /home/root/secret from the list of shared directories.
NOTE : If a directory is actually removed from the list of shares you MUST
'scan' again! The database of shared files is deleted to prevent
inconsistencies!

share clear
Clear the entire list of shared directories.

Use the scan command to scan the list of shared directories and initialise
the shared files database. Not doing so will result in a situation where the
shared files are still the same as they used to be.


2.3.9 scan

Used to scan the files that are the directories in your list of shared
directories.

scan

You must use the scan command to initialise the database of files that you
are sharing. Using the share command alone in not enough!


2.3.10 save

Used to save some things.

Possible parameters are hosts, shares, options.

save hosts
Save your current hosts database to file, hagelslag.hosts. See section 3.2.3
on hagelslag.hosts.

save options
Save your current options to file, hagelslag.conf. See section 3.2.1 on
hagelslag.conf.

save shares
Save the list of directories that you are currently sharing to file,
hagelslag.shares. See section 3.2.4 on hagelslag.shares.


2.3.11 holdon

Used to close the Control connection without terminating the program.

holdon

Only available when running in DAEMON mode. This option allows you to
temporarily disconnect. You may leave and go to class, or invent the wheel,
reconnect, and see that your downloads are still running. Or, if you are a 
gui programmer, you might use this feature in a web frontent where different
CGI's can connect to one running daemon.


2.3.12 quit

quit

Used to terminate the program.


2.3.13 version

version

Prints a version string.


2.3.14 continue

Used to scroll after a list command. You may enter 'c' (the abbriviation) too
list the next n items that would be displayed after your last 'list' command.

continue

This command is very usefull for scrolling though results.


3 Configuring Hagelslag


3.1 Intro

Hagelslag is quit flexible, is there is something that has a value, you can
almost certainly change it to a value of your liking.


3.2 The Files

There are several parameters you can use to tune hagelslag. These parameters
have a default value when the program is started. All configuration files
are stored in a directory .hagelslag in you home dir. A list of what you may
find here :

FileName			Description
-------------------------------------------------------------------------
hagelslag.conf			A list of parameters and their values. This
				is where you need to be to tune hagelslag.
hagelslag.cid			Contains your ClientID, an unique 16 byte
				string. There is no need to change this,
				hagelslag will automatically generate a
				new one if this file is missing.
hagelslag.hosts			Contains a list of hosts that were on the 
				GNUtella network. These are used to connect
				to.
hagelslag.shares		A list of directories that are shared.
				Please note that subdirectories are shared
				as well.

hagelslag.cid contains random ascii characters and should not be edited, all 
the other files contain plain text and can be modifies as you wish as long
as you make no mistakes in the syntax.


3.2.1 hagelslag.conf

The systax of this file is easy. It looks like this :
parameter value
parameter2 value2
parameter3 value3

etcetera. Simply name the parameter you wish to give a value and put the
value you desire behind it. Remember the 'save' command, if you use 
'save options' hagelslag will generate this file with all options and their
current values. You can adjust them in this file, or by using the 'set'
command and then saving your options.

Here is a list of the options and their meaning, some of which may require
some understanding of GNUtella.

PARAMETER		WHAT KIND OF VALUE	MEANING
-----------------------------------------------------------------------------
MAX_TTL			integer 0 - 255		the maximum value of the TTL 
						of any gnutella packet. All 
						packets, even with a larger 
						TTL will be cut down to this 
						value.
DEFAULT_TTL		integer 0 - 255		The TTL that our packets will 
						be given when we send them.
ROUTING_TABLE_SIZE	integer > 0		The number of packets of
						which we remember who sent
						them.
MAX_CONNECTIONS		integer 0 - 2000	The maximum number of open
						connections.
MAX_RESULTS		integer 0 - 15000	The maximum number of
						results to a search that
						will be accepted.
MAX_HOPS		integer 0 - 255		The maximum number of times
						a packet may be passed on
						before it is discarded.
MAX_PUSH_REQUEST	integer > 0		This value cannot be
						adjusted and is generated on
						basis of MAX_DOWNLOADS.
MAX_UPLOADS		integer 0 - 5000	The maximum number of 
						simultanious uploads.
MAX_DOWNLOADS		integer 0 - 5000	The maximum number of
						simultanious downloads.
MAX_HOSTS		integer > 0		The maximum number of
						entries in the hosts
						database.
PORT			integer 1 - 65535	The port on which hagelslag
						listens for GNUtella network
						connections.
SPEED			integer > 0		The speed in kb/s that is
						sent to others as our
						connection speed.
DOWNLOAD_DIR		string length < 256	The directory in which
						downloaded files are placed.
MAX_MONITOR_LENGTH	int 0 - 1000		The maximum number of
						queries that were seen that
						will be remembered.
AUTO_PUSH		int 0 or non-zero	A boolean which, if true,
						causes hagelslag to send a
						push request if a download
						fails automatically.
AUTO_CLEAR_COMPLETE	int 0 or non-zero	A boolean which, if true,
						causes hagelslag to clear
						completed or troubled
						downloads from the downloads
						database automatically.
AUTO_SAVE_HOSTS		int 0 or non-zero	A boolean which, if true,
						causes hagelslag to save the
						current hosts database on
						exit.
AUTO_CLEAR_RESULTS	int 0 or non-zero	A boolean which, if true,
						causes hagelslag to discard
						all search results if a new
						search is issued.
MAX_HOST_CON_FAIL	int 0 or greater	The number of times an
						attempt to connect to a host
						may fail before that host is
						deleted.
MAX_FILES_SHARED	int 0 - 500000		The maximum number of files
						that may be shared.
MAX_CON_ERROR		int 0 or greater	The number of incorrect
						packets that may be received
						from a connection before it
						is disconnected.
IGNORE_LOCAL_IP		int 0 or non-zero	A boolean, which, if true,
						causes hagelslag's host catcher
						to reject all local-net ip
						addresses (i.e. 10.0.0.3)
NOTIFY_RESULTS		int 0 or non-zero	A boolean, which, if true,
						cause hagelslag to send a
						notification to the user whenever
						results to a search were added.
CACHE_ENTRIES		int 0 or greater	The number of entries is the file-
						servers search cache. More cache-
						entries means more memory usage
						but less cpu usage.

3.2.2 hagelslag.cid

This file is automatically generated, it's contents are not per se suitable
for a text editor and this value should be unique to every host. In simple
words : DON'T TOUCH.


3.2.3 hagelslag.hosts

hagelslag.hosts contains a list of hosts that were registered on the
GNUtella network. This list is saved automatically every now and then, and
you can save it manually by using the 'save hosts' command.
The format of the file is :

1.2.3.4:5000 0 STRING
6.7.8.9:1000 3 NOCID

the format is : First the ip number in dotted notation, a ':', then the port number,
then a space (' '). Next, a number indicating how many succesive times a
connection to this host could not be establisheda and another space (' '). At last, 
the hosts ClientID, or the keyword NOCID if that ClientID is unknown,
followed by a newline.

Reminder : all ip adresses starting with :
10.
172.16.
192.168.
are so-called 'local' adresses that may NOT be used on internet. Through
firewalling and masquarading, these hosts may still appear. Don't try to
connect to them over the internet, and try to keep your hosts database clean
of these polluting elements. See IGNORE_LOCAL_IP.


3.2.4 hagelslag.shares

hagelslag.shares is simply a list of directories that you share across the
GNUtella network. syntax :
dir1
dir2
dir3

example :
/tmp
/foo
/usr/doc/
/mnt/data/OpenSource
/exports


4 Feedback

In order to increase the quality of this software, and to boost/destoy my ego
some feedback is appreciated. Please send your core dumps, bug reports and
comments to luciferPLEASE@tiefighterNO.et.SPAMtudelft.nl (remove capitals
from address).
I presume you are capable of removing the capitals from that address, not
adding a few in other documents has brougth me a spanish plea for SOMETHING
(I don't speak spanish), a few offers of absolutely free porn for only $24.- 
etcetera.


5 Diehards

For those of you who wish to create GUI's, I encourage you to read the
README, have a glance at the Programmers Manual which contains mostly
theoretical bullshit and the source code, especially Commander.cpp. If I 
find the time I may write something like a program structure design document.

If you are interrested in creating a GUI, you will need the README, the
Programmers Manual (well, not in its current form...) and a printed copy of
Commander.cpp. Practise a little with the hagelslag command line and you
should be sufficiently informed. There is no need to look at the internals
of hagelslag.

If you are interrested in hagelslag itself, you would want to read some
documentation, which is currently partly-existent. Please refer to the source.
This is my first c++ program. This is my first program using tcp/ip. You are
warned.

Good luck en enjoy Hagelslag,

F.P.Beekhof.
