Forge Home


Package provider for Gentoo that supports use flags, keywords and slots


6,473 latest version

3.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.1.1 (latest)
  • 2.1.0 (deleted)
  • 2.0.3
  • 2.0.2
  • 2.0.1
  • 1.0.1 (deleted)
  • 1.0.0 (deleted)
released May 20th 2016
This version is compatible with:
  • Puppet 3.5.x
  • Gentoo

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'Whatbox-portagegt', '2.1.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add Whatbox-portagegt
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install Whatbox-portagegt --version 2.1.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



Whatbox/portagegt — version 2.1.1 May 20th 2016


Build Status


PortageGT (short for "Portage using Gentoo") is a replacement Package Provider for Puppet. It was written by Whatbox Inc. to improve server management, and released as on Open Source project under the Apache 2 license. Patches and bug reports are welcome, please see our CLA.

I will also warn you that this module is not completely compatible with the existing Portage Provider. Rather than making assumptions, this provider will throw errors in the event of ambiguity, preferring developer clarification over the possibility of performing an unintended action.


The following packages are necessary for this module.

  • dev-lang/ruby >= 1.9.0
  • app-admin/puppet >= 3.5.0
  • sys-apps/portage
  • app-portage/eix


The following things are assumed:

  • /etc/portage/package.use is a directory
  • /etc/portage/package.accept_keywords is a directory
  • Both of the above are free for modification by puppet
  • WARNING: Folders contained within either of these will be automatically removed by this plugin


PortageGT can be installed from Puppet Forge:

puppet module install Whatbox-portagegt

All code is contained within the lib folder if you wish to place it in an existing module.

To use the PortageGT provider for all of your packages you can set in your manifests, alternatively you can add the provider attribute to any individual packages you desire.

Package {
  provider => 'portagegt'


Using PortageGT should be pretty familiar to anyone already using puppet on Gentoo, the only differences are in the added attributes that may be included in the manifests. The simplest case is the same as it is with existing puppet setups.

package { "vnstat":
    ensure => "1.11-r2";


Name based

package { "net-analyzer/vnstat":
    ensure => "1.11-r2";

Attribute based

package { "vnstat":
    ensure   => "1.11-r2",
    category => "net-analyzer";


Name based

package { "dev-lang/php:5.4":
    ensure => latest;

package { "dev-lang/php:5.3":
    ensure => absent;

Attribute based

package { "dev-lang/python":
    ensure           => latest,
    package_settings => {
        slot => "2.7",

package { "dev-lang/python:3.1":
    ensure           => latest,
    package_settings => {
        slot => "3.1",


package { "sys-boot/grub":
    ensure           => "2.00",
    package_settings => {
        slot     => "2",
        keywords => "~amd64",


Specify the latest version of a specific overlay available on your systems, to ensure you don't accidentally build code from the wrong overlay.

package { "www-servers/nginx":
    ensure => latest,
    package_settings => {
        repository => "company-overlay",

Use flags


package { "www-servers/apache2":
    ensure => latest,
    package_settings => {
        use    => "apache2_modules_alias apache2_modules_auth_basic",


package { "www-servers/apache2":
    ensure           => latest,
    package_settings => {
        use => [

Additional emerge options

package { "media-libs/libpng":
    ensure          => latest;
    install_options => ["--oneshot"],

Customizing the environment per package

All of your desired environment variables can saved in a named file, as follows:

file {'/etc/portage/env':
    ensure  => directory;

file { '/etc/portage/env/notest':
    content => 'FEATURES="-test"';

file {'/etc/portage/env/fastmath':
    ensure => file,
    source  => 'puppet:///modules/portage/env/fastmath';


package { 'dev-ruby/facter':
    ensure          => latest,
    package_settings => {
        environment => 'notest',


package { 'media-libs/libpng':
    ensure          => latest,
    package_settings => {
        environment => ['notest', 'fastmath'],

Keywords & Use flags on dependencies

If you need to keyword or add use flags to a package without wanting to manage it's version directly.

package { "dev-libs/boost":
    package_settings => {
        use => ["icu", "threads"],


eselect is useful when selecting specific versions from between several slots


eselect { "php-fpm":
    ensure    => "php5.4",
    module    => "php",
    submodule => "fpm";


eselect { "gcc":
    listcmd => "gcc-config -l",
    setcmd  => "gcc-config",
    ensure  => "x86_64-pc-linux-gnu-4.5.3";


eselect { "ruby":
    ensure => "ruby19";


eselect { "python":
    ensure => "python3.2";

eselect { "python2":
    module    => "python",
    submodule => "--python2",
    ensure    => "python2.7";

eselect { "python3":
    module    => "python",
    submodule => "--python3",
    ensure    => "python3.2";


eselect { "profile":
    ensure => "default/linux/amd64/13.0";

kernel (/usr/src/linux)

eselect { "kernel":
    ensure => "linux-3.7.0-hardened";


eselect { "locale":
    ensure => "en_US.UTF-8";

Tuning behavior

Some configuration opetions can be found near the start of lib/puppet/provider/package/portagegt.rb that allow tuning of the modules behavior. The defaults cause explict use flag changes to recompile packages, and eix-sync to be run if it has been more than 48 hours since the last sync.


To install dependencies necessary for running the tests use bundle install, tests can be run with bundle exec rspec. This project attempts to adhere to the Ruby Style Guide, you can verify your changes are in adhere to this guide using bundle exec rubocop.

Note: eix must be installed to test successfully on Gentoo, this is not necessary when running tests from other operating systems.


  • Using first-class parameters (PUP-1183)
  • More extensive unit testing
  • Easier configuration of provider options

Features Omitted

These are features we're not implementing at this time

  • package mask
    • using puppet ensure => :held
  • package unmask