OpenPKG Specs / file revision

 =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