Initial import.
[doldaconnect.git] / INSTALL
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
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
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
99    a better option where all users are trusted and/or Kerberos is not
100    available.
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
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). 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.
132
133                          Starting the daemon
134
135 To  start the  daemon, just  run  "doldacond" --  as root  if you  are
136 running  in multi-user  mode, and  as your  ordinary user  if  you are
137 running in single-user  mode.
138
139 The first time you start the daemon, it will need to calculate the TTH
140 hashes on all  the files you share (as required  by the Direct Connect
141 protocol). The TTH  calculation process runs with a  higher nice value
142 (+10)  than  the server  itself,  and  should  therefore not  conflict
143 terribly with the  rest of the system CPU-wise, so  that you should be
144 able to  work normally meanwhile. However,  if you have  a fast enough
145 CPU, the I/O  bandwidth required to read all files  may slow down your
146 system  (especially when  sharing  files from  a  network mount).  The
147 server is usable  while calculating TTH hashes, but  some hubs may not
148 allow you in if not all TTH hashes are calculated.
149
150
151
152 This documented was last updated 2006-10-27, reflecting release 0.3 of
153 Dolda Connect.