diff -r 71503088f51b -r f880f219c566 openpkg/register.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/register.pod	Tue Jul 31 12:23:42 2012 +0200
@@ -0,0 +1,358 @@
+
+=pod
+
+=head1 NAME
+
+B<openpkg register> - OpenPKG Registry Command-Line Client
+
+=head1 SYNOPSIS
+
+B<register> [-u|--user=<user|token>] [-l|--link=<token>] [I<-d|--desc=<text>>]
+          [-m|--mode=fake|post|wipe] [I<-a|--args=<args>>]
+          [I<--plat=<text>>] [I<--orel=<text>>] [I<--uuid=<file>>]
+          [I<--conf=<file>>] [I<--prep=<file>>] [I<--tran=<file>>]
+          [I<--util=<file>>] [--data=<tag>[,<tag>...]]
+          [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.
+
+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 daily. 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<-v>, B<--verbose>
+
+Display progress information during data posting.
+
+=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|token>
+
+Overrides C<${REGISTRY_USER}> variable in C<${REGISTRY_CONF}> file.
+Indicates the registry user which will find this registration in his arrival queue.
+The user can also specified as a token which is enabled for use as "user".
+If the token is also enabled for "assoc" the registered instance is immediately associated
+to the user with no need for the user to visit the web interface.
+This information in submitted via the "registry_user" attribute of the XML request.
+Retrieves default online from http://openpkg.org/go/autoregister and is a manadatory setting.
+
+=item B<-l>, B<--link> I<token>
+
+Overrides C<${REGISTRY_LINK}> variable in C<${REGISTRY_CONF}> file.
+Indicates the registry user which will find this registration linked to his token.
+The link must be specified as a token which is enabled for use as "link".
+If a user token is used and the link token is also enabled for "assoc" then the registered instance
+is immediately associated to the user with no need for the user to visit the web interface.
+This information in submitted via the "registry_link" attribute of the XML request.
+Has no default and is an optional setting.
+Be aware that linked users see the same information about an instance as the associated user
+can find on his "association" page but they cannot alter or delete information.
+
+=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://${FQDN}${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>
+
+=item B<--data>
+
+Overrides C<${REGISTRY_DATA}> variable in C<${REGISTRY_CONF}> file.
+Comma separated list of tags to prepare. Available tags are "request",
+"package" and "provides". The "request" refers to the whole thing and
+is mandatory. The "package" includes name-version-release information
+for all installed packages and "provides" adds more details required to
+capture package options. For details see OPENPKG_PREP below.
+Defaults to "request,package,provides"
+
+=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="me@example.com"
+         registry_desc="openpkg://rm0.openpkg.net/openpkg-dev"
+         registry_plat="ix86-freebsd6.1"
+         registry_orel="OpenPKG-CURRENT"
+         uuid_registry="..."
+         uuid_instance="..."
+         uuid_platform="..."
+     />
+     <package id="..." name="ssmtp" version="2.61" release="20050608">
+        <provides name="ssmtp::with_ssl" flag="=" version="no"/>
+        <provides name="MTA" flag="" version=""/>
+        <provides name="ssmtp" flag="=" version="2.61-20050608"/>
+     </package>
+ </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_DBID="..."
+ REGISTRY_DONE="yes"
+ REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
+
+=back
+
+=head1 EXAMPLES
+
+ # su - openpkg-mop
+ $ openpkg register --printstatus
+ REGISTRY_DBID="..."
+ 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 --user=thl@openpkg.net --mode=post
+ REGISTRY_DBID="...."
+ REGISTRY_DONE="yes"
+ REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
+ $ openpkg register --printstatus >/dev/null && echo "Yup"
+ Yup
+ $ openpkg register --rewriteurls http://download.openpkg.org/foo/bar
+ ftp://...:...@download.openpkg.org/foo/bar
+
+=head1 SEE ALSO
+
+bash(1), C<openpkg man uuid>, C<http://registry.openpkg.org/>
+
+=head1 AUTHOR
+
+Thomas Lotterer E<lt>thl@openpkg.orgE<gt>
+
+=cut
+