[[vagrant-registration]] = vagrant-registration :toc: :toc-placement!:

The vagrant-registration plugin for Vagrant allows developers to easily register their guests for updates on systems with a subscription model (like Red Hat Enterprise Linux).

This plugin would run register action on vagrant up before any provisioning and unregister on vagrant halt or vagrant destroy. The actions then call the registration capabilities that have to be provided for the given OS.

''' toc::[] '''

== Installation

Install vagrant-registration as any other Vagrant plugin:

[source,shell]

$ vagrant plugin install vagrant-registration

If you are on Fedora, you can install the packaged version of the plugin by running:

[source,shell]

dnf install vagrant-registration

---

== Usage

The plugin is designed in a registration-manager agnostic way, which means, that the plugin itself, depends neither on any OS nor on the way of registration. The vagrant-registration plugin only calls registration capabilities for the given guest, passes the configuration options to them and handles interactive registration.

That being said, this plugin currently ships only with registration capability files for RHEL's Subscription Manager and rhn_register. Feel free to submit others.

To configure the plugin, always include the configuration options mentioned in this file within the following configuration block in your Vagrantfile.

.... Vagrant.configure('2') do |config| ... end ....

=== General Configuration

• skip skips the registration. If you wish to skip the registration process altogether, you can do so by setting a skip option to true:

[source,ruby]

config.registration.skip = true

• unregister_on_halt disables or enables automatic unregistration on halt (on shut down). By default the plugin unregisters on halt, you can however change that by setting the option to false so that the box will unregister only on destroy:

[source,ruby]

config.registration.unregister_on_halt = false

• manager selects the registration manager provider. By default the plugin will use the subscription_manager as the registration manager provider. You can however, change that by setting the option to a different manager:

[source,ruby]

config.registration.manager = 'subscription_manager'

=== Credential Configuration

You can set up the credentials as follows:

[source,ruby]

Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') config.registration.username = 'foo' config.registration.password = 'bar' end

Alternatively

if Vagrant.has_plugin?('vagrant-registration') config.registration.org = 'foo' config.registration.activationkey = 'bar' end ... end

This should go, preferably, into the Vagrantfile in your Vagrant home directory (defaults to ~/.vagrant.d), to make it available for every project. It can be later overridden in an individual project's Vagrantfile if needed.

If you prefer not to store your username and/or password on your filesystem, you can optionally configure vagrant-registration plugin to use environment variables such as:

[source,ruby]

Vagrant.configure('2') do |config| ... config.registration.username = ENV['SUB_USERNAME'] config.registration.password = ENV['SUB_PASSWORD'] ... end

If you do not configure your credentials as outlined above, you will receive a maximum of 3 prompts for them during the vagrant up process.

Please note that the interactive mode asks you for the preferred registration pair only for the configured manager.

=== HTTP Proxy Configuration

HTTP Proxy can be configured via the proxy, proxyUser and proxyPassword configuration options:

[source,ruby]

Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') config.registration.proxy = 'mongo:8080' config.registration.proxyUser = 'flash' config.registration.proxyPassword = 'zarkov' end ... end

As described in the link:#credentials-configuration[credentials configuration] section, these settings can be placed either into the Vagrantfile in the Vagrant home directory or provided as environment variables.

=== subscription-manager Configuration

The vagrant-registration plugin uses subscription_manager as the default manager. This can also be explicitly configured by setting the manager option to subscription_manager:

[source,ruby]

Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') config.registration.manager = 'subscription_manager' end ... end

In case you choose subscription_manager as the manager, you would be asked for your user credentials, such as the username and password.

The vagrant-registration plugin supports all the options for the subscription-manager's register command. You can set any option easily by setting config.registration.OPTION_NAME = 'OPTION_VALUE' in your Vagrantfile (please see the subscription-manager's documentation for option description).

==== subscription-manager Default Options

• --force: Subscription Manager will fail if you attempt to register an already registered machine (see the man page for explanation), therefore vagrant-registration appends the --force flag automatically when subscribing. If you would like to disable this feature, set force option to false:

[source,ruby]

config.registration.force = false

• --auto-attach: Vagrant would fail to install packages on registered RHEL system if the subscription is not attached, therefore vagrant-registration appends the --auto-attach flag automatically when subscribing. To disable this option, set auto_attach option to false:

[source,ruby]

config.registration.auto_attach = false

Note that the auto_attach option is set to false when using org/activationkey for registration or if pools are specified.

==== subscription-manager Options Reference

[source,ruby]

The username to subscribe with (required)

config.registration.username

The password of the subscriber (required)

config.registration.password

Give the hostname of the subscription service to use (required for Subscription

Asset Manager, defaults to Customer Portal Subscription Management)

config.registration.serverurl

A path to a CA certificate, this file would be copied to /etc/rhsm/ca and

if the file does not have .pem extension, it will be automatically added

config.registration.ca_cert

Give the hostname of the content delivery server to use to receive updates

(required for Satellite 6)

config.registration.baseurl

Give the organization to which to join the system (required, except for

hosted environments)

config.registration.org

Register the system to an environment within an organization (optional)

config.registration.environment

Name of the subscribed system (optional, defaults to hostname if unset)

config.registration.name

Auto attach suitable subscriptions (optional, auto attach if true,

defaults to true)

config.registration.auto_attach

Attach existing subscriptions as part of the registration process (optional)

config.registration.activationkey

Set the service level to use for subscriptions on that machine

(optional, used only used with the --auto-attach)

config.registration.servicelevel

Set the operating system minor release to use for subscriptions for

the system (optional, used only used with the --auto-attach)

config.registration.release

Force the registration (optional, force if true, defaults to true)

config.registration.force

Set what type of consumer is being registered (optional, defaults to system)

config.registration.type

Skip the registration (optional, skip if true, defaults to false)

config.registration.skip

Specify a HTTP proxy to use. This config option if of the format [|:], eg mongo:8080

config.registration.proxy

Specify a username to use with an authenticated HTTP proxy

config.registration.proxyUser

Specify a password to use with an authenticated HTTP proxy

config.registration.proxyPassword

Attach to specified pool(s) (optional)

#

Example:

config.registration.pools = [ 'POOL-ID-1', 'POOL-ID-2' ]

config.registration.pools

=== rhn-register Configuration

vagrant-registration will use the rhn_register manager only if explicitly configured by setting the manager option to rhn_register:

[source,ruby]

Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') config.registration.manager = 'rhn_register' end ... end

In case of a rhn_register manager, the preferred registration pair is the username/password/serverurl combination.

vagrant-registration supports most of the options of rhnreg_ks's command. You can set any option easily by setting config.registration.OPTION_NAME = 'OPTION_VALUE' in your Vagrantfile (please see the rhnreg_ks's documentation for option description).

rhn_register manager reuses the naming of subscription-manager's command options where possible.

==== rhn-register Default Options

• --force: rhnreg_ks command will fail if you attempt to register an already registered machine (see the man page for explanation), therefore vagrant-registration appends the --force flag automatically when subscribing. If you would like to disable this feature, set force option to false:

[source,ruby]

config.registration.force = false

==== rhn-register Options Reference

[source,ruby]

The username to register the system with under Spacewalk Server, Red Hat Satellite or

Red Hat Network Classic. This can be an existing Spacewalk, Red Hat Satellite or

Red Hat Network Classic username, or a new user‐name.

config.registration.username

The password associated with the username specified with the --username option.

This is an unencrypted password.

config.registration.password

Give the URL of the subscription service to use (required for registering a

system with the "Spacewalk Server", "Red Hat Satellite" or "Red Hat Network Classic").

The configuration name is mapped to the --serverUrl option of rhnreg_ks command.

#

The serverurl is mandatory and if you do not provide a value,

you will be prompted for them in the "up process."

config.registration.serverurl

A path to a CA certificate file (optional)

The configuration name is mapped to the --sslCACert option of rhnreg_ks command.

#

The CA certificate file is be uploaded to /usr/share/rhn/ in guest

and the configuration in /etc/sysconfig/rhn/up2date is updated to:

sslCACert=/usr/share/rhn/<ca_file_name>

#

As default only the configuration in /etc/sysconfig/rhn/up2date is updated

to point to the CA certificate file that is present on Fedora, CentOS and RHEL:

sslCACert=/usr/share/rhn/RHNS-CA-CERT

config.registration.ca_cert

Give the organization to which to join the system (required, except for

hosted environments)

The configuration name is mapped to the --systemorgid option of rhnreg_ks command.

config.registration.org

Name of the subscribed system (optional, defaults to hostname if unset)

The configuration name is mapped to the --profilename option of rhnreg_ks command.

config.registration.name

Attach existing subscriptions as part of the registration process (optional)

config.registration.activationkey

Subscribe this system to the EUS channel tied to the system's redhat-release (optional)

config.registration.use_eus_channel

Do not probe or upload any hardware info (optional)

config.registration.nohardware

Do not profile or upload any package info (optional)

config.registration.nopackages

Do not upload any virtualization info (optional)

config.registration.novirtinfo

Do not start rhnsd after completion (optional)

config.registration.norhnsd

Force the registration (optional, force if true, defaults to true)

config.registration.force

Skip the registration (optional, skip if true, defaults to false)

config.registration.skip

Specify a HTTP proxy to use. This config option if of the format [|:], eg mongo:8080

config.registration.proxy

Specify a username to use with an authenticated HTTP proxy

config.registration.proxyUser

Specify a password to use with an authenticated HTTP proxy

config.registration.proxyPassword

== Development

The use of https://rvm.io[RVM] is recommended. Verified to work with ruby-2.2.10.

.... rvm install 2.2 rvm use 2.2 ....

To install a development environment, clone the repo and prepare dependencies by:

.... gem install bundler bundle install ....

=== Tests

==== Minitest

The source contains a set of http://ruby-doc.org/stdlib-2.0.0/libdoc/minitest/rdoc/MiniTest.html[Minitest] based unit tests. They can be run via:

.... $ bundle exec rake test ....

==== Acceptance tests

The source also contains a set of https://cucumber.io/[Cucumber] based acceptance tests. They can be run via:

.... $ bundle exec rake features ....

The tests assume that the CDK box files are available under build/boxes/cdk-.box. You can either copy the box files manually or use the _getcdk rake task to download them.

As per default, only the scenarios for CDK in combination with VirtualBox are run. You can also run the tests against Libvirt, using the environment variable PROVIDER:

....

Run tests against Libvirt

$ bundle exec rake features PROVIDER=libvirt

Run against VirtualBox and Libvirt

$ bundle exec rake features PROVIDER=virtualbox,libvirt ....

You can also run a single feature specifying the explicit feature file to use:

.... $ bundle exec rake features FEATURE=features/.feature ....

After test execution the acceptance test reports can be found under __build/features_report.html__. They can also be opened via:

.... $ bundle exec rake features:open_report ....

== Releasing

To release a new version of vagrant-registration you will need to do the following:

(only contributors of the GitHub repo and owners of the project at RubyGems will have rights to do this)

1. First, bump, commit, and push the version in ~/lib/vagrant-registration/version.rb:
   • Follow Semantic Versioning.
2. Then, create a matching GitHub Release (this will also create a tag):
   • Preface the version number with a v.
   • https://github.com/projectatomic/adb-vagrant-registration/releases
3. You will then need to build and push the new gem to RubyGems:
   • rake build
   • gem push pkg/vagrant-registration-1.3.2.gem
4. Then, when John Doe runs the following, they will receive the updated vagrant-registration plugin:
   • vagrant plugin update
   • vagrant plugin update vagrant-registration

== Acknowledgements

The project would like to make sure we thank https://github.com/purpleidea/[purpleidea], https://github.com/humaton/[humaton], https://github.com/strzibny[strzibny], https://github.com/scollier/[scollier], https://github.com/puzzle[puzzle], https://github.com/voxik[voxik], https://github.com/lukaszachy[lukaszachy], https://github.com/goern[goern], https://github.com/iconoeugen[iconoeugen] and https://github.com/pvalena[pvalena] (in no particular order) for their contributions of ideas, code and testing for this project.