mmlib/mmat: replace some variables by literal constants
[mmondor.git] / mmsoftware / mmspawnd2 / mmspawnd.conf.5
1 .\" $Id: mmspawnd.conf.5,v 1.1 2005/11/17 13:32:24 mmondor Exp $
2 .\"
3 .\" Copyright (C) 2003, Matthew Mondor
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\"    must display the following acknowledgement:
16 .\"      This product includes software written by Matthew Mondor.
17 .\" 4. The name of Matthew Mondor may not be used to endorse or promote
18 .\"    products derived from this software without specific prior written
19 .\"    permission.
20 .\" 5. Redistribution of source code may not be released under the terms of
21 .\"    any GNU Public License derivate.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY MATTHEW MONDOR ``AS IS'' AND ANY EXPRESS OR
24 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
26 .\" IN NO EVENT SHALL MATTHEW MONDOR BE LIABLE FOR ANY DIRECT, INDIRECT,
27 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
29 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
32 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 .\"
34 .Dd October 28, 2003
35 .Dt MMSPAWND.CONF 5
36 .Os mmsoftware
37 .Sh NAME
38 .Nm mmspawnd.conf
39 .Nd
40 .Xr mmspawnd.conf 5
41 configuration file for
42 .Xr mmspawnd 8
43 .Sh DESCRIPTION
44 The
45 .Nm /usr/local/etc/mmspawnd.conf
46 file may contain one or more keyword/value pairs per line, empty lines or
47 comments.  A ';' or '#' character causes all other characters to be considered
48 as a comment, and to be ignored, until the end of the current line. It is
49 very important to enclose the value for a keyword in double quotes ('"'
50 characters) if the following characters are found in it: ';', '#', space and
51 tab. It is allowed to use an equal sign '=' between the keyword name and it's
52 argument. Here are documented the various possible keywords and their
53 allowed values, as well as their defaults.
54 .Pp
55 .Ss Service administration parameters
56 .Pp
57 .Bl -tag -width indent -offset indent
58 .It Nm CHROOT_DIR Ar "directory"
59 If specified and non-empty, causes the daemon to use
60 .Xr chroot 2
61 at initialization so that it becomes jailed into the wanted alternative root
62 directory. Obviously, all required files for the application should have a copy
63 within the new root (this may include files such as
64 .Nm /etc/resolv.conf ,
65 .Nm /etc/hosts ,
66 .Nm /etc/passwd ,
67 .Nm /etc/group ,
68 a few shared libraries, the executable binary to be launched, and so on,
69 as required by the application and libc.
70 .It Nm LOCK_PATH Ar "fullpath"
71 Specifies the location where the internal synchronization (and anti-recursive
72 runlock) are to be created (before chrooting). Should consist of an absolute
73 full pathname including a filename, after which will automatically be postfixed
74 extensions for the various locks.
75 When several server instances are run concurrently to serve multiple services,
76 the name of the lock files should be different for each to not conflict.
77 .It Nm PID_PATH Ar "fullpath"
78 Tells where to store the file holding the server process ID to be killed with
79 .Dv SIGTERM
80 (sig 15) to cause the server to cleanly exit. This is done before chrooting.
81 When several server instances are run concurrently to serve multiple services,
82 the name of the PID files should be different for each to not conflict.
83 .It Nm ALOCK_PATH Ar "fullpath"
84 If specified and non-empty, this enables a special feature of
85 .Nm mmspawnd
86 which allows advisory locking to be used on a special file with third
87 party applications to synchronize with the service. This obviously should
88 be configured with care, but is most useful with some setups. The file
89 will be created before calling
90 .Xr chroot 2
91 and thus anywhere wanted on the filesystem.
92 .Pp
93 When this facility is enabled,
94 .Nm mmspawnd
95 uses
96 .Xr flock 2
97 to obtain an exclusive advisory lock on that file whenever one or more
98 connections exist, still being served by the service. This means that
99 whenever another application is allowed to obtain the lock using the
100 same manner (it should also use exclusive mode), no clients are connected
101 anymore to the service, and the other application may be allowed to safely
102 perform special operations which requires the service to be busy. For as long
103 as the file remains locked by the third party application, the
104 .Nm mmspawnd
105 server will refuse connections from any users (it will in fact accept them
106 but immediately drop the connection without running the service). As soon
107 as the other application releases back the lock, normal operation is resumed.
108 .Pp
109 .Xr mmanoncvs 8
110 for instance uses this feature during the short amount of time required for
111 two rename(2) operations to update the public cvs pserver read-only repository.
112 It is very important to make sure that permissions are properly set on the
113 lock file when using this feature, to only enable the wanted application to
114 obtain the lock (which requires at least read access to the file). See
115 the few next options to do this.
116 .It Nm ALOCK_USER Ar "user"
117 When the
118 .Nm ALOCK_PATH
119 is set, enabling the alock feature, this specifies the user which should be
120 set to be the owner of the lock file.
121 .It Nm ALOCK_GROUP Ar "group"
122 When the alock feature is enabled, tells which group should be set for the lock
123 file.
124 .It Nm ALOCK_MODE Ar "mode"
125 To be used when the alock feature is enabled. Specifies the permission mode
126 bits to apply to the lock file, so that only the intended application can use
127 it.
128 .It Nm USER Ar "user"
129 At server initialization, it drops privileges from the superuser to the
130 specified user, definitively. This can be specified as either a username
131 or it's user ID number.
132 .It Nm GROUPS Ar "group,..."
133 When dropping privileges, the process will become part of these groups.
134 More than one group may be specified, by name or ID, separated by commas,
135 without spaces. The first group will be set to the real process group, and
136 others as secondary access ones.
137 .It Nm LOG_FACILITY Ar "facility"
138 Syslog facility which should be used for error logging. Should normally be
139 one of
140 .Dv LOG_AUTH , LOG_AUTHPRIV , LOG_CRON,  LOG_DAEMON ,
141 .Dv LOG_FTP , LOG_KERN , LOG_LPR , LOG_MAIL ,
142 .Dv LOG_NEWS , LOG_SYSLOG , LOG_USER
143 or
144 .Dv LOG_UUCP .
145 See
146 .Xr syslog 3
147 man page for more information.
148 .It Nm COMMAND Ar "command"
149 Specifies the command which should be executed for each client which will
150 be served. There can be as many command line arguments as
151 .Nm MAX_ARGUMENTS
152 allows. The path to the executable to launch should be absolute. No globbing
153 or substitution of any kind is done on the arguments. It is allowed to
154 delimit arguments containing spaces or tabs into single quotes (').
155 .It Nm MAX_ARGUMENTS Ar "number"
156 This parameter sets the maximum allowed number of command line parameters which
157 can be passed to the application in
158 .Sy COMMAND .
159 .It Nm PROCTITLE Ar "string"
160 This is useful if multiple services are served using
161 .Xr mmspawnd 8
162 for commands such as
163 .Xr ps 1 ,
164 notably on BSD systems. Where available, this causes the supplied string
165 to prefix the comments attached to the processes using
166 .Xr setproctitle 3 .
167 It also is appended to the daemon name for
168 .Xr syslog 3
169 at
170 .Xr openlog 3
171 time.
172 .El
173 .Ss TCP server administration
174 .Bl -tag -width indent -offset indent
175 .It Nm LISTEN_ADDRESSES Ar "address ..."
176 Tells to which interfaces the server should listen to, separated by spaces.
177 The arguments should be enclosed in double quotes if more than one address
178 is supplied. These addresses are used for
179 .Xr bind 2 .
180 Specifying "0.0.0.0" causes
181 .Nm mmspawnd
182 to listen to all interfaces.
183 .It Nm LISTEN_PORT Ar "number"
184 Supplies which TCP port number to listen to. This must be a numeric port number
185 within the range of 1 to 65535.
186 .It Nm MAX_CONNECTIONS Ar "number"
187 The maximum number of simultaneous clients which should be served at once.
188 .It Nm MAX_ADDRESSES Ar "number"
189 The maximum number of simultaneous different client IP addresses to serve.
190 .It Nm MAX_PER_ADDRESS Ar "number"
191 The maximum number of simultaneous clients to serve at once per IP address.
192 .It Nm CONNECTION_RATE Ar "number"
193 The maximum number of connections to accept from each address within
194 .Nm CONNECTION_PERIOD .
195 Can be 0 to disable connection rate throttling.
196 .It Nm CONNECTION_PERIOD Ar "number"
197 If
198 .Nm CONNECTION_RATE
199 is non-zero, specifies the number of seconds during which a maximum of
200 .Nm CONNECTION_RATE
201 connections are to be allowed.
202 .It Nm RESOLVE_ADDRESSES Ar "boolean"
203 Specifies weither client addresses should be resolved to hostnames when
204 logging the connection event via
205 .Xr syslog 3 .
206 An internal cache is maintained for recently connected addresses for faster
207 performance. This is done in the child serving process so that it does not
208 slow down the listener process responsible for accepting new connections.
209 Should be TRUE or FALSE.
210 .El
211 .Ss Application security limits
212 .Bl -tag -width indent -offset indent
213 .It Nm COMMAND_TIMEOUT Ar "seconds"
214 Specifies the maximum number of seconds allowed for complete execution of
215 .Nm COMMAND .
216 If the command does not terminate before this number of seconds elapse, it
217 is forcefully killed using the
218 .Dv SIGTERM
219 signal. Beware to put this limit high enough so that it does not interfere
220 with normal service operation. This feature however allows to get rid of
221 eternally idle or frozen sessions.
222 .Pp
223 Eventually, support for network inactivity timeout, as well as bandwidth
224 shaping/throttling will be added. However, since those require a new design
225 and a rewrite of
226 .Xr mmspawnd 8 ,
227 this is the best we can do for now. (This behavior is still better than
228 .Xr inetd 8 ,
229 however). We also ensure to set the
230 .Dv SO_KEEPALIVE
231 option on the client descriptors to better recognize connection problems and
232 act accordingly to stop the process.
233 .It Nm RLIMITS Ar "boolean"
234 If TRUE, all following
235 .Nm RLIMIT_*
236 parameters will be applied to the children processes before launching the
237 application command if they are not set to -1 values.
238 .Xr setrlimit 2
239 is called to perform this. Note that these should be set to sane values
240 for proper function, by a competent administrator, if this option is
241 enabled. When disabled, or if enabled but for each following option specified
242 with -1, the defaults are used, which are inherited from the server process.
243 .Bl -tag -width indent -offset indent
244 .It Nm RLIMIT_CORE Ar "value"
245 If not -1, the largest size (in bytes) core file that may be created.
246 .It Nm RLIMIT_CPU Ar "value"
247 If not -1, The maximum amount of cpu time (in seconds) to be used by
248 each process.
249 .It Nm RLIMIT_DATA Ar "value"
250 -1 or The maximum size (in bytes) of the data segment for a process;
251 this defines how far a program may extend its break with the
252 .Xr sbrk 2
253 or
254 .Xr mmap 2
255 system calls.
256 .It Nm RLIMIT_FSIZE Ar "value"
257 The largest size (in bytes) file that may be created, or -1.
258 .It Nm RLIMIT_MEMLOCK Ar "value"
259 The maximum size (in bytes) which a process may lock into physical memory
260 (wire) using the
261 .Xr mlock 2
262 system call function, or -1.
263 .It Nm RLIMIT_NOFILE Ar "value"
264 If not -1, the maximum number of open files for this process.
265 .It Nm RLIMIT_NPROC Ar "value"
266 The maximum number of simultaneous processes for this user ID, or -1.
267 .It Nm RLIMIT_RSS Ar "value"
268 The maximum size (in bytes) to which a process's resident
269 set size may grow.  This imposes a limit on the amount of
270 physical memory to be given to a process; if memory is
271 tight, the system will prefer to take memory from processes
272 that are exceeding their declared resident set size.
273 -1 to use the defaults.
274 .It Nm RLIMIT_STACK Ar "value"
275 If not -1, the maximum size (in bytes) of the stack segment for a
276 process; this defines how far a program's stack segment
277 may be extended.  Stack extension is performed automatically by the system.
278 .El
279 .El
280 .Ss Debugging support
281 .Bl -tag -width indent -offset indent
282 .It Nm STDERR_FILE Ar "fullpath"
283 By default, the standard error stream (stderr) of
284 .Nm COMMAND
285 is redirected to the "/dev/null" device. However, it may be nice to be able
286 to obtain those messages from time to time, or to see if any are generated
287 by the application. This option, if non-empty, creates, or appends to the
288 specified file (outside of the chroot setup). This option should not be
289 used on production systems, as the file will grow without bounds. If a log
290 rotation system is used,
291 .Xr mmspawnd 8
292 will require to be restarted everytime it is ran. It is merely for debugging.
293 .El
294 .Sh DEFAULTS
295 The following defaults are used:
296 .Pp
297 .Bd -literal -offset indent
298 CHROOT_DIR              ""
299 LOCK_PATH               "/var/run/mmspawnd.lock"
300 PID_PATH                "/var/run/mmspawnd.pid"
301 ALOCK_PATH              ""
302 ALOCK_USER              "mmspawnd"
303 ALOCK_GROUP             "mmspawnd"
304 ALOCK_MODE              "400"
305 USER                    "mmspawnd"
306 GROUPS                  "mmspawnd"
307 LOG_FACILITY            "LOG_AUTHPRIV"
308 COMMAND                 "/sbin/nologin"
309 MAX_ARGUMENTS           16
310 PROCTITLE               ""
311
312 LISTEN_ADDRESSES        "127.0.0.1"
313 LISTEN_PORT             2323
314 MAX_CONNECTIONS         32
315 MAX_ADDRESSES           32
316 MAX_PER_ADDRESS         1
317 CONNECTION_RATE         5
318 CONNECTION_PERIOD       30
319 RESOLVE_ADDRESSES       FALSE
320
321 COMMAND_TIMEOUT         300
322 RLIMITS                 FALSE
323 RLIMIT_CORE             -1
324 RLIMIT_CPU              -1
325 RLIMIT_DATA             -1
326 RLIMIT_FSIZE            -1
327 RLIMIT_MEMLOCK          -1
328 RLIMIT_NOFILE           -1
329 RLIMIT_NPROC            -1
330 RLIMIT_RSS              -1
331 RLIMIT_STACK            -1
332
333 STDERR_FILE             ""
334 .Ed
335 .Sh AUTHOR
336 .Nm mmspawnd
337 was written by Matthew Mondor, and is
338 Copyright (c) 2003, Matthew Mondor, All rights reserved.
339 .Sh FILES
340 .Bl -tag -width indent -offset indent
341 .It Pa /usr/local/etc/mmspawnd.conf
342 This file
343 .It Pa /usr/local/sbin/mmspawnd
344 The
345 .Xr mmspawnd 8
346 server binary itself.
347 .El
348 .Sh SEE ALSO
349 .Xr mmspawnd 8 ,
350 .Xr syslog 3 ,
351 .Xr openlog 3 ,
352 .Xr chroot 2 ,
353 .Xr bind 2 ,
354 .Xr setrlimit 2 ,
355 .Xr ps 1 ,
356 .Xr setproctitle 3 .
357 .Sh BUGS
358 Not really a bug, but tied to each interface could be most connection control
359 options.
360 .Pp
361 Please report any bug to mmondor@accela.net