summaryrefslogtreecommitdiffabout
path: root/doc/gsc.texi
Side-by-side diff
Diffstat (limited to 'doc/gsc.texi') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gsc.texi449
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

Return to:

Send suggestions and report system problems to the System administrator.