diff options
Diffstat (limited to 'doc/gsc.texi')
-rw-r--r-- | doc/gsc.texi | 449 |
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 @@ -121,3 +121,2 @@ Root Utilities * session-cleanup:: Manage PHP Sessions. -* jabberd:: Jabberd dispatcher daemon. @@ -127,13 +126,2 @@ firewall -Jabberd - -* jabintro:: Jabberd Operation Overview -* jabopts:: Command Line Options. -* jabberd.cfg:: Main Jabberd Configuration File. - -Jabberd Configuration File - -* cfgstat:: Configuration File Statements -* example:: An Example of the Configuration file - Startup Scripts @@ -843,3 +831,2 @@ cases, though not always. Such files should probably be inspected after * session-cleanup:: Manage PHP Sessions. -* jabberd:: Jabberd dispatcher daemon. @end menu @@ -1169,438 +1156,2 @@ actually remove them. -@node jabberd -@section Jabberd -@cindex jabberd - The @command{jabberd} utility is a dispatcher daemon for -@samp{Jabberd 2.x} -(@uref{http://www.jabber.org/software/jabberd2x.shtml}). It is -intended as a replacement for the similar utility shipped with the -@samp{jabberd 2.x} package. There were two reasons that urged for the -replacement: first, the original @command{jabberd} is written in Perl -and consumes way too many resources because of that. Secondly, it is -not flexible enough. In particular, it is only able to control jabber -daemons, but cannot control external transports (such as @acronym{GG} -or @acronym{GIT}. - -@menu -* jabintro:: Jabberd Operation Overview -* jabopts:: Command Line Options. -* jabberd.cfg:: Main Jabberd Configuration File. -@end menu - -@node jabintro -@subsection Jabberd Operation Overview - - The @acronym{GSC} @command{jabberd} is a supervisor daemon that -starts a number of @dfn{components} and controls their execution. -A component is either a jabberd core component (as, -e.g. @command{c2s}) or some external program (e.g. a transport). The -daemon reads the list of components from its configuration file upon -startup. By default, the configuration file is named -@file{jabberd.cfg} and is located in @code{$sysconfdir} directory, but -its exact location can be overridden at startup (see @option{-c} -option, below). If run with the root privileges, @command{jabberd} -switches to the privileges of a selected user (by default -@samp{jabber}) right after startup. Then, the program changes file -creation mask to a safe value (the default is @samp{037}). Unless -explicitly requested to remain in the foreground, the utility detaches -itself from the controlling terminal and switches to the background. -The daemon starts the configured components -in the order of their appearance in the configuration file. The exact -command line options and arguments for each component are specified -in the configuration file. If a particular subprocess prints its -diagnostics on stderr or stdout, you may instruct @command{jabberd} to -capture and divert it to a particular @command{syslogd} -priority (@pxref{stdout}). After launching the components -@command{jabberd} enters its main loop. It sleeps until either some -component finishes or a signal is delivered. If a component finishes, -@command{jabberd} scans its internal list to find components that -depend on the finished one. Each such component is then terminated -by sending it @acronym{SIGTERM} signal. Then, the finished component and -its dependent components are started again. If a process is -restarted more than 10 times within a two minutes interval, it is -disabled for the next five minutes (the same way the standard -@acronym{UNIX} @command{init} utility operates). - - The @command{jabberd} utility exits if it recieves any of the -following signals: @acronym{SIGTERM}, @acronym{SIGQUIT}, -@acronym{SIGINT}. It attempts to restart itself if delivered the -@acronym{SIGHUP} signal. This is possible only if the utility is -started using its absolute file name. In any case, before exiting, -the utility shuts down all components @emph{in the reverse -order} of their appearance in the configuration file. The processes -are shut down by sending them @acronym{SIGTERM} signals. If a -component does not exit within a 1 second interval, it is re-sent the -same signal. This procedure continues until either all components -terminate or the @dfn{shutdown timeout} interval expires, whichever -happens first. If the latter happens, any components still left -running are slayed using @acronym{SIGKILL} signal. The default -shutdown timeout is 5 seconds and it may be changed using -@code{shutdown-timeout} configuration file statement (@pxref{cfgstat}). - - Two signals are special to @command{jabberd}: @acronym{SIGUSR1} -and @acronym{SIGUSR2}. The @acronym{SIGUSR1} signal instructs the -program to shut down and restart a particular component or a set -of components. The list of components to be restarted is passed to -the running program via a @dfn{control file} (@pxref{ctlfile}). This -mechanism is used by @command{jabberd ---restart}. @FIXME-xref{restarting selected components}. - - The @acronym{SIGUSR2} signal instructs @command{jabberd} to return -statistics about running components. It is used by @command{jabberd ---status} (@FIXME-pxref{showing runtime statistics}). - -@node jabopts -@subsection Jabberd Invocation -@UNREVISED{} - - By default, @command{jabberd} attempts to start in @dfn{dispatcher -mode}, which is described in the previous subsection. If started -without additional options, the program will use compiled-in defaults. -Otherwise, the following options may be given: - -@table @option -@item --config-file=@var{file} -@itemx -c @var{file} - Use @var{file} as the main configuration file. - -@item --debug -@itemx -D - Increase debugging level. - -@item --foreground -@itemx -f - Do not disconnect from the controlling terminal, but run in -foreground mode instead. This option is mainly useful for debugging. -It implies @option{-e} (see below). - -@item --force - Attempt to start up even if another instance of @command{jabberd} -seems to be running. - -@item --stderr -@itemx -e - Print all diagnostics on the standard output. -@end table - - A set of options may be used to control the running instance of the -program and request a detailed information about it. - -@table @option -@item --restart @var{tag} [@var{tags}...] -@itemx -r @var{tag} [@var{tag}...] - Restart named components. Any number of arguments can be -specified. Each @var{tag} must correspond to a valid tag in -@file{jabberd.cfg} file. - -@item --status - Display information about the running instance. Return 0 if the -instance is running, 1 otherwise. - -@smallexample -$ jabberd --status -jabberd: [INFO] jabberd is running; PID 537 -retranslator jit/stderr 548 -retranslator jit/stdout 547 -retranslator ggtrans/stderr 545 -retranslator ggtrans/stdout 544 -core router 539 router -c /usr/local/etc/jabberd/router.xml -core resolver 540 resolver -c /usr/local/etc/jabberd/resolver.xml -core sm 541 sm -c /usr/local/etc/jabberd/sm.xml -core s2s 542 s2s -c /usr/local/etc/jabberd/s2s.xml -core c2s 543 c2s -c /usr/local/etc/jabberd/c2s.xml -transport ggtrans 546 /usr/local/sbin/jggtrans -f -transport jit 549 /usr/local/bin/jabberd-jit -c /usr/local/etc/jit.xml -@end smallexample - -@item --stop - Stop the running instance by sending it the @acronym{SIGTERM} signal. - -@item --reload -@item --hup - Restart the running instance by sending it the @acronym{SIGHUP} signal. -@end table - - The following are informational options: - -@table @option -@item --help -@itemx -h - Display a terse usage summary. - -@item --version -@itemx -v - Print program version and licensing information and exit. -@end table - -@node jabberd.cfg -@subsection Jabberd Configuration File - - The configuration file has a line-oriented syntax. Empty lines are -ignored. Comments are introduced by a pound sign (@samp{#}), -everything starting from the first occurrence of @samp{#} up to the -end of line is ignored. - - Configuration statements consist of @dfn{command word} and one or -several @dfn{arguments}, separated by any amount of whitespace. There -are @samp{simple} and @samp{compound} configuration statements. -Simple statements occupy a single line. Compound statements begin -with a simple statement, occupy several lines, and end with @code{end} -statement, appearing on a line by itself. Compound statements in turn -contain another simple statements. - - The simplest working @file{jabberd.cfg} file is: - -@smallexample -prog router /usr/local/etc/jabberd/router.xml -prog resolver /usr/local/etc/jabberd/resolver.xml -prog sm /usr/local/etc/jabberd/sm.xml -prog s2s /usr/local/etc/jabberd/s2s.xml -prog c2s /usr/local/etc/jabberd/c2s.xml -@end smallexample - - This file instructs @command{jabberd} to launch five basic jabber -components and supply the given configuration files to them. The -@code{prog} statement is a simple statement taking one to two -arguments. The first one names the program to lauch, and an optional -second one specifies its configuration file. All the programs will be -launched in the order of their appearance in the @file{jabberd.cfg} -file, and will be shut down in the reverse order. The @code{prog} -statement is designed expressly to start jabber core programs, it -should not be used to start third-party programs. - - To start third-party programs, e.g. transports, use @code{transport} -statement. It is a compound statement that has the following -structure: - -@smallexample -transport @var{tag} - command @var{command-line} - depend @var{modlist} - stdout @var{prio} - stderr @var{prio} -end -@end smallexample - - The sub-statement @code{command} specifies the full command line of -the program. Notice that most transports behave as daemons. If it is -so, you will have to use a special command line option requiring the -transport to remain in the foreground (see the transport documentation -to find this option). If the program prints its diagnostics on the -standard error, the @code{stderr} statement can be used to capture and -redirect it to the syslog. For example, @code{stderr debug}, -instructs @command{jabberd} to divert the program's standard error to -the syslog, using priority @samp{debug}. In this case the log entries -will be prefixed with @var{tag}, or, if it is absent, with the first -word of @var{command-line}. - - For example, the @acronym{GG} transport can be started using the -following statement: - -@smallexample -transport ggtrans - command /usr/local/sbin/jggtrans -f - depend all - stdout notice - stderr notice -end -@end smallexample - - - Several configuration statemenst control various aspects of the -behavior of the @command{jabberd}. For example, @code{user} statement -instructs it to switch to privileges of the named user after startup. -By default the utility will switch to the privileges of the user -@samp{jabberd}, this statement can be used to change that, for -example: - -@smallexample -user nobody -@end smallexample - - When switching to user privileges, @command{jabberd} retains only -the main user group, as specified in @file{/etc/passwd} file and drops -all supplementary groups the user might be a member of. To retain the -privileges of a supplementary group, name it with @code{group} -statement. This statement can be used several times, to retain -several groups. For example, the following statement switches to the -privileges of user @samp{nobody} and retains two supplementary groups: -@samp{staff} and @samp{ftp}: - -@smallexample -user nobody -group staff -group ftp -@end smallexample - - The following subsubsection describes all configuration file -statements in detail. - -@menu -* cfgstat:: Configuration File Statements -* example:: An Example of the Configuration file -@end menu - -@node cfgstat -@subsubsection Configuration File Statements - -@deffn {Jabber Statement} transport [@var{tag}] -Schedule a third-party program (e.g. a transport) for startup. -@var{tag} specifies the prefix to identify this program in the -diagnostic poutput. The @code{transport} statement is a block statement -that have the following structure: - -@smallexample -transport @var{tag} - command @var{command-line} - depend @var{component-list} - stdout @var{prio} - stderr @var{prio} - facility @var{fac} -end -@end smallexample - -The subordinate statements are: - -@deffn {transport statement} command @var{command-line} -Set the command line of the transport. @var{command-line} is parsed -much the same way as in shell, except that no variable substitution -takes place. -@end deffn - -@deffn {transport statement} depend @var{component-list} -Declare that this module depends on the components listed in -@var{component-list}. Whenever one of these components is restarted, -the transport will be restarted as well. - -@var{component-list} is either a whitespace-separated list of -components, or one of the following words: @samp{all}, meaning that -this transport depends on all core components started before it, and -@samp{none}, meaning that it does not depend on anything. - -The default is @samp{all}. -@end deffn - -@anchor{stdout} -@deffn {transport statement} stdout @var{prio} -@deffnx {transport statement} stderr @var{prio} -Redirect program's standard output (or error, in case of -@code{stderr}) to the given syslog priority. Allowed values for -@var{prio} are: @samp{EMERG}, @samp{ALERT}, @samp{CRIT}, @samp{ERR}, -@samp{WARNING}, @samp{NOTICE}, @samp{INFO}, and @samp{DEBUG}, -optionally prefixed with @samp{LOG_}. The string matching is -case-insensitive. -@end deffn - -@deffn {transport statement} facility @var{facility} -This statement does nothing. It is reserved for future use. - -@deffn {transport statement} pidfile @var{file} -Remove @var{file} before starting the transport. It may be useful if -the transport fails to delete its pidfile at the exit. -@end deffn -@end deffn - -@end deffn -@deffn {Jabber Statement} group @var{name} -Retain supplementary group @var{name} after switching to the user's -privileges. -@end deffn - -@deffn {Jabber Statement} pidfile @var{file} -Write master process @acronym{ID} to @var{file} -@end deffn - -@anchor{ctlfile} -@deffn {Jabber Statement} ctlfile @var{file} -Set location of the control file. This file is used to pass additional -information to the running daemon program (e.g., when running -@command{jabberd --restart @var{comp}}). The default value is -@file{/usr/local/var/jabberd/.jabberd.ctl}. -@end deffn - -@deffn {Jabber Statement} statfile @var{file} -Set location of the statistics output file. This file is used to pass -statistics information from the running daemon program (e.g., when running -@command{jabberd --status}). The default value is -@file{/usr/local/var/jabberd/.jabberd.stat}. -@end deffn - -@deffn {Jabber Statement} prog @var{command} [@var{config-file}] -Schedule a jabber core program for startup. The program name is given -by @var{command} argument. Optional @var{config-file} gives the -location of its configuration file. The program command line will be -(parts enclosed by square brackets being optional): - -@smallexample -@var{command} [-c @var{config-file}] [-D] -@end smallexample - - The @option{-D} is given only if the @command{jabberd} debugging -level is greater than 2 (e.g. when running it as @command{jabberd -DDD}). -@end deffn - -@deffn {Jabber Statement} umask @var{n} -Set file creation mask to @var{n}. The default umask is @samp{037}. -@end deffn - -@deffn {Jabber Statement} user @var{name} -Run with this user privileges. -@end deffn - -@deffn {Jabber Statement} shutdown-timeout @var{n} -Wait @var{n} seconds for all children to shut down. -@end deffn - -@deffn {Jabber Statement} syslog-facility @var{facility} -Output diagnostics to the given syslog facility. The @var{facility} -may be one of the following: @samp{USER}, @samp{DAEMON}, @samp{AUTH}, -@samp{AUTHPRIV}, @samp{LOCAL0} through @samp{LOCAL7}, and @samp{MAIL}. -The string matching is case insensitive. Optionally, @samp{LOG_} -prefix may be prepended to @var{facility}. -@end deffn - -@deffn {Jabber Statement} syslog-tag @var{tag} -Mark @command{jabberd} diagnostics with the given syslog tag. By -default @samp{jabberd} is used. -@end deffn - -@node example -@subsubsection An Example of @file{jabberd.cfg} file - -@smallexample -# @r{Run as user @samp{jabber}} -user jabber -# @r{Retain two supplementary groups:} -group staff -group nobody - -# @r{Store @acronym{PID} to the given file} -pidfile /usr/local/var/jabberd/pid/jabberd.pid -# @r{Wait 10 seconds for the shutdown of the children.} -shutdown-timeout 10 - -# @r{Start basic jabberd framework:} -prog router /usr/local/etc/jabberd/router.xml -prog resolver /usr/local/etc/jabberd/resolver.xml -prog sm /usr/local/etc/jabberd/sm.xml -prog s2s /usr/local/etc/jabberd/s2s.xml -prog c2s /usr/local/etc/jabberd/c2s.xml - -# @r{Start @acronym{GG} transport and capture its output:} -transport ggtrans - command /usr/local/sbin/jggtrans -f - stdout notice - stderr notice -end - -# @r{Start @acronym{ICQ} transport and capture its output:} -transport jit - command /usr/local/bin/jabberd-jit -c /usr/local/etc/jit.xml - # @r{Ensure the pidfile is removed at the startup.} - pidfile /usr/local/var/jabberd/pid/jit.pid - stdout notice - stderr notice -end -@end smallexample - @node Sendmail mc Files, Startup Scripts, Root Utilities, Top |