OpenPKG CVS Repository
http://cvs.openpkg.org/
____________________________________________________________________________
Server: cvs.openpkg.org Name: Thomas Lotterer
Root: /v/openpkg/cvs Email: [EMAIL PROTECTED]
Module: openpkg-registry Date: 10-Jul-2006 17:18:14
Branch: HEAD Handle: 2006071016181300
Modified files:
openpkg-registry register.sh
Log:
openpkg man register
Summary:
Revision Changes Path
1.36 +331 -16 openpkg-registry/register.sh
____________________________________________________________________________
patch -p0 <<'@@ .'
Index: openpkg-registry/register.sh
============================================================================
$ cvs diff -u -r1.35 -r1.36 register.sh
--- openpkg-registry/register.sh 10 Jul 2006 10:23:02 -0000 1.35
+++ openpkg-registry/register.sh 10 Jul 2006 15:18:13 -0000 1.36
@@ -253,11 +253,6 @@
##
## Primary operation Preparation
##
-## Creates registry data for one request and dumpes it stdout
-## in XML format. That request can be filtered and piped into
-## the --Tran phase or it can be copied and pasted into the
-## XMLdump CGI facility manually.
-##
preparation()
{
if [ ".$REGISTRY_MODE" = .wipe ]; then
@@ -301,13 +296,6 @@
##
## Primary operation Transaction
##
-## Reads registry data with one request from stdin, executes
-## the transaction and writes registry data with one or more
-## responses to stdout in XML format. Depending on the mode of
-## operation, the transaction might be an actual transport to the
-## XMLdump CGI facility or a fake activity which complements the
-## manual preparation.
-##
transaction()
{
if [ ".$REGISTRY_MODE" = .wipe ]; then
@@ -353,10 +341,6 @@
##
## Primary operation Utilization
##
-## Reads registry data with one response from stdin and updates
-## the local registry information. Note that this step requires
-## write accesss to the $REGISTRY_UTIL file.
-##
utilization()
{
if [ ".$REGISTRY_MODE" = .wipe ]; then
@@ -572,4 +556,335 @@
## primary operation switch
##
eval $op "\"[EMAIL PROTECTED]""
+exit $?
+
+##
+## MANUAL PAGE
+##
+
+=pod
+
+=head1 NAME
+
+B<openpkg register> - OpenPKG Registry Command-Line Client
+
+=head1 SYNOPSIS
+
+B<register> -m|--mode=fake|post|wipe [I<-a|--args=<args>>]
+ -u|--user=<user> [I<-d|--desc=<text>>]
+ [I<--plat=<text>>] [I<--orel=<text>>] [I<--uuid=<file>>]
+ [I<--conf=<file>>] [I<--prep=<file>>] [I<--tran=<file>>]
+ [I<--util=<file>>]
+ [I<-P|--preparation>] [I<-T|--transaction>]
+ [I<-U|--utilization>] [I<-C|--convenience>]
+ [I<-I|--interaction>]
+ [I<-v|--verbose>] [I<-h|--help>]
+
+B<register> -S|--printstatus
+
+B<register> -R|--rewriteurls [I<url> ...]
+
+=head1 DESCRIPTION
+
+B<openpkg register> is the Command-Line Client the OpenPKG Registry. It is
+used by administrators to register an instance with the OpenPKG Registry for
+later association.
+
+Automatic association is intentionally not possible and login to the web form
+on http://registry.openpkg.org/ is required.
+
+After association, B<openpkg register> can be used for repetitive
+reregistrations which update the heartbeat of the instance on the Registry
+server, avoiding premature depature from the database. It is assumed that
+every instance will be reregistered every quarter of the year. Dormant
+instances might be discarded from the Registry, revoking their access to
+additional resources.
+
+=head1 PRIMARY OPERATIONS
+
+The following primary operations are available:
+
+=over 4
+
+=item B<-h>, B<--help>
+
+Display brief usage message.
+
+=item B<-P>, B<--preparation>
+
+Execute the primary operation "preparation".
+Creates registry data for one request and dumps it stdout
+in XML format. That request can be filtered and piped into
+the transaction phase or it can be copied and pasted into the
+XMLdump CGI facility manually.
+A copy of the output of the last run is also saved to the
C<${REGISTRY_PREP}> file.
+
+=item B<-T>, B<--transaction>
+
+Execute the primary operation "transaction".
+Reads registry data with one request from stdin, executes
+the transaction and writes registry data with one or more
+responses to stdout in XML format.
+Depending on the mode of operation, the transaction might be an actual
+transport to the XMLdump CGI facility or a fake activity which complements
the
+manual preparation.
+A copy of the output of the last run is also saved to the
C<${REGISTRY_TRAN}> file.
+
+=item B<-U>, B<--utilization>
+
+Execute the primary operation "utilization".
+Reads registry data with one response from stdin and updates the local
+registry information.
+Depending on the mode of operation, the utilization might be an actual
+processing of a transaction response or a fake activity which complements the
+manual transaction.
+Anyway, this step finalizes the registration process and makes the instance
+assume it has been properly registered. This status can be printed. URL
+rewriting is activated.
+A copy of the output of the last run is also saved to the
C<${REGISTRY_UTIL}> file.
+
+=item B<-C>, B<--convenience>
+
+Execute the primary operation "convenience".
+This executes the three primary operations "preparation", "transaction" and
+"utilization" in that order and pipes data through this chain.
+
+=item B<-I>, B<--interaction>
+
+Execute the primary operation "interaction".
+Like "convenience" but user is interactively asked for information. This is
+the easiest way to do registration but it is not meat to be automated.
+
+=item B<-S>, B<--printstatus>
+
+If the instance has been registered, information about the registration is
printed in a
+format suitable for shell evaluation and return code is true.
+Otherwise nothing is printed and return code is false.
+
+=item B<-R>, B<--rewriteurls> [I<url> ...]
+
+If the instance has been registered, the given URLs are rewritten to prepend
+user:pass information before hostnames below the openpkg.(org|net|com)
+domains. Note the username is is UUID_REGISTRY and the password is the
+concatenation of UUID_INSTANCE and UUID_PLATFORM from the
+PREFIX/etc/openpkg/uuid file. Both informations are not meant to be used for
+traditional authentication, they are merly statistical information.
+Otherwise the URLs are returned verbatim.
+
+=back
+
+=head1 STANDARD OPTIONS
+
+Standard options are typically used to automate registration (not
+association).
+
+=over 4
+
+=item B<-m>, B<--mode> fake|post|wipe
+
+Overrides C<${REGISTRY_MODE}> variable in C<${REGISTRY_CONF}> file.
+Has no default and is a manadatory setting.
+
+In B<post> mode, transactions are carried out using real network
connectivity.
+The "preparation" step creates a XMLdump and writes it into the
+C<${REGISTRY_PREP}> file. The "transaction" step posts it to the DropXML form
+using a HTTP request. The response coming back from Registration server is
+also in XML format and is saved to C<${REGISTRY_TRAN}> file. The
+"utilization" step processes this response and writes the final results to
the
+C<${REGISTRY_UTIL}> file.
+
+In B<fake> mode, no network connectivity takes place.
+The "prepararation" step creates a XMLdump and writes it into the
+C<${REGISTRY_PREP}> file. The "transaction" step is a fake only. It assumes a
+successful response from the Registration server and saves it to
+C<${REGISTRY_TRAN}> file. The "utilization" step processes this response and
+writes the final results to the C<${REGISTRY_UTIL}> file.
+I<Note>: fake mode is meant as a way to register instances which cannot or
must
+not post data directly to the Registration server.
+
+In B<wipe> mode, the registration is wiped out locally. The status is reset
+and URL rewriting is disabled.
+I<Note>: the registration server is not contacted, the instace must be
removed
+manually using the web interface.
+I<Note>: wiping registration is highly recommended as a precursor action of
+cloning activities.
+
+=item B<-a>, B<--args> "arg [arg ...]"
+
+Overrides C<${REGISTRY_ARGS}> variable in C<${REGISTRY_CONF}> file.
+Complements the mode and is specific to it.
+Defaults to "http://registry.openpkg.org/register"; which is the official
registry of the OpenPKG Project.
+This default is useful for "post" mode.
+
+=item B<-u>, B<--user> I<user>
+
+Overrides C<${REGISTRY_USER}> variable in C<${REGISTRY_CONF}> file.
+Indicates the registry user which will find this registration in his arrival
queue.
+This information in submitted via the "registry_user" attribute of the XML
request.
+Has no default and is a manadatory setting.
+
+=item B<-d>, B<--desc> I<description>
+
+Overrides C<${REGISTRY_DESC}> variable in C<${REGISTRY_CONF}> file.
+Indicates a human readable description of the instance.
+This information in submitted via the "registry_desc" attribute of the XML
request.
+It appears in the "description" column on the "association" page of the web
form and can be edited on the server side.
+Defaults to "openpkg://${HOSTNAME}${PREFIX}"
+
+=back
+
+=head1 ADVANCED OPTIONS
+
+Advanced options can be enganged to tailor and fully automate a registration
+(not association).
+
+=over 4
+
+=item B<--plat>
+
+Overrides C<${REGISTRY_PLAT}> variable in C<${REGISTRY_CONF}> file.
+Indicates the platform. Concatenated information from CPU architecture
(arch) and Operating System (os).
+This information in submitted via the "registry_plat" attribute of the XML
request.
+Defaults to "%{l_platform -p}", e.g. "ix86-freebsd6.1"
+
+=item B<--orel>
+
+Overrides C<${REGISTRY_VERS}> variable in C<${REGISTRY_CONF}> file.
+Indicates the OpenPKG release.
+This information in submitted via the "registry_orel" attribute of the XML
request.
+Defaults to "%{l_openpkg_release}", e.g. "OpenPKG-CURRENT",
"OpenPKG-2-STABLE", "OpenPKG-2.5",
+
+=item B<--uuid>
+
+Overrides C<${REGISTRY_UUID}> variable in C<${REGISTRY_CONF}> file.
+Indicates the UUID file of the instance.
+This information in submitted via the "uuid_registry", "uuid_instance" and
"uuid_platform" attributes of the XML request.
+Defaults to F<${PREFIX}/etc/openpkg/uuid>
+
+=item B<--conf>
+
+Overrides C<${REGISTRY_CONF}> variable from previous C<${REGISTRY_CONF}>
file. Processing
+of the current configuration file is aborted immediately with all variables
+read so far kept. THe new configuration file is read in immediately and
+processing continues there. This works similar to an include but is more
+primitive as it does not allow nesting, only chaining.
+Defaults to F<${PREFIX}/etc/openpkg/register.conf>
+
+=item B<--prep>
+
+Overrides C<${REGISTRY_PREP}> variable in C<${REGISTRY_CONF}> file.
+File to save a copy of the output from the "preparation" step.
+Defaults to F<${PREFIX}/etc/openpkg/register.prep>
+
+=item B<--tran>
+
+Overrides C<${REGISTRY_TRAN}> variable in C<${REGISTRY_CONF}> file.
+File to save a copy of the output from the "transaction" step.
+Defaults to F<${PREFIX}/etc/openpkg/register.tran>
+
+=item B<--util>
+
+Overrides C<${REGISTRY_UTIL}> variable in C<${REGISTRY_CONF}> file.
+File to save a copy of the output from the "utilization" step.
+Defaults to F<${PREFIX}/etc/openpkg/register.util>
+
+=back
+
+=head1 FILES
+
+The following files are used by B<openpkg register>:
+
+=over 4
+
+=item OPENPKG_UUID=F<${PREFIX}/etc/openpkg/uuid>
+
+ UUID_REGISTRY="..."
+ UUID_INSTANCE="..."
+ UUID_PLATFORM="..."
+
+=item OPENPKG_CONF=F<${PREFIX}/etc/openpkg/register.conf>
+
+Format suitable for shell evaluation. Interactive mode appends remarked date
+and current settings for reuse as new defaults for future runs. Can be preset
+to customize or automate registration.
+
+=item OPENPKG_PREP=F<${PREFIX}/etc/openpkg/register.prep>
+
+ <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+ <!DOCTYPE registry
+ PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
+ "http://registry.openpkg.org/registry.dtd"; []>
+ <registry>
+ <request id="..."
+ registry_user="[EMAIL PROTECTED]"
+ registry_desc="openpkg://rm0.openpkg.net/openpkg-dev"
+ registry_plat="ix86-freebsd6.1"
+ registry_orel="OpenPKG-CURRENT"
+ uuid_registry="..."
+ uuid_instance="..."
+ uuid_platform="..."
+ />
+ </registry>
+
+The XML request starts with <?xml version ...> and <!DOCTYPE registry ...>
+headers followed by a <registry> container. The request is inside a <request>
+tag. Successful submission into the XMLdump form requires the headers and
+exactly one container. It is possible to merge multiple requests into a
single
+container manually or otherwise and submit them all at once.
+
+=item OPENPKG_TRAN=F<${PREFIX}/etc/openpkg/register.tran>
+
+ <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+ <!DOCTYPE registry
+ PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
+ "http://registry.openpkg.org/registry.dtd"; []>
+ <registry>
+ <response id="..."
done="yes">openpkg://rm0.openpkg.net/openpkg-dev</response>
+ </registry>
+
+The XML response starts with <?xml version ...> and <!DOCTYPE registry ...>
+headers followed by a <registry> container. The response is inside a
<request>
+tag. The data carried in the tag comes from the "description" column on the
+"association" page of the web form and can be edited on the server side.
+
+=item OPENPKG_UTIL=F<${PREFIX}/etc/openpkg/register.util>
+
+ REGISTRY_UUID="..."
+ REGISTRY_DONE="yes"
+ REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
+
+=back
+
+=head1 EXAMPLES
+
+ # su - openpkg-mop
+ $ openpkg register --printstatus
+ REGISTRY_UUID="..."
+ REGISTRY_DONE="yes"
+ REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
+ $ openpkg register --printstatus >/dev/null && echo "Yup"
+ Yup
+ $ eval `openpkg register --printstatus`; echo DONE=$REGISTRY_DONE
+ DONE=yes
+ $ openpkg register --mode=wipe
+ $ openpkg register --printstatus || echo "Nope"
+ Nope
+ $ openpkg register [EMAIL PROTECTED] --mode=post
+ REGISTRY_UUID="...."
+ REGISTRY_DONE="yes"
+ REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
+ $ openpkg register --printstatus >/dev/null && echo "Yup"
+ Yup
+ $ openpkg register --rewriteurls ftp://ftp.openpkg.org/foo/bar
+ ftp://...:[EMAIL PROTECTED]/foo/bar
+
+=head1 SEE ALSO
+
+bash(1), C<openpkg man uuid>, C<http://registry.openpkg.org/>
+
+=head1 AUTHOR
+
+Thomas Lotterer E<lt>[EMAIL PROTECTED]<gt>
+
+=cut
@@ .
______________________________________________________________________
The OpenPKG Project www.openpkg.org
CVS Repository Commit List openpkg-cvs@openpkg.org
