diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-07 09:36:14 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-07 09:36:14 +0000 |
commit | 399b6a3682437d576dc4b7d77f66b5d88be4f7f3 (patch) | |
tree | 3f2623c404c7e2b937ff04ece4c283a46d115d9f /doc/wydawca.texi | |
parent | 610f147e2f7358eee94651e87994736a33be4633 (diff) | |
download | wydawca-399b6a3682437d576dc4b7d77f66b5d88be4f7f3.tar.gz wydawca-399b6a3682437d576dc4b7d77f66b5d88be4f7f3.tar.bz2 |
Update
git-svn-id: file:///svnroot/wydawca/trunk@319 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33
Diffstat (limited to 'doc/wydawca.texi')
-rw-r--r-- | doc/wydawca.texi | 195 |
1 files changed, 140 insertions, 55 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi index 3109c9b..6bc79a9 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -22,7 +22,7 @@ @ifinfo @direntry -* wydawca: (wydawca). Automatic project upload daemon. +* wydawca: (wydawca). Automatic release submission daemon. @end direntry @end ifinfo @@ -102,15 +102,16 @@ How to Configure @command{wydawca}. Mail Notification * mailer:: -* admin notification:: -* user notification:: +* templates:: +* statreports:: +* event notification:: @end detailmenu @end menu @node Intro, overview, Top, Top @chapter Introduction to Wydawca -@UNREVISED{} +@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 @dfn{distribution @acronym{URL}s}: @indicateurl{ftp.gnu.org}, which @@ -127,6 +128,9 @@ Uploads, maintain, Information for maintainers of GNU software}. @uref{http://www.gnu.org/prep/maintain/html_node/Automated-Upload-Procedure.html, Automated Upload Procedure}. @end ifhtml +@cindex upload site +@cindex source directory +@cindex directory, source The following is a short summary of it: there is an @acronym{FTP} @dfn{upload site}, which has two @dfn{source directories}, each one corresponding to a certain distribution @acronym{URL}. For example, @@ -137,21 +141,26 @@ corresponding to a certain distribution @acronym{URL}. For example, @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 -of the stable version @file{foo-1.0.tar.gz}, he creates a detached -signature @file{foo-1.0.tar.gz.sig}, using his PGP key, the creates a -special @dfn{directive} file, that contain some information needed bt -the server, and clearsigns it, obtaining this way the file +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 +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 (a @dfn{triplet}) to the upload site, storing them into the directory @file{/incoming/ftp}. - From now on it is the responsibility of an @dfn{automated upload -daemon}, to scan the source directories, to gather the triplets, -verify them, and to move the files to distribution sites, if they had -passed the verification successfully. +@cindex release submission daemon + From now on it is the responsibility of an @dfn{release submission daemon} +to scan the source directories, to gather the triplets, verify them, +and to any files that had passed the verification successfully to +their distribution sites. - @command{Wydawca} is such an automated upload daemon. It is able to + @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 @@ -162,7 +171,76 @@ effective and consumes little resources. @node overview, starting, Intro, Top @chapter Operation Overview -@UNREVISED{} +@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 +@cindex upload directory +@cindex directory, upload +@cindex source directory +@cindex directory, source +@cindex distribution directory +@cindex directory, distribution +@cindex destination directory +@cindex directory, destination + The 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. It also supplies all the information +necessary to access user and project databases. + + When started, @command{wydawca} scans each source directory and +prepares a list of files found there. Then, it compacts this list by +looking for @dfn{directive files} and re-arranging list members in +@dfn{triplets}. A @dfn{directive file} is a special file that must be +supplied with each upload, 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 +@ifnothtml +@ref{FTP Upload Directive File - v1.1, +Standalone directives, Standalone directives, +maintain, Information for maintainers of GNU software}. +@end ifnothtml +@ifhtml +@uref{http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html, +Standalone directives}. +@end ifhtml + + 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 +(@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. + +@cindex @acronym{PGP} +@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. + + Finally, the directives from each 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. @node starting, configuring, overview, Top @chapter How to invoke @command{wydawca}. @@ -208,7 +286,7 @@ the same as @option{--syslog}, but it may change in the future. @anchor{debug} @xopindex{debug, described} @sopindex{d, described} - The @option{--debug} (@option{-d}) tells the program to inrease its + The @option{--debug} (@option{-d}) tells the program to increase its debugging level by 1. The @dfn{debugging level} determines the amount of information the program reports when it runs. By default it is 0, meaning to report only errors and other critical conditions. Raising @@ -478,6 +556,7 @@ end @node access methods @section Access Methods @cindex Access method +@cindex @acronym{PGP} key An @dfn{access method} defines how @command{wydawca} can access some piece of information it needs while verifying the submission. This information can be, for example, the user's @acronym{PGP} key or his @@ -503,7 +582,7 @@ below: future use. @end table - Access methods are defined in the confguration file using the + Access methods are defined in the configuration file using the following syntax: @smallexample @@ -564,6 +643,8 @@ 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 Retrieve the public @acronym{PGP} key of a user. This method must return exactly one string. @@ -636,7 +717,7 @@ the ones uploaded earlier. Although this practice is not encouraged, it still can happen. In that case, @command{wydawca} needs to first @dfn{archive} the already existing file, and then put the new one in its place. Moreover, the directive file format allows maintainers to -explicitely require archivation of their existing files. +explicitly require archivation of their existing files. @cindex archivation methods @kwindex archive @@ -774,8 +855,8 @@ describing the pair. At least two statements are required: distribution) directory. Apart from these obligatory statements, the @code{directory} block may contain @code{archive} statement (@pxref{archivation}) and access method definitions (@pxref{access -methods}). If any of these statements is present, it override the -corresponding global definition only for this directory pair. The +methods}). Any of these statements, if present, overrides the +corresponding global definition for this directory pair. The @code{directory} statement ends with the @code{end} keyword on a separate line. @@ -794,8 +875,8 @@ end This directory pair will be using archivation type and access methods defined globally. - The following example shows the same directory pair block, that additionally -overriding the archivation method: + The following example shows the same directory pair block, that +additionally overrides archivation method: @smallexample @group @@ -815,8 +896,7 @@ such case. @node statistics @section Statistics -@UNREVISED{} - +@cindex statistics At the end of the run, @command{wydawca} can print the detailed statistics of its execution on the diagnostic channel @samp{info}. The following example illustrates what you might get if you configured @@ -854,13 +934,14 @@ Any warning conditions occurred during the run. @kwindex bad-signatures@r{, statistics} @item bad-signatures +@cindex @acronym{PGP} signature A @acronym{PGP} signature not matches the public key for the user that issued it. @kwindex access-violations@r{, statistics} @item access-violations A user is attempting to upload files for some project, but it is not -authorised to do so. +authorized to do so. @kwindex complete-triplets@r{, statistics} @item complete-triplets @@ -943,7 +1024,6 @@ statistics all errors warnings @node notification @section Mail Notification -@UNREVISED{} @cindex mail notification While running, @command{wydawca} keeps track of certain events occurring, such as, for example, broken @acronym{PGP} signatures or @@ -962,7 +1042,7 @@ from-address ftp-uploads@@gnu.org.ua @end smallexample @noindent -It is not strictly necessary to specify it, however. In the absense of +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. @@ -970,8 +1050,8 @@ from the name of the user @command{wydawca} runs as (usually @menu * mailer:: * templates:: -* admin notification:: -* user notification:: +* statreports:: +* event notification:: @end menu @node mailer @@ -1045,7 +1125,7 @@ mailer smtp://remote.server.net:24 @cindex notification message template @cindex message template Each notification message is build from a message template, by -expanding any occurrances of @samp{%@{@var{name}@}} within it with the value +expanding any occurrences of @samp{%@{@var{name}@}} within it with the value of macro-variable @var{name}. The sets of defined macro-variables depend on the type of the notification and are described below. @@ -1103,18 +1183,18 @@ define-message my-message -EOT EOT @end smallexample -@node admin notification -@subsection Admin Notification +@node statreports +@subsection Statistic Reports @kwindex mail-admin-stat - Sending notifications to the system administrator is enabled by + Sending statistic reports to the system administrator is enabled by @code{mail-admin-stat} statement. It takes two or more arguments. The first argument supplies the identifier of a message template, which should be previously defined by a @code{define-message}. The rest of arguments is a list of statistics keywords as described in -@ref{statistics}. The notification will be sent only if statistics +@ref{statistics}. A report will be sent only if statistics counters for at least one of the requested categories are not zero. For example, the following statement requires sending -notifications only if there ocurred any errors or access violation +notifications only if there occurred any errors or access violation attempts, or any bad signature was uploaded: @smallexample @@ -1188,17 +1268,18 @@ Wydawca end @end smallexample -@node user notification -@subsection User Notification -@UNREVISED{} -@cindex mail notification, project admin - Project administrators (@dfn{owners}) and/or users may recieve email -notifications about any of the following events: - +@node event notification +@subsection Event Notification +@cindex event notification + The following @dfn{events} are tracked during the execution. Any of +them can be used to trigger sending an email notification to any party +concerned: the system administrator, project administrators, or +the user that initiated the upload: + @table @code @kwindex success @item success - Successfull upload. + Successful upload. @kwindex bad-ownership @item bad-ownership @@ -1288,9 +1369,9 @@ Full listing of the uploaded triplet. It is equivalent to: For example: @smallexample --rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz --rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig --rw-r--r-- gray users 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc +-rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz +-rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig +-rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc @end smallexample @kwindex triplet:upload @@ -1298,8 +1379,8 @@ For example: Listing of the uploaded files. E.g.: @smallexample --rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz --rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig +-rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz +-rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig @end smallexample @kwindex triplet:dist @@ -1372,7 +1453,7 @@ Appending Files to an Archive, Appending Files to an Archive, tar, @item directory The @var{archive-name} specifies a directory name where to store -archive copies. If it is a relative pathname, this directory will be +archive copies. If it is a relative file name, this directory will be created under the @code{destination} directory. If it is absolute file name, the archive name directory will be constructed for each triplet using the following rule: @@ -1504,6 +1585,7 @@ Is ignored. @end table @end deffn +@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. @@ -1531,14 +1613,16 @@ omitted, seconds are supposed. Sets the umask to be used. The @var{value} must be octal. @end deffn -@deffn {Wydawca Statement} tar-command @var{string} +@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}. + +@xref{archivation}, for more information on when this statement is needed. @end deffn @deffn {Wydawca Block Statement} sql @var{identifier} This statement begins a MySQL database definition. It may contain -several substatements, defining how to access the database. The +several sub-statements, defining how to access the database. The statement ends with the @code{end} keyword on a line by itself. @xref{sql}, for more information. @@ -1630,6 +1714,8 @@ name. @end deffn @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. @@ -1660,7 +1746,7 @@ a user. @deffn {Wydawca Statement} admin-address @var{email} Sets email address or addresses to send administrator notification to. -@xref{admin notification}. +@xref{statreports}. @end deffn @deffn {Wydawca Statement} from-address @var{email} @@ -1670,10 +1756,9 @@ Sets the sender address for mail notifications. @end deffn @deffn {Wydawca Statement} mail-admin-stat @var{msg-id} @var{condition-list} -Defines statistics categories that trigger administrator -notifications. +Defines statistics categories that trigger statistic reports. -@xref{admin notification}. +@xref{statreports}. @end deffn @deffn {Wydawca Statement} define-message @@ -1778,7 +1863,7 @@ Print the program version and exit. @chapter How to Report a Bug As the purpose of bug reporting is to improve software, please be -sure to include maximum information when reporting a bug. The mimimum +sure to include maximum information when reporting a bug. The minimum information needed is: @itemize |