Updated ChangeLog.
[doldaconnect.git] / doc / man / doldacond.conf.5.in
CommitLineData
7a80ce3c 1.\"
302a2600 2.\" Copyright (C) 2007 Fredrik Tolf <fredrik@dolda2000.com>
7a80ce3c 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.CONF 5 "@DATE@" "" "Dolda Connect manual"
25.SH NAME
26doldacond.conf \- Dolda Connect daemon configuration file
27.SH DESCRIPTION
13e05ddc 28The \fBdoldacond\fP(8) daemon will examine the doldacond.conf file
29upon startup and reception of SIGHUP. The file is written in a
7a80ce3c 30line-oriented ASCII format, using the following rules.
31.P
32A line is either empty, a comment, or a configuration directive. Empty
33lines are permitted to contain horizontal whitespace, but nothing
13e05ddc 34else. A comment line begins with a hash sign (`#'), optionally
35preceded by whitespace. A configuration directive is a line with at
36least one token, each token being a series of non-whitespace
37characters or quoted whitespace characters. Quoting can be done either
38by surrounding the characters to be quoted with double quotation
39marks, or by preceding a single character to be quoted with a
40backslash. The first token is considered the directive to be
41evaluated, and the rest being arguments to the directive. Each of the
42possible configuration directives are described in their own sections.
7a80ce3c 43.SH CONFIGURATION VARIABLES
44The vast majority of the daemon's configuration is controlled via
45named configuration variables. The \fBset\fP directive is used to set
46the value of the configuration variables, which obeys the following
47syntax:
48.P
49\fBset\fP \fIvariable\fP \fIvalue\fP
50.P
51The value of a variable is either a boolean, an integer, a string or
52an IPv4 address. Which one depends on the variable. A boolean may be
53specified using either \fBtrue\fP/\fBfalse\fP, \fBon\fP/\fBoff\fP,
54\fByes\fP/\fBno\fP or \fB1\fP/\fB0\fP. Integers may be given in either
55decimal, octal or hexadecimal format, using standard C syntax \- that
56is, hexadecimal numbers prefixed with \fB0x\fP, octal numbers prefixed
57with \fB0\fP, or directly entered decimal numbers. Strings may contain
58arbitrary Unicode characters, and are decoded according to the
59system's default character coding. IPv4 addresses are specified in
60dotted quad decimal notation. A list of all the known configuration
61variables follows.
62@VARIABLES@
3f47c229 63.SH SHARES
64A very central function of a file-sharing daemon is to share files. To
65determine what files are to be shared, the \fBshare\fP directive is
66used, according to the following syntax:
67.P
68\fBshare\fP \fIsharename\fP \fIpath\fP
69.P
70The \fIsharename\fP is the name of the share as seen by other peers on
71the network. The \fIpath\fP is the path in the real filesystem to a
72directory containing the files to be shared. All files under the
73specified directory will be shared, except for files that begin with a
74dot, or files that do not match the criteria given by the
75\fBclient.scanfilemask\fP and \fBclient.scandirmask\fP variables, as
76described above.
77.P
78The \fBshare\fP directive may be used multiple times to define several
79shares.
80.SH USER AUTHORIZATION
81In multi-user mode (when running as root), the \fBdoldacond\fP(8)
82daemon can serve multiple users, but commonly not every user on the
83system should be authorized to be served. To specify which users to
84serve, and to assign permissions to the users to be served, the
85\fBuser\fP directive is used, according to the following syntax:
86.P
87\fBuser\fP {\fIusername\fP|\fBdefault\fP} [-]\fIpermission\fP...
88.P
89As indicated by the syntax, the special username \fBdefault\fP can be
90used to specify permissions for users not matched by any other user
91directive (if you have a user called \fBdefault\fP, tough luck).
92.P
93The assignable permissions are as follows:
94.P
95.TP
96.B admin
97Involves commands controlling the function of the daemon, such as
98shutting it down remotely.
99.TP
100.B fnetctl
101Allows connecting and disconnecting fnetnodes (a.k.a. hubs).
102.TP
103.B trans
104Allows queuing of transfers.
105.TP
106.B transcu
107Allows cancelling of uploads.
108.TP
109.B chat
110Allows sending and receiving of chat messages.
111.TP
112.B srch
113Allows submitting of search requests.
114.TP
115.B disallow
116A negative permission, used to prevent a user from being
117authorized. Mostly useful for the \fBdefault\fP user.
118.TP
119.B all
120Sets all the above permssions.
121.P
122A permissions may be prefixed with a minus sign, which means that that
123permission should be removed (commonly used after \fBall\fP, since
124permissions are scanned from left to right).
125.P
126Note that the \fBall\fP pseudo-permission really turns on \fIall\fP
127other permissions, including \fBdisallow\fP. Thus, to allow a user
128jdoe full control over the daemon, one would normally use "\fBuser
129jdoe all -disallow\fP".
7a80ce3c 130.SH TOS VALUES
131Some configuration variables specify IP Type of Service values. Valid
132values for those variables are as follows:
133.TP
1340
135System default TOS.
136.TP
1371
138Minimize cost
139.TP
1402
141Maximize reliability
142.TP
1433
144Maximize throughput
145.TP
1464
147Minimize delay
148.P
149How routers interpret TOS values is defined by the administrator of
150those routers. For IPv6 connections, which use Diffserv instead of the
151older IPv4 TOS values, the Diffserv values to use are specified by the
152\fBnet.diffserv-mincost\fP, \fBnet.diffserv-maxrel\fP,
153\fBnet.diffserv-maxtp\fP and \fBnet.diffserv-mindelay\fP configuration
0062d351
FT
154variables, as described above. For a way to use DSCP in IPv4 as well,
155see the \fBnet.dscp-tos\fP option above.
7a80ce3c 156.SH FILES
157All file names specified in the configuration file, and the
158configuration file itself, are looked up by the daemon in a rather
159flexible manner. The only difference between the main configuration
160file and all other files is that the configuration must always be
161named \fBdoldacond.conf\fP, while the name of all other files may be
162specified in the configuration file. In all else, lookup is done
163according to the following rules:
164.TP
1651
166If the specified name contains any slashes (not applicable for
167doldacond.conf), it will be considered absolute, and no locations
168other than the explicitly specified will be examined.
169.TP
1702
171The home directory of the user running the daemon (as specified by
172either the \fBHOME\fP environment variable or as returned by the
173\fBgetpwuid\fP(3) function) is checked for a dot-file with the
174specified name.
175.TP
1763
177If the \fBPATH\fP environment variable exists, the directories it
178specifies are iterated, the last path element of each is replaced by
179`etc', and the resulting directories are checked for the existence of
180the specified file. For example, if \fBPATH\fP is
181/bin:/opt/doldaconnect/bin:/usr/bin, the directories /etc,
182/opt/doldaconnect/etc and /usr/etc will be checked for the file.
183.TP
1844
185If the \fBPATH\fP environment variable does not exist (but \fInot\fP
186if \fBPATH\fP does exist and the file simply could not be found
187according to the previous rule), the directories /usr/local/etc, /etc
188and /usr/etc are checked for the file.
189.P
190For files that are created on the fly, such as the hash cache, the
191file will be overwritten in place if found. If not found, it will be
192created in the home directory of the user running the daemon. If the
193home directory cannot be determined, the file will be created in /etc.
13e05ddc 194.SH BUGS
0062d351
FT
195The TOS-related options have a number of interesting quirks:
196.TP
1971
198It is currently unclear to me whether Linux has an API to set IPv6
199DSCP values, so it is left unimplemented for now.
200.TP
2012
202I am rather sure that Linux lacks an API to set IPv4 DSCP
203values. However, it seems that it is possible to use the TOS API to
204set DSCP values, so it has been implemented as an option (see the
205\fBnet.dscp-tos\fP options above).
206.TP
2073
208Even though Linux lacks an explicit API to set the DSCP field in IPv4,
209the TOS API is "DSCP compliant" in the interesting way that it masks
210away the two least significant bits. Therefore, the minimum cost TOS
bb3900f7 211value cannot currently be set on Linux without patching the kernel.
0062d351
FT
212.TP
2134
214I have not examined how these issues compare to other operating
215systems, like FreeBSD.
7a80ce3c 216.SH AUTHOR
217Fredrik Tolf <fredrik@dolda2000.com>
218.SH SEE ALSO
219\fBdoldacond\fP(8)