michael@428: 
michael@428: =pod
michael@428: 
michael@428: =head1 NAME
michael@428: 
michael@428: B<openpkg register> - OpenPKG Registry Command-Line Client
michael@428: 
michael@428: =head1 SYNOPSIS
michael@428: 
michael@428: B<register> [-u|--user=<user|token>] [-l|--link=<token>] [I<-d|--desc=<text>>]
michael@428:           [-m|--mode=fake|post|wipe] [I<-a|--args=<args>>]
michael@428:           [I<--plat=<text>>] [I<--orel=<text>>] [I<--uuid=<file>>]
michael@428:           [I<--conf=<file>>] [I<--prep=<file>>] [I<--tran=<file>>]
michael@428:           [I<--util=<file>>] [--data=<tag>[,<tag>...]]
michael@428:           [I<-P|--preparation>] [I<-T|--transaction>]
michael@428:           [I<-U|--utilization>] [I<-C|--convenience>]
michael@428:           [I<-I|--interaction>]
michael@428:           [I<-v|--verbose>] [I<-h|--help>]
michael@428: 
michael@428: B<register> -S|--printstatus
michael@428: 
michael@428: B<register> -R|--rewriteurls [I<url> ...]
michael@428: 
michael@428: =head1 DESCRIPTION
michael@428: 
michael@428: B<openpkg register> is the Command-Line Client the OpenPKG Registry. It is
michael@428: used by administrators to register an instance with the OpenPKG Registry for
michael@428: later association.
michael@428: 
michael@428: After association, B<openpkg register> can be used for repetitive
michael@428: reregistrations which update the heartbeat of the instance on the Registry
michael@428: server, avoiding premature depature from the database. It is assumed that
michael@428: every instance will be reregistered daily. Dormant
michael@428: instances might be discarded from the Registry, revoking their access to
michael@428: additional resources.
michael@428: 
michael@428: =head1 PRIMARY OPERATIONS
michael@428: 
michael@428: The following primary operations are available:
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item B<-h>, B<--help>
michael@428: 
michael@428: Display brief usage message.
michael@428: 
michael@428: =item B<-v>, B<--verbose>
michael@428: 
michael@428: Display progress information during data posting.
michael@428: 
michael@428: =item B<-P>, B<--preparation>
michael@428: 
michael@428: Execute the primary operation "preparation".
michael@428: Creates registry data for one request and dumps it stdout
michael@428: in XML format. That request can be filtered and piped into
michael@428: the transaction phase or it can be copied and pasted into the
michael@428: XMLdump CGI facility manually.
michael@428: A copy of the output of the last run is also saved to the C<${REGISTRY_PREP}> file.
michael@428: 
michael@428: =item B<-T>, B<--transaction>
michael@428: 
michael@428: Execute the primary operation "transaction".
michael@428: Reads registry data with one request from stdin, executes
michael@428: the transaction and writes registry data with one or more
michael@428: responses to stdout in XML format.
michael@428: Depending on the mode of operation, the transaction might be an actual
michael@428: transport to the XMLdump CGI facility or a fake activity which complements the
michael@428: manual preparation.
michael@428: A copy of the output of the last run is also saved to the C<${REGISTRY_TRAN}> file.
michael@428: 
michael@428: =item B<-U>, B<--utilization>
michael@428: 
michael@428: Execute the primary operation "utilization".
michael@428: Reads registry data with one response from stdin and updates the local
michael@428: registry information.
michael@428: Depending on the mode of operation, the utilization might be an actual
michael@428: processing of a transaction response or a fake activity which complements the
michael@428: manual transaction.
michael@428: Anyway, this step finalizes the registration process and makes the instance
michael@428: assume it has been properly registered. This status can be printed. URL
michael@428: rewriting is activated.
michael@428: A copy of the output of the last run is also saved to the C<${REGISTRY_UTIL}> file.
michael@428: 
michael@428: =item B<-C>, B<--convenience>
michael@428: 
michael@428: Execute the primary operation "convenience".
michael@428: This executes the three primary operations "preparation", "transaction" and
michael@428: "utilization" in that order and pipes data through this chain.
michael@428: 
michael@428: =item B<-I>, B<--interaction>
michael@428: 
michael@428: Execute the primary operation "interaction".
michael@428: Like "convenience" but user is interactively asked for information. This is
michael@428: the easiest way to do registration but it is not meat to be automated.
michael@428: 
michael@428: =item B<-S>, B<--printstatus>
michael@428: 
michael@428: If the instance has been registered, information about the registration is printed in a
michael@428: format suitable for shell evaluation and return code is true.
michael@428: Otherwise nothing is printed and return code is false.
michael@428: 
michael@428: =item B<-R>, B<--rewriteurls> [I<url> ...]
michael@428: 
michael@428: If the instance has been registered, the given URLs are rewritten to prepend
michael@428: user:pass information before hostnames below the openpkg.(org|net|com)
michael@428: domains.  Note the username is is UUID_REGISTRY and the password is the
michael@428: concatenation of UUID_INSTANCE and UUID_PLATFORM from the
michael@428: PREFIX/etc/openpkg/uuid file. Both informations are not meant to be used for
michael@428: traditional authentication, they are merly statistical information.
michael@428: Otherwise the URLs are returned verbatim.
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 STANDARD OPTIONS
michael@428: 
michael@428: Standard options are typically used to automate registration (not
michael@428: association).
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item B<-m>, B<--mode> fake|post|wipe
michael@428: 
michael@428: Overrides C<${REGISTRY_MODE}> variable in C<${REGISTRY_CONF}> file.
michael@428: Has no default and is a manadatory setting.
michael@428: 
michael@428: In B<post> mode, transactions are carried out using real network connectivity.
michael@428: The "preparation" step creates a XMLdump and writes it into the
michael@428: C<${REGISTRY_PREP}> file. The "transaction" step posts it to the DropXML form
michael@428: using a HTTP request. The response coming back from Registration server is
michael@428: also in XML format and is saved to  C<${REGISTRY_TRAN}> file.  The
michael@428: "utilization" step processes this response and writes the final results to the
michael@428: C<${REGISTRY_UTIL}> file.
michael@428: 
michael@428: In B<fake> mode, no network connectivity takes place.
michael@428: The "prepararation" step creates a XMLdump and writes it into the
michael@428: C<${REGISTRY_PREP}> file. The "transaction" step is a fake only. It assumes a
michael@428: successful response from the Registration server and saves it to
michael@428: C<${REGISTRY_TRAN}> file.  The "utilization" step processes this response and
michael@428: writes the final results to the C<${REGISTRY_UTIL}> file.
michael@428: I<Note>: fake mode is meant as a way to register instances which cannot or must
michael@428: not post data directly to the Registration server.
michael@428: 
michael@428: In B<wipe> mode, the registration is wiped out locally. The status is reset
michael@428: and URL rewriting is disabled.
michael@428: I<Note>: the registration server is not contacted, the instace must be removed
michael@428: manually using the web interface.
michael@428: I<Note>: wiping registration is highly recommended as a precursor action of
michael@428: cloning activities.
michael@428: 
michael@428: =item B<-a>, B<--args> "arg [arg ...]"
michael@428: 
michael@428: Overrides C<${REGISTRY_ARGS}> variable in C<${REGISTRY_CONF}> file.
michael@428: Complements the mode and is specific to it.
michael@428: Defaults to "http://registry.openpkg.org/register" which is the official registry of the OpenPKG Project.
michael@428: This default is useful for "post" mode.
michael@428: 
michael@428: =item B<-u>, B<--user> I<user|token>
michael@428: 
michael@428: Overrides C<${REGISTRY_USER}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates the registry user which will find this registration in his arrival queue.
michael@428: The user can also specified as a token which is enabled for use as "user".
michael@428: If the token is also enabled for "assoc" the registered instance is immediately associated
michael@428: to the user with no need for the user to visit the web interface.
michael@428: This information in submitted via the "registry_user" attribute of the XML request.
michael@428: Retrieves default online from http://openpkg.org/go/autoregister and is a manadatory setting.
michael@428: 
michael@428: =item B<-l>, B<--link> I<token>
michael@428: 
michael@428: Overrides C<${REGISTRY_LINK}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates the registry user which will find this registration linked to his token.
michael@428: The link must be specified as a token which is enabled for use as "link".
michael@428: If a user token is used and the link token is also enabled for "assoc" then the registered instance
michael@428: is immediately associated to the user with no need for the user to visit the web interface.
michael@428: This information in submitted via the "registry_link" attribute of the XML request.
michael@428: Has no default and is an optional setting.
michael@428: Be aware that linked users see the same information about an instance as the associated user
michael@428: can find on his "association" page but they cannot alter or delete information.
michael@428: 
michael@428: =item B<-d>, B<--desc> I<description>
michael@428: 
michael@428: Overrides C<${REGISTRY_DESC}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates a human readable description of the instance.
michael@428: This information in submitted via the "registry_desc" attribute of the XML request.
michael@428: It appears in the "description" column on the "association" page of the web form and can be edited on the server side.
michael@428: Defaults to "openpkg://${FQDN}${PREFIX}"
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 ADVANCED OPTIONS
michael@428: 
michael@428: Advanced options can be enganged to tailor and fully automate a registration
michael@428: (not association).
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item B<--plat>
michael@428: 
michael@428: Overrides C<${REGISTRY_PLAT}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates the platform. Concatenated information from CPU architecture (arch) and Operating System (os).
michael@428: This information in submitted via the "registry_plat" attribute of the XML request.
michael@428: Defaults to "%{l_platform -p}", e.g. "ix86-freebsd6.1"
michael@428: 
michael@428: =item B<--orel>
michael@428: 
michael@428: Overrides C<${REGISTRY_VERS}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates the OpenPKG release.
michael@428: This information in submitted via the "registry_orel" attribute of the XML request.
michael@428: Defaults to "%{l_openpkg_release}", e.g. "OpenPKG-CURRENT", "OpenPKG-2-STABLE", "OpenPKG-2.5",
michael@428: 
michael@428: =item B<--uuid>
michael@428: 
michael@428: Overrides C<${REGISTRY_UUID}> variable in C<${REGISTRY_CONF}> file.
michael@428: Indicates the UUID file of the instance.
michael@428: This information in submitted via the "uuid_registry", "uuid_instance" and "uuid_platform" attributes of the XML request.
michael@428: Defaults to F<${PREFIX}/etc/openpkg/uuid>
michael@428: 
michael@428: =item B<--conf>
michael@428: 
michael@428: Overrides C<${REGISTRY_CONF}> variable from previous C<${REGISTRY_CONF}> file. Processing
michael@428: of the current configuration file is aborted immediately with all variables
michael@428: read so far kept. THe new configuration file is read in immediately and
michael@428: processing continues there. This works similar to an include but is more
michael@428: primitive as it does not allow nesting, only chaining.
michael@428: Defaults to F<${PREFIX}/etc/openpkg/register.conf>
michael@428: 
michael@428: =item B<--prep>
michael@428: 
michael@428: Overrides C<${REGISTRY_PREP}> variable in C<${REGISTRY_CONF}> file.
michael@428: File to save a copy of the output from the "preparation" step.
michael@428: Defaults to F<${PREFIX}/etc/openpkg/register.prep>
michael@428: 
michael@428: =item B<--tran>
michael@428: 
michael@428: Overrides C<${REGISTRY_TRAN}> variable in C<${REGISTRY_CONF}> file.
michael@428: File to save a copy of the output from the "transaction" step.
michael@428: Defaults to F<${PREFIX}/etc/openpkg/register.tran>
michael@428: 
michael@428: =item B<--util>
michael@428: 
michael@428: Overrides C<${REGISTRY_UTIL}> variable in C<${REGISTRY_CONF}> file.
michael@428: File to save a copy of the output from the "utilization" step.
michael@428: Defaults to F<${PREFIX}/etc/openpkg/register.util>
michael@428: 
michael@428: =item B<--data>
michael@428: 
michael@428: Overrides C<${REGISTRY_DATA}> variable in C<${REGISTRY_CONF}> file.
michael@428: Comma separated list of tags to prepare. Available tags are "request",
michael@428: "package" and "provides". The "request" refers to the whole thing and
michael@428: is mandatory. The "package" includes name-version-release information
michael@428: for all installed packages and "provides" adds more details required to
michael@428: capture package options. For details see OPENPKG_PREP below.
michael@428: Defaults to "request,package,provides"
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 FILES
michael@428: 
michael@428: The following files are used by B<openpkg register>:
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item OPENPKG_UUID=F<${PREFIX}/etc/openpkg/uuid>
michael@428: 
michael@428:  UUID_REGISTRY="..."
michael@428:  UUID_INSTANCE="..."
michael@428:  UUID_PLATFORM="..."
michael@428: 
michael@428: =item OPENPKG_CONF=F<${PREFIX}/etc/openpkg/register.conf>
michael@428: 
michael@428: Format suitable for shell evaluation. Interactive mode appends remarked date
michael@428: and current settings for reuse as new defaults for future runs. Can be preset
michael@428: to customize or automate registration.
michael@428: 
michael@428: =item OPENPKG_PREP=F<${PREFIX}/etc/openpkg/register.prep>
michael@428: 
michael@428:  <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
michael@428:  <!DOCTYPE registry
michael@428:    PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
michael@428:    "http://registry.openpkg.org/registry.dtd" []>
michael@428:  <registry>
michael@428:      <request id="..."
michael@428:          registry_user="me@example.com"
michael@428:          registry_desc="openpkg://rm0.openpkg.net/openpkg-dev"
michael@428:          registry_plat="ix86-freebsd6.1"
michael@428:          registry_orel="OpenPKG-CURRENT"
michael@428:          uuid_registry="..."
michael@428:          uuid_instance="..."
michael@428:          uuid_platform="..."
michael@428:      />
michael@428:      <package id="..." name="ssmtp" version="2.61" release="20050608">
michael@428:         <provides name="ssmtp::with_ssl" flag="=" version="no"/>
michael@428:         <provides name="MTA" flag="" version=""/>
michael@428:         <provides name="ssmtp" flag="=" version="2.61-20050608"/>
michael@428:      </package>
michael@428:  </registry>
michael@428: 
michael@428: The XML request starts with <?xml version ...> and <!DOCTYPE registry ...>
michael@428: headers followed by a <registry> container. The request is inside a <request>
michael@428: tag. Successful submission into the XMLdump form requires the headers and
michael@428: exactly one container. It is possible to merge multiple requests into a single
michael@428: container manually or otherwise and submit them all at once.
michael@428: 
michael@428: =item OPENPKG_TRAN=F<${PREFIX}/etc/openpkg/register.tran>
michael@428: 
michael@428:  <?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
michael@428:  <!DOCTYPE registry
michael@428:    PUBLIC "-//OpenPKG//DTD OpenPKG Registry 0.0.1//EN"
michael@428:    "http://registry.openpkg.org/registry.dtd" []>
michael@428:  <registry>
michael@428:      <response id="..." done="yes">openpkg://rm0.openpkg.net/openpkg-dev</response>
michael@428:  </registry>
michael@428: 
michael@428: The XML response starts with <?xml version ...> and <!DOCTYPE registry ...>
michael@428: headers followed by a <registry> container. The response is inside a <request>
michael@428: tag. The data carried in the tag comes from the "description" column on the
michael@428: "association" page of the web form and can be edited on the server side.
michael@428: 
michael@428: =item OPENPKG_UTIL=F<${PREFIX}/etc/openpkg/register.util>
michael@428: 
michael@428:  REGISTRY_DBID="..."
michael@428:  REGISTRY_DONE="yes"
michael@428:  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 EXAMPLES
michael@428: 
michael@428:  # su - openpkg-mop
michael@428:  $ openpkg register --printstatus
michael@428:  REGISTRY_DBID="..."
michael@428:  REGISTRY_DONE="yes"
michael@428:  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
michael@428:  $ openpkg register --printstatus >/dev/null && echo "Yup"
michael@428:  Yup
michael@428:  $ eval `openpkg register --printstatus`; echo DONE=$REGISTRY_DONE
michael@428:  DONE=yes
michael@428:  $ openpkg register --mode=wipe
michael@428:  $ openpkg register --printstatus || echo "Nope"
michael@428:  Nope
michael@428:  $ openpkg register --user=thl@openpkg.net --mode=post
michael@428:  REGISTRY_DBID="...."
michael@428:  REGISTRY_DONE="yes"
michael@428:  REGISTRY_RESP="openpkg://foo.example.com/my/openpkg/prefix"
michael@428:  $ openpkg register --printstatus >/dev/null && echo "Yup"
michael@428:  Yup
michael@428:  $ openpkg register --rewriteurls http://download.openpkg.org/foo/bar
michael@428:  ftp://...:...@download.openpkg.org/foo/bar
michael@428: 
michael@428: =head1 SEE ALSO
michael@428: 
michael@428: bash(1), C<openpkg man uuid>, C<http://registry.openpkg.org/>
michael@428: 
michael@428: =head1 AUTHOR
michael@428: 
michael@428: Thomas Lotterer E<lt>thl@openpkg.orgE<gt>
michael@428: 
michael@428: =cut
michael@428: