From 5fc738e4d43eb708428c4b30e60e570e2dd55470 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sat, 28 Feb 2009 18:54:48 +0200 Subject: Various fixes * doc/Makefile.am: Improve checking and final rules. * doc/fdl.texi, doc/rendition.texi: Use single-space sentence separators. * doc/wydawca.texi: Update. * src/config.c (cb_email_address): Accept a list of addresses. * src/meta.c (meta_expand_string): Take two additional arguments. Quote expansions if they are provided. * src/triplet.c (triplet_expand_method_query): New function. * src/mail.c, src/verify.c: Use triplet_expand_method_query * src/wydawca.h: Update. * src/meta.c (meta_escape): Remove. --- doc/Makefile.am | 23 +- doc/fdl.texi | 82 ++--- doc/rendition.texi | 6 +- doc/wydawca.texi | 1031 ++++++++++++++++++++++++++++------------------------ src/config.c | 54 ++- src/mail.c | 8 +- src/meta.c | 48 +-- src/triplet.c | 34 +- src/verify.c | 29 +- src/wydawca.h | 10 +- 10 files changed, 731 insertions(+), 594 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 0ef1e64..f53e47c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -41,12 +41,20 @@ manual: $(GENDOCS) $(PACKAGE) '$(PACKAGE_NAME) manual' # Checking -check-format: +check-tabs: @if test -n "`cat $(info_TEXINFOS) $(wydawca_TEXINFOS) | tr -d -c '\t'`"; then \ echo "Sources contain tabs; run make untabify"; \ false; \ fi +check-sentence-spacing: + @if grep -q '\. [@A-Z]' $(info_TEXINFOS) $(wydawca_TEXINFOS); then \ + echo >&2 "Sources contain double-space sentence separators"; \ + echo >&2 "Run make fix-sentence-spacing to fix"; \ + fi + +check-format: check-tabs check-sentence-spacing + check-options: @check-docs.sh options \ '/OPTIONS_BEGIN/,/OPTIONS_END/s/OPTION( *\([^,][^,]*\),.*/\1/pg' \ @@ -70,7 +78,7 @@ check-fixmes: rm -f $@-t check-writeme: - @grep -Hn @WRITEME $(info_TEXINFOS) $(mailfromd_TEXINFOS) > $@-t; \ + @grep -Hn @WRITEME $(info_TEXINFOS) $(wydawca_TEXINFOS) > $@-t; \ if [ -s $@-t ]; then \ echo "Empty nodes:"; \ cat $@-t; \ @@ -102,5 +110,14 @@ master-menu: untabify: emacs -batch -l untabify.el $(info_TEXINFOS) $(wydawca_TEXINFOS) -final: untabify master-menu +fix-sentence-spacing: + for file in $(info_TEXINFOS) $(wydawca_TEXINFOS); \ + do \ + if grep -q '\. [@A-Z]' $$file; then \ + mv $$file $${file}~; \ + sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \ + fi; \ + done + +final: untabify fix-sentence-spacing master-menu diff --git a/doc/fdl.texi b/doc/fdl.texi index edd86d4..3f42957 100644 --- a/doc/fdl.texi +++ b/doc/fdl.texi @@ -23,16 +23,16 @@ to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It +works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; +software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License +whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. @item @@ -40,11 +40,11 @@ APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a +distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. @@ -65,15 +65,15 @@ them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a +that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may +the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, @@ -83,19 +83,19 @@ straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file +to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain @sc{ascii} without markup, Texinfo input format, La@TeX{} input format, @acronym{SGML} or @acronym{XML} using a publicly available @acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples +PostScript or @acronym{PDF} designed for human modification. Examples of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be +@acronym{JPG}. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, @acronym{SGML} or @acronym{XML} for which the @acronym{DTD} and/or processing tools are not generally available, and the machine-generated @acronym{HTML}, @@ -104,7 +104,7 @@ output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in +this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. @@ -118,7 +118,7 @@ of such a section when you modify the Document means that it remains a section ``Entitled XYZ'' according to this definition. The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty +states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has @@ -131,10 +131,10 @@ You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use +conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and @@ -148,10 +148,10 @@ printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. +visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. @@ -186,14 +186,14 @@ the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: +of it. In addition, you must do these things in the Modified Version: @enumerate A @item Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version +of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. @item @@ -229,7 +229,7 @@ Include an unaltered copy of this License. @item Preserve the section Entitled ``History'', Preserve its Title, and add to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If +publisher of the Modified Version as given on the Title Page. If there is no section Entitled ``History'' in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified @@ -239,7 +239,7 @@ Version as stated in the previous sentence. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. +it was based on. These may be placed in the ``History'' section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @@ -252,11 +252,11 @@ dedications given therein. @item Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers +unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item -Delete any section Entitled ``Endorsements''. Such a section +Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. @item @@ -270,7 +270,7 @@ Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the +of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. @@ -282,9 +282,9 @@ standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of +of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already +through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit @@ -306,7 +306,7 @@ license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but +copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. @@ -316,7 +316,7 @@ Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled ``History'' in the various original documents, forming one section Entitled ``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all +and any sections Entitled ``Dedications''. You must delete all sections Entitled ``Endorsements.'' @item @@ -361,11 +361,11 @@ distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a +original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between +of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. @@ -378,9 +378,9 @@ title. TERMINATION You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to +as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, +automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. @@ -389,9 +389,9 @@ parties remain in full compliance. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new +of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See +differ in detail to address new problems or concerns. See @uref{http://www.gnu.org/copyleft/}. Each version of the License is given a distinguishing version number. @@ -399,7 +399,7 @@ If the Document specifies that a particular numbered version of this License ``or any later version'' applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version +Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. @end enumerate diff --git a/doc/rendition.texi b/doc/rendition.texi index 45ac068..5d04105 100644 --- a/doc/rendition.texi +++ b/doc/rendition.texi @@ -5,10 +5,10 @@ @c ====================================================================== @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF, -@c as decided by @set symbols. The PUBLISH rendition does not show -@c notes or marks asking for revision. Most users will prefer having more +@c as decided by @set symbols. The PUBLISH rendition does not show +@c notes or marks asking for revision. Most users will prefer having more @c information, even if this information is not fully revised for adequacy, -@c so DISTRIB is the default for distributions. The PROOF rendition +@c so DISTRIB is the default for distributions. The PROOF rendition @c show all marks to the point of ugliness, but is nevertheless useful to @c those working on the manual itself. @c ====================================================================== diff --git a/doc/wydawca.texi b/doc/wydawca.texi index 589f2f7..237f196 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -37,11 +37,11 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license +and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License''. (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -this GNU Manual, like GNU software. Copies published by the Free +this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.'' @end copying @@ -89,6 +89,7 @@ already listed, mentioned here so you can get to them in one step: How to Configure @command{wydawca}. +* Syntax:: Configuration file syntax. * syslog:: * sql:: * access methods:: @@ -97,12 +98,32 @@ How to Configure @command{wydawca}. * statistics:: * notification:: +Configuration file syntax + +* Comments:: +* Pragmatic Comments:: +* Statements:: +* Preprocessor:: + +Access Methods + +* sql type:: +* builtin type:: +* external type:: + +SQL Access Methods + +* gpg-key-sql:: +* project-owner-sql:: +* user-data-sql:: +* verify-user-sql:: + Mail Notification -* mailer:: -* templates:: -* statreports:: -* event notification:: +* mailer:: +* templates:: +* statreports:: +* event notification:: @end detailmenu @end menu @@ -184,8 +205,8 @@ effective and consumes little resources. @cindex operation @cindex overview Usually, @command{wydawca} is installed on the machine that receives -release uploads. It may be run either periodically as a cron-job, or -as a standalone daemon. It supposes that both upload and distribution +release uploads. It may be run either periodically as a cron-job, or +as a standalone daemon. It supposes that both upload and distribution directories are accessible in the local file system hierarchy. If that is not the case (e.g. if upload and distribution sites are handled by different machines), one of them should be mounted using @@ -232,7 +253,7 @@ Standalone directives}. Each @dfn{incomplete} triplet, i.e. such that misses one or more necessary files, is then verified by checking if the modification date of its oldest file is older than a predefined amount of time -(@pxref{file-sweep-time}), and if so, all files from this triplet are +(@FIXME-pxref{file-sweep-time}), and if so, all files from this triplet are removed (an @dfn{expired triplet}). This gives users the possibility to restart interrupted or otherwise broken uploads later. @@ -354,7 +375,7 @@ detected, and withs status 1 otherwise. @opindex -E, introduced @xopindex{no-preprocessor, introduced} Before parsing, configuration file is preprocessed using -@command{m4} (@FIXME-pxref{Preprocessor}). To see the preprocessed +@command{m4} (@pxref{Preprocessor}). To see the preprocessed configuration without actually parsing it, use @option{-E} command line option. To avoid preprocessing it, use @option{--no-preprocessor} option. @@ -383,13 +404,14 @@ directives any time by running @command{wydawca --config-help}. There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called @dfn{white space} are ignored except as they serve to separate -tokens. Some white space is required to separate otherwise adjacent +tokens. Some white space is required to separate otherwise adjacent keywords and values. @menu * Comments:: * Pragmatic Comments:: * Statements:: +* Preprocessor:: @end menu @node Comments @@ -469,7 +491,7 @@ compatibility with the @sc{c} preprocessor. In fact, these statements provide a rudimentary preprocessing features. For more sophisticated ways to modify configuration before -parsing, see @FIXME-ref{Preprocessor}. +parsing, see @ref{Preprocessor}. @node Statements @subsection Statements @@ -478,7 +500,7 @@ parsing, see @FIXME-ref{Preprocessor}. @cindex statement, simple @cindex simple statements A @dfn{simple statement} consists of a keyword and value -separated by any amount of whitespace. Simple statement is terminated +separated by any amount of whitespace. Simple statement is terminated with a semicolon (@samp{;}). Examples of simple statements: @@ -561,6 +583,44 @@ example above: @end group @end smallexample +@anchor{meta-interpretation} +Depending on the context, the contents of a quoted string may be +subject to @dfn{meta-variable interpretation}. During this process, +any sequence + +@smallexample +$@{@var{var}@} +@end smallexample + +@noindent +where @var{var} is the name of a defined meta-variable, is replaced with +the value of the variable. This sequence is called @dfn{meta- +reference}. For example, if the meta-variable @samp{user} has the +value @samp{smith}, then the string + +@smallexample +"where user = '$@{user@}'" +@end smallexample + +@noindent +becomes + +@smallexample +"where user = 'smith'" +@end smallexample + +If the name of the variable consists of a single character, the curly +braces around it may be omitted. Thus, @code{$@{u@}} and @code{$u} are +equivalent. + +If @var{var} is not defined, the meta-reference is left unchanged. + +To insert a literal @samp{$} character in a string that is subject to +meta-variable interpretation, duplicate it: @samp{$$}. + +The exact set of defined meta-variables and their values depend on the +context and are discussed in detail below. + @anchor{here-document} @item Here-document @cindex here-document @@ -569,8 +629,8 @@ strings of text containing embedded newlines. The @code{<<@var{word}} construct instructs the parser to read all the following lines up to the line containing only @var{word}, with -possible trailing blanks. Any lines thus read are concatenated -together into a single string. For example: +possible trailing blanks. Any lines thus read are concatenated +together into a single string. For example: @smallexample @group @@ -657,7 +717,43 @@ spool download @{ The closing curly brace may be followed by a semicolon, although this is not required. - + +@node Preprocessor +@subsection Preprocessor +@cindex preprocessor +@cindex m4 + Before parsing its configuration file, @command{wydawca} preprocesses +it. The built-in preprocessor handles only file inclusion +and @code{#line} statements (@pxref{Pragmatic Comments}), while the +rest of traditional preprocessing facilities, such as macro expansion, +is supported via @command{m4}, which is used as an external preprocessor. + + The detailed description of @command{m4} facilities lies far beyond +the scope of this document. You will find a complete user manual in +@ifnothtml +@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. +@end ifnothtml +@ifhtml +@uref{http://www.gnu.org/software/m4/manual}. +@end ifhtml +For the rest of this subsection we assume the reader is sufficiently +acquainted with @command{m4} macro processor. + +@cindex @file{pp-setup} + The external preprocessor is invoked with @option{-s} flag, which +instructs it to include line synchronization information in its +output. This information is then used by the parser to display meaningful +diagnostic. An initial set of macro definitions is supplied by the +@file{pp-setup} file, located in +@file{@var{$prefix}/share/wydawca/@var{version}/include} directory (where +@var{version} means the version of Wydawca package). + +The default @file{pp-setup} file renames all @command{m4} built-in +macro names so they all start with the prefix @samp{m4_}. This +is similar to GNU m4 @option{--prefix-builtin} options, but has an +advantage that it works with non-GNU @command{m4} implementations as +well. + @node syslog @section Syslog Configuration Directives @cindex syslog, configuration @@ -746,7 +842,7 @@ database. 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} and the colon may be omitted. If, however, it is present, it must be @samp{localhost}. -@xref{sql-host}, for more information and examples. +@FIXME-xref{sql-host}, for more information and examples. @end deffn @deffn {Configuration} database @var{name} @@ -797,7 +893,7 @@ access-method @var{method-name} @{ Access method statements can appear either in the global scope of the configuration file, or inside a @code{spool} statement -(@FIXME-pxref{spool}). Global definitions affect all directory +(@pxref{spool}). Global definitions affect all directory pairs in the configuration file, and ones inside a @code{directory} statement override them for that particular directory pair. @@ -856,7 +952,7 @@ See below for a detailed description of these access methods. @deffn {Configuration} query @var{string} Sets the query used for retrieving the data. The @var{string} is -subject to meta-variable expansion (@FIXME-pxref{meta-variables}). The +subject to meta-variable interpretation (@pxref{meta-interpretation}). The following meta-variables are defined: @table @code @@ -864,6 +960,7 @@ following meta-variables are defined: @kwindex user @item u @itemx user +@itemx user:name The system name of the user that submitted the triplet. @kwindex p @@ -874,6 +971,24 @@ following meta-variables are defined: submitted. It is defined as the value of directive @code{directory}, or, in case this value contains slashes, the shortest initial prefix of that value, not containing slashes. + +@item spool + The name of the distribution spool where this upload originates +(@pxref{spool}). + +@item url + The @acronym{URL} of the spool, as set in the @code{url} statement +of the @code{spool} block (@pxref{spool, url}). + +@item dir +Directory (relative to the project distribution root) where the +files are going to be uploaded. + +@item dest-dir +Spool destination directory (@pxref{spool, destination}). + +@item source-dir +Spool source directory (@pxref{spool, source}). @end table @end deffn @@ -940,11 +1055,11 @@ access-method project-owner @{ type sql; params (default); query "SELECT user.email, user.realname " - "FROM user,user_group,groups " - "WHERE user_group.user_id=user.user_id " - "AND user_group.group_id=groups.group_id " - "AND user_group.admin_flags = 'A' " - "AND groups.unix_group_name = '$@{project@}'"; + "FROM user,user_group,groups " + "WHERE user_group.user_id=user.user_id " + "AND user_group.group_id=groups.group_id " + "AND user_group.admin_flags = 'A' " + "AND groups.unix_group_name = '$@{project@}'"; @} @end smallexample @@ -972,11 +1087,11 @@ access-method verify-user @{ type sql; params (default); query "SELECT user.user_name " - "FROM user,user_group, groups " - "WHERE user_group.user_id=user.user_id " - "AND user_group.group_id=groups.group_id " - "AND user_group.admin_flags = 'A' " - "AND groups.unix_group_name='$@{project@}' " + "FROM user,user_group, groups " + "WHERE user_group.user_id=user.user_id " + "AND user_group.group_id=groups.group_id " + "AND user_group.admin_flags = 'A' " + "AND groups.unix_group_name='$@{project@}' " "AND user.user_name='$@{user@}'"; @} @end smallexample @@ -1010,7 +1125,7 @@ their existing files. @command{tar} file, and to a separate directory. The method to be used is configured using @code{archive} statement. This statement can appear either in the global scope, in which case it affects all -spools, or within a @code{spool} block (@FIXME-pxref{spool}), +spools, or within a @code{spool} block (@pxref{spool}), where it affects only the given spool. @kwindex archive @@ -1186,7 +1301,7 @@ spool @var{tag} @{ The @var{tag} argument defines a unique identifier for this spool. It will be used in log messages, timers (@FIXME-pxref{timers}) and in -meta-substitutions (@FIXME-pxref{meta-variables, spool}). +meta-variable interpretation (@pxref{meta-interpretation}). @deffn {Configuration} url @var{string} Defines download @acronym{URL}, associated with this spool. Its value @@ -1264,10 +1379,9 @@ spool ftp @{ @node statistics @section Statistics @cindex statistics -@UNREVISED At the end of the run, @command{wydawca} prints a detailed statistics of its execution on the diagnostic channel @samp{info}. -The statistics is printed only if at least one of the items is not zero. +The statistics is printed only if at least one of its items is not zero. The following example illustrates what you might get if you configured full statistics output: @@ -1354,18 +1468,18 @@ A symlink is removed. @end table @kwindex statistics - Amount of information included in the statistics summary is + The amount of information included in the statistics summary is configured using the @code{statistics} statement. This statement takes a list of arguments, each one being one of the keywords, described above. For example, the following statement causes only the information about errors and warnings to be printed: @smallexample -statistics errors warnings +statistics (errors, warnings); @end smallexample @noindent -It will produce the following output: +The output produced looks like: @smallexample errors: 0 @@ -1373,28 +1487,27 @@ warnings: 2 @end smallexample @kwindex none@r{, statistics} - The special keyword @samp{none} can be used to suppress this output + A special keyword @samp{none} can be used to suppress this output altogether (which is the default), as in @smallexample -statistics none +statistics none; @end smallexample @kwindex all@r{, statistics} - Another special keyword is @samp{all}, that enables all statistics + Another special keyword is @samp{all}. It enables full statistics output. This keyword may also be followed by any number of statistics keywords, which are in this case @emph{excluded} from the summary. For example, to output all statistics, except errors and warnings one would set: @smallexample -statistics all errors warnings +statistics (all, errors, warnings); @end smallexample @node notification @section Mail Notification @cindex mail notification -@UNREVISED While running, @command{wydawca} keeps track of certain events occurring, such as, for example, broken @acronym{PGP} signatures or file uploads attempted by unauthorized users. The utility can notify, @@ -1403,168 +1516,229 @@ concern their projects. Additionally, the system administrator can choose to obtain via email the execution statistics, described in the previous section. -@kwindex from-address The sender email address for these notifications is set using the -@code{from-address} statement, e.g.: +@code{from-address} statement. + +@deffn {Configuration} from-address @var{address} +Set sender address for outgoing mails. E.g.: @smallexample -from-address ftp-uploads@@gnu.org.ua +from-address ftp-uploads@@gnu.org.ua; @end smallexample +@end deffn -@noindent -It is not strictly necessary to specify it, however. In the absence of -@code{from-address} statement, the sender email will be constructed -from the name of the user @command{wydawca} runs as (usually -@samp{root}) and the full domain name of the machine it runs at. +It is not strictly necessary to specify the sender address. In the +absence of @code{from-address} statement, the sender email will be +constructed from the name of the user @command{wydawca} runs as +(@FIXME-pxref{user privs}) and the full domain name of the machine it +runs at. + +@deffn {Configuration} admin-address @var{email} +Sets the admin email address or addresses. The statistics +notifications and any notifications configured to be sent to admins +will be forwarded to this address. The @var{email} argument is either +a @acronym{RFC} 822 email address, or a list of such addresses. For +example, the following statement configures a single admin address: + +@smallexample +admin-address root@@gnu.org.ua; +@end smallexample + +The example below illustrates how to configure multiple addresses: + +@smallexample +admin-address "root@@gnu.org.ua,ftp-adm@@gnu.org.ua"; +@end smallexample + +Yet another way to configure them is: + +@smallexample +admin-address (root@@gnu.org.ua, ftp-adm@@gnu.org.ua); +@end smallexample +@end deffn @menu -* mailer:: -* templates:: -* statreports:: -* event notification:: +* mailer:: +* templates:: +* statreports:: +* event notification:: @end menu @node mailer @subsection Mailer @cindex mailer -@kwindex mailer -@UNREVISED To send messages, @command{wydawca} uses a special logical entity -called @dfn{mailer}. It is set in the configuration file using -@code{mailer} keyword: +called a @dfn{mailer}. It is set in the configuration file using +@code{mailer} keyword. -@smallexample -mailer @var{url} -@end smallexample +@deffn {Configuration} mailer @var{url} +Set mailer @acronym{URL}. +@end deffn @cindex @acronym{URL}, mailer @cindex mailer @acronym{URL} - A mailer @acronym{URL} begins with a protocol specification. -Two protocol specifications are currently supported: @samp{sendmail} -and @samp{smtp}. The former means to use a -@command{sendmail}-compatible program to send mails. Such a program -must be able to read mail from its standard input and must support the -following options: + A mailer @acronym{URL} consists of a scheme specification, followed +by @samp{://} separator and additional data. The @acronym{URL}s +supported by Wydawca version @value{VERSION} are described in the +table below. As usual, square brackets indicate optional parts: + +@table @asis +@item smtp://@var{host}[:@var{port}] +Use an SMTP server on @var{host} to relay messages. The @var{host} part is +either an IP address in dotted-quad notation or as a symbolic host +name. In the latter case, DNS system is be used to resolve +it. Optional @var{port} specifies port number or symbolic name (as +defined in @file{/etc/services}). It defaults to 25. For example: + +@smallexample +mailer smtp://remote.server.net:24; +@end smallexample + +@item sendmail://@var{progname} +Use sendmail-compatible program +@var{progname}. @dfn{Sendmail-compatible} means that the program must +be able to read an RFC-822 message from its standard input and must +support the following command line options: @table @option @item -oi -Do not treat '.' as message terminator. +Do not treat @samp{.} as message terminator. @item -f @var{addr} -Use @var{addr} as the address of the sender. +Use @var{addr} as the sender address. @item -t Get recipient addresses from the message. @end table -These conditions are met by most existing @acronym{MTA} programs, such -as @command{exim} or @command{postfix} (to say nothing of -@command{sendmail} itself). +Example: + +@smallexample +mailer sendmail:///usr/sbin/exim; +@end smallexample + +@item sendmail: +This is a special form of the @samp{sendmail} mailer. It uses the +@command{sendmail} binary from the @code{_PATH_SENDMAIL} macro in your +@file{/usr/include/paths.h}. It is the default mailer. -Following the protocol specification is the @dfn{mailer location}, which -is separated from it with a colon. For the @samp{sendmail} protocol, -the mailer location sets the full file name of the sendmail-compatible -@acronym{MTA} binary, for example: +@item prog://@var{progname}?@var{query} +A @dfn{prog} mailer. This is a generalization of @samp{sendmail} +mailer that allows to use arbitrary external programs as mailers. + +The full file name of the program is given in @var{progname} part. +The @var{query} part is a list of arguments, separated by @samp{&} +signs. Arguments may contain the following macro-substitutions: + +@table @samp +@item $@{sender@} +Expands to the sender email address. + +@item $@{rcpt@} +Expands to the recipient email addresses. + +The program @var{progname} must read an RFC-822 message from its +standard input. + +An example of @samp{prog} mailer definition: + +@smallexample +mailer "prog:///bin/nullmail?localhost&-F$@{sender@}&$@{rcpt@} +@end smallexample + +When sending a mail, @command{wydawca} will invoke: @smallexample -mailer sendmail:/usr/sbin/sendmail +/bin/nullmail localhost -F@var{sender} @var{rcpt} @end smallexample -A special form of a sendmail @acronym{URL}, consisting of protocol -specification only (@samp{sendmail:}) is also allowed. It means -``use the sendmail binary from the @code{_PATH_SENDMAIL} -macro in your @file{/usr/include/paths.h} file''. This is the default -mailer. +@noindent +where @var{sender} means the sender address, and @var{rcpt} stands for +the recipient email address. -The @samp{smtp} protocol means to use an @acronym{SMTP} server directly. -In this case, mailer location consists of two slashes, -followed by the @acronym{IP} address or host name of the @acronym{SMTP} -server, and, optionally, the port number. If the port number is -present, it is separated from the rest of @acronym{URL} by a colon. -For example: +@item | @var{prog} @var{args..} +Equivalent to the @samp{prog} mailer, described above, but written in +a more natural fashion. In this notation, the example definition above +becomes: @smallexample -@group -mailer smtp://remote.server.net -mailer smtp://remote.server.net:24 -@end group +mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}" @end smallexample +@end table +@end table + @node templates @subsection Message Templates @cindex templates, notification messages @cindex notification message template @cindex message template -@UNREVISED Each notification message is build from a message template, by -expanding any occurrences of @samp{%@{@var{name}@}} within it with the value -of macro-variable @var{name}. Sets of defined macro-variables -depend on the type of the notification and are described below. +expanding meta-variables (@pxref{meta-interpretation}) within it. +The message text may be specified either in place within the +configuration directive it belongs to (@FIXME-pxref{notification}), or +defined by @code{define-message} statement. + +@deffn {Configuration} define-message @var{name} @var{text}; +Define message @var{name} to be @var{text}. This message can be +referred to from other configuration statements by @code{@@@var{name}} +notation. +@end deffn -@kwindex define-message - Message templates are defined using @code{define-message} -statement. Its syntax is as follows: +The message text must be formatted as a valid RFC-822 message, i.e. it +must consist of two parts, message headers and body, separated by a +single empty line. Therefore @var{text} is usually a +@dfn{here-document} construct (@pxref{here-document}). For example: @smallexample -define-message @var{id} [-]@var{delimiter} -@var{lines} -@var{delimiter} +define-message my-message <}}; -@table @option -@item archives -Number of files successfully archived. +# Start in foreground even in daemon mode +foreground @var{arg:@i{}}; -@item bad_triplets -Number of bad triplets detected. +# Do not spawn subprocesses +single-process @var{arg:@i{}}; -@item complete_triplets -Number of complete triplets. +# Set wake-up interval +wakeup-interval @var{time:@i{}}; -@item errors -Number of errors during the run. +# Set pid file name +pidfile @var{file:@i{}}; -@item expired_triplets -Number of expired triplets. +# Run with UID and GID of this user +user @var{name:@i{}}; -@item incomplete_triplets -Number of incomplete triplets. +# Retain these supplementary groups +group @var{arg:@i{}}; -@item rmsymlinks -Number of symlinks successfully removed. +# Enable or disable locking +locking @var{arg:@i{}}; -@item symlinks -Number of symlinks successfully created. +# Set directory for lock files +lockdir @var{dir:@i{}}; -@item triplet_success -Number of triplets successfully processed. +# Define lock expiration interval +lock-expire-time @var{interval:@i{}}; -@item uploads -Number of successful uploads. +# Listen on this address +listen @var{socket:@i{}}; -@item warnings -Number of warnings. -@end table +# Configure TCP wrappers +tcp-wrapper @{ + # Enable TCP wrapper access control. Default is "yes". + enable @var{arg:@i{}}; - Two special keywords are also recognized: + # Set daemon name for TCP wrapper lookups. Default is program name. + daemon @var{name:@i{}}; -@table @option -@item all -Print all information. + # Use file for positive client address access control (default: + # /etc/hosts.allow). + allow-table @var{file:@i{}}; -@item none -Do not print any statistics. -@end table + # Use file for negative client address access control (default: + # /etc/hosts.deny). + deny-table @var{file:@i{}}; -@xref{statistics}, for more information. -@end deffn + # Log host allows at this syslog priority. + allow-syslog-priority @var{prio:@i{}}; -@anchor{file-sweep-time} -@deffn {Wydawca Statement} file-sweep-time @var{interval} -Sets the amount of time after which any unprocessed file will be -removed. + # Log host denies at this syslog priority. + deny-syslog-priority @var{prio:@i{}}; +@} - 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: +# Set mailer URL +mailer @var{url:@i{}}; -@smallexample -@group -1 hour -2 hours 35 seconds -1 year 7 months 2 weeks 2 days 11 hours 12 seconds -@end group -@end smallexample +# Set admin email address +admin-address @var{email:@i{}}; -@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 +# Set sender email address +from-address @var{email:@i{}}; -@deffn {Wydawca Statement} umask @var{value} -Sets the umask to be used. The @var{value} must be octal. -@end deffn +# Define file sweep time +file-sweep-time @var{interval:@i{}}; -@deffn {Wydawca Statement} tar-program @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}. +# Set tar invocation command line +tar-program @var{prog:@i{}}; -@xref{archivation}, for more information on when this statement is needed. -@end deffn +# Set umask +umask @var{mask:@i{}}; -@deffn {Wydawca Block Statement} sql @var{identifier} -This statement begins a MySQL database definition. It may contain -several sub-statements, defining how to access the database. The -statement ends with the @code{end} keyword on a line by itself. +# Print these stats at the end of run +statistics @var{items:@i{}}; -@xref{sql}, for more information. +# Define SQL database +sql @var{id:@i{}} @{ + # Set SQL server hostname or IP address + host @var{host:@i{}}; -@var{Identifier} is the symbolic name that can be used in -subsequent configuration statements to refer to this @acronym{SQL} -database. + # Set database name + database @var{dbname:@i{}}; -@smallexample -sql default - host localhost:/tmp/mysql.sock - database savane - user savane - password guessme -end -@end smallexample + # Set SQL user name + user @var{name:@i{}}; -The following statements are recognized within the @code{sql} block: + # Set SQL user password + password @var{arg:@i{}}; +@} -@anchor{sql-host} -@deffn {Wydawca Statement} host @var{hostname}[:@var{port-or-socket}] -Hostname where the database is running; @var{hostname} is either -a symbolic hostname of the machine, or its IP address in usual -@samp{dotted-quad} notation. +# Configure syslog logging +syslog @{ + # Set syslog facility. Arg is one of the following: user, daemon, auth, + # authpriv, mail, cron, local0 through local7 (case-insensitive), or a + # facility number. + facility @var{name:@i{}}; -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, @var{hostname} may be omitted. If, -however, it is present, it must be @samp{localhost}. + # Tag syslog messages with this string + tag @var{string:@i{}}; -Examples: + # Prefix each message with its priority + print-priority @var{arg:@i{}}; +@} -@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 +# Define message text +define-message @var{ident:@i{}} @var{text:@i{}}; -@deffn {Wydawca Statement} database @var{string} -Specifies the database name. -@end deffn +# Set up archivation +archive @var{type:@i{}} @{ + # Name of archive file or directory + name @var{file-or-dir:@i{}}; -@deffn {Wydawca Statement} user @var{string} -Specifies the database user name. -@end deffn + # Define backup type + backup @var{type:@i{}}; +@} -@deffn {Wydawca Statement} password @var{string} -Specifies the password. -@end deffn -@end deffn +# Send statistics +mail-statistics @{ + # Message text + message @var{text:@i{}}; -@deffn {Wydawca Block Statement} directory -Defines a directory pair. The syntax is: + # Send mail if one or more of these items are set + statistics @var{items:@i{}}; +@} -@smallexample -@group -directory [@var{url}] - source @var{name} - destination @var{name} - [@var{statements}] -end -@end group -@end smallexample +# Configure notification +notify-event @{ + # Event on which to notify + event @var{ev-id:@i{}}; -@noindent -where optional @var{url} specifies the @acronym{URL} of the -distribution site defined by this directory (for diagnostic purposes), -@code{source} and @code{destination} are two obligatory statements, -defining source and distribution directories, and @var{statements} are -any optional archive and/or access method definitions, overriding the -global ones for this directory pair. + # Notify this recipient + recipient @var{who:@i{}}; -@xref{spool}, for more information. + # Text of the notification or identifier of a defined message template + message @var{text-or-id:@i{}}; +@} -The following statements must be present in a @code{directory} block: +# Define access method +access-method @var{ident} @{ + # Method type + type @var{type:@i{}}; -@deffn {Wydawca Statement} source @var{dirname} -Sets source directory name. The @var{dirname} must be an absolute file -name. -@end deffn + # Query template + query @var{string:@i{}}; -@deffn {Wydawca Statement} destination @var{dirname} -Sets source directory name. The @var{dirname} must be an absolute file -name. -@end deffn -@end deffn + # Set method parameters + params @var{arg:@i{}}; +@} -@deffn {Wydawca Statement} gpg-key @var{type} @var{id} @var{command} -@cindex @acronym{PGP} public key, retrieving -@cindex public @acronym{PGP} key, retrieving -Defines an access method for retrieving user's public @acronym{PGP} -key. +# Define distribution spool +spool @var{tag:@i{}} @{ + # URL corresponding to this spool + url @var{arg:@i{}}; -@xref{access methods}, for a detailed description. -@end deffn + # Aliases + alias @var{arg:@i{}}; -@deffn {Wydawca Statement} project-owner @var{type} @var{id} @var{command} -Defines an access method for retrieving email addresses and real names -of administrators (@dfn{owners}) of a project. + # Source directory + source @var{dir:@i{}}; -@xref{access methods}, for a detailed description. -@end deffn + # Destination directory + destination @var{dir:@i{}}; -@deffn {Wydawca Statement} verify-user @var{type} @var{id} @var{command} -Defines an access method for verifying if the user is allowed to make -uploads for a certain project. + # Define file sweep time + file-sweep-time @var{interval:@i{}}; -@xref{access methods}, for a detailed description. -@end deffn + # Define access method + access-method @var{ident} @{ + # Method type + type @var{type:@i{}}; -@deffn {Wydawca Statement} user-data @var{type} @var{id} @var{command} -Defines an access method for retriev