diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-01 13:10:38 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-01 13:10:38 +0000 |
commit | e514267900bfc760990b1044dc85524e6d4253e7 (patch) | |
tree | 1e2093df29a57caa9b2516ff710e13f8315774fc /doc/gsc.texi | |
parent | 76c0d827e9127bf0bfbd3920ccca916d1d173f70 (diff) | |
download | gsc-e514267900bfc760990b1044dc85524e6d4253e7.tar.gz gsc-e514267900bfc760990b1044dc85524e6d4253e7.tar.bz2 |
Move wydawca to a separate project
git-svn-id: file:///svnroot/gsc/trunk@303 d2de0444-eb31-0410-8365-af798a554d48
Diffstat (limited to 'doc/gsc.texi')
-rw-r--r-- | doc/gsc.texi | 743 |
1 files changed, 11 insertions, 732 deletions
diff --git a/doc/gsc.texi b/doc/gsc.texi index a6dbc2f..2b03461 100644 --- a/doc/gsc.texi +++ b/doc/gsc.texi @@ -120,12 +120,22 @@ Root Utilities * firewall:: M4 Wrappers For Setting Firewalls. * session-cleanup:: Manage PHP Sessions. * jabberd:: Jabberd dispatcher daemon. -* wydawca:: Automatic project release utility. firewall * Primitives:: A set of primitives defined in @file{firewall.m4} +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 * rc.inet1:: A Replacement for Slackware @command{rc.inet1}. @@ -800,7 +810,6 @@ cases, though not always. Such files should probably be inspected after * firewall:: M4 Wrappers For Setting Firewalls. * session-cleanup:: Manage PHP Sessions. * jabberd:: Jabberd dispatcher daemon. -* wydawca:: Automatic project release utility. @end menu @node ckaliases @@ -1562,736 +1571,6 @@ transport jit end @end smallexample -@node wydawca -@section Automatic project release utility -@UNREVISED{} - Let's begin with a short synopsis. Suppose you run a developer's -site, like, e.g. @indicateurl{gnu.org}. You have at least two -@dfn{distribution @acronym{URL}s}: @indicateurl{ftp.gnu.org}, which -distributes stable versions of the software, and -@indicateurl{alpha.gnu.org}, which distributes alpha and pre-test -versions. Now, package maintainers should have a way of uploading -their packages to one of these sites. The currently accepted scheme -is described in -@ifnothtml -@ref{Automated FTP Uploads, Automated FTP Uploads, Automated FTP -Uploads, maintain, Information for maintainers of GNU software}. -@end ifnothtml -@ifhtml -@uref{http://www.gnu.org/prep/maintain/html_node/Automated-Upload-Procedure.html, -Automated Upload Procedure}. -@end ifhtml -The following is a short summary of it: there is an @acronym{FTP} -@dfn{upload site}, which has two @dfn{source directories}, each one -corresponding to a certain distribution @acronym{URL}. For example, - -@multitable @columnfractions 0.4 0.4 -@headitem Source Directory @tab Distribution Site -@item @file{/incoming/ftp} @tab @indicateurl{ftp.gnu.org} -@item @file{/incoming/alpha} @tab @indicateurl{alpha.gnu.org} -@end multitable - - Now, if the maintainer of the project @samp{foo} wishes to make a release -of the stable version @file{foo-1.0.tar.gz}, he creates a detached -signature @file{foo-1.0.tar.gz.sig}, using his PGP key, the creates a -special @dfn{directive} file, that contain some information needed bt -the server, and clearsigns it, obtaining this way the file -@file{foo-1.0.tar.gz.directive.asc}. Then he uploads these three files -(a @dfn{triplet}) to the upload site, storing them into the directory -@file{/incoming/ftp}. - - From now on it is the responsibility of an @dfn{automated upload -daemon}, to scan the source directories, to gather the triplets, -verify them, and to move the files to distribution sites, if they had -passed the verification successfully. - - @command{Wydawca} is such an automated upload daemon. It is able to -handle any number of @samp{source/destination} pairs, offers an -extensible logging and mail notification mechanism, allowing both -package maintainers and site administrators to be immediately notified -about any occurring problems. - - The program is written entirely in @acronym{C}, is highly -effective and consumes little resources. - -@menu -* starting:: How to Invoke @command{wydawca}. -* configuring:: How to Configure @command{wydawca}. -* wydawca.rc:: @command{Wydawca} configuration file. -* invocation:: @command{Wydawca} invocation summary. -@end menu - -@node starting -@subsection How to invoke @command{wydawca}. -@UNREVISED{} - -@anchor{wydawca--config-file} -@cindex @option{--config-file}, @command{wydawca} option -@cindex @option{-c}, @command{wydawca} option - @command{Wydawca} gets all information it needs from its -@dfn{configuration file} (@pxref{wydawca.rc}). The default -configuration file is @file{@var{sysconfdir}/wydawca.rc}, but if it is -located elsewhere, you can specify its new location with the -@option{--config-file} (@option{-c}) command line option. - -@anchor{wydawca--lint} -@cindex @option{--lint}, @command{wydawca} option -@cindex @option{-t}, @command{wydawca} option - If you wish to check your configuration file for syntax errors, use -@option{--lint} (@option{-t}) command line option. When given this -option, @command{wydawca} prints all diagnostics on its standard -error and exits with code 0 if the file is OK, or 1 otherwise. - -@anchor{wydawca--stderr} -@cindex @option{--stderr}, @command{wydawca} option -@cindex @option{-e}, @command{wydawca} option -@cindex @option{--syslog}, @command{wydawca} option - Normally, @command{wydawca} attempts to detect automatically whether -it is run from an interactive console, and if so it prints it -diagnostics to the standard error. Otherwise, the diagnostics is -directed to the @command{syslog}, and the facility to use is gotten from the -@code{syslog-facility} configuration file statement -(@FIXME-pxref{}). Two options are provided if you wish to disable this -autodetection: the option @option{--syslog} instructs the program to print -all diagnostics using @command{syslog}, and the option -@option{--stderr} (or @option{-e}) instructs it to print everything on -the standard error. - -@cindex @option{--cron}, @command{wydawca} option - Usually you will run @command{wydawca} as a cron job. In that case, -it seldom needs any additional arguments, but we suggest to use -@option{--cron} command line option anyway. Currently, its effect is -the same as @option{--syslog}, but it may change in the future. - -@anchor{wydawca--debug} -@cindex @option{--debug}, @command{wydawca} option -@cindex @option{-d}, @command{wydawca} option - The @option{--debug} (@option{-d}) tells the program to inrease its -debugging level by 1. The @dfn{debugging level} determines the amount -of information the program reports when it runs. By default it is 0, -meaning to report only errors and other critical conditions. Raising -it may be necessary when debugging new configurations. Each -@option{-d} option raises the level by one, so you can say -@command{wydawca -dd} to obtain level 2, for example. The maximum -debugging level currently is 4, which prints impractically many -information and is useful primarily for @command{wydawca} developers. - -@anchor{wydawca--dry-run} -@cindex @option{--dry-run}, @command{wydawca} option -@cindex @option{-n}, @command{wydawca} option - Yet another debugging facility is the @option{--dry-run} -(@option{-n}) option. It instructs @command{wydawca} no to do any -modifications to the disk contents, but to verbosely print them. It -set the debugging level to 1 and directs the diagnostics output to the -standard error, as if @option{--debug --stderr} options have been -given. You can raise debugging level further by supplying additional -@option{--debug} options. The @option{--dry-run} option is useful when -testing new configurations, for example: - -@smallexample -$ wydawca -c new.cfg --dry-run -@end smallexample - -@cindex @option{--help}, @command{wydawca} option -@cindex @option{-h}, @command{wydawca} option -@cindex @option{--version}, @command{wydawca} option -@cindex @option{-v}, @command{wydawca} option - Two usual informational options are available as well: -@option{--help} (@option{-h}) prints a short usage summary, and -@option{--version} (@option{-v}) prints program version number. - -@node configuring -@subsection How to Configure @command{wydawca}. -@UNREVISED{} - The @command{wydawca} configuration file has a simple 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. Non-empty non-comment lines -contain configuration statements. - - A @dfn{configuration statement} consists of a @dfn{command word} -optionally followed by one or more @dfn{arguments}, separated by any -amount of whitespace. There are @samp{simple} and @samp{compound} -configuration statements. @dfn{Simple statements} occupy a single -line, for example: - -@smallexample -syslog-print-priority yes -@end smallexample - -If a simple statement is so long that it is inconvenient to keep it on -a single line, it can be split to several lines by ending each line -with a backslash character (@samp{\}). Notice, that the backslash -character must immediately precede the terminating newline. For -example, this is a single statement split over several lines: - -@smallexample -@group -user-data sql default SELECT realname, email \ - FROM user \ - WHERE user_name='%@{user@}' -@end group -@end smallexample - - -@dfn{Compound statements} begin with a simple statement, occupy -several lines, and end with @code{end} statement, appearing on a line -by itself. Each line of a compound statement is itself a simple -statement. - - This subsection will guide you through the @command{wydawca} -configuration on step-by-step basis. - -@menu -* syslog:: -* access methods:: -* directory pairs:: -* notification:: -@end menu - -@node syslog -@subsubsection Syslog Configuration Directives -@UNREVISED{} - Syslog is the default diagnostics channel for @command{wydawca}. By -default, the program uses facility @samp{local1}. To change this, use -@code{syslog-facility} statement: - -@smallexample -syslog-facility local2 -@end smallexample - - It takes a single argument, denoting the facility to use. Allowed -values are: @samp{auth}, @samp{authpriv}, @samp{cron}, @samp{daemon}, -@samp{ftp}, @samp{local0} through @samp{local7}, and -@samp{mail}. These names are case-insensitive and may be optionally -prefixed with @samp{LOG_}. The default is @samp{local1}. - - Another thing you may wish to tune is @dfn{syslog tag}, a string -identifying each message issued by the program. By default it is a -string @samp{wydawca}. To change it, use @code{syslog-tag} statement: - -@smallexample -syslog-tag wydawca -@end smallexample - - In addition to priority segregation, provided by @command{syslog}, -you can instruct @command{wydawca} to prefix each syslog message with -its priority. To do so, set: - -@smallexample -syslog-print-priority yes -@end smallexample - - At the end of each run, the program can pring detailed summary of -executed actions, which looks like that: - -@smallexample -errors: 0 -warnings: 2 -bad signatures: 0 -access violation attempts: 0 -complete triplets: 6 -incomplete triplets: 2 -bad triplets: 0 -expired triplets: 0 -triplet successes: 6 -files uploaded: 12 -files archived: 2 -symlinks created: 0 -symlinks removed: 0 -@end smallexample - - You can nofigure the information displayed, using @code{statistics} -statement. It takes arbitrary number of arguments, each one specifying -which part of the above statistics to display. For example, given the -following statement: - -@smallexample -statistics errors warnings -@end smallexample - -@noindent -the above output will be reduced to - -@smallexample -errors: 0 -warnings: 2 -@end smallexample - - The special keyword @samp{none} can be used to suppress this output -altogether (which is the default), as in - -@smallexample -statistics no -@end smallexample - - Another special keyword is @samp{all}, that enables all statistics -output. This keyword may also be followed by any number of usual -arguments, which are in this case @emph{subtracted}. For example, to -output all statistics, except errors and warnings one would set: - -@smallexample -statistics all errors warnings -@end smallexample - - The following table summarizes all the keywords, available for -@code{statistics} statement: - -@FIXME{write descriptions} -@table @asis -@item errors -@item warnings -@item bad_signatures -@item access_violations -@item complete_triplets -@item incomplete_triplets -@item bad_triplets -@item expired_triplets -@item triplet_success -@item uploads -@item archives -@item symlinks -@item rmsymlinks -@end table - -@node access methods -@subsubsection Access Methods -@UNREVISED{} - -@node directory pairs -@subsubsection directory pairs -@UNREVISED{} - A @dfn{directory pair} definition is a core of @command{wydawca} -configuration. It defines the location of the source directory and its -corresponding distribution directory, archivation type being used, and, -eventually, access methods for GPG key and other user information. The -directory pair definition begins with the @code{directory} and ends -with the @code{end} keyword, in a separate line. A minimal directory -pair definition should contain @code{source} and @code{destination} -statements. For example, the following definition says that the valid -uploads to @file{/home/ftp/incoming/ftp} should be transferred to -@file{/home/ftp/gnu}: - -@smallexample -directory - source /home/ftp/incoming/ftp - destination /home/ftp/gnu -end -@end smallexample - - The distribution directory is implicitly supposed to be located on -the same machine as the upload directory. If they are located on -different machines, one of the directories can be mounted using -@acronym{NFS}. The future versions will contain special provisions for -such case. - - The @code{archive} sub-statement specifies the archivation type used -for the destination, in case when a file with the same name as the one -being transferred already exists, or when a maintainer explicitly -requires archivation in the submitted @file{directive} file. The -@code{archive} keyword takes several arguments. The first argument -specifies the archivation type: - -@table @asis -@item none - Disable archivation. - -@item tar - Use @command{tar} archive. - -@item directory - Use separate directory or directory hierarchy. -@end table - - When archivation type @asis{tar} is used, the second argument to -@code{archive} sets the full name of the tar archive to use, e.g.: - -@smallexample -archive tar /var/spool/uploads/archive.tar -@end smallexample - - The file being archived is appended to the archive using -@command{tar -r} (@pxref{appending files, Appending Files to an -Archive, Appending Files to an Archive, tar, @acronym{GNU} tar: an -archiver tool}). Any archived instance can subsequently be retrieved -using GNU tar @option{--occurrence} option (@pxref{multiple, Multiple -Files with the Same Name, Multiple Files with the Same Name, tar, -@acronym{GNU} tar: an archiver tool}). - - By default, @code{wydawca} will search for @command{tar} binary in -your search path. If you wish to use a particular binary, you may -specify its full file name using @code{tar-program} statement. - - The archivation type @samp{directory} means that archive copies will -be stored in a directory specified by the second argument to -@code{archive}. If it begins with a slash (i.e. represents an absolute -file name), an exact copy of the distribution directory hierarchy will -be created under it. For example, given this configuration: - -@smallexample -directory - source /home/ftp/incoming/ftp - destination /home/ftp/gnu - archive directory /var/backups/gnu -end -@end smallexample - -@noindent -all files from @file{/home/@/ftp/@/gnu/@/tar} will be archived in -@file{/var/@/backups/@/gnu/@/tar}, files from -@file{/home/@/ftp/@/gnu/@/tar/@/old} -will be archived in @file{/var/@/backups/@/gnu/@/tar/@/old}, etc. - - If the directory name does not begin with a slash, it will be located -immediately under the corresponding distribution directory. Following -our example, the following @code{directory} settings: - -@smallexample - destination /home/ftp/gnu - archive directory .archive -@end smallexample - -@noindent -mean that files from @file{/home/ftp/gnu/tar} will be archived in the -directory @file{/home/ftp/gnu/tar/.archive}, files from -@file{/home/ftp/gnu/tar/old} --- in -@file{/home/ftp/gnu/tar/.archive/old}, etc. - - With the @samp{directory} archivation type, it may happen that the -archive file with the same name as the one about to be created already -exists. In this case the third argument to @code{archive} specifies -how to handle the existing copy, in other words, how to @dfn{backup} -it. This argument corresponds to the Emacs variable @samp{version-control}, -and it accepts the same values as in Emacs. @xref{backup-method, -Backup methods}, for the detailed description of the supported methods. - - If third argument is not given, the value of the @env{VERSION_CONTROL} -environment variable will be used. And if @env{VERSION_CONTROL} is -not set, the @samp{existing} is used by default. - -@node notification -@subsubsection Mail notification -@UNREVISED{} - -@node wydawca.rc -@subsection @command{Wydawca} configuration file. -@UNREVISED{} - -@deffn {Wydawca 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 {Wydawca Statement} syslog-tag @var{tag} -Mark @command{wydawca} diagnostics with the given syslog tag. By -default the string @samp{wydawca} is used. -@end deffn - -@deffn {Wydawca Statement} syslog-print-priority @var{bool} -Begin each diagnostic message with its priority. -@end deffn - -@deffn {Wydawca Statement} statistics @var{stat-list} -Print usage statistics at the end of the run. These data are output -at @samp{info} priority. The @var{stat-list} is a white-space -separated list of items that specify what statistics data are to be -printed. The valid items of @var{stat-list} are: - -@table @option -@item archives -Number of files successfully archived. - -@item bad_triplets -Number of bad triplets detected. - -@item complete_triplets -Number of complete triplets. - -@item errors -Number of errors during the run. - -@item expired_triplets -Number of expired triplets. - -@item incomplete_triplets -Number of incomplete triplets. - -@item rmsymlinks -Number of symlinks successfully removed. - -@item symlinks -Number of symlinks successfully created. - -@item triplet_success -Number of triplets successfully processed. - -@item uploads -Number of successful uploads. - -@item warnings -Number of warnings. -@end table - - Two special keywords are also recognized: - -@table @option -@item all -Print all information. - -@item none -Do not print any statistics. -@end table - - These keywords must be the very first items in @var{stat-list}. -When followed by another keywords, these special keywords modify list -handling as follows: - -@table @option -@item all -The sense of all subsequent items is inverted. For example, to print -everything, except the number of warnings and errors, one would use: - -@smallexample -statistics all errors warning -@end smallexample - -@item none -Is ignored. -@end table -@end deffn - -@deffn {Wydawca Statement} file-sweep-time @var{interval} -Sets the amount of time after which any unprocessed file will be -removed. - - The @var{interval} is a string that defines a time interval, much -the same way we do this in English: it consists of one or more pairs -``@samp{number} @samp{time unit}''. For example, the following are -valid interval specifications: - -@smallexample -@group -1 hour -2 hours 35 seconds -1 year 7 months 2 weeks 2 days 11 hours 12 seconds -@end group -@end smallexample - -@noindent -The pairs can occur in any order, however unusual it may sound to a -human ear, e.g. @samp{2 days 1 year}. If the @samp{time unit} is -omitted, seconds are supposed. -@end deffn - -@deffn {Wydawca Statement} umask @var{value} -Sets the umask to be used. The @var{value} must be octal. -@end deffn - -@deffn {Wydawca Statement} tar-command @var{string} -Sets the file name of the @command{tar} utility. If @var{string} is -not an absolute file name, it will be searched in @env{PATH}. -@end deffn - -@deffn {Wydawca Block Statement} sql @var{identifier} -This statement begins an @dfn{MySQL database} definition. It may contain -several substatements, defining how to access the database. The -statement ends with the @code{end} keyword on a line by itself. - -The @var{identifier} is the symbolic name that can be used in -subsequent configuration statements to refer to this @acronym{SQL} -database. - -@smallexample -sql default - host localhost:/tmp/mysql.sock - database savane - user savane - password guessme -end -@end smallexample - -The following statements are recognized within the @code{sql} block: - -@deffn {Wydawca Statement} host @var{hostname}[:@var{port-or-socket}] -Hostname where the database is running. The @var{hostname} is either -a symbolic hostname of the machine, or its IP address in usual -@samp{dotted-quad} notation. - -The optional @var{port-or-socket} specifies port number (for -@acronym{TCP} connections) or socket name (for @acronym{UNIX} sockets) -to use. In the latter case, the @var{hostname} may be omitted. If, -however, it is present, it must be @samp{localhost}. - -Examples: - -@smallexample -host 10.10.10.1 -host sql.server.com -host sql.server.com:3100 -host localhost:/tmp/mysql.sock -host /tmp/mysql.sock -@end smallexample -@end deffn - -@deffn {Wydawca Statement} database @var{string} -Specifies the database name. -@end deffn - -@deffn {Wydawca Statement} user @var{string} -Specifies the database user name. -@end deffn - -@deffn {Wydawca Statement} password @var{string} -Specifies the password. -@end deffn -@end deffn - -@deffn {Wydawca Block Statement} directory -Defines a directory pair. The statement ends with the @code{end} -keyword on a line by itself. - -The following statements are recognized within the @code{sql} block: - -@deffn {Wydawca Statement} source @var{dirname} -Sets source directory name. The @var{dirname} must be an absolute file -name. -@end deffn - -@deffn {Wydawca Statement} destination @var{dirname} -Sets source directory name. The @var{dirname} must be an absolute file -name. -@end deffn - -@deffn {Wydawca Statement} verify-user @var{type} @var{id} @var{command} -@FIXME{Description.} -@end deffn - -@deffn {Wydawca Statement} gpg-key @var{type} @var{id} @var{command} -@FIXME{Description.} -@end deffn - -@deffn {Wydawca Statement} archive @var{type} @var{archive-name} @ - [@var{backup-method}] -Defines archivation defaults for the destination directory. The -@var{type} specifies the archivation type: - -@table @asis -@item tar -The @var{archive-name} is a full file name of the @command{tar} -archive used for archivation. Files being archived are appended to -that archive using @command{tar -r} command (@FIXME-pxref{tar}). -The default file name of the @command{tar} binary is set by -@code{tar-program} statement. - -@item directory -The @var{archive-name} specifies a directory name where to store -archive copies. If it is a relative pathname, this directory will be -created under the @code{destination} directory. If it is absolute file -name, the archive name directory will be constructed for each triplet -using the following rule: - -@smallexample -@var{archive-name}/@var{dir} -@end smallexample - -@noindent -where @var{dir} is the value of @code{directory} directive from the -triplet file. - -@anchor{backup-method} -@vindex VERSION_CONTROL -@cindex backups -For @samp{directive} archivation type, the optional @var{backup-method} -parameter specifies how to back up an existing archive whose name -coincides with the one @command{wydawca} is about to create. If -@var{backup-method} is not specified, the value of the @env{VERSION_CONTROL} -environment variable will be used. And if @env{VERSION_CONTROL} is not set, -the @samp{existing} method (see below) is used by default. - -@vindex version-control @r{Emacs variable} -This option corresponds to the Emacs variable @samp{version-control}; -the same values for @var{backup-method} are accepted as in Emacs. This option -also allows more descriptive names. The valid @var{method}s are: - -@table @samp -@item t -@itemx numbered -@cindex numbered @r{backup method} -Always make numbered backups. - -@item nil -@itemx existing -@cindex existing @r{backup method} -Make numbered backups of files that already have them, simple backups. -of the others. - -@item never -@itemx simple -@cindex simple @r{backup method} -Always make simple backups. - -@end table -@end table - -@end deffn -@end deffn - -@node invocation -@subsection @command{Wydawca} invocation summary. -@UNREVISED{} - -@table @option -@item --config-file=@var{file} -@itemx -c @var{file} -Use @var{FILE} instead of the default configuration -file. - -@xref{wydawca--config-file, The @option{--config-file} option}. - -@item --cron -@itemx --syslog -Log all diagnostics to syslog. - -@xref{wydawca--stderr, The @option{--syslog} option}. - -@item --debug -@itemx -d -Increase debugging level by 1. - -@xref{wydawca--debug, The @option{--debug} option}. - -@item --stderr -@itemx -e -Log to the standard error. - -@xref{wydawca--stderr, The @option{--syslog} option}. - -@item --dry-run -@itemx -n -@dfn{Dry-run mode}: do nothing, print almost everything. This option -implies @option{--debug --stderr}. - -@xref{wydawca--dry-run, The dry-run mode}. - -@item --lint -@itemx -t -Parse configuration file, report any errors on the standard error and -exit with code 0, if the syntax is OK, and with code 1 otherwise. - -@xref{wydawca--lint, The @option{--lint} option}. - -@item --help -@itemx -h -Print a concise usage summary and exit. - -@item --version -@itemx -v -Print the program version and exit. -@end table - @node Sendmail mc Files, Startup Scripts, Root Utilities, Top @chapter Sendmail @file{mc} Files |