doc/man/doldacond.conf.5.in

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