doc/man/doldacond.8

   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 "2008-02-14" "" "Dolda Connect manual"
  25 .SH NAME
  26 doldacond \- Dolda Connect daemon
  27 .SH SYNOPSIS
  28 .B doldacond
  29 [ \fB-hnsV\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, such
  35 as \fBdolcon\fP(1), connect to \fBdoldacond\fP over a socket in order
  36 to command it and/or display 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 .B -V
  60 Displays version and build information on stdout and exits.
  61 .TP
  62 .BI -C " configfile"
  63 Use \fIconfigfile\fP instead of the normal search list for
  64 configuration files. See \fBdoldacond.conf\fP(5) for the normal
  65 behavior.
  66 .TP
  67 .BI -p " pidfile"
  68 Write the daemon's PID to \fIpidfile\fP after daemonization. Works
  69 even if the -n option has been specified.
  70 .TP
  71 .BI -f " facility"
  72 Use \fIfacility\fP when logging to syslog. The facility can be any of
  73 \fBauth\fP, \fBauthpriv\fP, \fBcron\fP, \fBdaemon\fP, \fBftp\fP,
  74 \fBkern\fP, \fBlpr\fP, \fBmail\fP, \fBnews\fP, \fBsyslog\fP,
  75 \fBuser\fP, \fBuucp\fP or \fBlocal0\fP...\fB7\fP, although only a
  76 subset probably make sense for \fBdoldacond\fP. The default is
  77 \fBdaemon\fP. Also see the BUGS section.
  78 .SH FILES
  79 The configuration file will normally be called
  80 /usr/local/etc/doldacond.conf, /etc/doldacond.conf or
  81 ~/.doldacond.conf, but a multitude of others are possible. See the
  82 \fBdoldacond.conf\fP(5) manual page for details.
  83 .SH SIGNALS
  84 .TP
  85 .B SIGHUP
  86 Causes the daemon to reread its configuration file and update its
  87 operation accordingly, and to rescan all shared directories. SIGHUP
  88 can safely be sent at any time \- no connected clients or hubs will be
  89 affected.
  90 .TP
  91 .B SIGINT, SIGTERM
  92 Shut down the daemon cleanly, unlinking temporary files and sockets.
  93 .TP
  94 .B SIGUSR1, SIGUSR2
  95 Used for debugging. USR1 will cause the daemon to fork and dump a core
  96 file, and USR2 will dump some memory usage information to /tmp.
  97 .SH SECURITY
  98 Dolda Connect, including \fBdoldacond\fP and its assorted clients, are
  99 capable of a number of different authentication methods. The default
 100 configuration will cause the daemon to only listen for client
 101 connections on a Unix socket, over which authentication will be made
 102 using Unix credentials passing.
 103 .P
 104 When running clients over a network, authentication can be done using
 105 either PAM, Kerberos 5 (requires the MIT libraries) or client trust
 106 (no authentication). Unix credentials passing and Kerberos
 107 authentication should be perfectly secure. PAM authentication should
 108 be secure in itself, but the client protocol is not encrypted, and
 109 therefore causes passwords to be sent over the network in the
 110 clear. Authentication-less operation is, obviously, not secure at all
 111 and is disabled by default. It may be useful on a trusted network,
 112 however.
 113 .SH BUGS
 114 \fBdoldacond\fP has proved to be surprisingly stable. I have had it
 115 running for far longer than a month without any sign of instability or
 116 memory leaks, which is probably a lot longer than a program of this
 117 kind really needs to be able to stay running.
 118 .P
 119 That said, it is not without bugs. Here follows a list of the more
 120 prominent ones.
 121 .P
 122 Most importantly, \fBdoldacond\fP will fail miserably at sharing files
 123 from filesystems that do not have persistent i-numbers, since hashes
 124 are indexed by the i-number of the file. This is done so because
 125 indexing by i-numbers rather than file names allows the daemon to not
 126 rehash files that have merely been renamed. However, among the
 127 filesystems that do not have persistent i-numbers is the Linux
 128 implementation of FAT, which means that it is impossible to share
 129 files that are shared with Microsoft Windows. All the standard Unix
 130 filesystems, including at least ufs, ext2/3, reiserfs, xfs or any of
 131 them shared over nfs are known to be safe.
 132 .P
 133 From time to time, the hash controller can get stuck, and stop
 134 processing more files. The obvious work-around is to restart
 135 \fBdoldacond\fP, at which point it will continue where it left off. If
 136 you feel adventurous and/or really need to not restart it, you can
 137 attach \fBgdb\fP(1) (or your debugger of choice) to the running
 138 \fBdoldacond\fP process and set the hashjob variable to -1, which will
 139 force \fBdoldacond\fP to resume hashing. Don't do that while a hash
 140 job is actually running, though.
 141 .SH AUTHOR
 142 Fredrik Tolf <fredrik@dolda2000.com>
 143 .SH SEE ALSO
 144 \fBdoldacond.conf\fP(5), \fBdolcon\fP(1)