About this manual

This manual began life when I was a new Valknut user, trying to fathom the multitudes of options the program had. As my experience and understanding grew, it dawned on me that I should attempt to write down what I had learned, so others could avoid having such a steep learning experience. I hoped it would also stop people repeatedly asking the same basic questions on the discussion board :)

As I'm still not an expert on Valknut this document is nowhere near complete, and is very much a work-in-progress. Your comments, suggestions and corrections are welcomed, please write to me at <agreig at flashmail dot com>.

It is intended that this manual will be kept up-to-date with the latest releases of Valknut. It is currently being updated for the 0.3.4 release. The XML source code of this document is under CVS, which can be browsed at http://cvs.berlios.de/cgi-bin/viewcvs.cgi/dcgui/valknut/valknut/docs/en/dcgui_manual.xml

About Valknut

Valknut is a program the uses the Direct Connect protocol. It is compatible with other DC clients, such as the original DC from Neomodus, DC++ and derivatives. Valknut also interoperates with all common DC hub software.

Valknut is written by Mathias Küster <mathen at users dot berlios dot de > and is licensed under the GNU GPL. It is written in C++ and uses the cross-platform Qt (TM) library for its GUI. Valknut compiles and runs on Linux, FreeBSD, MacOSX and Windows.

Originally, Valknut was called DCGUI, which unfortunately was very similar to the name of another Linux DC client. It was then renamed to dcgui-qt to avoid confusion. However, trademark problems relating to the use of 'Qt' in the name forced another name change, to the rather unique Valknut. Most occurences of the old names have been replaced, but in some places, such as where it would cause too much disruption, the name hasn't been changed.

Finding out more

• Homepage: http://dcgui.berlios.de/

• Board/Forum: http://dcgui.berlios.de/forum/index.php

• Mailing list: https://lists.berlios.de/mailman/listinfo/dcgui-common

Contributors

The following people have helped make this manual possible, by providing information, text or corrections:

• Mathias Küster wrote the program, and is the source of most facts about it.

• Firechild wrote the original Bookmarks and Profiles sections.

• Jason Starr provided several corrections and explanations of program options.

• Stefan Huszics corrected my mis-capitalisation of kB, and provided bandwidth figures for some types of internet links.

Precompiled Packages

The Valknut download page is at http://dcgui.berlios.de/download.php. This is the best place to look for pre-packaged versions of Valknut for various operating systems.

Debian packages are included in the official 'sarge' release, and can be installed by running apt-get install dcgui-qt.

Gentoo users can do emerge valknut.

Contributed binary packages are announced on the distribution forum http://dcgui.berlios.de/forum/viewforum.php?f=5

Source Code

Released versions are available at http://developer.berlios.de/project/filelist.php?group_id=370 or http://download.berlios.de/dcgui/.

There are two parts you need, dclib and valknut. The 'dc' tarballs contain both.

If you really want to be on the bleeding edge you can get the latest CVS version with the following steps:

cvs -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui login  (just press enter when prompted for a password.)
cvs -z3 -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui co valknut
cvs -z3 -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui co dclib
        

Compiling on Linux

make -f Makefile.dist
./configure --enable-debug=full
make
make install           (you will probably want to run this command as root)
        

make -f Makefile.dist
./configure --enable-debug=full --with-qt-dir=/usr/lib/qt3 --with-libdc=/usr/local  (modify the --with-qt-dir parameter if your Qt (TM) libraries are in a different place)
make
make install           (you will probably want to run this command as root)
        

checking for Qt... configure: error: Qt (>= Qt 3.0) (headers and libraries) not found. Please check your installation!

./configure --with-qt-includes=/usr/include/qt3 --with-libdc=/usr/local

Compiling on Mac OS X

There are two ways of using Valknut on OS X: as a native application; or as an X11 application. The native version fits in more neatly with the standard Mac interface, wheras the X11 version requires you to run X as well. The X11 version may feel a bit strange to those with a Mac background, but will feel familiar to those with a UNIX background.

For instructions on compiling the native version, see http://dcgui.berlios.de/forum/viewtopic.php?t=2091

The instructions below for OS 10.3 Panther on X11 are derived from forum posts by drealynn42 and others.

make -f Makefile.dist
./configure --prefix=/tmp/dcguibuild --disable-shared
make
make install
        

make -f Makefile.dist
./configure --with-libdc=/tmp/dcguibuild --enable-static-link
-- or if you get an error about qt3 --
./configure --with-libdc=/tmp/dcguibuild --enable-static-link --with-extra-libs=/sw/lib/ --with-extra-includes=/sw/include/  --with-qt-includes=/sw/include/qt --disable-shared
make
make install
        

checking for X... configure: error: Can't find X includes. Please check your installation and add the correct paths!

checking for xml2-config... /usr/bin/xml2-config
checking for libxml - version >= 2.0.0... *** libxml header files (version 2.5.4) do not match
*** xml2-config (version 2.6.7)
no
configure: error: libxml2 must be installed.
          

Making a Debug build

If Valknut crashes unexpectedly, then you can help the developers work out why by running a debug build. The differences from a normal build are:

• Add --enable-debug=full to the ./configure line for dclib.

• Add --enable-debug=full --enable-link-static to the ./configure line for Valknut.

• Don't run "make install" in the Valknut directory, instead run the program from the compilation directory, e.g.

  cd Valknut; ./Valknut

Submitting a bug report

You need to supply the following information:

• Distribution

• Qt (TM) version

• Valknut/dclib version

• If it is a self compiled source or rpm (rpm distribution)

• Bug description

Command-line options

Usually you can start Valknut without any command-line options and it will work fine. These options are mainly for testing and debugging use.

Environment Variables

Help! It won't run!

Checking Qt (TM) version ...
Compiled for '3.0.5' using '3.1.2'
Checking Qt (TM) privates ...
Valknut: relocation error: Valknut: undefined symbol: _ZN19QSharedDoubleBufferC1EbbP7QPixmap 
        

Checking Qt (TM) version ...
Compiled for '3.0.5' using '3.0.5'
Checking Qt (TM) privates ...
private test ok !
PARITY : 64 64
Signal (11) received, stackdump follows; eax='00000000', ebx='00000000', ecx='00000000', edx='00000000', eip='00000000'
--- retaddr=0x0, ebp=0x0
          

Set necessary options

The very first time you run Valknut you will be presented with an options screen before the main program loads. You need to set a few things before continuing.

On the Identify tab, fill in the following fields:

• Nick: A nickname to identify yourself.

• Search Nick: A different nickname.

• Speed: Your internet connection speed.

On the Transfer tab:

• Download Folder: Where you want downloaded files to go.

• Share Folders: You need to make some of your files available for others. Click the "Add" button (the one that looks like a sheet of paper with a green plus symbol) and choose a folder to share.

• Click the blue icon with the swirly arrow to update your list of shared files, then click the "Save" button.

Get a list of hubs and connect to one

Ok, Valknut is now open fully, but it isn't doing much yet.

• Click the "Action" menu, and choose "Hub List".

• Click the swirly arrow icon to get a list of hubs. This may take a minute, so be patient.

• The Hub List window should now be full of strangely-named hubs. Choose one that looks interesting, and has lots of users, and double-click its name.

• A new window will open up. Within a short time you should start seeing messages about connecting. If nothing happens, or you get disconnected, close the window and try again with another hub.

Find and download files

If you've made it this far, you're nearly there. Its time to grab some files.

• Click the "Action" menu, and choose "Hub Search".

• In the space below the word "Search", type in a word or two, then click "Start".

• Click the "Results" tab, and see what turns up. It may take a minute or two before all the results are in.

• Double-click the name of one of the found files to tell Valknut you want to download it.

• You might get some messages about multi-download. Its ok to say Yes to these.

• Click the "Action" menu, and choose "Transfer List". This will show you the progress (if any) of your download.

Identify

Transfer

Connection

GUI

Sound

You can choose to have sounds played when various events happen in Valknut. Sounds are disabled by default.

Log

Hub Lists

Security

Getting a list of public hubs

Before you can do anything with DC you need to connect to at least one hub. This window will give you a list of public hubs for you to browse through. You can connect to a hub simply by double-clicking its name in the list.

However, when you first run Valknut there are no hubs listed here. You need to click on the Reload Public Hublist button to get the list. The list is obtained from special locations that provide this service, see the Section called Hub Lists in Chapter 6 for information about the source urls. A progress bar will appear at the right of the second toolbar while the reload is happening.

Public hubs are usually run by generous users on their personal computers, which tends to mean they come and go fairly frequently. If you find that hubs in your list no longer exist when you try to connect to them, its probably time to update your list. Clicking the Update Public Hublist button will do that.

Using Filters

At the of writing there are over 3000 public DC hubs available. To make it easier for you to find hubs that are of interest to you, you can filter the list to only show certain hubs.

Bookmarks

Bookmarks let you easily keep track of your favourite hubs. The public server list is not always reliable, so bookmarking hubs you find interesting is a good thing to do. To access your Bookmarks, open the Hub List window and click on the Bookmarks tab.

Profiles

You can specify certain options, such as your nickname and description, on a per-hub basis by using Profiles. Other possibilities include making certain hubs connect automatically when you start Valknut, and hubs requiring authentication be set up so you login automatically without having to enter your password each time.

Profile are managed in the Bookmarks tab in the Hub List window.

Transfer

Shows transfers that are in progress.

Wait

Lists the users you are waiting to get files from.

Files

Lists the files you are waiting to download.

Slots

Shows what download slots you have granted to other users.

Log

Shows detailed information on the connection and transfer process.

Mechanics of searching

When you open the Hub Search window, type in a query and click 'Search', the following happens:

• Your search query is sent to the hubs you are connected to.

• Each hub passes the query onto each client connected to it.

• If a client has files that match the query, they send a response:

  • If you are in active mode, the client sends the response directly to you.

  • If you are in passive mode, the client sends the response to the hub, which then passes it onto you.

• Valknut sorts out the responses and displays them.

If you are in passive mode you won't see search results from others in passive mode, as you won't be able to get their files anyway. You will find a lot more files if you are active!

By default Valknut stops waiting for responses after two minutes. This is usually heaps of time for all the results to trickle in. You can stop it sooner by clicking on the 'Stop' button.

Most clients have a maximum number of responses they will give to one query, commonly about 10. If you search for common words this prevents hundreds or thousands of matches coming back from each client.

Each search puts a load on the hubs and every client connected to it. Searches happen regardless of slots. The 'Spy' function shows the amount of searches you are seeing - its a lot! Searching can be abused, often called search-spam. Some hubs kick clients doing lots of rapid searches.

Searching wisely

The words you search for have a huge impact on what results you will get. Similar files often have very different names, so your search string have to be generic enough to catch relevant files, while not including too many irrelevant ones.

Managing search results

sorting and grouping

filtering

browsing files of those that matched search

searching for clones

File menu

View menu

Action menu

What are plugins?

A Valknut plugin is a small piece of code that adds some extra function to the program. This allows other developers to write programs that can access Valknut's internal state, without them having to modify the Valknut source. Currently the only plugin is one which allows you to control Valknut over http.

Getting and compiling plugins

Plugins aren't included in the core Valknut/dclib distribution, you have to get them seperately. You can find the source for released plugins on the developers page at http://developer.berlios.de/project/showfiles.php?group_id=370 or check out the module from cvs:

cvs -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui login
cvs -z3 -d:pserver:anonymous@cvs.dcgui.berlios.de:/cvsroot/dcgui co plugin
      

Compilation is similar to the rest of Valknut:

make -f Makefile.dist
./configure
make
make install    (as root)
        

HTTP plugin

The http plugin allows you to control Valknut via a web browser. This could be really useful if you don't always have physical access to the machine running the client, and a graphical remote control method like VNC is not suitable.

Currently the http plugin allows you to see the current state of Valknut, display and cancel transfers and connect to hubs. There is no way at the moment to search or browse filelists, or add new downloads.

By default, the http plugin listens on port 1480 and only accepts connections from localhost. Connecting to http://localhost:1480/ will present you with a login prompt. The default username is "dcgui" and the password is "admin". Once you are logged in you can change the password and security settings. The configuration of the plugin is stored in ~/.dc/plugin/http.xml

Why do my downloads slow to a crawl when I am uploading?

This is a common problem in the P2P community, and is not unique to Valknut. It is due to the behaviour of the TCP protocol on heavily loaded links. When you are downloading a file, your computer continuously sends 'acknowledgements' or ACKs to the source computer, telling it 'I got those last few bits, send some more'. When you are also uploading flat-out, the acknowledgements take longer to send because they have to queue up behind the data you are uploading. The slower the ACKs are sent, the slower your peers will send you data, thus the slower your download rate.

There are two ways of avoiding this problem. The first would be to set an upload rate limit in Valknut to just below your actual maximum upload speed. This will allow a bit of breathing space for those ACK packets to fit into. Unfortunately, most hub operators have an irrational fear of upload limiters, and will kick you from the hub if you use them.

The second method works the same way, by artificially limiting your upload speed, and giving priority to ACK packets. However this time it is done outside of Valknut, either by your operating system or an external program. In some ways this is better solution, as it is transparent to Valknut, and can let you manage your bandwidth across other network applications as well.

The Linux kernel comes with packet filtering and quality-of-service features. You can make it prioritise acknowledgement packets, letting them "jump the queue" so your downloads and uploads both run as fast as they can. See http://www.lartc.org/ for full details, including the 'Wondershaper' script. An alternate script with a similar aim is at http://www.digriz.org.uk/jdg-qos-script/

OpenBSD users have the powerful pf utility. See http://www.benzedrine.cx/ackpri.html for a guide to ACK prioritisation.

MacOS X users might find this article about throttled lets them do almost the same thing. http://wincent.org/article/articleview/161/1/25/

Windows users may want to try the shareware program Netlimiter, from http://www.netlimiter.com/

What port(s) does Valknut use?

Unless you have an unusual situation, there is no need to change the port Valknut runs on away from the default 9172. Sure, DC++ and other clients use other ports, so what? It make no functional difference if you are on a different port, the programs tell each other what port they are on and it all works fine. In addition, you really shouldn't try to run Valknut on ports less than 1024, as this requires that you run the program as root, which is *never* a good idea.

How do I configure my firewall so I can be in Active mode?

There is no one answer to this, as there as so many different types of firewall in use. The basic aim is to get TCP and UDP traffic for port 9172 (by default) to reach the computer running Valknut. If the firewall is on the machine running Valknut then you just need to permit that traffic. If the firewall is a separate device, and is doing NAT, the traffic needs to be forwarded to the Valknut machine.

Here are some suggested firewall rules for those with a Linux iptables-based firewall. There is NO GUARANTEE that these rules will work, or that they won't leave your systems wide open. Make sure you know what you are doing before playing with firewall rules, and test afterwards. Use these suggestions AT YOUR OWN RISK.

The following assumptions are made:

• your default INPUT and FORWARD policy is DENY, your default OUTPUT policy is ACCEPT

• $IPTABLES is the iptables command

• $PUBLICIP is your public IP address

• $PRIVATEIP is the internal IP of your firewall

• $EXTIF is your external network device, e.g. ppp0, eth1

• $INTIF is your the internal network device, e.g. eth0

• $MYPC is the private IP address of the computer running Valknut behind a NAT

Machine running Valknut has a public IP address, e.g. a dialup modem connection.

$IPTABLES -A INPUT -i $EXTIF -d $PUBLICIP -p tcp --dport 9176 -j ACCEPT
$IPTABLES -A INPUT -i $EXTIF -d $PUBLICIP -p udp --dport 9176 -j ACCEPT
        

Machine running Valknut is behind a NATing Linux firewall.

$IPTABLES -t nat -A PREROUTING -d $PUBLICIP -p tcp --dport 9176 -j DNAT --to $MYPC
$IPTABLES -t nat -A PREROUTING -d $PUBLICIP -p udp --dport 9176 -j DNAT --to $MYPC
$IPTABLES -A FORWARD -o $INTIF -d $MYPC -p tcp --dport 9176 -j ACCEPT
$IPTABLES -A FORWARD -o $INTIF -d $MYPC -p udp --dport 9176 -j ACCEPT
        

$IPTABLES -t nat -A POSTROUTING -d $MYPC -s 192.168.1.0/24 -p tcp --dport 9176 -j SNAT --to $PRIVATEIP
        

Why doesn't Valknut do <favourite feature>, like DC++ does?

Valknut isn't a clone, imitation or port of DC++ or other DC clients. It is an independent program that has been written from scratch. Certainly there are similarities between these programs, because they are all trying to do the same job, and good features tend to be implemented in all clients eventually. However that doesn't mean a feature will be added just because some other program does it. Feature requests and suggestions are welcomed, but keep in mind that the developers are trying to make the best DC client they can, not just an imitation of another program.

Valknut prints a whole lot of stuff to the console while its running. What does it all mean?

[FIXME - I don't feel qualified to answer this]

SSL Transfer mode

Where can I find out more about Direct Connect?

Direct Connect is a program originally written by NeoModus http://www.neo-modus.com/. Many other programs have been written that use the same protocol. See http://sourceforge.net/docman/?group_id=36589 for some details of the DC protocol.