DARXITE USAGE FOR RELEASE 0.4
=============================

This file explains the basics of using the programs contained within Darxite
release 0.4 (Agrajag). For more information, try running any of the
programs with the -h command-line switch - the system is surprisingly
complicated.

Note that, from version 0.3 onwards, Darxite can download via HTTP. It can
also utilise an HTTP proxy. Also, a set of man pages have been written for
darxite, darxget, darxstat, darxcmd and dxftp. These should have
automatically been installed.

From version 0.4 onwards, Darxite can upload via FTP. Recursive FTP uploads
and downloads are also possible.

THE DAEMON
----------

The Darxite daemon executable produced is daemon/darxite.

Before you can start transferring any files, you need to run the Darxite
daemon, which actually does it all. To do so, simply type "darxite". This
will run the daemon (unless it is running already), create a ".darxite"
directory in your home directory (unless it already exists) and generally
set things up. After running the daemon, a socket file "darxsock.USERNAME"
should appear in the "/tmp" directory, where "USERNAME" is your user name.
Don't delete this file, as it's used for all daemon-client communication.

If you run the daemon with the flag "-q", it will silently quit if another
copy is already running. This is useful if you want to have Darxite running
all the time; you can put "darxite -q" in your ".bash_profile" or whatever.
Alternatively, the flag "-k" will cause the daemon not to run, but to kill
another instance of Darxite (if it's running). Type "darxite -h" for an
explanation of other flags you can pass it.

To configure the daemon with things like your e-mail address or proxy
settings, see the section at the bottom of this file about config files.

Running a remote daemon
-----------------------

New in release 0.2, you can run the Darxite daemon on a remote computer and
the clients on the local computer. This means that you can, for example, use
a faster computer as a kind-of FTP proxy. If you want the daemon to listen
on a port below 5000, you will need to setuid the daemon to run as root.
Edit your ".darxiterc" (qv) to contain the line "ListenOnPort <number>",
where number is any port number you like that isn't likely to be used, and
run Darxite on the remote computer. Note that, as soon as it has bound the
port on startup, the daemon drops any root privileges, so it's reasonably
secure. But you are recommended NOT to run it as root anyway.

You also need to set a password for the daemon, which it will ask all
clients for when they connect to it. Do this with the "-p" command-line
option; there is no way of setting it in a config file (by design). Note
that if you do *not* pass it this option, the password will be blank, but
will still be required.

Now, to connect to the daemon, on your local computer run any of the clients
with the option "-c host:port", host being the name of the host you're
running the daemon on, and port being the same as in the ".darxiterc". The
client should connect to the daemon and be able to talk to it as per usual,
although the first thing it will do is ask you for a password.

Now you're running the daemon, you can start to get some files.

DARXGET
-------

The darxget utility executable produced is clients/util/darxget.

The "simplest" way to get files is to use the command-line tool "darxget".
You simply pass it a URL, eg. "ftp://sunsite.doc.ic.ac.uk/pub/MIRRORS" and
it will get it. By default, this will be done asynchronously - ie. the
client will pass the URL on to the daemon, which will then get it in the
background. If you would rather the program didn't return until the transfer
is complete, type "darxget -b". The other important command-line switch is
"-o filename", which selects the local filename you want the file to be
written to.

New in release 0.3, if the local filename is "-", darxget will output the
file you download to stdout. Also, the '-r' option will do a recursive
download.

DARXPUT
-------

The darxput executable produced is clients/util/darxput.

This program simply uploads a file. You run it as "darxput -i<file> <url>",
where <file> is the name of the local file to upload. If the file name is
"-", data will be transferred from standard input. Other command-line
options supported are similar to darxget. Note that, if you specify a remote
directory but not a remote filename, the file's current name will be used.

DXFTP
-----

The dxFTP application executable produced is clients/cmdline/dxftp.

A slightly more useful way of downloading files is to use the command-line
program "dxftp". This is similar to programs such as "ftp" and "ncftp". To
start it, type "dxftp <hostname>" and it will connect to that host and log
in anonymously. To log in as a specific user, type "dxftp -u ashley
<hostname>", or whatever. You'll then be presented with a prompt. The syntax
is like a shell in that you type "ls" to get a list of files and "cd" to
change directory. Type "get <filename>" to transfer a file (asynchronously).
A recursive download can be accomplished by typing "get -r".

From version 0.4, you can use the "put" command to upload a file. "put -r"
will upload a directory recursively.

The commands "open <site>" and "close" open a new site and close the current
connection, respectively. When you're finished, type "quit", "exit" or "bye"
to close the program. There are some commands for remote file management:
rm, mv, rename, cd etc. work as expected. See the man page for more
information or type "help" in dxftp.

There is also a set of commands for working with local files: lls, lrm, lmv
and lcd work as you would expect them to. Also, from version 0.2 dxFTP uses
GNU readline, so there is command-line editing and a history. There is also
tab-completion for local files, and for remote files once they have been
listed.

NOCTFTP
-------

The NoctFTP application executable produced is clients/gtk/noctftp/noctftp.

This program is a GTK FTP client. Similarly to other FTP clients, two lists
are displayed: local files on the left and remote files on the right. A
dialogue also pops up so you can connect to a server straight away; if you
don't want to, just click on "Cancel". The GUI is pretty self-explanatory;
note that double-clicking on a remote file will get it, but double-clicking
on a directory will cd to it. Also, to refresh the list boxes, either click
on the arrow widget in the top left-hand corner or on the relevant "List"
button.

The connection manager that pops up on startup allows you to save
"bookmarks" to hosts, with a default path, username and password, and
comment. You can just enter a URL in the "Quick Connect" box if you don't
want to bother with the other stuff. Note that a bookmark will automatically
be saved to any server from which you download a file.

The entry boxes showing the current local and remote directories are
editable. Changing the local directory determines where files you get will
be put. In the "Options" menu, the definition of a "hidden" file is one
whose name begins with a dot. The program also has an anti-idle facility,
whereby it will send the FTP server a "NOOP" every 4 minutes to ensure the
client doesn't get disconnected.

New in release 0.3, NoctFTP supports asynchronous recursive downloading. To
download a directory, simply click on it and click on the "Get" button. You
can even download multiple directories at once. A limitation is that
symbolic links will not be recursed when a recursive download is being
performed.

NoctFTP also supports drag-and-drop of URLs from GTK applications and
Netscape. This applies to both upload and download; to upload a file, simply
drop its URL onto the remote list box, and to download a file, drop it on
the local list box.

There are also some programs to display the current status of the files
you're transferring.

DARXSTAT
--------

The darxstat utility executable produced is clients/util/darxstat.

When run, this simple program displays a list of the files currently in the
Darxite batch (whether they're currently being transferred or not) and some
information about them. If you type "darxstat -a", it displays in dodgy ANSI
colour that may or may not work...

DARXSTAT-GTK
------------

The darxstat-gtk utility executable produced is clients/gtk/dsgtk.

This is similar to darxstat, but uses (shock!) GTK. It also stays running
and polls the Darxite daemon for status once a second, so it's more of a
load on the daemon than the other clients. The executable is called "dsgtk",
and you can also use it to pause or cancel batched files. Note that, if the
batch contains a very large number of files, the program may not be able to
display them all.

GNOME DARXITE MONITOR
---------------------

The monitor executable produced is
clients/gnome/monitor_applet/darxite-monitor_applet.

When installed, you can add this applet to the GNOME panel by selecting it
from the "Add Applet/Network" menu, or you can run it directly. As well as
displaying whether the daemon is running and the percentage of downloading
that's complete, if you drag and drop a URL from any GNOME program (or even
Netscape), it will add it to the Darxite batch. The applet is also highly
configurable, and can run the other GTK clients directly. Once running,
click on it with the right mouse button to see the options.

It will try to automatically connect to the daemon if it's running. If it
isn't, it can (optionally) start the daemon. Anyway, it will try to start
the daemon when a drop is accepted.

It can also connect to a remote daemon running on another machine.

The panel applet was written by Manuel Clos. Many thanks!

GNOME DARXITE CONTROL
---------------------

Executable produced is clients/gnome/control/darxite-control.

This program provides a GNOME-ified way of controlling the files in the
batch. It displays a list of all files in the batch (and ones that have been
completed) and some information about them. You can pause, cancel, resume or
reget files by clicking on various simple buttons. There is also a list of
the completed/cancelled/erroneous transfers where you can find, for example,
the date you finished downloading it, % got, where you stored it, ... this
files can be regot or continued.

It will try to automatically connect to the daemon if it's running. If it
isn't, it can (optionally) start the daemon. Anyway, it will try to start
the daemon when a drop is accepted.

It can also connect to a remote daemon running on another machine.

This application was also written by Manuel Clos. Thanks again!

DXCLIP
------

Executable produced is clients/gtk/dxclip.

This program is a GTK-based clipboard monitor. When you copy an FTP, HTTP or
file:// URL to the clipboard, it will be added to dxclip's list. You can
then transfer it by clicking on the "Get" button. Clicking on "Clear" will
clear the list. This program is especially useful for integration with
Netscape.

PDARXGET
--------

This simple Perl script (executable in clients/util) was designed to show
just how easy it is to write a Darxite client. Simply call it as "pdarxget
<url>" and it will get the file specified and print it on stdout. Anyone who
knows anything about Perl is more than welcome to mess around with it and
make it CGI-able if they want.

DARXCMD
-------

The darxcmd utility executable produced is clients/util/darxcmd.

This is just a utility program most useful for debugging: it sends one or
more raw commands to the daemon. If you're brave, it can be used to do
anything that the others can, but it's not as nice. You can run it just as
"darxcmd <command>", or if you don't pass it any parameters, it will
interactively let you type in multiple commands. Some useful commands are:

"Get <url>" - gets a URL
"Status" - displays the status of the batch and connected clients
"Version" - shows the daemon's version
"Cancel <url>" - cancels a file
"Disconnect" - disconnects from the daemon

All of the commands are listed in the develop.txt file.

Telnetting to Darxite
---------------------

If you have to use Windows (or some other OS) and you want to download files
onto a remote computer, you can still do so. Run Darxite on the remote
computer as explained above, then telnet to the port you've told the daemon
to listen on. You will then be told what to do. For example, if you were
telnetting to a daemon running on localhost, you might type:

ashley: ~> telnet localhost 5678
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
900 Welcome to Darxite 0.39. Enter your password.
password
900 Password OK; tell me your name.
Ashley
900 "Ashley" connected OK.
version
900 Darxite daemon v0.39, release 0.39 (Agrajag) by Ashley Montanaro
quit
Connection closed by foreign host.

Commands are exactly the same as you would send with "darxcmd".

CONFIGURING DARXITE
-------------------

Darxite can be configured to a certain degree by use of config files:
/usr/etc/darxite.conf or ~/.darxite/conf. If both are present, settings in
the latter override the former. The file sample.darxiterc provided
illustrates the possible commands. Note that some settings can be overridden
by passing arguments to the daemon when you run it, or to "darxget" when you
get a file. It is improtant to set the daemon up correctly.

There is now a more friendly way of configuring Darxite: via the GTK-based
utility "dxpref", which brings up a dialogue allowing you to configure the
rc files. Every possible variable can be configured, including setting up
file types for automatic running of programs when downloading's complete,
and the daemon's config can be reloaded on the fly. Note that, if you want
to update the daemon's configuration while it's running, you should save a
configuration file first.

PROBLEMS?
---------

Contact me at <hell@ukgateway.net>.