Further clarify Linux TOS limitations.

[doldaconnect.git] / doc / man / doldacond.conf.5.in

.\"
.\" Copyright (C) 2007 Fredrik Tolf <fredrik@dolda2000.com>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.TH DOLDACOND.CONF 5 "@DATE@" "" "Dolda Connect manual"
.SH NAME
doldacond.conf \- Dolda Connect daemon configuration file
.SH DESCRIPTION
The \fBdoldacond\fP(8) daemon will examine the doldacond.conf file
upon startup and reception of SIGHUP. The file is written in a
line-oriented ASCII format, using the following rules.
.P
A line is either empty, a comment, or a configuration directive. Empty
lines are permitted to contain horizontal whitespace, but nothing
else. A comment line begins with a hash sign (`#'), optionally
preceded by whitespace. A configuration directive is a line with at
least one token, each token being a series of non-whitespace
characters or quoted whitespace characters. Quoting can be done either
by surrounding the characters to be quoted with double quotation
marks, or by preceding a single character to be quoted with a
backslash. The first token is considered the directive to be
evaluated, and the rest being arguments to the directive. Each of the
possible configuration directives are described in their own sections.
.SH CONFIGURATION VARIABLES
The vast majority of the daemon's configuration is controlled via
named configuration variables. The \fBset\fP directive is used to set
the value of the configuration variables, which obeys the following
syntax:
.P
\fBset\fP \fIvariable\fP \fIvalue\fP
.P
The value of a variable is either a boolean, an integer, a string or
an IPv4 address. Which one depends on the variable. A boolean may be
specified using either \fBtrue\fP/\fBfalse\fP, \fBon\fP/\fBoff\fP,
\fByes\fP/\fBno\fP or \fB1\fP/\fB0\fP. Integers may be given in either
decimal, octal or hexadecimal format, using standard C syntax \- that
is, hexadecimal numbers prefixed with \fB0x\fP, octal numbers prefixed
with \fB0\fP, or directly entered decimal numbers. Strings may contain
arbitrary Unicode characters, and are decoded according to the
system's default character coding. IPv4 addresses are specified in
dotted quad decimal notation. A list of all the known configuration
variables follows.
@VARIABLES@
.SH SHARES
A very central function of a file-sharing daemon is to share files. To
determine what files are to be shared, the \fBshare\fP directive is
used, according to the following syntax:
.P
\fBshare\fP \fIsharename\fP \fIpath\fP
.P
The \fIsharename\fP is the name of the share as seen by other peers on
the network. The \fIpath\fP is the path in the real filesystem to a
directory containing the files to be shared. All files under the
specified directory will be shared, except for files that begin with a
dot, or files that do not match the criteria given by the
\fBclient.scanfilemask\fP and \fBclient.scandirmask\fP variables, as
described above.
.P
The \fBshare\fP directive may be used multiple times to define several
shares.
.SH USER AUTHORIZATION
In multi-user mode (when running as root), the \fBdoldacond\fP(8)
daemon can serve multiple users, but commonly not every user on the
system should be authorized to be served. To specify which users to
serve, and to assign permissions to the users to be served, the
\fBuser\fP directive is used, according to the following syntax:
.P
\fBuser\fP {\fIusername\fP|\fBdefault\fP} [-]\fIpermission\fP...
.P
As indicated by the syntax, the special username \fBdefault\fP can be
used to specify permissions for users not matched by any other user
directive (if you have a user called \fBdefault\fP, tough luck).
.P
The assignable permissions are as follows:
.P
.TP
.B admin
Involves commands controlling the function of the daemon, such as
shutting it down remotely.
.TP
.B fnetctl
Allows connecting and disconnecting fnetnodes (a.k.a. hubs).
.TP
.B trans
Allows queuing of transfers.
.TP
.B transcu
Allows cancelling of uploads.
.TP
.B chat
Allows sending and receiving of chat messages.
.TP
.B srch
Allows submitting of search requests.
.TP
.B disallow
A negative permission, used to prevent a user from being
authorized. Mostly useful for the \fBdefault\fP user.
.TP
.B all
Sets all the above permssions.
.P
A permissions may be prefixed with a minus sign, which means that that
permission should be removed (commonly used after \fBall\fP, since
permissions are scanned from left to right).
.P
Note that the \fBall\fP pseudo-permission really turns on \fIall\fP
other permissions, including \fBdisallow\fP. Thus, to allow a user
jdoe full control over the daemon, one would normally use "\fBuser
jdoe all -disallow\fP".
.SH TOS VALUES
Some configuration variables specify IP Type of Service values. Valid
values for those variables are as follows:
.TP
0
System default TOS.
.TP
1
Minimize cost
.TP
2
Maximize reliability
.TP
3
Maximize throughput
.TP
4
Minimize delay
.P
How routers interpret TOS values is defined by the administrator of
those routers. For IPv6 connections, which use Diffserv instead of the
older IPv4 TOS values, the Diffserv values to use are specified by the
\fBnet.diffserv-mincost\fP, \fBnet.diffserv-maxrel\fP,
\fBnet.diffserv-maxtp\fP and \fBnet.diffserv-mindelay\fP configuration
variables, as described above. For a way to use DSCP in IPv4 as well,
see the \fBnet.dscp-tos\fP option above.
.SH FILES
All file names specified in the configuration file, and the
configuration file itself, are looked up by the daemon in a rather
flexible manner. The only difference between the main configuration
file and all other files is that the configuration must always be
named \fBdoldacond.conf\fP, while the name of all other files may be
specified in the configuration file. In all else, lookup is done
according to the following rules:
.TP
1
If the specified name contains any slashes (not applicable for
doldacond.conf), it will be considered absolute, and no locations
other than the explicitly specified will be examined.
.TP
2
The home directory of the user running the daemon (as specified by
either the \fBHOME\fP environment variable or as returned by the
\fBgetpwuid\fP(3) function) is checked for a dot-file with the
specified name.
.TP
3
If the \fBPATH\fP environment variable exists, the directories it
specifies are iterated, the last path element of each is replaced by
`etc', and the resulting directories are checked for the existence of
the specified file. For example, if \fBPATH\fP is
/bin:/opt/doldaconnect/bin:/usr/bin, the directories /etc,
/opt/doldaconnect/etc and /usr/etc will be checked for the file.
.TP
4
If the \fBPATH\fP environment variable does not exist (but \fInot\fP
if \fBPATH\fP does exist and the file simply could not be found
according to the previous rule), the directories /usr/local/etc, /etc
and /usr/etc are checked for the file.
.P
For files that are created on the fly, such as the hash cache, the
file will be overwritten in place if found. If not found, it will be
created in the home directory of the user running the daemon. If the
home directory cannot be determined, the file will be created in /etc.
.SH BUGS
The TOS-related options have a number of interesting quirks:
.TP
1
It is currently unclear to me whether Linux has an API to set IPv6
DSCP values, so it is left unimplemented for now.
.TP
2
I am rather sure that Linux lacks an API to set IPv4 DSCP
values. However, it seems that it is possible to use the TOS API to
set DSCP values, so it has been implemented as an option (see the
\fBnet.dscp-tos\fP options above).
.TP
3
Even though Linux lacks an explicit API to set the DSCP field in IPv4,
the TOS API is "DSCP compliant" in the interesting way that it masks
away the two least significant bits. Therefore, the minimum cost TOS
value cannot currently be set on Linux without patching the kernel.
.TP
4
I have not examined how these issues compare to other operating
systems, like FreeBSD.
.SH AUTHOR
Fredrik Tolf <fredrik@dolda2000.com>
.SH SEE ALSO
\fBdoldacond\fP(8)