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