diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-21 15:57:21 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-21 15:57:57 +0200 |
commit | 43ba0c3da9ff8913f0286a01a82875fa59601dc0 (patch) | |
tree | fac6765cc2fb90ae39f5eb47d2c41abcaf93fb6d /doc/wydawca.texi | |
parent | 30e1c54062fe7098b9c71601370df1ce27f873d3 (diff) | |
download | wydawca-43ba0c3da9ff8913f0286a01a82875fa59601dc0.tar.gz wydawca-43ba0c3da9ff8913f0286a01a82875fa59601dc0.tar.bz2 |
Namespace cleanup.
Rename "access method" to "dictionary".
All sources affected.
* src/method.c: renamed to...
* src/dictionary.c: ... this.
Diffstat (limited to 'doc/wydawca.texi')
-rw-r--r-- | doc/wydawca.texi | 177 |
1 files changed, 94 insertions, 83 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi index a136fd6..04b599f 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -92,7 +92,7 @@ How to Configure @command{wydawca}. * Syntax:: Configuration file syntax. * syslog:: * sql:: -* access methods:: +* dictionaries:: * archivation:: * spool:: * statistics:: @@ -105,13 +105,13 @@ Configuration file syntax * Statements:: * Preprocessor:: -Access Methods +Dictionaries * sql type:: * builtin type:: * external type:: -SQL Access Methods +SQL Dictionary * project-owner-sql:: * project-uploader-sql:: @@ -130,13 +130,13 @@ Mail Notification @chapter Introduction to Wydawca @cindex introduction 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 +site, like, e.g. @indicateurl{gnu.org}. You have 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 +versions. Now, package maintainers need to have a way of uploading +their packages to one of these sites. This is done using the +@dfn{Automated FTP Upload} method, as described in @ifnothtml @ref{Automated FTP Uploads, Automated FTP Uploads, Automated FTP Uploads, maintain, Information for maintainers of GNU software}. @@ -157,16 +157,17 @@ corresponding to a certain distribution @acronym{URL}. For example, @item @file{/incoming/ftp} @tab @indicateurl{ftp.gnu.org} @item @file{/incoming/alpha} @tab @indicateurl{alpha.gnu.org} @end multitable +@* @cindex @acronym{PGP} @cindex detached signature @cindex signature, detached - Now, if the maintainer of the project @samp{foo} wishes to make a release + Now, if maintainer of the project @samp{foo} wishes to make a release of the stable version @file{foo-1.0.tar.gz}, he first creates a detached signature @file{foo-1.0.tar.gz.sig}. Then he creates a special -@dfn{directive} file, that contains information about where the +@dfn{directive} file, which contains information about where the distributed tarball must be placed, and clear-signs it using his -@acronym{PGP} key, thus obtaining file +@acronym{PGP} key, thus obtaining the file @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}. @@ -179,9 +180,9 @@ their distribution sites. @command{Wydawca} is such a release submission daemon. It is able to 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. +@dfn{spools}) in real time, and 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 @@ -224,7 +225,7 @@ that case. 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 +directories. The configuration file also supplies all the information necessary to access user and project databases. When started, @command{wydawca} scans each source directory and @@ -235,9 +236,9 @@ supplied with each upload and that contains directive regarding the placement of the uploaded files. A @dfn{triplet} is a standard entity, consisting of three files: a clear-signed directive file, a file to be distributed, and a detached signature of the latter. -In some special cases, a clear-signed directive file alone is valid, -namely when it contains only @dfn{standalone directives}, as described -in +In some special cases, a clear-signed directive file alone is valid. +This happens when it contains only @dfn{standalone directives}, as +described in @ifnothtml @ref{FTP Upload Directive File - v1.1, Standalone directives, Standalone directives, @@ -248,26 +249,38 @@ maintain, Information for maintainers of GNU software}. Standalone directives}. @end ifhtml - Each @dfn{incomplete} triplet, i.e. such that misses one or more +@cindex triplet, incomplete +@cindex incomplete triplet +@cindex triplet, expired +@cindex expired triplet + Each @dfn{incomplete} triplet, i.e. a triplet missing 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 -(@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. - - Then, the utility ensures that each of the remaining triplets is -created by a single person. Any triplets that do not are immediately -removed. +(@FIXME-pxref{file-sweep-time}). If so, the triplet is considered +@dfn{expired}, and all its files are removed. This gives users the +possibility to restart interrupted or otherwise broken uploads later. +@cindex dictionary @cindex @acronym{PGP} + After completing these preliminary stages, @command{wydawca} +analyzes the directive file and extracts the project name +from it. Using this name as a key, it looks up in the @dfn{project +dictionary} a list of users authorized to make uploads for this +project. This list contains user names and their corresponding public +@acronym{PGP} keys. @command{Wydawca} tries to verify the directive +file using each @acronym{PGP} key from this list, until a matching +key is found, or the list in exhausted. In the latter case, the +triplet is rejected. Otherwise, the key and its owner are remembered +for the next step. + +@cindex detached signature @cindex detached signature @cindex signature, detached - Then, @acronym{PGP} signatures of directive files and any detached -signatures (if available) are verified. If they do not match public -keys of the user who uploaded the triplet, such a triplet is -discarded. + In this step, the uploaded file and its detached signature +are verified. If they do not match the public key obtained in the +previous step, the triplet is rejected. - Finally, the directives from each directive file are executed. On + Finally, directives from the directive file are executed. On this stage of the processing, the uploaded files are actually moved to their destination directories, requested symbolic links are created, etc. @@ -387,7 +400,7 @@ directives any time by running @command{wydawca --config-help}. * Syntax:: Configuration file syntax. * syslog:: * sql:: -* access methods:: +* dictionaries:: * archivation:: * spool:: * statistics:: @@ -860,7 +873,7 @@ sql @var{id} @{ 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 +dictionaries, see the next section) to refer to this database. @end deffn @@ -904,21 +917,21 @@ sql default @{ @end group @end smallexample -@node access methods -@section Access Methods -@cindex Access method +@node dictionaries +@section Dictionaries +@cindex dictionaries @cindex @acronym{PGP} key - -An @dfn{access method} defines the ways to retrieve user information +@UNREVISED +A @dfn{dictionary} defines the ways to retrieve user information necessary to verify the submission. This information can be, for example, the user's @acronym{PGP} key or his permissions on a project. - Access methods are defined in configuration file using the + Dictionary is defined in configuration file using the following syntax: -@deffn {Config} access-method +@deffn {Config} dictionary @smallexample -access-method @var{method-name} @{ +dictionary @var{dict-id} @{ type @var{type}; query @var{string}; params (@var{param1},@var{param2},...); @@ -926,14 +939,14 @@ access-method @var{method-name} @{ @end smallexample @end deffn - Access method statements can appear either in the global scope of + A @code{dictionary} statement can appear either in the global scope of the configuration file, or inside a @code{spool} statement (@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 two access methods, identified by the value of -@var{method-name} tag: +There are two dictionaries, identified by the value of +@var{dict-id} tag: @table @asis @kwindex project-owner @@ -949,10 +962,10 @@ order. the users that are allowed to make uploads for the project. @end table -The sub-statements of @code{access-method} are: +The sub-statements of @code{dictionary} are: -@deffn {Config: access-method} type @var{name} -Defines the type of this method. @var{Name} is one of the following: +@deffn {Config: dictionary} type @var{name} +Defines the type of this dictionary. @var{Name} is one of the following: @table @asis @kwindex builtin @@ -966,14 +979,14 @@ Defines the type of this method. @var{Name} is one of the following: @kwindex external @item external - Retrieve data using an external program. This method is reserved for -future use. + Retrieve data using an external program. This dictionary type is +reserved for future use. @end table -See below for a detailed description of these access methods. +See below for a detailed description of these dictionary types. @end deffn -@deffn {Config: access-method} query @var{string} +@deffn {Config: dictionary} query @var{string} Sets the query used for retrieving the data. The @var{string} is subject to meta-variable interpretation (@pxref{meta-interpretation}). The following meta-variables are defined: @@ -1012,12 +1025,12 @@ Spool source directory (@pxref{spool, source}). @itemx user @itemx user:name The system name of the user that submitted the triplet. This is -defined only in @samp{project-owner} access method. +defined only for @samp{project-owner} dictionaries. @end table @end deffn -@deffn {Config: access-method} params (@var{param1}, @var{param2}, ...) -Supplies additional parameters for the method. +@deffn {Config: dictionary} params (@var{param1}, @var{param2}, ...) +Supplies additional parameters. @end deffn @menu @@ -1027,9 +1040,9 @@ Supplies additional parameters for the method. @end menu @node sql type -@subsection SQL Access Methods -@cindex sql access type -Access methods of @samp{sql} type retrieve information from an +@subsection SQL Dictionary +@cindex sql dictionary +Dictionaries of @samp{sql} type retrieve information from an @acronym{SQL} database (as of version @value{VERSION}, only @samp{MySQL} databases are supported). @@ -1042,8 +1055,7 @@ which determines database name and user credentials needed to access it. @cindex Savane The following sub-nodes contain sample definitions for the -access methods using the @code{sql} type. They are based -on the database structure used in +@code{sql} dictionaries. They are based on the database structure used in @uref{http://gna.org/projects/savane, @command{Savane} system}. @menu @@ -1059,7 +1071,7 @@ on the database structure used in consisting of two columns: an email address and a user name, in this order. @smallexample -access-method project-owner @{ +dictionary project-owner @{ type sql; params (default); query "SELECT user.email, user.realname " @@ -1077,7 +1089,7 @@ access-method project-owner @{ @UNREVISED @smallexample -access-method project-owner @{ +dictionary project-owner @{ type sql; params (default); query "SELECT user.email, user.realname " @@ -1090,15 +1102,15 @@ access-method project-owner @{ @end smallexample @node builtin type -@subsection Built-in access methods -@cindex builtin access type +@subsection Built-in Dictionary +@cindex builtin dictionary @WRITEME @node external type -@subsection External access methods -@cindex external access type +@subsection External Dictionary +@cindex external dictionary -As of version @value{VERSION} this access type is not yet +As of version @value{VERSION} this dictionary is not yet implemented. @node archivation @@ -1275,7 +1287,7 @@ archive-signatures no; A @dfn{distribution spool} defines the location of the source directory and the corresponding distribution (or @dfn{destination}) directory. It may also set archivation type, -various access methods and notifications for that directory, thus overriding +various dictionaries and notifications for that directory, thus overriding global settings. Distribution spool is defined in the configuration file by the @@ -1289,7 +1301,7 @@ spool @var{tag} @{ source @var{dir}; destination @var{dir}; file-sweep-time @var{interval}; - access-method @{ @dots{} @} + dictionary @{ @dots{} @} archive @{ @dots{} @} notify-event @{ @dots{} @} @} @@ -1338,9 +1350,9 @@ Configure spool-specific archivation. @xref{archivation}, for its description. @end deffn -@deffn {Config: spool} access-method @var{tag} @{ @dots{} @} -Configure spool-specific access-method. @xref{access -methods}, for a detailed discussion of this statement. +@deffn {Config: spool} dictionary @var{tag} @{ @dots{} @} +Configure spool-specific dictionary. @xref{dictionaries}, for a +detailed discussion of this statement. @end deffn @deffn {Config: spool} notify-event @{ @dots{} @} @@ -1364,7 +1376,7 @@ spool ftp @{ @end smallexample @noindent -This spool defines no particular archivation type, access method or +This spool defines no particular archivation type, dictionary or notifications, so it will inherit these settings from the global configuration. @@ -1885,13 +1897,12 @@ The system administrator, as defined in @code{admin-address} statement @kwindex owner @item owner Administrators of the project for which the files where -uploaded. Their addresses are retrieved using the @samp{project-owner} -access method (@pxref{access methods}). +uploaded. Their addresses are retrieved from the @samp{project-owner} +dictionary (@pxref{dictionaries}). @kwindex user @item user -The user who uploaded files. The user address is returned by -@samp{user-data} access method (@pxref{access methods}). +The user who uploaded files. @end table @end deffn @@ -2202,15 +2213,15 @@ notify-event @{ message @var{text-or-id:@i{<string>}}; @} -# Define access method -access-method @var{ident} @{ - # Method type +# Define a dictionary +dictionary @var{ident} @{ + # Dictionary type type @var{type:@i{<string>}}; # Query template query @var{string:@i{<string>}}; - # Set method parameters + # Set dictionary parameters params @var{arg:@i{<list of string>}}; @} @@ -2231,15 +2242,15 @@ spool @var{tag:@i{<string>}} @{ # Define file sweep time file-sweep-time @var{interval:@i{<string>}}; - # Define access method - access-method @var{ident} @{ - # Method type + # Define a dictionary + dictionary @var{ident} @{ + # Dictionary type type @var{type:@i{<string>}}; # Query template query @var{string:@i{<string>}}; - # Set method parameters + # Set dictionary parameters params @var{arg:@i{<list of string>}}; @} |