diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..264ea8d --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,78 @@ += Revision History +:toc: + +[[section]] +== 1.3.0 + +* Fixed formatting, typo, grammar in README +* Added MAINTAINERS file +* Fix #44 allow more than one try to fill username and password +* Fixes #99 using proxy info to unregister +* Fix #107 register when passing credentials as env variables + +[[section-1]] +== 1.2.3 + +* Issue #90 Use locale based messaging +* Issue #65 Adding cucumber tests for proxy settings +* Issue #65 Adding proxy options to rhn_register and +subscription_manager +* Adding minitest as unit test framework and setting up basic test +harness for Vagrant plugins +* Issue #65 Removing obsolete bash tests + +[[section-2]] +== 1.2.2 + +* Introducing Cucumber based acceptance tests. +* Fix: Handling of vagrant-registration action hooks depending on +provider used. + +[[section-3]] +== 1.2.1 + +* Fix regression: Use sudo when asking on registration managers being +present + +[[section-4]] +== 1.2.0 + +* Fix: `vagrant destroy` not triggering subscription deactivation and +removal, issue #57 +* Fix: Allow auto-attach and force options to be configured +* Fix: Remove unnecessary shebang from python script +* Support for attaching to specified subscription pool(s), issue #36 +* Fix: rhn_register upload certificate fails, issue #60 + +[[section-5]] +== 1.1.0 + +* Print warning if specifically selected manager is not available +* Support running alongside vagrant-vbguest, issue #40 +* Support rhn_register manager +* Fix: Handle various types of configuration option values, issue #48 +* Fix: Hide password on registration failure, issue #47 + +[[section-6]] +== 1.0.1 + +* Fix: Set repo_ca_cert option in /etc/rhsm/rhsm.conf after uploading a +certificate + +[[section-7]] +== 1.0.0 + +* Support providing a CA certificate via `config.registration.ca_cert` +option +* Issue warnings on unsupported configuration options +* Do not ship tests + +[[section-8]] +== 0.0.19 + +* Remove extra files from installation + +[[section-9]] +== 0.0.18 + +* Support `config.registration.unregister_on_halt` option diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index f78f6b7..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,60 +0,0 @@ -# Changelog - -## 1.3.0 - -- Fixed formatting, typo, grammar in README -- Added MAINTAINERS file -- Fix #44 allow more than one try to fill username and password -- Fixes #99 using proxy info to unregister -- Fix #107 register when passing credentials as env variables - -## 1.2.3 - -- Issue #90 Use locale based messaging -- Issue #65 Adding cucumber tests for proxy settings -- Issue #65 Adding proxy options to rhn_register and subscription_manager -- Adding minitest as unit test framework and setting up basic test harness for Vagrant plugins -- Issue #65 Removing obsolete bash tests - -## 1.2.2 - -- Introducing Cucumber based acceptance tests. -- Fix: Handling of vagrant-registration action hooks depending on provider used. - -## 1.2.1 - -- Fix regression: Use sudo when asking on registration managers being present - -## 1.2.0 - -- Fix: `vagrant destroy` not triggering subscription deactivation and removal, issue #57 -- Fix: Allow auto-attach and force options to be configured -- Fix: Remove unnecessary shebang from python script -- Support for attaching to specified subscription pool(s), issue #36 -- Fix: rhn_register upload certificate fails, issue #60 - -## 1.1.0 - -- Print warning if specifically selected manager is not available -- Support running alongside vagrant-vbguest, issue #40 -- Support rhn_register manager -- Fix: Handle various types of configuration option values, issue #48 -- Fix: Hide password on registration failure, issue #47 - -## 1.0.1 - -- Fix: Set repo_ca_cert option in /etc/rhsm/rhsm.conf after uploading a certificate - -## 1.0.0 - -- Support providing a CA certificate via `config.registration.ca_cert` option -- Issue warnings on unsupported configuration options -- Do not ship tests - -## 0.0.19 - -- Remove extra files from installation - -## 0.0.18 - -- Support `config.registration.unregister_on_halt` option diff --git a/LICENSE.md b/LICENSE similarity index 100% rename from LICENSE.md rename to LICENSE diff --git a/README.md b/README.adoc similarity index 52% rename from README.md rename to README.adoc index e1a5605..f5dbefa 100644 --- a/README.md +++ b/README.adoc @@ -1,87 +1,96 @@ -# vagrant-registration +[[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). -- [Installation](#installation) -- [Usage](#usage) - - [General Configuration](#general-configuration) - - [Credential Configuration](#credential-configuration) - - [HTTP Proxy Configuration](#http-proxy-configuration) - - [subscription-manager Configuration](#subscription-manager-configuration) - - [subscription-manager Default Options](#subscription-manager-default-options) - - [subscription-manager Options Reference](#subscription-manager-options-reference) - - [rhn-register Configuration](#rhn-register-configuration) - - [rhn-register Default Options](#rhn-register-default-options) - - [rhn-register Options Reference](#rhn-register-options-reference) -- [Development](#development) - - [Tests](#tests) - - [Minitest](#minitest) - - [Acceptance tests](#acceptance-tests) -- [Acknowledgements](#acknowledgements) +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::[] +''' -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. - - -## Installation +== Installation Install vagrant-registration as any other Vagrant plugin: -```shell +[source,shell] +---- $ vagrant plugin install vagrant-registration -``` +---- -If you are on Fedora, you can install the packaged version of the plugin by running: +If you are on Fedora, you can install the packaged version of the plugin +by running: -```shell +[source,shell] +---- # dnf install vagrant-registration -``` +---- - -## Usage +== 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. +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. +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. +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 +=== 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`: +* *skip* skips the registration. If you wish to skip the registration +process altogether, you can do so by setting a `skip` option to `true`: -```ruby +[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: +* *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: -```ruby +[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: +* *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: -```ruby +[source,ruby] +---- config.registration.manager = 'subscription_manager' -``` +---- - -### Credential Configuration +=== Credential Configuration You can set up the credentials as follows: -```ruby +[source,ruby] +---- Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') @@ -96,35 +105,40 @@ Vagrant.configure('2') do |config| 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. +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: +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: -```ruby +[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. +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. +Please note that the interactive mode asks you for the preferred +registration pair only for the configured manager. - -### HTTP Proxy Configuration +=== HTTP Proxy Configuration -HTTP Proxy can be configured via the _proxy_, _proxyUser_ and _proxyPassword_ configuration options: +HTTP Proxy can be configured via the __proxy__, _proxyUser_ and +_proxyPassword_ configuration options: -```ruby +[source,ruby] +---- Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') @@ -134,18 +148,21 @@ Vagrant.configure('2') do |config| end ... end -``` +---- -As described in the [credentials configuration](#credentials-configuration) section, these settings -can be placed either into the Vagrantfile in the Vagrant home directory or provided as -environment variables. +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 +=== 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`: +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`: -```ruby +[source,ruby] +---- Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') @@ -153,38 +170,48 @@ Vagrant.configure('2') do |config| 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. +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). +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 +==== 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`: +* **--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`: -```ruby +[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`: +* **--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`: -```ruby +[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. +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 +==== subscription-manager Options Reference -```ruby +[source,ruby] +---- # The username to subscribe with (required) config.registration.username @@ -251,14 +278,15 @@ or if pools are specified. # Example: # config.registration.pools = [ 'POOL-ID-1', 'POOL-ID-2' ] config.registration.pools -``` +---- - -### rhn-register Configuration +=== rhn-register Configuration -vagrant-registration will use the `rhn_register` manager only if explicitly configured by setting the `manager` option to `rhn_register`: +vagrant-registration will use the `rhn_register` manager only if +explicitly configured by setting the `manager` option to `rhn_register`: -```ruby +[source,ruby] +---- Vagrant.configure('2') do |config| ... if Vagrant.has_plugin?('vagrant-registration') @@ -266,27 +294,36 @@ Vagrant.configure('2') do |config| end ... end -``` +---- -In case of a `rhn_register` manager, the preferred registration pair is the username/password/serverurl combination. +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). +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` manager reuses the naming of `subscription-manager`'s +command options where possible. - -#### rhn-register Default Options +==== 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`: +* **--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`: -```ruby +[source,ruby] +---- config.registration.force = false -``` +---- - -#### rhn-register Options Reference +==== rhn-register Options Reference -```ruby +[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. @@ -357,61 +394,82 @@ vagrant-registration supports most of the options of rhnreg_ks's command. You ca # Specify a password to use with an authenticated HTTP proxy config.registration.proxyPassword -``` +---- - -## Development +== Development -To install a development environment, clone the repo and prepare dependencies by: +To install a development environment, clone the repo and prepare +dependencies by: -``` +.... gem install bundler bundler install -``` +.... -The use of [RVM](https://rvm.io) is recommended. Verified to work with ruby 2.0.0p643. +The use of https://rvm.io[RVM] is recommended. Verified to work with +ruby 2.0.0p643. - -### Tests +=== Tests - -#### Minitest +==== Minitest -The source contains a set of [Minitest](http://ruby-doc.org/stdlib-2.0.0/libdoc/minitest/rdoc/MiniTest.html) +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 +.... +$ bundle exec rake test +.... - -#### Acceptance tests +==== Acceptance tests -The source also contains a set of [Cucumber](https://cucumber.io/) based acceptance tests. They can be run via: +The source also contains a set of https://cucumber.io/[Cucumber] based +acceptance tests. They can be run via: - $ bundle exec rake features +.... +$ 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 _get_cdk_ 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 - - -## Acknowledgements - -The project would like to make sure we thank [purpleidea](https://github.com/purpleidea/), [humaton](https://github.com/humaton/), [strzibny](https://github.com/strzibny), [scollier](https://github.com/scollier/), [puzzle](https://github.com/puzzle), [voxik](https://github.com/voxik), [lukaszachy](https://github.com/lukaszachy), [goern](https://github.com/goern), [iconoeugen](https://github.com/iconoeugen) and [pvalena](https://github.com/pvalena) (in no particular order) for their contributions of ideas, code and testing for this project. +__build/boxes/cdk-.box__. You can either copy the box files +manually or use the _get_cdk_ 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 +.... + +== 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.