path: root/doc/gsc.texi
Diffstat (limited to 'doc/gsc.texi') (more/less context) (show whitespace changes)
1 files changed, 0 insertions, 449 deletions
diff --git a/doc/gsc.texi b/doc/gsc.texi
index 29e5e1b..87e1ce5 100644
--- a/doc/gsc.texi
+++ b/doc/gsc.texi
@@ -119,23 +119,11 @@ Root Utilities
119* bind replication:: A Framework for Replicating Master @command{bind} Server. 119* bind replication:: A Framework for Replicating Master @command{bind} Server.
120* firewall:: M4 Wrappers For Setting Firewalls. 120* firewall:: M4 Wrappers For Setting Firewalls.
121* session-cleanup:: Manage PHP Sessions. 121* session-cleanup:: Manage PHP Sessions.
122* jabberd:: Jabberd dispatcher daemon.
123 122
124firewall 123firewall
125 124
126* Primitives:: A set of primitives defined in @file{firewall.m4} 125* Primitives:: A set of primitives defined in @file{firewall.m4}
127 126
130* jabintro:: Jabberd Operation Overview
131* jabopts:: Command Line Options.
132* jabberd.cfg:: Main Jabberd Configuration File.
134Jabberd Configuration File
136* cfgstat:: Configuration File Statements
137* example:: An Example of the Configuration file
139Startup Scripts 127Startup Scripts
140 128
141 * rc.inet1:: A Replacement for Slackware @command{rc.inet1}. 129 * rc.inet1:: A Replacement for Slackware @command{rc.inet1}.
@@ -841,7 +829,6 @@ cases, though not always. Such files should probably be inspected after
841* bind replication:: A Framework for Replicating Master @command{bind} Server. 829* bind replication:: A Framework for Replicating Master @command{bind} Server.
842* firewall:: M4 Wrappers For Setting Firewalls. 830* firewall:: M4 Wrappers For Setting Firewalls.
843* session-cleanup:: Manage PHP Sessions. 831* session-cleanup:: Manage PHP Sessions.
844* jabberd:: Jabberd dispatcher daemon.
845@end menu 832@end menu
846 833
847@node ckaliases 834@node ckaliases
@@ -1167,442 +1154,6 @@ actually remove them.
1167@option{-n}. 1154@option{-n}.
1168@end table 1155@end table
1169 1156
1170@node jabberd
1171@section Jabberd
1172@cindex jabberd
1173 The @command{jabberd} utility is a dispatcher daemon for
1174@samp{Jabberd 2.x}
1175(@uref{}). It is
1176intended as a replacement for the similar utility shipped with the
1177@samp{jabberd 2.x} package. There were two reasons that urged for the
1178replacement: first, the original @command{jabberd} is written in Perl
1179and consumes way too many resources because of that. Secondly, it is
1180not flexible enough. In particular, it is only able to control jabber
1181daemons, but cannot control external transports (such as @acronym{GG}
1182or @acronym{GIT}.
1185* jabintro:: Jabberd Operation Overview
1186* jabopts:: Command Line Options.
1187* jabberd.cfg:: Main Jabberd Configuration File.
1188@end menu
1190@node jabintro
1191@subsection Jabberd Operation Overview
1193 The @acronym{GSC} @command{jabberd} is a supervisor daemon that
1194starts a number of @dfn{components} and controls their execution.
1195A component is either a jabberd core component (as,
1196e.g. @command{c2s}) or some external program (e.g. a transport). The
1197daemon reads the list of components from its configuration file upon
1198startup. By default, the configuration file is named
1199@file{jabberd.cfg} and is located in @code{$sysconfdir} directory, but
1200its exact location can be overridden at startup (see @option{-c}
1201option, below). If run with the root privileges, @command{jabberd}
1202switches to the privileges of a selected user (by default
1203@samp{jabber}) right after startup. Then, the program changes file
1204creation mask to a safe value (the default is @samp{037}). Unless
1205explicitly requested to remain in the foreground, the utility detaches
1206itself from the controlling terminal and switches to the background.
1207The daemon starts the configured components
1208in the order of their appearance in the configuration file. The exact
1209command line options and arguments for each component are specified
1210in the configuration file. If a particular subprocess prints its
1211diagnostics on stderr or stdout, you may instruct @command{jabberd} to
1212capture and divert it to a particular @command{syslogd}
1213priority (@pxref{stdout}). After launching the components
1214@command{jabberd} enters its main loop. It sleeps until either some
1215component finishes or a signal is delivered. If a component finishes,
1216@command{jabberd} scans its internal list to find components that
1217depend on the finished one. Each such component is then terminated
1218by sending it @acronym{SIGTERM} signal. Then, the finished component and
1219its dependent components are started again. If a process is
1220restarted more than 10 times within a two minutes interval, it is
1221disabled for the next five minutes (the same way the standard
1222@acronym{UNIX} @command{init} utility operates).
1224 The @command{jabberd} utility exits if it recieves any of the
1225following signals: @acronym{SIGTERM}, @acronym{SIGQUIT},
1226@acronym{SIGINT}. It attempts to restart itself if delivered the
1227@acronym{SIGHUP} signal. This is possible only if the utility is
1228started using its absolute file name. In any case, before exiting,
1229the utility shuts down all components @emph{in the reverse
1230order} of their appearance in the configuration file. The processes
1231are shut down by sending them @acronym{SIGTERM} signals. If a
1232component does not exit within a 1 second interval, it is re-sent the
1233same signal. This procedure continues until either all components
1234terminate or the @dfn{shutdown timeout} interval expires, whichever
1235happens first. If the latter happens, any components still left
1236running are slayed using @acronym{SIGKILL} signal. The default
1237shutdown timeout is 5 seconds and it may be changed using
1238@code{shutdown-timeout} configuration file statement (@pxref{cfgstat}).
1240 Two signals are special to @command{jabberd}: @acronym{SIGUSR1}
1241and @acronym{SIGUSR2}. The @acronym{SIGUSR1} signal instructs the
1242program to shut down and restart a particular component or a set
1243of components. The list of components to be restarted is passed to
1244the running program via a @dfn{control file} (@pxref{ctlfile}). This
1245mechanism is used by @command{jabberd
1246--restart}. @FIXME-xref{restarting selected components}.
1248 The @acronym{SIGUSR2} signal instructs @command{jabberd} to return
1249statistics about running components. It is used by @command{jabberd
1250--status} (@FIXME-pxref{showing runtime statistics}).
1252@node jabopts
1253@subsection Jabberd Invocation
1256 By default, @command{jabberd} attempts to start in @dfn{dispatcher
1257mode}, which is described in the previous subsection. If started
1258without additional options, the program will use compiled-in defaults.
1259Otherwise, the following options may be given:
1261@table @option
1262@item --config-file=@var{file}
1263@itemx -c @var{file}
1264 Use @var{file} as the main configuration file.
1266@item --debug
1267@itemx -D
1268 Increase debugging level.
1270@item --foreground
1271@itemx -f
1272 Do not disconnect from the controlling terminal, but run in
1273foreground mode instead. This option is mainly useful for debugging.
1274It implies @option{-e} (see below).
1276@item --force
1277 Attempt to start up even if another instance of @command{jabberd}
1278seems to be running.
1280@item --stderr
1281@itemx -e
1282 Print all diagnostics on the standard output.
1283@end table
1285 A set of options may be used to control the running instance of the
1286program and request a detailed information about it.
1288@table @option
1289@item --restart @var{tag} [@var{tags}...]
1290@itemx -r @var{tag} [@var{tag}...]
1291 Restart named components. Any number of arguments can be
1292specified. Each @var{tag} must correspond to a valid tag in
1293@file{jabberd.cfg} file.
1295@item --status
1296 Display information about the running instance. Return 0 if the
1297instance is running, 1 otherwise.
1300$ jabberd --status
1301jabberd: [INFO] jabberd is running; PID 537
1302retranslator jit/stderr 548
1303retranslator jit/stdout 547
1304retranslator ggtrans/stderr 545
1305retranslator ggtrans/stdout 544
1306core router 539 router -c /usr/local/etc/jabberd/router.xml
1307core resolver 540 resolver -c /usr/local/etc/jabberd/resolver.xml
1308core sm 541 sm -c /usr/local/etc/jabberd/sm.xml
1309core s2s 542 s2s -c /usr/local/etc/jabberd/s2s.xml
1310core c2s 543 c2s -c /usr/local/etc/jabberd/c2s.xml
1311transport ggtrans 546 /usr/local/sbin/jggtrans -f
1312transport jit 549 /usr/local/bin/jabberd-jit -c /usr/local/etc/jit.xml
1313@end smallexample
1315@item --stop
1316 Stop the running instance by sending it the @acronym{SIGTERM} signal.
1318@item --reload
1319@item --hup
1320 Restart the running instance by sending it the @acronym{SIGHUP} signal.
1321@end table
1323 The following are informational options:
1325@table @option
1326@item --help
1327@itemx -h
1328 Display a terse usage summary.
1330@item --version
1331@itemx -v
1332 Print program version and licensing information and exit.
1333@end table
1335@node jabberd.cfg
1336@subsection Jabberd Configuration File
1338 The configuration file has a line-oriented syntax. Empty lines are
1339ignored. Comments are introduced by a pound sign (@samp{#}),
1340everything starting from the first occurrence of @samp{#} up to the
1341end of line is ignored.
1343 Configuration statements consist of @dfn{command word} and one or
1344several @dfn{arguments}, separated by any amount of whitespace. There
1345are @samp{simple} and @samp{compound} configuration statements.
1346Simple statements occupy a single line. Compound statements begin
1347with a simple statement, occupy several lines, and end with @code{end}
1348statement, appearing on a line by itself. Compound statements in turn
1349contain another simple statements.
1351 The simplest working @file{jabberd.cfg} file is:
1354prog router /usr/local/etc/jabberd/router.xml
1355prog resolver /usr/local/etc/jabberd/resolver.xml
1356prog sm /usr/local/etc/jabberd/sm.xml
1357prog s2s /usr/local/etc/jabberd/s2s.xml
1358prog c2s /usr/local/etc/jabberd/c2s.xml
1359@end smallexample
1361 This file instructs @command{jabberd} to launch five basic jabber
1362components and supply the given configuration files to them. The
1363@code{prog} statement is a simple statement taking one to two
1364arguments. The first one names the program to lauch, and an optional
1365second one specifies its configuration file. All the programs will be
1366launched in the order of their appearance in the @file{jabberd.cfg}
1367file, and will be shut down in the reverse order. The @code{prog}
1368statement is designed expressly to start jabber core programs, it
1369should not be used to start third-party programs.
1371 To start third-party programs, e.g. transports, use @code{transport}
1372statement. It is a compound statement that has the following
1376transport @var{tag}
1377 command @var{command-line}
1378 depend @var{modlist}
1379 stdout @var{prio}
1380 stderr @var{prio}
1382@end smallexample
1384 The sub-statement @code{command} specifies the full command line of
1385the program. Notice that most transports behave as daemons. If it is
1386so, you will have to use a special command line option requiring the
1387transport to remain in the foreground (see the transport documentation
1388to find this option). If the program prints its diagnostics on the
1389standard error, the @code{stderr} statement can be used to capture and
1390redirect it to the syslog. For example, @code{stderr debug},
1391instructs @command{jabberd} to divert the program's standard error to
1392the syslog, using priority @samp{debug}. In this case the log entries
1393will be prefixed with @var{tag}, or, if it is absent, with the first
1394word of @var{command-line}.
1396 For example, the @acronym{GG} transport can be started using the
1397following statement:
1400transport ggtrans
1401 command /usr/local/sbin/jggtrans -f
1402 depend all
1403 stdout notice
1404 stderr notice
1406@end smallexample
1409 Several configuration statemenst control various aspects of the
1410behavior of the @command{jabberd}. For example, @code{user} statement
1411instructs it to switch to privileges of the named user after startup.
1412By default the utility will switch to the privileges of the user
1413@samp{jabberd}, this statement can be used to change that, for
1417user nobody
1418@end smallexample
1420 When switching to user privileges, @command{jabberd} retains only
1421the main user group, as specified in @file{/etc/passwd} file and drops
1422all supplementary groups the user might be a member of. To retain the
1423privileges of a supplementary group, name it with @code{group}
1424statement. This statement can be used several times, to retain
1425several groups. For example, the following statement switches to the
1426privileges of user @samp{nobody} and retains two supplementary groups:
1427@samp{staff} and @samp{ftp}:
1430user nobody
1431group staff
1432group ftp
1433@end smallexample
1435 The following subsubsection describes all configuration file
1436statements in detail.
1439* cfgstat:: Configuration File Statements
1440* example:: An Example of the Configuration file
1441@end menu
1443@node cfgstat
1444@subsubsection Configuration File Statements
1446@deffn {Jabber Statement} transport [@var{tag}]
1447Schedule a third-party program (e.g. a transport) for startup.
1448@var{tag} specifies the prefix to identify this program in the
1449diagnostic poutput. The @code{transport} statement is a block statement
1450that have the following structure:
1453transport @var{tag}
1454 command @var{command-line}
1455 depend @var{component-list}
1456 stdout @var{prio}
1457 stderr @var{prio}
1458 facility @var{fac}
1460@end smallexample
1462The subordinate statements are:
1464@deffn {transport statement} command @var{command-line}
1465Set the command line of the transport. @var{command-line} is parsed
1466much the same way as in shell, except that no variable substitution
1467takes place.
1468@end deffn
1470@deffn {transport statement} depend @var{component-list}
1471Declare that this module depends on the components listed in
1472@var{component-list}. Whenever one of these components is restarted,
1473the transport will be restarted as well.
1475@var{component-list} is either a whitespace-separated list of
1476components, or one of the following words: @samp{all}, meaning that
1477this transport depends on all core components started before it, and
1478@samp{none}, meaning that it does not depend on anything.
1480The default is @samp{all}.
1481@end deffn
1484@deffn {transport statement} stdout @var{prio}
1485@deffnx {transport statement} stderr @var{prio}
1486Redirect program's standard output (or error, in case of
1487@code{stderr}) to the given syslog priority. Allowed values for
1488@var{prio} are: @samp{EMERG}, @samp{ALERT}, @samp{CRIT}, @samp{ERR},
1489@samp{WARNING}, @samp{NOTICE}, @samp{INFO}, and @samp{DEBUG},
1490optionally prefixed with @samp{LOG_}. The string matching is
1492@end deffn
1494@deffn {transport statement} facility @var{facility}
1495This statement does nothing. It is reserved for future use.
1497@deffn {transport statement} pidfile @var{file}
1498Remove @var{file} before starting the transport. It may be useful if
1499the transport fails to delete its pidfile at the exit.
1500@end deffn
1501@end deffn
1503@end deffn
1504@deffn {Jabber Statement} group @var{name}
1505Retain supplementary group @var{name} after switching to the user's
1507@end deffn
1509@deffn {Jabber Statement} pidfile @var{file}
1510Write master process @acronym{ID} to @var{file}
1511@end deffn
1514@deffn {Jabber Statement} ctlfile @var{file}
1515Set location of the control file. This file is used to pass additional
1516information to the running daemon program (e.g., when running
1517@command{jabberd --restart @var{comp}}). The default value is
1519@end deffn
1521@deffn {Jabber Statement} statfile @var{file}
1522Set location of the statistics output file. This file is used to pass
1523statistics information from the running daemon program (e.g., when running
1524@command{jabberd --status}). The default value is
1526@end deffn
1528@deffn {Jabber Statement} prog @var{command} [@var{config-file}]
1529Schedule a jabber core program for startup. The program name is given
1530by @var{command} argument. Optional @var{config-file} gives the
1531location of its configuration file. The program command line will be
1532(parts enclosed by square brackets being optional):
1535@var{command} [-c @var{config-file}] [-D]
1536@end smallexample
1538 The @option{-D} is given only if the @command{jabberd} debugging
1539level is greater than 2 (e.g. when running it as @command{jabberd -DDD}).
1540@end deffn
1542@deffn {Jabber Statement} umask @var{n}
1543Set file creation mask to @var{n}. The default umask is @samp{037}.
1544@end deffn
1546@deffn {Jabber Statement} user @var{name}
1547Run with this user privileges.
1548@end deffn
1550@deffn {Jabber Statement} shutdown-timeout @var{n}
1551Wait @var{n} seconds for all children to shut down.
1552@end deffn
1554@deffn {Jabber Statement} syslog-facility @var{facility}
1555Output diagnostics to the given syslog facility. The @var{facility}
1556may be one of the following: @samp{USER}, @samp{DAEMON}, @samp{AUTH},
1557@samp{AUTHPRIV}, @samp{LOCAL0} through @samp{LOCAL7}, and @samp{MAIL}.
1558The string matching is case insensitive. Optionally, @samp{LOG_}
1559prefix may be prepended to @var{facility}.
1560@end deffn
1562@deffn {Jabber Statement} syslog-tag @var{tag}
1563Mark @command{jabberd} diagnostics with the given syslog tag. By
1564default @samp{jabberd} is used.
1565@end deffn
1567@node example
1568@subsubsection An Example of @file{jabberd.cfg} file
1571# @r{Run as user @samp{jabber}}
1572user jabber
1573# @r{Retain two supplementary groups:}
1574group staff
1575group nobody
1577# @r{Store @acronym{PID} to the given file}
1578pidfile /usr/local/var/jabberd/pid/
1579# @r{Wait 10 seconds for the shutdown of the children.}
1580shutdown-timeout 10
1582# @r{Start basic jabberd framework:}
1583prog router /usr/local/etc/jabberd/router.xml
1584prog resolver /usr/local/etc/jabberd/resolver.xml
1585prog sm /usr/local/etc/jabberd/sm.xml
1586prog s2s /usr/local/etc/jabberd/s2s.xml
1587prog c2s /usr/local/etc/jabberd/c2s.xml
1589# @r{Start @acronym{GG} transport and capture its output:}
1590transport ggtrans
1591 command /usr/local/sbin/jggtrans -f
1592 stdout notice
1593 stderr notice
1596# @r{Start @acronym{ICQ} transport and capture its output:}
1597transport jit
1598 command /usr/local/bin/jabberd-jit -c /usr/local/etc/jit.xml
1599 # @r{Ensure the pidfile is removed at the startup.}
1600 pidfile /usr/local/var/jabberd/pid/
1601 stdout notice
1602 stderr notice
1604@end smallexample
1606@node Sendmail mc Files, Startup Scripts, Root Utilities, Top 1157@node Sendmail mc Files, Startup Scripts, Root Utilities, Top
1607@chapter Sendmail @file{mc} Files 1158@chapter Sendmail @file{mc} Files
1608 1159

Return to:

Send suggestions and report system problems to the System administrator.