- 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.
-
-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.
-
- 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 (if ~/.doldacond 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", "share" and "user" settings. Most
-directives are explained in comments in the shipped file and need no
-further explanation here. However, there are a few points to note.
-
-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.
- * 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". It is also greatly recommended that the "ui.onlylocal"
-setting be set to "1" when using password-less authentication, so that
-connections are only accepted from localhost. If you use password-less
-authentication without turning on "ui.onlylocal", you should make sure
-that you *really* know what you are doing before proceeding.
-
-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.
-
- 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.
-
-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 documented was last updated 2006-10-27, reflecting release 0.3 of
-Dolda Connect.
+The real INSTALL file is in the doc/ directory.