| 1 | .\" |
| 2 | .\" Copyright (C) 2007 Fredrik Tolf (fredrik@dolda2000.com) |
| 3 | .\" |
| 4 | .\" This is free documentation; you can redistribute it and/or |
| 5 | .\" modify it under the terms of the GNU General Public License as |
| 6 | .\" published by the Free Software Foundation; either version 2 of |
| 7 | .\" the License, or (at your option) any later version. |
| 8 | .\" |
| 9 | .\" The GNU General Public License's references to "object code" |
| 10 | .\" and "executables" are to be interpreted as the output of any |
| 11 | .\" document formatting or typesetting system, including |
| 12 | .\" intermediate and printed output. |
| 13 | .\" |
| 14 | .\" This manual is distributed in the hope that it will be useful, |
| 15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 17 | .\" GNU General Public License for more details. |
| 18 | .\" |
| 19 | .\" You should have received a copy of the GNU General Public |
| 20 | .\" License along with this manual; if not, write to the Free |
| 21 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, |
| 22 | .\" USA. |
| 23 | .\" |
| 24 | .TH DOLDACOND 8 "2007-04-11" "" "Dolda Connect manual" |
| 25 | .SH NAME |
| 26 | doldacond \- Dolda Connect daemon |
| 27 | .SH SYNOPSIS |
| 28 | .B doldacond |
| 29 | [ \fB-hns\fP ] [ \fB-C\fP \fIconfigfile\fP ] |
| 30 | [ \fB-p\fP \fIpidfile\fP ] [ \fB-f\fP \fIfacility\fP ] |
| 31 | .SH DESCRIPTION |
| 32 | The \fBdoldacond\fP program is the primary part of the collection of |
| 33 | software that makes up Dolda Connect. It runs in the background and |
| 34 | carries out all the actual work of filesharing. Other programs connect |
| 35 | to \fBdoldacond\fP over a socket in order to command it and/or display |
| 36 | its status to a user. |
| 37 | .P |
| 38 | The configuration of \fBdoldacond\fP is controlled via the |
| 39 | \fBdoldacond.conf\fP(5) file, which is described in detail in its own |
| 40 | manual page. |
| 41 | .SH OPTIONS |
| 42 | .TP |
| 43 | .B -h |
| 44 | Displays a brief usage message on stdout and exits. |
| 45 | .TP |
| 46 | .B -s |
| 47 | Normally, \fBdoldacond\fP will print log messages to stderr before it |
| 48 | has daemonized, and switch to syslog output after daemonization. With |
| 49 | the -s option, however, it will log to syslog directly, and never to |
| 50 | stderr. It is probably only useful when starting \fBdoldacond\fP from |
| 51 | an init script. |
| 52 | .TP |
| 53 | .B -n |
| 54 | Causes \fBdoldacond\fP to not daemonize. As a side-effect of avoiding |
| 55 | daemonization, log messages will be printed to stderr rather than to |
| 56 | syslog even after the point where the daemon would normally have |
| 57 | daemonized (unless the -s option is also specified). |
| 58 | .TP |
| 59 | .BI -C " configfile" |
| 60 | Use \fIconfigfile\fP instead of the normal search list for |
| 61 | configuration files. See \fBdoldacond.conf\fP(5) for the normal |
| 62 | behavior. |
| 63 | .TP |
| 64 | .BI -p " pidfile" |
| 65 | Write the daemon's PID to \fIpidfile\fP after daemonization. Works |
| 66 | even if the -n option has been specified. |
| 67 | .TP |
| 68 | .BI -f " facility" |
| 69 | Use \fIfacility\fP when logging to syslog. The facility can be any of |
| 70 | \fBauth\fP, \fBauthpriv\fP, \fBcron\fP, \fBdaemon\fP, \fBftp\fP, |
| 71 | \fBkern\fP, \fBlpr\fP, \fBmail\fP, \fBnews\fP, \fBsyslog\fP, |
| 72 | \fBuser\fP, \fBuucp\fP or \fBlocal0\fP...\fB7\fP, although only a |
| 73 | subset probably make sense for \fBdoldacond\fP. The default is |
| 74 | \fBdaemon\fP. Also see the BUGS section. |
| 75 | .SH FILES |
| 76 | The configuration file will normally be called |
| 77 | /usr/local/etc/doldacond.conf, /etc/doldacond.conf or |
| 78 | ~/.doldacond.conf, but a multitude of others are possible. See the |
| 79 | \fBdoldacond.conf\fP(5) manual page for details. |
| 80 | .SH SIGNALS |
| 81 | .TP |
| 82 | .B SIGHUP |
| 83 | Causes the daemon to reread its configuration file and update its |
| 84 | operation accordingly, and to rescan all shared directories. SIGHUP |
| 85 | can safely be sent at any time \- no connected clients or hubs will be |
| 86 | affected. |
| 87 | .TP |
| 88 | .B SIGINT, SIGTERM |
| 89 | Shut down the daemon cleanly, unlinking temporary files and sockets. |
| 90 | .TP |
| 91 | .B SIGUSR1, SIGUSR2 |
| 92 | Used for debugging. USR1 will cause the daemon to fork and dump a core |
| 93 | file, and USR2 will dump some memory usage information to /tmp. |
| 94 | .SH SECURITY |
| 95 | Dolda Connect, including \fBdoldacond\fP and its assorted clients, are |
| 96 | capable of a number of different authentication methods. The default |
| 97 | configuration will cause the daemon to only listen for client |
| 98 | connections on a Unix socket, over which authentication will be made |
| 99 | using Unix credentials passing. |
| 100 | .P |
| 101 | When running clients over a network, authentication can be done using |
| 102 | either PAM, Kerberos 5 (requires the MIT libraries) or client trust |
| 103 | (no authentication). Unix credentials passing and Kerberos |
| 104 | authentication should be perfectly secure. PAM authentication should |
| 105 | be secure in itself, but the client protocol is not encrypted, and |
| 106 | therefore causes passwords to be sent over the network in the |
| 107 | clear. Authentication-less operation is, obviously, not secure at all |
| 108 | and is disabled by default. It may be useful on a trusted network, |
| 109 | however. |
| 110 | .SH BUGS |
| 111 | \fBdoldacond\fP has proved to be surprisingly stable. I have had it |
| 112 | running for far longer than a month without any sign of instability or |
| 113 | memory leaks, which is probably a lot longer than a program of this |
| 114 | kind really needs to be able to stay running. |
| 115 | .P |
| 116 | That said, it is not without bugs. Here follows a list of the more |
| 117 | prominent ones. |
| 118 | .P |
| 119 | Most importantly, \fBdoldacond\fP will fail miserably at sharing files |
| 120 | from filesystems that do not have persistent i-numbers, since hashes |
| 121 | are indexed by the i-number of the file. This is done so because |
| 122 | indexing by i-numbers rather than file names allows the daemon to not |
| 123 | rehash files that have merely been renamed. However, among the |
| 124 | filesystems that do not have persistent i-numbers is the Linux |
| 125 | implementation of FAT, which means that it is impossible to share |
| 126 | files that are shared with Microsoft Windows. All the standard Unix |
| 127 | filesystems, including at least ufs, ext2/3, reiserfs, xfs or any of |
| 128 | them shared over nfs are known to be safe. |
| 129 | .P |
| 130 | From time to time, the hash controller can get stuck, and stop |
| 131 | processing more files. The obvious work-around is to restart |
| 132 | \fBdoldacond\fP, at which point it will continue where it left off. If |
| 133 | you feel adventurous and/or really need to not restart it, you can |
| 134 | attach \fBgdb\fP(1) (or your debugger of choice) to the running |
| 135 | \fBdoldacond\fP process and set the hashjob variable to -1, which will |
| 136 | force \fBdoldacond\fP to resume hashing. Don't do that while a hash |
| 137 | job is actually running, though. |
| 138 | .SH AUTHOR |
| 139 | Fredrik Tolf <fredrik@dolda2000.com> |
| 140 | .SH SEE ALSO |
| 141 | \fBdoldacond.conf\fP(5) |