sancho is a gui that connects to a core p2p application. The core application (mldonkey) handles all the p2p operations on the network; sancho simply connects to the core to display information sent to it from the core.

The mldonkey executable binary is called "mlnet"

If you are running the gui on a machine other than the one on which mldonkey is running, you must set the "allowed_ips" setting in the mldonkey core (security feature).

the default setting is to only allow connections from 127.0.0.1

ie: set allowed_ips "127.0.0.1 192.168.1.255 10.1.3.4" in the mldonkey telnet/web interface (or edit the downloads.ini file while the mldonkey core is stopped. 255 = (wildcard *)

By default, mldonkey listens to:
telnet localhost 4000
http://localhost:4080
gui 4001

run "sancho -?" for possible commandline parameters

Host = The IP address of the machine on which the mldonkey core is running. Use "localhost" or "127.0.0.1" if it is the same machine as sancho.

Port = The port. mldonkey uses 4001 by default for its gui communication.

User/Pass: "admin/<empty>" is the default in mldonkey. Use the "add_user admin <newpass>" command in mldonkey (telnet|web|console) to change it.

If you want to connect to your mldonkey core using an ssh2 tunnel, you can optionally enable this (advanced users).

This uses JSch and your JVM's internal crypto libraries. A connection will be made to the remote host

Set the "SSH host" to the IP of the remote system, and set the "SSH user" to the login name of the user. The default port is 22.

Why would you want to store an ssh password here? Well, normally you wouldn't. If you leave it blank, you will be prompted for the password each time you try to initiate a connection. If you store one here it will be written to disk as plain-text. I can't think of any way to reliabily store it -- and pretending that it is encrypted by just encoding it would give a false sense of security.

One option is to store it on an encrypted disk (pgpdisk or similar), and run "sancho -j x:\" to save the pref file to the encrypted x: drive. Far from safe, but... you are in charge of your own security.

(Note: It uses ~/.ssh/known_hosts for the known_hosts file, unless you use -j, in which case it uses the directory you specify)

The "SSH local port" is the port you most likely set as "Port:" in the main settings since it will be the one sancho tries to connect with.

The remote host/remote port paramters set the interface to connect with on the remote host. If mldonkey core has a gui port open on 192.168.1.1:4001 then set it here. Most likely it is 127.0.0.1:4001.

The host manager also lets you add entries for other mldonkey cores and save them. The buttons should be pretty self explanatory.

To use ssh without a password:

"ssh-keygen -t dsa" and don't enter a password (creates ~/.ssh/id_dsa and id_dsa.pub)
cd ~/.ssh ; cat id_dsa.pub >> authorized_keys   (appends public key to openssh authorized_keys file)
move id_dsa (private key) to the sancho machine and put it in ~/.ssh/id_dsa 
	(windows: c:\documents and settings\username\.ssh\id_dsa)
sancho will automatically read ~/.ssh/id_dsa (and/or id_rsa) if they exist

(** gcj compiled sancho might have problems with id_rsa, try id_dsa or the sancho-java version 
if experiencing id_rsa problems **)

SSH2 NOTE: (might not be required if using 0.9.4-22 or newer and id_dsa)

In order for SSH2 tunneling to function correctly one must ensure that the
following line is uncommented in /etc/ssh/sshd_config :
--------------------------CUT-------------------------------
# Change to yes to enable tunnelled clear text passwords
PasswordAuthentication yes
--------------------------CUT-------------------------------

Otherwise the initiation of the tunnel will fail with
 "SSH Initialization failed, try again?
   com.jcraft.jsch.JSchException: Auth fail"

To configure tabs to use small/large buttons, or to disable/enable/re-order tabs, simply right click on the toolbar and select the appropriate option. (Also available from the Menu->View item.)

Each tab has one or more "views". (ie: Downloads, Clients, Uploaders, Pending, etc)

Most views have a header bar with optional convenience buttons, and a pull down menu is available when the icon is left clicked. (or right-click anywhere on the view's header)

The combo in the top right of a view's header lets you input regular expressions to filter a view's table. (last 20 entries are saved between sessions - click the button to the left of the combo to clear the filter)

The column selector lets you select the columns (and their order) of the contained table.

The flip sash item will toggle the container sash between horizontal and vertical orientation.

The dynamic column lets you select a table column that will try to adjust so the table will fit exactly the width of your window as it is resized if it is not too wide (with an optional minimum width option).

The show filters let you toggle types of information to include/exclude from the table. (file type, networks, etc)

Double clicking the header bar will maximize/restore the view within its container.

Toggle Tabs: This allows you add tabs to a view and preset filters for each tab allowing easier organization of files or table entries.

Example:
Right click the existing tab and create a new tab (menuItem). Call it whatever you want.
Select any filters from the filters menu above, plus input any regex filter in the view's top right filter combo box, and whenever you switch to this tab these filters will be used. Switch to another tab and the filters for that tab will be in use.

ie: Create tab "Videos from BitTorrent" and Filter "BitTorrent + VideoFiles"
ie: Create tab "My jpg files" and Filter "Show Image files" and "jpg" in the regex filter box

The link ripper window lets you input an http:// url for ripping. The file will be retrieved and all supported links will be listed and can be selected for download.

Win32:

The integrated browser tab lets you surf your p2p web sites and all supported links will be sent to the core when you click on them.

Click the globe (top left) to view your favorites. This subdirectory is configured in preferences.

Shortcut toolitems (and the number of them to display) can be configured in preferences.

If you leave the linkripper open while surfing, it will be auto updated with the links found on the page currently being viewed.

If you know that a link is a torrent, but it doesn't have a torrent extension (ie: http://site.com/redirect.php?hash=1234), you can hold down the CTRL key while clicking it to have it sent to the core with a .torrent extension. The core should then handle it properly.

Other OSs:

The integrated SWT browser requires a certain version of Mozilla with XFT support. It works with the gtk/motif/photon/carbon widget sets. More information on getting it to work is here.

Example on linux:

export MOZILLA_FIVE_HOME=/usr/lib/mozilla-1.6
export LD_LIBRARY_PATH=:
./sancho

You can run "./sancho -d" in a terminal window to see any error messages that might occur while loading the web browser.

All supported link-types (torrents/ed2k/etc) clicked within this integrated browser are automatically sent to the core.

Force Mozilla

The integrated browser defaults to mozilla on *nix platforms. If you use win32 or OSX and want to use mozilla rather than the OS default, you can force the use of mozilla. This requires XULRunner to be installed.

Click the checkbox in Prefs->Main->WebBrowser.

WIN32: Download XULRunner and run "xulrunner --register-global"

OSX:
on OS X your jre must be "Java for Mac OS X 10.4, Release 5 Developer Preview
2", which is available on Apple Developer Connection ( http://connect.apple.com/ ) (registration is free)

Can use xulrunner 1.8.1.3 (this is a real release). It's available at
http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.1.3/contrib/

Click the arrow button on the status line to toggle the link entry input window.

Type/Paste any supported links, and press CTRL-ENTER, or the Send button to send them to the core.

This supports local links (ie: c:\dir\my.torrent) if your core and gui are on the same machine. (or if you use a core version > 2.5.17 the core and gui can be on different machines)

There is also a File->Input Link dialog, available from the main menu.

Windows registry

On the Win32 platform, Preferences has a Windows Registry Page. On this page you can configure protocols that you want to associate with sancho. If you do this, when you click a link of this protocol type it will be sent to sancho, which will in turn send it on to the core.

Only register a file extension (bittorrent) if your core and gui are on the same machine! This process involves pointing the core to the web browser cache (the location of the clicked torrent, which is on the local hard drive).

* This "same machine" restriction is not applicable with mldonkey core version > 2.5.17

Sending links from the commandLine

sancho -l "ed2k://|file|makerublesfast.pdf|12133593|9aceac181c7fc86dc8be5e1c1c75040c|"
sancho -l "http://www.microsoft.com/linux.torrent"
sancho -l /home/billy/mysecrethiddenfolder/nakedpenguins.torrent

If they are offering files, a plus sign (+) will appear in their icon. Click on their nick to fill in the Directories and Files tables. Select files to download if you find something you want.

What do these columns mean?

Id = File Id # (as reported by mldonkey)
Network = P2P Network
Filename = Filename
Size = Size
Downloaded = Bytes downloaded
% = Per cent complete
Sources = (#Active Sources) #Sources
Avail = Availability of the remaining parts of the file
Rate = Download speed/rate
Chunks = # of chunks complete
ETA = Estimated Time of Arrival (remaining / current rate)
Priority = File priority
Last = Last seen Complete
Age = Age of download
ETA2 = ETA based on past performance ((remaining * age) / downloaded)
Clients = # Clients as reported by mldonkey
Sources2 = # Sources as reported by mldonkey
Remaining = Bytes remaining to be downloaded
Comments = # of file comments (in Rt-click->File Details)
User = File User/Owner
Group = File Group

What is the difference between Sources and Sources2?

The Sources column represents the number of "Clients" sent by the core to the gui, as well as how many of those "Clients" are actively transferring data (as can be seen in the Clients table if you "Toggle clients table" from the Download's view toolbar). To save memory, MLDonkey stores inactive sources in a secondary structure called "Sources" that are smaller than "Clients", and does not send these structures to the gui. Sources2 represents the total number of "Clients" and "Sources" as reported by the MLDonkey core.

Why are some files coloured red?

Preferences>sancho: Main>Transfers>Recolor files that contain "Fake" in names/comments.
Preferences>sancho: Display>Transfers>Contains "Fake" color

Why doesn't the transfer table stay sorted?

Preferences>sancho>display>Transfers>Maintain sort order.
It is off by default since it might cause added 'flickering' as files often change sort order

The clients table doesn't seem to sort alphabetically by state

Clients are sorted by Queue ranking first. (clients that have notified you of a queue number for their queue should always be at the top)

Chunk graphs

Colours are similar to this.

Drag & Drop

This only seems to work on win32. You can drop links from your web browser on to the downloads table to have them added to the downloads list. Or, drag links from the download list and paste them into a text area.

Colours & fonts

These are configurable in Preferences->Display>Transfers

Preview

Preferences->Transfers->Preview

mldonkey has a built in preview script that can be run. If you prefer to spawn a local app to preview files you can configure it with these settings.

Since the mldonkey core might be on a remote machine, and you might be using an nfs/samba mount to view your temp files, you must input the mldonkey temp directory as the working directory. Or you can use the preview.bat (in distrib directory) as your preview executable (which points to the directory).

In addition to specifying an app to use to preview files locally, you can also select different apps to spawn based on file extension. The main preview app must be filled in -- it becomes the default

input an extension and a program and "Add" it to the list

select an entry from the list and press "Remove" to remove it

Examples:

mp3 = c:\mp3player\mp3player.exe

avi = /usr/local/bin/aviplayer

txt = d:\windows\system32 otepad.exe

What are the network icons for?

Network icons can be used to enable/disable specific networks. They indicate their status by the color of the icon or a little dot within the icon.

Gray = Network is disabled
Red dot = Network enabled, but conneted to 0 servers (if network uses servers)
Yellow dot = Network enabled, but conneted to less than max_connected_servers (if network uses servers)
Normal colour = Network enabled, and conneced to >= max_connected+servers (if network uses servers)

Some networks use servers, others (G2/FT) can use nodes. There is a preference option to show all nodes within the servers tab (Preferences->Servers>Show GNUT/FT nodes), but this list can become very large which slows down the server table.

Right click on the status line (on top of the rate indicators) for a popup menu to easily access bandwidth settings

IRC

MenuBar > Tools > IRC Client

IRC is "Internet Relay Chat". This small client lets you connect to an IRC server, join channels, and chat with people. By default it is set to join the #mldonkey support channel. (You can change these defaults in Preferences).

This is a very small&simple irc client. Type "/help" for the supported commands. Full featured irc clients can be found on the web.

Statistics

Double click on a graph to rotate between its styles (gradient/flat/line). It will be updated on the next refresh/update. Gradient uses the most CPU, and the line graph uses the least CPU.

Localization

All strings are localised to use the sancho.properties file. See the downloads page for translations.

This file is a "Key = Value" text file.

Search table

CS column = Complete sources (how many sources have the complete file)

Hover the mouse over a filename to see the tooltip information. (These can be disabled in Preferences->Search)

Search entries are saved between sessions in the combo boxes (20 entries) so you can easily repeat searches

(These can be cleared by rt-clicking on the search bar header and using the context menu)