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). |
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 | |
58 | Gtk2 and Kerberos V support are detected automatically by the |
59 | configure script. Make sure to check the output at the end so that all |
60 | features that you want are selected. In particular, Gtk2 support |
61 | requires that the Gtk2 headers can be found, and many Linux |
62 | distributions ship without these. The author cannot possibly give |
63 | support for all Linux distributions, so make sure to check this |
64 | thoroughly. Almost all Linux distributions support installing these as |
65 | optional packages through its package manager. |
66 | |
9edc5f70 |
67 | To use PAM authentication (see below), you also need to install a PAM |
68 | configuration file. On most Linux distributions, the file |
69 | pam.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 | |
74 | When installing Dolda Connect, the configuration file is normally |
75 | named /usr/local/etc/doldacond.conf, but it depends on the |
76 | installation prefixes that are chosen. If Dolda Connect will be |
77 | running in multi-user mode, it should remain there, but if it will be |
78 | running in single-user mode, it is recommended that you make a copy of |
79 | it named ~/.doldacond (if ~/.doldacond does not exist, the server will |
80 | still read the system-wide file, but it will be easier to edit a local |
81 | copy, as you need not be root to do so). |
82 | |
83 | Edit the configuration file. If you do no other changes, make sure to |
84 | at least change the "cli.defnick", "share" and "user" settings. Most |
85 | directives are explained in comments in the shipped file and need no |
86 | further explanation here. However, there are a few points to note. |
87 | |
88 | First, you need to choose how you will authenticate to the server. If |
89 | you are an administrator of a Kerberos-enabled network using the MIT |
90 | Kerberos libraries, you can use Kerberos V authentication and get |
91 | secure single sign-on, which gives the best of all worlds, but for |
92 | normal 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 | |
102 | PAM authentication is always enabled. To enable password-less |
103 | authentication, set the "auth.authless" setting in the configuration |
104 | file to "1". It is also greatly recommended that the "ui.onlylocal" |
105 | setting be set to "1" when using password-less authentication, so that |
106 | connections are only accepted from localhost. If you use password-less |
107 | authentication without turning on "ui.onlylocal", you should make sure |
108 | that you *really* know what you are doing before proceeding. |
109 | |
fffcf1c6 |
110 | If the computer running the daemon is connected directly to the |
111 | Internet, no network configuration will be necessary. However, if it |
112 | is behind a NAT router or similar, some configuration has to be done |
113 | since Direct Connect requires clients to be able to connect to each |
114 | other. 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 |
129 | the NAT router). |
130 | |
89ab1068 |
131 | Starting the daemon |
132 | |
133 | To start the daemon, just run "doldacond" -- as root if you are |
134 | running in multi-user mode, and as your ordinary user if you are |
135 | running in single-user mode. |
136 | |
137 | The first time you start the daemon, it will need to calculate the TTH |
138 | hashes on all the files you share (as required by the Direct Connect |
139 | protocol). The TTH calculation process runs with a higher nice value |
140 | (+10) than the server itself, and should therefore not conflict |
141 | terribly with the rest of the system CPU-wise, so that you should be |
142 | able to work normally meanwhile. However, if you have a fast enough |
143 | CPU, the I/O bandwidth required to read all files may slow down your |
144 | system (especially when sharing files from a network mount). The |
145 | server is usable while calculating TTH hashes, but some hubs may not |
146 | allow you in if not all TTH hashes are calculated. |
147 | |
148 | |
149 | |
fffcf1c6 |
150 | This documented was last updated 2006-09-04, reflecting release 0.2 of |
89ab1068 |
151 | Dolda Connect. |