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-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 "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 as long as Dolda Connect was compiled with PAM support. 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" option. 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-10-15, reflecting release 1.0 of Dolda Connect.