Convenience script for testing.
[doldaconnect.git] / 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).
49 * --enable-gtk2pbar enables graphical progress bars in the Gtk2 GUI
50 client, instead of textual percent indicators. However, these
51 progress bars have proven to be unstable with certain Gtk2 themes,
52 so if the GUI crashes with them enabled, try turning them off
53 before reporting a bug.
54 * --enable-gnomeapplet selects the GNOME panel applet for
55 compilation.
56 * --enable-gaimplugin selects the Gaim chat plugin for compilation.
57
58Gtk2 and Kerberos V support are detected automatically by the
59configure script. Make sure to check the output at the end so that all
60features that you want are selected. In particular, Gtk2 support
61requires that the Gtk2 headers can be found, and many Linux
62distributions ship without these. The author cannot possibly give
63support for all Linux distributions, so make sure to check this
64thoroughly. Almost all Linux distributions support installing these as
65optional packages through its package manager.
66
9edc5f70 67To use PAM authentication (see below), you also need to install a PAM
68configuration file. On most Linux distributions, the file
69pam.d-doldacond in the contrib directory can be installed as
70/etc/pam.d/doldacond and work perfectly.
71
89ab1068 72 Customizing the configuration file
73
74When installing Dolda Connect, the configuration file is normally
75named /usr/local/etc/doldacond.conf, but it depends on the
76installation prefixes that are chosen. If Dolda Connect will be
77running in multi-user mode, it should remain there, but if it will be
78running in single-user mode, it is recommended that you make a copy of
79it named ~/.doldacond (if ~/.doldacond does not exist, the server will
80still read the system-wide file, but it will be easier to edit a local
81copy, as you need not be root to do so).
82
83Edit the configuration file. If you do no other changes, make sure to
84at least change the "cli.defnick", "share" and "user" settings. Most
85directives are explained in comments in the shipped file and need no
86further explanation here. However, there are a few points to note.
87
88First, you need to choose how you will authenticate to the server. If
89you are an administrator of a Kerberos-enabled network using the MIT
90Kerberos libraries, you can use Kerberos V authentication and get
91secure single sign-on, which gives the best of all worlds, but for
92normal users, there are two choices:
93
94 * PAM based password authentication -- The clients will ask for your
95 password every time they connect to the server. This option can be
96 somewhat cumbersome, but should be perfectly secure.
97 * Password-less authentication -- The server will simply trust the
98 clients not to lie. This option is completely insecure, but may be
fffcf1c6 99 a better option where all users are trusted and/or Kerberos is not
100 available.
89ab1068 101
102PAM authentication is always enabled. To enable password-less
103authentication, set the "auth.authless" setting in the configuration
104file to "1". It is also greatly recommended that the "ui.onlylocal"
105setting be set to "1" when using password-less authentication, so that
106connections are only accepted from localhost. If you use password-less
107authentication without turning on "ui.onlylocal", you should make sure
108that you *really* know what you are doing before proceeding.
109
fffcf1c6 110If the computer running the daemon is connected directly to the
111Internet, no network configuration will be necessary. However, if it
112is behind a NAT router or similar, some configuration has to be done
113since Direct Connect requires clients to be able to connect to each
114other. There are currently two options available:
115
116 * Running in passive mode. No other clients will attempt to connect
117 to a client in passive mode, which makes Direct Connect work, but
118 with rather severe limitations. Obviously, no two passive mode
119 clients can connect to one another. Also, search results are
120 proxied through the hub, which drains a hub's bandwidth horribly,
121 and is therefore frowned upon by hub owners. Indeed, many hubs do
122 not even allow clients in passive mode. If you even so wish to use
123 passive mode, set the "net.mode" setting to "1" in the
124 configuration file.
125 * Tunnel a port through the NAT router and set up Dolda Connect to
126 listen specifically to that port. The port to use is set in the
127 configuration file using the "dc.udpport" and "dc.tcpport"
128 settings (evidently, both UDP and TCP need to be tunneled through
c1e49dad 129 the NAT router). The daemon also needs to be told of the public
130 IPv4 address of the NAT router, by way of the "net.visibleipv4"
131 setting.
fffcf1c6 132
89ab1068 133 Starting the daemon
134
135To start the daemon, just run "doldacond" -- as root if you are
136running in multi-user mode, and as your ordinary user if you are
137running in single-user mode.
138
139The first time you start the daemon, it will need to calculate the TTH
140hashes on all the files you share (as required by the Direct Connect
141protocol). The TTH calculation process runs with a higher nice value
142(+10) than the server itself, and should therefore not conflict
143terribly with the rest of the system CPU-wise, so that you should be
144able to work normally meanwhile. However, if you have a fast enough
145CPU, the I/O bandwidth required to read all files may slow down your
146system (especially when sharing files from a network mount). The
147server is usable while calculating TTH hashes, but some hubs may not
148allow you in if not all TTH hashes are calculated.
149
150
151
c1e49dad 152This documented was last updated 2006-10-27, reflecting release 0.3 of
89ab1068 153Dolda Connect.