Merge branch 'dolcon-split'

[doldaconnect.git] / doc / INSTALL

		     Dolda Connect - Installation

Three main  steps are required  in order to  get Dolda Connect  up and
running:

1. Compile and install the sources
2. Customize the configuration file
3. Start the daemon

Each of these steps are detailed below. However, it is first necessary
to understand that Dolda Connect can be run in either single-user mode
or multi-user mode, and that the chosen mode fundamentally changes how
each step should  be carried out. The differences  between these modes
will be described  right away. If you have read them  and are still in
doubt which to choose, go with the single-user mode.

In multi-user  mode, the  daemon runs as  root and can  serve multiple
users simultaneously. The  primary advantage is that if  you know that
several people will  be using Dolda Connect, there will  be no need to
run several instances for each of them, and that they will all benefit
from being connected  to the same hubs. The  primary disadvantages are
that there may  be unknown security issues with  running the server as
root, and  that, since the hubs  are shared, searches will  have to be
arbitrated by  the server, which may  be annoying for  large values of
simultaneous  searches.  Indirect advantages  are  mostly  that it  is
easier to start the server at boot time when running as root.

In single-user  mode, the daemon  runs as the  user who will  be using
it. The primary advantages is that no root privileges are required for
running the server in single-user  mode -- including for tasks such as
editing the configuration file -- and that any unknown security issues
will at least be restricted to  the user running the server. When only
one  user is  using  Dolda  Connect, there  are  no known  significant
disadvantages to running in single-user mode.

		 Compiling and installing the sources

Compiling  the  sources  involve  the ordinary  GNU  autotools  steps:
./configure,  make, and  make install,  where the  last  step normally
needs to be carried out as root (unless you are installing in your own
home directory). You are assumed to be familiar with these steps.

However, there are special  notes that deserve attention regarding the
configure script.  Some optional features  can be enabled  through the
use of command-line parameters:

 * --with-guile enables the Guile extension library, necessary for any
   clients written in Scheme (such as the automatic downloader).
 * --enable-gtk2pbar enables graphical progress bars in the Gtk2 GUI
   client, instead of textual percent indicators. However, these
   progress bars have proven to be unstable with certain Gtk2 themes,
   so if the GUI crashes with them enabled, try turning them off
   before reporting a bug.
 * --enable-gnomeapplet selects the GNOME panel applet for
   compilation.
 * --enable-gaimplugin selects the Gaim chat plugin for compilation.
 * --enable-pidginplugin selects the Pidgin chat plugin for
   compilation.

Gtk2  and  Kerberos  V  support  are  detected  automatically  by  the
configure script. Make sure to check the output at the end so that all
features  that you  want are  selected.  In  particular,  Gtk2 support
requires  that  the  Gtk2  headers   can  be  found,  and  many  Linux
distributions  ship without  these.  The  author cannot  possibly give
support  for all  Linux  distributions,  so make  sure  to check  this
thoroughly. Almost all Linux distributions support installing these as
optional packages through its package manager.

To use PAM authentication (see below),  you also need to install a PAM
configuration   file.   On   most   Linux  distributions,   the   file
pam.d-doldacond  in   the  contrib  directory  can   be  installed  as
/etc/pam.d/doldacond and work perfectly.

The GNOME applet and GAIM/Pidgin plugin are marked as experimental not
so much because  there is anything wrong with them,  but because it is
tricky to  install them. Please see the  seperate `INSTALL.applet' and
`INSTALL.gaim' files for instructions.

		  Customizing the configuration file

When  installing Dolda  Connect,  the configuration  file is  normally
named   /usr/local/etc/doldacond.conf,   but   it   depends   on   the
installation  prefixes that  are  chosen.  If  Dolda  Connect will  be
running in multi-user mode, it should  remain there, but if it will be
running in single-user mode, it is recommended that you make a copy of
it named  ~/.doldacond.conf (if ~/.doldacond.conf does  not exist, the
server will still read the system-wide  file, but it will be easier to
edit a local copy, as you need not be root to do so).

Edit the configuration file. If you  do no other changes, make sure to
at  least change the  "cli.defnick" and  "share". Most  directives are
explained  in  comments  in  the  shipped file  and  need  no  further
explanation here. However, there are a few points to note.

If  the computer  running  the  daemon is  connected  directly to  the
Internet, no  network configuration will be necessary.  However, if it
is behind a  NAT router or similar, some configuration  has to be done
since Direct  Connect requires clients to  be able to  connect to each
other. There are currently two options available:

 * Running in passive mode. No other clients will attempt to connect
   to a client in passive mode, which makes Direct Connect work, but
   with rather severe limitations. Obviously, no two passive mode
   clients can connect to one another. Also, search results are
   proxied through the hub, which drains a hub's bandwidth horribly,
   and is therefore frowned upon by hub owners. Indeed, many hubs do
   not even allow clients in passive mode. If you even so wish to use
   passive mode, set the "net.mode" setting to "1" in the
   configuration file.
 * Tunnel a port through the NAT router and set up Dolda Connect to
   listen specifically to that port. The port to use is set in the
   configuration file using the "dc.udpport" and "dc.tcpport"
   settings (evidently, both UDP and TCP need to be tunneled through
   the NAT router). The daemon also needs to be told of the public
   IPv4 address of the NAT router, by way of the "net.visibleipv4"
   setting.

There is  a large  number of configuration  directives not  covered in
this  file, nor  in the  default  configuration file.  Please see  the
doldacond.conf(5) manual page for information on the rest.

		   Running clients over the network

For  convenience of  setup,  the default  configuration file  disables
running  clients over  the  network. Using  the default  configuration
file, the daemon will only enable clients to connect over a local Unix
socket.    They  will   use  Unix   socket  credentials   passing  for
authentication, for maximum security. It is also likely that many will
want to keep  it that way. However,  for those who want to  be able to
run clients  over the  network, just follow  the instructions  in this
section to enable UIs over TCP.

First, you need to choose how  you will authenticate to the server. If
you are an  administrator of a Kerberos-enabled network  using the MIT
Kerberos  libraries, you  can use  Kerberos V  authentication  and get
secure single  sign-on, which  gives the best  of all worlds,  but for
normal users, there are two choices:

 * PAM based password authentication -- The clients will ask for your
   password every time they connect to the server. This option can be
   somewhat cumbersome, but should be perfectly secure. Note, however,
   that the password is transmitted to the server unencrypted.
 * Password-less authentication -- The server will simply trust the
   clients not to lie. This option is completely insecure, but may be
   a better option where all users are trusted and/or Kerberos is not
   available.

PAM  authentication  is   always  enabled.   To  enable  password-less
authentication, set  the "auth.authless" setting  in the configuration
file to "1". If your network is not completely trusted (especially the
host running  doldacond is globally accessible via  the Internet), you
really should  make sure to set  up some firewalling  rules.

Note  that doldacond  does  *not* support  tcp-wrappers,  but it  does
support  very   simple  internal  firewalling  in  the   form  of  the
"ui.onlylocal" options. When "ui.onlylocal" is set to true, the daemon
will  only  accept UI  connections  over  a  loopback interface.  That
includes 127.0.0.1, ::ffff:127.0.0.1, ::1 and Unix sockets.

			 Starting the daemon

To  start the  daemon, just  run  "doldacond" --  as root  if you  are
running  in multi-user  mode, and  as your  ordinary user  if  you are
running in single-user mode. See the doldacond(8) manual page for more
detailed   information  about   command-line   switches  and   related
information.

If you  are using the daemon  in multi-user mode on  Gentoo, you might
find  contrib/gentoo-init.d-doldacond,  an  init  script  for  Gentoo,
useful.

The first time you start the daemon, it will need to calculate the TTH
hashes on all  the files you share (as required  by the Direct Connect
protocol). The TTH  calculation process runs with a  higher nice value
(+10)  than  the server  itself,  and  should  therefore not  conflict
terribly with the  rest of the system CPU-wise, so  that you should be
able to  work normally meanwhile. However,  if you have  a fast enough
CPU, the I/O  bandwidth required to read all files  may slow down your
system  (especially when  sharing  files from  a  network mount).  The
server is usable  while calculating TTH hashes, but  some hubs may not
allow you in if not all TTH hashes are calculated.



This document  was last updated 2007-07-18, reflecting  release 0.5 of
Dolda Connect.