1 Dolda Connect - Installation
3 Three main steps are required in order to get Dolda Connect up and
6 1. Compile and install the sources
7 2. Customize the configuration file
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.
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.
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.
36 Compiling and installing the sources
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.
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:
47 * --with-guile enables the Guile extension library, necessary for any
48 clients written in Scheme (such as the automatic downloader and the
50 * --enable-gnomeapplet selects the GNOME panel applet for
52 * --enable-gaimplugin selects the Gaim chat plugin for compilation.
53 * --enable-pidginplugin selects the Pidgin chat plugin for
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.
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.
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.
75 Customizing the configuration file
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).
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.
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:
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
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"
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.
118 Running clients over the network
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.
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:
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
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.
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.
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
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,
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.
182 This document was last updated 2008-02-14, reflecting release 1.1 of