aboutsummaryrefslogtreecommitdiff
path: root/doc/wydawca.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-21 15:57:21 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-21 15:57:57 +0200
commit43ba0c3da9ff8913f0286a01a82875fa59601dc0 (patch)
treefac6765cc2fb90ae39f5eb47d2c41abcaf93fb6d /doc/wydawca.texi
parent30e1c54062fe7098b9c71601370df1ce27f873d3 (diff)
downloadwydawca-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.texi177
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>}};
@}

Return to:

Send suggestions and report system problems to the System administrator.