| 1 | Dolda Connect - Installation |
| 2 | |
| 3 | Three main steps are required in order to get Dolda Connect up and |
| 4 | running: |
| 5 | |
| 6 | 1. Compile and install the sources |
| 7 | 2. Customize the configuration file |
| 8 | 3. Start the daemon |
| 9 | |
| 10 | Each of these steps are detailed below. However, it is first necessary |
| 11 | to understand that Dolda Connect can be run in either single-user mode |
| 12 | or multi-user mode, and that the chosen mode fundamentally changes how |
| 13 | each step should be carried out. The differences between these modes |
| 14 | will be described right away. If you have read them and are still in |
| 15 | doubt which to choose, go with the single-user mode. |
| 16 | |
| 17 | In multi-user mode, the daemon runs as root and can serve multiple |
| 18 | users simultaneously. The primary advantage is that if you know that |
| 19 | several people will be using Dolda Connect, there will be no need to |
| 20 | run several instances for each of them, and that they will all benefit |
| 21 | from being connected to the same hubs. The primary disadvantages are |
| 22 | that there may be unknown security issues with running the server as |
| 23 | root, and that, since the hubs are shared, searches will have to be |
| 24 | arbitrated by the server, which may be annoying for large values of |
| 25 | simultaneous searches. Indirect advantages are mostly that it is |
| 26 | easier to start the server at boot time when running as root. |
| 27 | |
| 28 | In single-user mode, the daemon runs as the user who will be using |
| 29 | it. The primary advantages is that no root privileges are required for |
| 30 | running the server in single-user mode -- including for tasks such as |
| 31 | editing the configuration file -- and that any unknown security issues |
| 32 | will at least be restricted to the user running the server. When only |
| 33 | one user is using Dolda Connect, there are no known significant |
| 34 | disadvantages to running in single-user mode. |
| 35 | |
| 36 | Compiling and installing the sources |
| 37 | |
| 38 | Compiling the sources involve the ordinary GNU autotools steps: |
| 39 | ./configure, make, and make install, where the last step normally |
| 40 | needs to be carried out as root (unless you are installing in your own |
| 41 | home directory). You are assumed to be familiar with these steps. |
| 42 | |
| 43 | However, there are special notes that deserve attention regarding the |
| 44 | configure script. Some optional features can be enabled through the |
| 45 | use of command-line parameters: |
| 46 | |
| 47 | * --with-guile enables the Guile extension library, necessary for any |
| 48 | clients written in Scheme (such as the automatic downloader and the |
| 49 | hub manager). |
| 50 | * --enable-gnomeapplet selects the GNOME panel applet for |
| 51 | compilation. |
| 52 | * --enable-gaimplugin selects the Gaim chat plugin for compilation. |
| 53 | * --enable-pidginplugin selects the Pidgin chat plugin for |
| 54 | compilation. |
| 55 | |
| 56 | Gtk2 and Kerberos V support are detected automatically by the |
| 57 | configure script. Make sure to check the output at the end so that all |
| 58 | features that you want are selected. In particular, Gtk2 support |
| 59 | requires that the Gtk2 headers can be found, and many Linux |
| 60 | distributions ship without these. The author cannot possibly give |
| 61 | support for all Linux distributions, so make sure to check this |
| 62 | thoroughly. Almost all Linux distributions support installing these as |
| 63 | optional packages through its package manager. |
| 64 | |
| 65 | To use PAM authentication (see below), you also need to install a PAM |
| 66 | configuration file. On most Linux distributions, the file |
| 67 | pam.d-doldacond in the contrib directory can be installed as |
| 68 | /etc/pam.d/doldacond and work perfectly. |
| 69 | |
| 70 | The GNOME applet and GAIM/Pidgin plugin are marked as experimental not |
| 71 | so much because there is anything wrong with them, but because it is |
| 72 | tricky to install them. Please see the seperate `INSTALL.applet' and |
| 73 | `INSTALL.gaim' files for instructions. |
| 74 | |
| 75 | Customizing the configuration file |
| 76 | |
| 77 | When installing Dolda Connect, the configuration file is normally |
| 78 | named /usr/local/etc/doldacond.conf, but it depends on the |
| 79 | installation prefixes that are chosen. If Dolda Connect will be |
| 80 | running in multi-user mode, it should remain there, but if it will be |
| 81 | running in single-user mode, it is recommended that you make a copy of |
| 82 | it named ~/.doldacond.conf (if ~/.doldacond.conf does not exist, the |
| 83 | server will still read the system-wide file, but it will be easier to |
| 84 | edit a local copy, as you need not be root to do so). |
| 85 | |
| 86 | Edit the configuration file. If you do no other changes, make sure to |
| 87 | at least change "cli.defnick" and "share". Most directives are |
| 88 | explained in comments in the shipped file and need no further |
| 89 | explanation here. However, there are a few points to note. |
| 90 | |
| 91 | If the computer running the daemon is connected directly to the |
| 92 | Internet, no network configuration will be necessary. However, if it |
| 93 | is behind a NAT router or similar, some configuration has to be done |
| 94 | since Direct Connect requires clients to be able to connect to each |
| 95 | other. There are currently two options available: |
| 96 | |
| 97 | * Running in passive mode. No other clients will attempt to connect |
| 98 | to a client in passive mode, which makes Direct Connect work, but |
| 99 | with rather severe limitations. Obviously, no two passive mode |
| 100 | clients can connect to one another. Also, search results are |
| 101 | proxied through the hub, which drains a hub's bandwidth horribly, |
| 102 | and is therefore frowned upon by hub owners. Indeed, many hubs do |
| 103 | not even allow clients in passive mode. If you even so wish to use |
| 104 | passive mode, set the "net.mode" setting to "1" in the |
| 105 | configuration file. |
| 106 | * Tunnel a port through the NAT router and set up Dolda Connect to |
| 107 | listen specifically to that port. The port to use is set in the |
| 108 | configuration file using the "dc.udpport" and "dc.tcpport" |
| 109 | settings (evidently, both UDP and TCP need to be tunneled through |
| 110 | the NAT router). The daemon also needs to be told of the public |
| 111 | IPv4 address of the NAT router, by way of the "net.visibleipv4" |
| 112 | setting. |
| 113 | |
| 114 | There is a large number of configuration directives not covered in |
| 115 | this file, nor in the default configuration file. Please see the |
| 116 | doldacond.conf(5) manual page for information on the rest. |
| 117 | |
| 118 | Running clients over the network |
| 119 | |
| 120 | For convenience of setup, the default configuration file disables |
| 121 | running clients over the network. Using the default configuration |
| 122 | file, the daemon will only enable clients to connect over a local Unix |
| 123 | socket. They will use Unix socket credentials passing for |
| 124 | authentication, for maximum security. It is also likely that many will |
| 125 | want to keep it that way. However, for those who want to be able to |
| 126 | run clients over the network, just follow the instructions in this |
| 127 | section to enable UIs over TCP. |
| 128 | |
| 129 | First, you need to choose how you will authenticate to the server. If |
| 130 | you are an administrator of a Kerberos-enabled network using the MIT |
| 131 | Kerberos libraries, you can use Kerberos V authentication and get |
| 132 | secure single sign-on, which gives the best of all worlds, but for |
| 133 | normal users, there are two choices: |
| 134 | |
| 135 | * PAM based password authentication -- The clients will ask for your |
| 136 | password every time they connect to the server. This option can be |
| 137 | somewhat cumbersome, but should be perfectly secure. Note, however, |
| 138 | that the password is transmitted to the server unencrypted. |
| 139 | * Password-less authentication -- The server will simply trust the |
| 140 | clients not to lie. This option is completely insecure, but may be |
| 141 | a better option where all users are trusted and/or Kerberos is not |
| 142 | available. |
| 143 | |
| 144 | PAM authentication is always enabled as long as Dolda Connect was |
| 145 | compiled with PAM support. To enable password-less authentication, |
| 146 | set the "auth.authless" setting in the configuration file to "1". If |
| 147 | your network is not completely trusted (especially if the host running |
| 148 | doldacond is globally accessible via the Internet), you really should |
| 149 | make sure to set up some firewalling rules. |
| 150 | |
| 151 | Note that doldacond does *not* support tcp-wrappers, but it does |
| 152 | support very simple internal firewalling in the form of the |
| 153 | "ui.onlylocal" option. When "ui.onlylocal" is set to true, the daemon |
| 154 | will only accept UI connections over a loopback interface. That |
| 155 | includes 127.0.0.1, ::ffff:127.0.0.1, ::1 and Unix sockets. |
| 156 | |
| 157 | Starting the daemon |
| 158 | |
| 159 | To start the daemon, just run "doldacond" -- as root if you are |
| 160 | running in multi-user mode, and as your ordinary user if you are |
| 161 | running in single-user mode. See the doldacond(8) manual page for more |
| 162 | detailed information about command-line switches and related |
| 163 | information. |
| 164 | |
| 165 | If you are using the daemon in multi-user mode on Gentoo, you might |
| 166 | find contrib/gentoo-init.d-doldacond, an init script for Gentoo, |
| 167 | useful. |
| 168 | |
| 169 | The first time you start the daemon, it will need to calculate the TTH |
| 170 | hashes on all the files you share (as required by the Direct Connect |
| 171 | protocol). The TTH calculation process runs with a higher nice value |
| 172 | (+10) than the server itself, and should therefore not conflict |
| 173 | terribly with the rest of the system CPU-wise, so that you should be |
| 174 | able to work normally meanwhile. However, if you have a fast enough |
| 175 | CPU, the I/O bandwidth required to read all files may slow down your |
| 176 | system (especially when sharing files from a network mount). The |
| 177 | server is usable while calculating TTH hashes, but some hubs may not |
| 178 | allow you in if not all TTH hashes are calculated. |
| 179 | |
| 180 | |
| 181 | |
| 182 | This document was last updated 2008-02-14, reflecting release 1.1 of |
| 183 | Dolda Connect. |