--- /dev/null
+ Dolda Connect - Installation
+
+Three main steps are required in order to get Dolda Connect up and
+running:
+
+1. Compile and install the sources
+2. Customize the configuration file
+3. Start the daemon
+
+Each of these steps are detailed below. However, it is first necessary
+to understand that Dolda Connect can be run in either single-user mode
+or multi-user mode, and that the chosen mode fundamentally changes how
+each step should be carried out. The differences between these modes
+will be described right away. If you have read them and are still in
+doubt which to choose, go with the single-user mode.
+
+In multi-user mode, the daemon runs as root and can serve multiple
+users simultaneously. The primary advantage is that if you know that
+several people will be using Dolda Connect, there will be no need to
+run several instances for each of them, and that they will all benefit
+from being connected to the same hubs. The primary disadvantages are
+that there may be unknown security issues with running the server as
+root, and that, since the hubs are shared, searches will have to be
+arbitrated by the server, which may be annoying for large values of
+simultaneous searches. Indirect advantages are mostly that it is
+easier to start the server at boot time when running as root.
+
+In single-user mode, the daemon runs as the user who will be using
+it. The primary advantages is that no root privileges are required for
+running the server in single-user mode -- including for tasks such as
+editing the configuration file -- and that any unknown security issues
+will at least be restricted to the user running the server. When only
+one user is using Dolda Connect, there are no known significant
+disadvantages to running in single-user mode.
+
+ Compiling and installing the sources
+
+Compiling the sources involve the ordinary GNU autotools steps:
+./configure, make, and make install, where the last step normally
+needs to be carried out as root (unless you are installing in your own
+home directory). You are assumed to be familiar with these steps.
+
+However, there are special notes that deserve attention regarding the
+configure script. Some optional features can be enabled through the
+use of command-line parameters:
+
+ * --with-guile enables the Guile extension library, necessary for any
+ clients written in Scheme (such as the automatic downloader).
+ * --enable-gtk2pbar enables graphical progress bars in the Gtk2 GUI
+ client, instead of textual percent indicators. However, these
+ progress bars have proven to be unstable with certain Gtk2 themes,
+ so if the GUI crashes with them enabled, try turning them off
+ before reporting a bug.
+ * --enable-gnomeapplet selects the GNOME panel applet for
+ compilation.
+ * --enable-gaimplugin selects the Gaim chat plugin for compilation.
+
+Gtk2 and Kerberos V support are detected automatically by the
+configure script. Make sure to check the output at the end so that all
+features that you want are selected. In particular, Gtk2 support
+requires that the Gtk2 headers can be found, and many Linux
+distributions ship without these. The author cannot possibly give
+support for all Linux distributions, so make sure to check this
+thoroughly. Almost all Linux distributions support installing these as
+optional packages through its package manager.
+
+To use PAM authentication (see below), you also need to install a PAM
+configuration file. On most Linux distributions, the file
+pam.d-doldacond in the contrib directory can be installed as
+/etc/pam.d/doldacond and work perfectly.
+
+ Customizing the configuration file
+
+When installing Dolda Connect, the configuration file is normally
+named /usr/local/etc/doldacond.conf, but it depends on the
+installation prefixes that are chosen. If Dolda Connect will be
+running in multi-user mode, it should remain there, but if it will be
+running in single-user mode, it is recommended that you make a copy of
+it named ~/.doldacond.conf (if ~/.doldacond.conf does not exist, the
+server will still read the system-wide file, but it will be easier to
+edit a local copy, as you need not be root to do so).
+
+Edit the configuration file. If you do no other changes, make sure to
+at least change the "cli.defnick" and "share". Most directives are
+explained in comments in the shipped file and need no further
+explanation here. However, there are a few points to note.
+
+If the computer running the daemon is connected directly to the
+Internet, no network configuration will be necessary. However, if it
+is behind a NAT router or similar, some configuration has to be done
+since Direct Connect requires clients to be able to connect to each
+other. There are currently two options available:
+
+ * Running in passive mode. No other clients will attempt to connect
+ to a client in passive mode, which makes Direct Connect work, but
+ with rather severe limitations. Obviously, no two passive mode
+ clients can connect to one another. Also, search results are
+ proxied through the hub, which drains a hub's bandwidth horribly,
+ and is therefore frowned upon by hub owners. Indeed, many hubs do
+ not even allow clients in passive mode. If you even so wish to use
+ passive mode, set the "net.mode" setting to "1" in the
+ configuration file.
+ * Tunnel a port through the NAT router and set up Dolda Connect to
+ listen specifically to that port. The port to use is set in the
+ configuration file using the "dc.udpport" and "dc.tcpport"
+ settings (evidently, both UDP and TCP need to be tunneled through
+ the NAT router). The daemon also needs to be told of the public
+ IPv4 address of the NAT router, by way of the "net.visibleipv4"
+ setting.
+
+There is a large number of configuration directives not covered in
+this file, nor in the default configuration file. Please see the
+doldacond.conf(5) manual page for information on the rest.
+
+ Running clients over the network
+
+For convenience of setup, the default configuration file disables
+running clients over the network. Using the default configuration
+file, the daemon will only enable clients to connect over a local Unix
+socket. They will use Unix socket credentials passing for
+authentication, for maximum security. It is also likely that many will
+want to keep it that way. However, for those who want to be able to
+run clients over the network, just follow the instructions in this
+section to enable UIs over TCP.
+
+First, you need to choose how you will authenticate to the server. If
+you are an administrator of a Kerberos-enabled network using the MIT
+Kerberos libraries, you can use Kerberos V authentication and get
+secure single sign-on, which gives the best of all worlds, but for
+normal users, there are two choices:
+
+ * PAM based password authentication -- The clients will ask for your
+ password every time they connect to the server. This option can be
+ somewhat cumbersome, but should be perfectly secure. Note, however,
+ that the password is transmitted to the server unencrypted.
+ * Password-less authentication -- The server will simply trust the
+ clients not to lie. This option is completely insecure, but may be
+ a better option where all users are trusted and/or Kerberos is not
+ available.
+
+PAM authentication is always enabled. To enable password-less
+authentication, set the "auth.authless" setting in the configuration
+file to "1". If your network is not completely trusted (especially the
+host running doldacond is globally accessible via the Internet), you
+really should make sure to set up some firewalling rules.
+
+Note that doldacond does *not* support tcp-wrappers, but it does
+support very simple internal firewalling in the form of the
+"ui.onlylocal" options. When "ui.onlylocal" is set to true, the
+daemon will only accept UI connections over a loopback interface. That
+includes 127.0.0.1, ::ffff:127.0.0.1, ::1 and Unix sockets.
+
+ Starting the daemon
+
+To start the daemon, just run "doldacond" -- as root if you are
+running in multi-user mode, and as your ordinary user if you are
+running in single-user mode. See the doldacond(8) manual page for more
+detailed information about command-line switches and related
+information.
+
+If you are using the daemon in multi-user mode on Gentoo, you might
+find contrib/gentoo-init.d-doldacond, an init script for Gentoo,
+useful.
+
+The first time you start the daemon, it will need to calculate the TTH
+hashes on all the files you share (as required by the Direct Connect
+protocol). The TTH calculation process runs with a higher nice value
+(+10) than the server itself, and should therefore not conflict
+terribly with the rest of the system CPU-wise, so that you should be
+able to work normally meanwhile. However, if you have a fast enough
+CPU, the I/O bandwidth required to read all files may slow down your
+system (especially when sharing files from a network mount). The
+server is usable while calculating TTH hashes, but some hubs may not
+allow you in if not all TTH hashes are calculated.
+
+
+
+This documented was last updated 2007-04-11, reflecting release 0.3 of
+Dolda Connect.
Dolda2000 GitWeb / doldaconnect.git / blobdiff