Finished attempt at the new socket implementation.
[doldaconnect.git] / doc / man / doldacond.8
CommitLineData
9b522300 1.\"
302a2600 2.\" Copyright (C) 2007 Fredrik Tolf <fredrik@dolda2000.com>
9b522300 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.\"
e5834eb0 24.TH DOLDACOND 8 "2008-02-14" "" "Dolda Connect manual"
9b522300 25.SH NAME
26doldacond \- Dolda Connect daemon
27.SH SYNOPSIS
28.B doldacond
e5834eb0 29[ \fB-hnsV\fP ] [ \fB-C\fP \fIconfigfile\fP ]
4d06a8a5 30[ \fB-p\fP \fIpidfile\fP ] [ \fB-f\fP \fIfacility\fP ]
9b522300 31.SH DESCRIPTION
32The \fBdoldacond\fP program is the primary part of the collection of
33software that makes up Dolda Connect. It runs in the background and
4e38a36e
FT
34carries out all the actual work of filesharing. Other programs, such
35as \fBdolcon\fP(1), connect to \fBdoldacond\fP over a socket in order
36to command it and/or display its status to a user.
9b522300 37.P
38The configuration of \fBdoldacond\fP is controlled via the
39\fBdoldacond.conf\fP(5) file, which is described in detail in its own
40manual page.
41.SH OPTIONS
42.TP
43.B -h
44Displays a brief usage message on stdout and exits.
45.TP
46.B -s
47Normally, \fBdoldacond\fP will print log messages to stderr before it
48has daemonized, and switch to syslog output after daemonization. With
49the -s option, however, it will log to syslog directly, and never to
50stderr. It is probably only useful when starting \fBdoldacond\fP from
51an init script.
52.TP
53.B -n
54Causes \fBdoldacond\fP to not daemonize. As a side-effect of avoiding
55daemonization, log messages will be printed to stderr rather than to
56syslog even after the point where the daemon would normally have
57daemonized (unless the -s option is also specified).
58.TP
e5834eb0
FT
59.B -V
60Displays version and build information on stdout and exits.
61.TP
9b522300 62.BI -C " configfile"
63Use \fIconfigfile\fP instead of the normal search list for
64configuration files. See \fBdoldacond.conf\fP(5) for the normal
65behavior.
66.TP
67.BI -p " pidfile"
68Write the daemon's PID to \fIpidfile\fP after daemonization. Works
69even if the -n option has been specified.
70.TP
71.BI -f " facility"
72Use \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
76subset probably make sense for \fBdoldacond\fP. The default is
77\fBdaemon\fP. Also see the BUGS section.
78.SH FILES
79The 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
86Causes the daemon to reread its configuration file and update its
87operation accordingly, and to rescan all shared directories. SIGHUP
88can safely be sent at any time \- no connected clients or hubs will be
89affected.
90.TP
91.B SIGINT, SIGTERM
92Shut down the daemon cleanly, unlinking temporary files and sockets.
93.TP
94.B SIGUSR1, SIGUSR2
95Used for debugging. USR1 will cause the daemon to fork and dump a core
96file, and USR2 will dump some memory usage information to /tmp.
97.SH SECURITY
98Dolda Connect, including \fBdoldacond\fP and its assorted clients, are
99capable of a number of different authentication methods. The default
100configuration will cause the daemon to only listen for client
101connections on a Unix socket, over which authentication will be made
0bb98f50 102using Unix credentials passing.
103.P
104When running clients over a network, authentication can be done using
105either PAM, Kerberos 5 (requires the MIT libraries) or client trust
106(no authentication). Unix credentials passing and Kerberos
107authentication should be perfectly secure. PAM authentication should
108be secure in itself, but the client protocol is not encrypted, and
109therefore causes passwords to be sent over the network in the
110clear. Authentication-less operation is, obviously, not secure at all
111and is disabled by default. It may be useful on a trusted network,
112however.
9b522300 113.SH BUGS
114\fBdoldacond\fP has proved to be surprisingly stable. I have had it
115running for far longer than a month without any sign of instability or
116memory leaks, which is probably a lot longer than a program of this
117kind really needs to be able to stay running.
118.P
119That said, it is not without bugs. Here follows a list of the more
120prominent ones.
121.P
122Most importantly, \fBdoldacond\fP will fail miserably at sharing files
123from filesystems that do not have persistent i-numbers, since hashes
124are indexed by the i-number of the file. This is done so because
125indexing by i-numbers rather than file names allows the daemon to not
126rehash files that have merely been renamed. However, among the
127filesystems that do not have persistent i-numbers is the Linux
128implementation of FAT, which means that it is impossible to share
6bf74586 129files that are shared with Microsoft Windows. All the standard Unix
130filesystems, including at least ufs, ext2/3, reiserfs, xfs or any of
131them shared over nfs are known to be safe.
9b522300 132.P
133From time to time, the hash controller can get stuck, and stop
134processing more files. The obvious work-around is to restart
135\fBdoldacond\fP, at which point it will continue where it left off. If
136you feel adventurous and/or really need to not restart it, you can
137attach \fBgdb\fP(1) (or your debugger of choice) to the running
138\fBdoldacond\fP process and set the hashjob variable to -1, which will
139force \fBdoldacond\fP to resume hashing. Don't do that while a hash
140job is actually running, though.
9b522300 141.SH AUTHOR
142Fredrik Tolf <fredrik@dolda2000.com>
143.SH SEE ALSO
4e38a36e 144\fBdoldacond.conf\fP(5), \fBdolcon\fP(1)