diff options
-rw-r--r-- | doc/fdl.texi | 1 | ||||
-rw-r--r-- | doc/rendition.texi | 13 | ||||
-rw-r--r-- | doc/wydawca.texi | 1035 | ||||
-rw-r--r-- | src/cmdline.opt | 2 | ||||
-rw-r--r-- | src/config.c | 4 | ||||
-rw-r--r-- | src/vtab.c | 3 |
6 files changed, 694 insertions, 364 deletions
diff --git a/doc/fdl.texi b/doc/fdl.texi index f13635b..edd86d4 100644 --- a/doc/fdl.texi +++ b/doc/fdl.texi @@ -1,5 +1,4 @@ @setfilename fdl.info -@appendix GNU Free Documentation License @cindex FDL, GNU Free Documentation License @center Version 1.2, November 2002 diff --git a/doc/rendition.texi b/doc/rendition.texi index c4092ea..45ac068 100644 --- a/doc/rendition.texi +++ b/doc/rendition.texi @@ -1,7 +1,7 @@ @c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard @c I extended it by adding a FIXME_FOOTNOTE variable, which controls @c whether FIXME information should be placed in footnotes or -@c inlined. +@c inlined. @c ====================================================================== @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF, @@ -39,10 +39,19 @@ @c Output marks for nodes needing revision, but not in PUBLISH rendition. +@macro WRITEME +@ifclear PUBLISH +@quotation +@emph{This node is to be written.} +@end quotation +@end ifclear +@end macro + @macro UNREVISED @ifclear PUBLISH @quotation -@emph{(This message will disappear, once this node revised.)} +(@emph{The information in this node may be obsolete or otherwise inaccurate.} +This message will disappear, once this node revised.) @end quotation @end ifclear @end macro diff --git a/doc/wydawca.texi b/doc/wydawca.texi index ad274b2..589f2f7 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -31,7 +31,7 @@ Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA -Copyright @copyright{} 2007 Sergey Poznyakoff +Copyright @copyright{} 2007, 2009 Sergey Poznyakoff Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or @@ -59,13 +59,12 @@ Software Foundation raise funds for GNU development.'' @page @contents -@node Top, Intro, (dir), (dir) - -@ifinfo -@chapter Wydawca +@ifnottex +@node Top +@top Wydawca This edition of the @cite{Wydawca Manual}, last updated @value{UPDATED}, documents Wydawca Version @value{VERSION}. -@end ifinfo +@end ifnottex @menu * Intro:: What is Wydawca @@ -90,12 +89,11 @@ already listed, mentioned here so you can get to them in one step: How to Configure @command{wydawca}. -* include:: * syslog:: * sql:: * access methods:: * archivation:: -* directory pairs:: +* spool:: * statistics:: * notification:: @@ -109,7 +107,7 @@ Mail Notification @end detailmenu @end menu -@node Intro, overview, Top, Top +@node Intro @chapter Introduction to Wydawca @cindex introduction Let's begin with a short synopsis. Suppose you run a developer's @@ -150,21 +148,21 @@ signature @file{foo-1.0.tar.gz.sig}. Then he creates a special @dfn{directive} file, that contains information about where the distributed tarball must be placed, and clear-signs it using his @acronym{PGP} key, thus obtaining file -@file{foo-1.0.tar.gz.directive.asc}. Then he uploads these three files +@file{foo-1.0.tar.gz.directive.asc}. Finally, he uploads these three files (a @dfn{triplet}) to the upload site, storing them into the directory @file{/incoming/ftp}. @cindex release submission daemon From now on, it is the responsibility of a @dfn{release submission daemon} to scan the source directories, gather the triplets, verify them, -and to move any files that had passed the verification successfully to +and to move any files that had successfully passed verification to their distribution sites. @command{Wydawca} is such a release submission 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. +handle any number of @samp{source/destination} pairs (called +@dfn{spools}, offers an extensible logging and mail notification +mechanism, allowing both package maintainers and site administrators +to be immediately notified about any occurring problems. @command{Wydawca} supports version 1.1 of directory file, as described in @@ -181,19 +179,20 @@ Standalone directives}. The program is written entirely in @acronym{C}, is highly effective and consumes little resources. -@node overview, starting, Intro, Top +@node overview @chapter Operation Overview @cindex operation @cindex overview Usually, @command{wydawca} is installed on the machine that receives -release uploads and is run periodically as a cron-job. 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 @acronym{NFS}. Future versions will contain -special provisions for that case. - -@cindex directory pair +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 +@acronym{NFS}. Future versions will contain special provisions for +that case. + +@cindex spool @cindex upload directory @cindex directory, upload @cindex source directory @@ -202,11 +201,11 @@ special provisions for that case. @cindex directory, distribution @cindex destination directory @cindex directory, destination - A configuration file supplies the utility with the set of -@dfn{directory pairs}, i.e. pairs of upload and corresponding -distribution directories. In @command{wydawca} terminology, upload -directories are also called @dfn{source}, and distribution directories --- @dfn{destination} directories. The file also supplies all the information + A configuration file defines a set of @dfn{spools}, i.e. pairs of +upload and corresponding distribution directories. In +@command{wydawca} terminology, upload directories are also called +@dfn{source}, and distribution directories -- @dfn{destination} +directories. The file also supplies all the information necessary to access user and project databases. When started, @command{wydawca} scans each source directory and @@ -254,12 +253,13 @@ this stage of the processing, the uploaded files are actually moved to their destination directories, requested symbolic links are created, etc. -@node starting, configuring, overview, Top +@node starting @chapter How to invoke @command{wydawca}. @cindex invocation @anchor{config-file} @xopindex{config-file, described} @sopindex{c, described} +@UNREVISED{} @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 @@ -292,8 +292,7 @@ the standard error. @xopindex{cron, described} 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. +@option{--cron} command line option anyway. @anchor{debug} @xopindex{debug, described} @@ -334,179 +333,379 @@ $ wydawca -c new.cfg --dry-run @option{--help} (@option{-h}) prints a short usage summary, and @option{--version} (@option{-v}) prints program version number. -@node configuring, wydawca.rc, starting, Top +@node configuring @chapter 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 as well. Non-empty -and non-comment lines must contain valid 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: + Upon startup, @command{wydawca} reads its settings from the +@dfn{configuration file} @file{wydawca.rc}. By default it is located +in @var{$sysconfidr} (i.e., in most cases @file{/usr/local/etc}, or +@file{/etc}), but an alternative location may be specified using +@option{--config} command line option (@FIXME-pxref{--config}). + + If any errors are encountered in the configuration file, the program +reports them on its error output and exits with a non-zero status. + +@xopindex{lint, introduced} + To test the configuration file without starting the server use +@option{--lint} (@option{-t}) command line option. It causes +@command{wydawca} to check configuration file for syntax errors and +other inconsistencies and to exit with status 0 if no errors were +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 +configuration without actually parsing it, use @option{-E} command +line option. To avoid preprocessing it, use +@option{--no-preprocessor} option. + +@xopindex{config-help, introduced} + The rest of this section describes the configuration file syntax in +detail. You can receive a concise summary of all configuration +directives any time by running @command{wydawca --config-help}. + +@menu +* Syntax:: Configuration file syntax. +* syslog:: +* sql:: +* access methods:: +* archivation:: +* spool:: +* statistics:: +* notification:: +@end menu + +@node Syntax +@section Configuration file syntax + + Wydawca configuration file consists of statements and comments. + + 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 +keywords and values. + +@menu +* Comments:: +* Pragmatic Comments:: +* Statements:: +@end menu + +@node Comments +@subsection Comments +@cindex Comments in a configuration file +@cindex single-line comments + @dfn{Comments} may appear anywhere where white space may appear in the +configuration file. There are two kinds of comments: +single-line and multi-line comments. @dfn{Single-line} comments start +with @samp{#} or @samp{//} and continue to the end of the line: + +@smallexample +# This is a comment +// This too is a comment +@end smallexample + +@cindex multi-line comments + @dfn{Multi-line} or @dfn{C-style} comments start with the two +characters @samp{/*} (slash, star) and continue until the first +occurrence of @samp{*/} (star, slash). + + Multi-line comments cannot be nested. However, single-line comments +may well appear within multi-line ones. + +@node Pragmatic Comments +@subsection Pragmatic Comments +@cindex comments, pragmatic +@cindex pragmatic comments + Pragmatic comments are similar to usual single-line comments, +except that they cause some changes in the way the configuration is +parsed. Pragmatic comments begin with a @samp{#} sign and end with the +next physical newline character. Wydawca version @value{VERSION}, +understands the following pragmatic comments: + +@table @code +@kwindex #include +@item #include <@var{file}> +@itemx #include @var{file} +Include the contents of the file @var{file}. If @var{file} is an +absolute file name, both forms are equivalent. Otherwise, the form +with angle brackets searches for the file in the @dfn{include +search path}, while the second one looks for it in the current working +directory first, and, if not found there, in the include search +path. + +The default include search path is: + +@enumerate 1 +@item @file{@var{prefix}/share/wydawca/@value{VERSION}/include} +@item @file{@var{prefix}/share/wydawca/include} +@end enumerate + +@noindent +where @var{prefix} is the installation prefix. + + New directories can be appended in front of it using @option{-I} +(@option{--include-dir}) command line option (@FIXME-pxref{--include-dir}). + +@kwindex #include_once +@item #include_once <@var{file}> +@itemx #include_once @var{file} + Same as @code{#include}, except that, if the @var{file} has already +been included, it will not be included again. + +@kwindex #line +@item #line @var{num} +@itemx #line @var{num} "@var{file}" + This line causes @command{wydawca} to believe, for purposes of error +diagnostics, that the line number of the next source line is given by +@var{num} and the current input file is named by @var{file}. +If the latter is absent, the remembered file name does not change. + +@item # @var{num} "@var{file}" + This is a special form of @code{#line} statement, understood for +compatibility with the @sc{c} preprocessor. +@end table + + In fact, these statements provide a rudimentary preprocessing +features. For more sophisticated ways to modify configuration before +parsing, see @FIXME-ref{Preprocessor}. + +@node Statements +@subsection Statements +@cindex statements, configuration file +@cindex configuration file statements +@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 +with a semicolon (@samp{;}). + + Examples of simple statements: @smallexample -syslog-print-priority yes +daemon yes; +pidfile /var/run/wydawca.pid; @end smallexample -If a simple statement is so long that it is inconvenient to keep it on -a single line, it can be split over several lines by ending each line -except the last one 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: + A @dfn{keyword} begins with a letter and may contain letters, +decimal digits, underscores (@samp{_}) and dashes (@samp{-}). +Examples of keywords are: @samp{group}, @samp{file-sweep-time}. + + A @dfn{value} can be one of the following: + +@table @asis +@item number + A number is a sequence of decimal digits. + +@item boolean +@cindex boolean value + A boolean value is one of the following: @samp{yes}, @samp{true}, +@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no}, +@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}. + +@item unquoted string +@cindex string, unquoted + An unquoted string may contain letters, digits, and any of the +following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/}, +@samp{@@}, @samp{*}, @samp{:}. + +@item quoted string +@cindex quoted string +@cindex string, quoted +@cindex escape sequence + A quoted string is any sequence of characters enclosed in +double-quotes (@samp{"}). A backslash appearing within a quoted +string introduces an @dfn{escape sequence}, which is replaced +with a single character according to the following rules: + +@float Table, backslash-interpretation +@caption{Backslash escapes} +@multitable @columnfractions 0.30 .5 +@item Sequence @tab Replaced with +@item \a @tab Audible bell character (@acronym{ASCII} 7) +@item \b @tab Backspace character (@acronym{ASCII} 8) +@item \f @tab Form-feed character (@acronym{ASCII} 12) +@item \n @tab Newline character (@acronym{ASCII} 10) +@item \r @tab Carriage return character (@acronym{ASCII} 13) +@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9) +@item \v @tab Vertical tabulation character (@acronym{ASCII} 11) +@item \\ @tab A single backslash (@samp{\}) +@item \" @tab A double-quote. +@end multitable +@end float + + In addition, the sequence @samp{\@var{newline}} is removed from +the string. This allows to split long strings over several +physical lines, e.g.: @smallexample @group -user-data sql default SELECT realname, email \ - FROM user \ - WHERE user_name='%@{user@}' +"a long string may be\ + split over several lines" @end group @end smallexample + If the character following a backslash is not one of those specified +above, the backslash is ignored and a warning is issued. -A @dfn{compound statement} begins with a simple statement, occupies -several lines, and ends with @code{end} statement, appearing on a line -by itself. Within a compound statement any number of another -statements (both simple and compound) may appear. + Two or more adjacent quoted strings are concatenated, which gives +another way to split long strings over several lines to improve +readability. The following fragment produces the same result as the +example above: -@cindex scope of a statement -When a statement appears outside of any block statement, we say that -it appears at @dfn{the top level} or @dfn{its scope is global}. When -it appears within a block statement, we say that @dfn{it has block -scope}. +@smallexample +@group +"a long string may be" +" split over several lines" +@end group +@end smallexample - This subsection will guide you through the @command{wydawca} -configuration on a step-by-step basis. +@anchor{here-document} +@item Here-document +@cindex here-document + A @dfn{here-document} is a special construct that allows to introduce +strings of text containing embedded newlines. -@menu -* include:: -* syslog:: -* sql:: -* access methods:: -* archivation:: -* directory pairs:: -* statistics:: -* notification:: -@end menu + 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: -@node include -@section Include Statement -@cindex inclusion, configuration file -@kwindex include -@UNREVISED -You can request inclusion of any file into your configuration file -using @code{include} statement. Its only argument supplies the name of -file to be included. For example: +@smallexample +@group +<<EOT +A multiline +string +EOT +@end group +@end smallexample + + Body of a here-document is interpreted the same way as +double-quoted string, unless @var{word} is preceded by a backslash +(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case +the text is read as is, without interpretation of escape sequences. + + If @var{word} is prefixed with @code{-} (a dash), then all leading +tab characters are stripped from input lines and the line containing +@var{word}. Furthermore, if @code{-} is followed by a single space, +all leading whitespace is stripped from them. This allows to indent +here-documents in a natural fashion. For example: @smallexample -include /etc/wydawca/msg +@group +<<- TEXT + All leading whitespace will be + ignored when reading these lines. +TEXT +@end group @end smallexample - The effect of the above statement is that the contents of file -@file{/etc/wydawca/msg} is read and processed as if it were here, -instead of the @code{include} statement. - - The include statement is especially useful if you wish to avoid -keeping large static blocks of text in your configuration file, to -make it more readable. An example of such large blocks of text are -templates for notification messages (@pxref{notification}), which we -suggest to keep in a separate file, and to include this file into the -main configuration (this approach is used in the default configuration -files). - -@cindex inclusion directory -@cindex default inclusion directory - The @code{include} argument may also be a relative -file name (i.e. one not beginning with @samp{/}). In this case, -@command{wydawca} will look for that file in its @dfn{inclusion -directory}. By default, the inclusion directory is your system -configuration directory. So, for example, in the default -configuration, the following two statements are equivalent: + It is important that the terminating delimiter be the only token on +its line. The only exception to this rule is allowed if a +here-document appears as the last element of a statement. In this +case a semicolon can be placed on the same line with its terminating +delimiter, as in: @smallexample -include message/stat -include /usr/local/etc/message/stat +help-text <<-EOT + A sample help text. +EOT; @end smallexample -@xopindex{include-directory, described} -@sopindex{I, described} - The value of the inclusion directory can be changed at run time, -using the @option{--include-directory} (@option{-I}) command line -option. This option takes an @emph{optional} argument, which means -that if the argument is supplied, it must follow the short form of the -option immediately, without any intervening whitespace, as in -@option{-I/var/inc}. Similarly, when the long option form is used, the -argument must be separated from it by a single equals sign, as in -@option{--include-directory=/var/inc}. - - If an argument is given, this option instructs @command{wydawca} to -use it as the new inclusion path. Otherwise, if argument is omitted, -the include directory is defined as a directory part of the full -file name of the configuration file. This form might be useful when -debugging new configurations. For example, the following command -runs @command{wydawca} in dry run mode, using configuration file -@file{./test.rc}, and looking for include files in the current working -directory: +@item list +@cindex list + A @dfn{list} is a comma-separated list of values. Lists are +enclosed in parentheses. The following example shows a statement +whose value is a list of strings: @smallexample -$ wydawca --config ./test.rc -I --dry-run +alias (test,null); @end smallexample - Please notice, that unlike many other programs (e.g. @command{cc} or -@command{make}), @command{wydawca} allows only one value of the -inclusion directory: inclusion paths are not supported. If the command -line contains several @option{-I} options, only the last of them takes -effect. + In any case where a list is appropriate, a single value is allowed +without being a member of a list: it is equivalent to a list with a +single member. This means that, e.g. + +@smallexample +alias test; +@end smallexample + +@noindent +is equivalent to + +@smallexample +alias (test); +@end smallexample +@end table + +@cindex statement, block +@cindex block statement + A @dfn{block statement} introduces a logical group of +statements. It consists of a keyword, followed by an optional value, +and a sequence of statements enclosed in curly braces, as shown in +the example below: + +@smallexample +@group +spool download @{ + source /home/ftp/incoming/ftp; + destination /home/ftp/pub; +@} +@end group +@end smallexample + The closing curly brace may be followed by a semicolon, although +this is not required. + @node syslog @section Syslog Configuration Directives @cindex syslog, configuration -@kwindex syslog-facility -@UNREVISED +@kwindex syslog + Unless told otherwise, @command{wydawca} uses @code{syslog} to print its diagnostic messages. By default, the program uses the -@samp{local1} facility. To change this, use @code{syslog-facility} -statement: +@samp{local1} facility. The @code{syslog} statement allows to change that: @smallexample -syslog-facility local2 +syslog @{ + facility local1; + tag wydawca; + print-priority yes; +@} @end smallexample +@deffn {Configuration} facility @var{name} @kwindex authpriv@r{, syslog facility} @kwindex cron@r{, syslog facility} @kwindex daemon@r{, syslog facility} @kwindex ftp@r{, syslog facility} @kwindex local0 @r{through} local7@r{, syslog facilities} @kwindex mail@r{, syslog facility} - 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_} (case-insensitive as well). + Configures the syslog 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_} +(case-insensitive as well). +@end deffn -@kwindex syslog-tag +@deffn {Configuration} tag @var{string} @cindex syslog tag, configuring - Another thing you may wish to tune is the @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 uploads -@end smallexample + This statement sets the @dfn{syslog tag}, a string +identifying each message issued by the program. By default, the +name of the program (@samp{wydawca}) is used. +@end deffn -@kwindex syslog-print-priority +@deffn {Configuration} print-priority @var{bool} @cindex syslog priority, printing in diagnostics 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 +print-priority yes; @end smallexample +@end deffn @node sql @section @acronym{SQL} Databases @@ -514,9 +713,9 @@ syslog-print-priority yes @cindex @acronym{SQL} databases @cindex @command{MySQL} databases @cindex database, @command{MySQL} -@UNREVISED -Several statements in configuration file may need to access -@acronym{SQL} database. @command{Wydawca} can use any number of + +Several statements in configuration file may need to access an +@acronym{SQL} database. @command{Wydawca} is able to use any number of databases simultaneously, the only restriction being that they must be @command{MySQL} databases (this restriction will be removed in future releases). @@ -527,52 +726,52 @@ following syntax: @smallexample @group -sql @var{identifier} - @var{statements} -end +sql @var{id} @{ + host @var{hostname}; + database @var{dbname}; + user @var{username}; + password @var{string}; +@} @end group @end smallexample - Here, @var{identifier} is a string uniquely identifying this + Here, @var{id} is a string uniquely identifying this database. It is used by another configuration statements (e.g. by access methods, see the next section) to refer to this -database. @var{statements} stand for a set of statements that -determine access credentials for the database. Allowed statements are: +database. -@table @code -@kwindex host -@item host @var{hostname}[:@var{port-or-socket}] +@deffn {Configuration} host @var{hostname}[:@var{port-or-socket}] Set the hostname or @acronym{IP} address of the host running the -database. The optional @var{port-or-socket} specifies port number (for +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. +@end deffn -@kwindex database -@item database @var{name} +@deffn {Configuration} database @var{name} Specifies the database name. +@end deffn -@kwindex user -@item user @var{name} -Specifies the database user name. +@deffn {Configuration} user @var{name} +Sets the database user name. +@end deffn -@kwindex password -@item password @var{string} -Specifies the password for accessing the database. -@end table +@deffn {Configuration} password @var{string} +Sets the password for accessing the database. +@end deffn @noindent An example @code{sql} statement follows: @smallexample @group -sql default - host project.database.com:3306 - database savane - user savane - password guessme -end +sql default @{ + host project.database.com:3306; + database savane; + user root; + password guessme; +@} @end group @end smallexample @@ -581,67 +780,84 @@ end @cindex Access method @cindex @acronym{PGP} key @UNREVISED -An @dfn{access method} defines how @command{wydawca} accesses some -piece of information it needs while verifying the submission. This -information can be, for example, the user's @acronym{PGP} key or his -permissions on a project. +An @dfn{access method} defines the ways to retrieve user information +needed to verify the submission. This information can be, for example, +the user's @acronym{PGP} key or his permissions on a project. - @command{Wydawca} understands three types of access methods, only -one of them being implemented right now. These methods are summarized -in the table below: + Access methods are defined in configuration file using the +following syntax: + +@smallexample +access-method @var{method-name} @{ + type @var{type}; + query @var{string}; + params (@var{param1},@var{param2},...); +@} +@end smallexample + + 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 +pairs in the configuration file, and ones inside a @code{directory} +statement override them for that particular directory pair. + +There are four access methods, identified by the value of +@var{method-name} tag: + +@table @asis +@kwindex gpg-key +@item gpg-key +Retrieve the public @acronym{PGP} key of a user. This method must +return exactly one string. + +@kwindex project-owner +@item project-owner + Retrieve email addresses and real names of administrators (or +@dfn{owners}) of a project. It may return any number of rows, each one +consisting of two columns: an email address and a user name, in this +order. + +@kwindex user-data +@item user-data + Return email address and real name of a user. This method must +return one tuple, consisting of two columns: an email address and a user +name, in this order. + +@kwindex verify-user +@item verify-user + Verify if a user is allowed to make uploads for a certain project. This +method must return the system name of the user if he is allowed to +make uploads. +@end table + +The sub-statements of @code{access-method} are: + +@deffn {Configuration} type @var{name} +Defines the type of this method. @var{Name} is one of the following: @table @asis -@kwindex builtin@r{, access method type} +@kwindex builtin @item builtin - This method is reserved for future use. + The data are supplied in the configuration file. -@kwindex sql@r{, access method type} +@kwindex sql @item sql Retrieve data from an @acronym{SQL} database. Currently only @command{MySQL} is supported. -@kwindex external@r{, access method type} +@kwindex external @item external Retrieve data using an external program. This method is reserved for future use. @end table - Access methods are defined in configuration file using the -following syntax: - -@smallexample -@var{method-name} @var{type} @var{param1} @var{param2} -@end smallexample - -@noindent -where @var{method-name} is the predefined name of the access method, -@var{type} is its type and @var{param1} and @var{param2} are -@dfn{parameters}, that describe the method. - - Access method statements can appear either in the global scope of -the configuration file, or inside a @code{directory} statement -(@pxref{directory pairs}). Global definitions affect all directory -pairs in the configuration file, and ones inside a @code{directory} -statement override them for that particular directory pair. +See below for a detailed description of these access methods. +@end deffn - There are four predefined methods, which are described later in this -section. The @var{type} must currently always be @samp{sql}. The -@var{param1} is an identifier of one of the preceding @code{sql} blocks -(@pxref{sql}), which determines database name and user -credentials needed to access it. The @var{param2} is an @acronym{SQL} -statement that must be issued to obtain the requested data. Before -execution, this statement undergoes @dfn{variable expansion}, whereby -each occurrence of @code{%@{@var{name}@}} is replaced with the value -of meta-variable @var{name} (if @var{name} consists of a single -letter, the curly braces may be omitted). - - For example, following are two valid uses of macro-variables: -@code{%u} and @code{%@{user@}}, the first of them expands to the value -of macro variable @samp{u}, and the second one expands to the value of -the variable @samp{user}. Undefined variables are not expanded, but -are left in the query intact. - - The variables defined for use in access methods are: +@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 +following meta-variables are defined: @table @code @kwindex u @@ -659,85 +875,127 @@ 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. @end table +@end deffn + +@deffn {Configuration} params (@var{param1}, @var{param2}, ...) +Supplies additional parameters for the method. +@end deffn + +@menu +* sql type:: +* builtin type:: +* external type:: +@end menu + +@node sql type +@subsection SQL Access Methods +@cindex sql access type +Access methods having the type @samp{sql} retrieve information from an +@acronym{SQL} database (as of version @value{VERSION}, only +@samp{MySQL} databases are supported). + +The @code{query} statement supplies the @acronym{SQL} query to +execute. Normally, it should be a @code{SELECT} query. + +The @code{params} statement must supply a single parameter -- +an identifier of one of the preceding @code{sql} blocks (@pxref{sql}), +which determines database name and user credentials needed to access it. @cindex Savane - The rest of this section describes the access methods (referred to -by @var{method-name} in the syntax above) used by -@command{wydawca}. They are illustrated by example definitions, based + The following sub-nodes contain sample definitions of all four +access methods using the @code{sql} type. They are based on the database structure used in @uref{http://gna.org/projects/savane, @command{Savane} system}. -@deffn {Access Method} gpg-key -@cindex @acronym{PGP} public key, retrieving -@cindex public @acronym{PGP} key, retrieving +@menu +* gpg-key-sql:: +* project-owner-sql:: +* user-data-sql:: +* verify-user-sql:: +@end menu + +@node gpg-key-sql +@subsubsection Gpg-key: an SQL Implementation +@cindex gpg-key Retrieve the public @acronym{PGP} key of a user. This method must return exactly one string. - The sample definition is: - @smallexample -gpg-key sql default SELECT gpg_key \ - FROM user \ - WHERE user_name='%@{user@}' +access-method gpg-key @{ + type sql; + params (default); + query "SELECT gpg_key FROM user WHERE user_name='$@{user@}'"; +@} @end smallexample -@end deffn -@deffn {Access Method} project-owner +@node project-owner-sql +@subsubsection Project-owner: an SQL Implementation +@cindex project-owner Retrieve email addresses and real names of administrators (or @dfn{owners}) of a project. It may return any number of rows, each one consisting of two columns: an email address and a user name, in this order. @smallexample -@group -project-owner sql default 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@}' -@end group +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 " + " |