Commit | Line | Data |
---|---|---|
89ab1068 | 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). | |
89ab1068 | 49 | * --enable-gnomeapplet selects the GNOME panel applet for |
50 | compilation. | |
51 | * --enable-gaimplugin selects the Gaim chat plugin for compilation. | |
28f62c9c FT |
52 | * --enable-pidginplugin selects the Pidgin chat plugin for |
53 | compilation. | |
89ab1068 | 54 | |
55 | Gtk2 and Kerberos V support are detected automatically by the | |
56 | configure script. Make sure to check the output at the end so that all | |
57 | features that you want are selected. In particular, Gtk2 support | |
58 | requires that the Gtk2 headers can be found, and many Linux | |
59 | distributions ship without these. The author cannot possibly give | |
60 | support for all Linux distributions, so make sure to check this | |
61 | thoroughly. Almost all Linux distributions support installing these as | |
62 | optional packages through its package manager. | |
63 | ||
9edc5f70 | 64 | To use PAM authentication (see below), you also need to install a PAM |
65 | configuration file. On most Linux distributions, the file | |
66 | pam.d-doldacond in the contrib directory can be installed as | |
67 | /etc/pam.d/doldacond and work perfectly. | |
68 | ||
28f62c9c FT |
69 | The GNOME applet and GAIM/Pidgin plugin are marked as experimental not |
70 | so much because there is anything wrong with them, but because it is | |
ce515da4 | 71 | tricky to install them. Please see the seperate `INSTALL.applet' and |
72 | `INSTALL.gaim' files for instructions. | |
73 | ||
89ab1068 | 74 | Customizing the configuration file |
75 | ||
76 | When installing Dolda Connect, the configuration file is normally | |
77 | named /usr/local/etc/doldacond.conf, but it depends on the | |
78 | installation prefixes that are chosen. If Dolda Connect will be | |
79 | running in multi-user mode, it should remain there, but if it will be | |
80 | running in single-user mode, it is recommended that you make a copy of | |
d9e938a7 | 81 | it named ~/.doldacond.conf (if ~/.doldacond.conf does not exist, the |
82 | server will still read the system-wide file, but it will be easier to | |
83 | edit a local copy, as you need not be root to do so). | |
89ab1068 | 84 | |
85 | Edit the configuration file. If you do no other changes, make sure to | |
39d66815 | 86 | at least change "cli.defnick" and "share". Most directives are |
d9e938a7 | 87 | explained in comments in the shipped file and need no further |
88 | explanation here. However, there are a few points to note. | |
89ab1068 | 89 | |
fffcf1c6 | 90 | If the computer running the daemon is connected directly to the |
91 | Internet, no network configuration will be necessary. However, if it | |
92 | is behind a NAT router or similar, some configuration has to be done | |
93 | since Direct Connect requires clients to be able to connect to each | |
94 | other. There are currently two options available: | |
95 | ||
96 | * Running in passive mode. No other clients will attempt to connect | |
97 | to a client in passive mode, which makes Direct Connect work, but | |
98 | with rather severe limitations. Obviously, no two passive mode | |
99 | clients can connect to one another. Also, search results are | |
100 | proxied through the hub, which drains a hub's bandwidth horribly, | |
101 | and is therefore frowned upon by hub owners. Indeed, many hubs do | |
102 | not even allow clients in passive mode. If you even so wish to use | |
103 | passive mode, set the "net.mode" setting to "1" in the | |
104 | configuration file. | |
105 | * Tunnel a port through the NAT router and set up Dolda Connect to | |
106 | listen specifically to that port. The port to use is set in the | |
107 | configuration file using the "dc.udpport" and "dc.tcpport" | |
108 | settings (evidently, both UDP and TCP need to be tunneled through | |
c1e49dad | 109 | the NAT router). The daemon also needs to be told of the public |
110 | IPv4 address of the NAT router, by way of the "net.visibleipv4" | |
111 | setting. | |
fffcf1c6 | 112 | |
d9e938a7 | 113 | There is a large number of configuration directives not covered in |
114 | this file, nor in the default configuration file. Please see the | |
115 | doldacond.conf(5) manual page for information on the rest. | |
116 | ||
117 | Running clients over the network | |
118 | ||
119 | For convenience of setup, the default configuration file disables | |
120 | running clients over the network. Using the default configuration | |
121 | file, the daemon will only enable clients to connect over a local Unix | |
122 | socket. They will use Unix socket credentials passing for | |
123 | authentication, for maximum security. It is also likely that many will | |
124 | want to keep it that way. However, for those who want to be able to | |
125 | run clients over the network, just follow the instructions in this | |
126 | section to enable UIs over TCP. | |
127 | ||
128 | First, you need to choose how you will authenticate to the server. If | |
129 | you are an administrator of a Kerberos-enabled network using the MIT | |
130 | Kerberos libraries, you can use Kerberos V authentication and get | |
131 | secure single sign-on, which gives the best of all worlds, but for | |
132 | normal users, there are two choices: | |
133 | ||
134 | * PAM based password authentication -- The clients will ask for your | |
135 | password every time they connect to the server. This option can be | |
136 | somewhat cumbersome, but should be perfectly secure. Note, however, | |
137 | that the password is transmitted to the server unencrypted. | |
138 | * Password-less authentication -- The server will simply trust the | |
139 | clients not to lie. This option is completely insecure, but may be | |
140 | a better option where all users are trusted and/or Kerberos is not | |
141 | available. | |
142 | ||
39d66815 FT |
143 | PAM authentication is always enabled as long as Dolda Connect was |
144 | compiled with PAM support. To enable password-less authentication, | |
145 | set the "auth.authless" setting in the configuration file to "1". If | |
146 | your network is not completely trusted (especially the host running | |
147 | doldacond is globally accessible via the Internet), you really should | |
148 | make sure to set up some firewalling rules. | |
d9e938a7 | 149 | |
150 | Note that doldacond does *not* support tcp-wrappers, but it does | |
151 | support very simple internal firewalling in the form of the | |
39d66815 FT |
152 | "ui.onlylocal" option. When "ui.onlylocal" is set to true, the daemon |
153 | will only accept UI connections over a loopback interface. That | |
d9e938a7 | 154 | includes 127.0.0.1, ::ffff:127.0.0.1, ::1 and Unix sockets. |
155 | ||
89ab1068 | 156 | Starting the daemon |
157 | ||
158 | To start the daemon, just run "doldacond" -- as root if you are | |
159 | running in multi-user mode, and as your ordinary user if you are | |
d9e938a7 | 160 | running in single-user mode. See the doldacond(8) manual page for more |
161 | detailed information about command-line switches and related | |
162 | information. | |
163 | ||
164 | If you are using the daemon in multi-user mode on Gentoo, you might | |
165 | find contrib/gentoo-init.d-doldacond, an init script for Gentoo, | |
166 | useful. | |
89ab1068 | 167 | |
168 | The first time you start the daemon, it will need to calculate the TTH | |
169 | hashes on all the files you share (as required by the Direct Connect | |
170 | protocol). The TTH calculation process runs with a higher nice value | |
171 | (+10) than the server itself, and should therefore not conflict | |
172 | terribly with the rest of the system CPU-wise, so that you should be | |
173 | able to work normally meanwhile. However, if you have a fast enough | |
174 | CPU, the I/O bandwidth required to read all files may slow down your | |
175 | system (especially when sharing files from a network mount). The | |
176 | server is usable while calculating TTH hashes, but some hubs may not | |
177 | allow you in if not all TTH hashes are calculated. | |
178 | ||
179 | ||
180 | ||
39d66815 | 181 | This document was last updated 2007-10-15, reflecting release 1.0 of |
89ab1068 | 182 | Dolda Connect. |