search

puppetlabs / puppetlabs-windows_env

Puppet module for managing Windows environment variables.
https://forge.puppet.com/puppet/windows_env
Apache License 2.0
14 stars 23 forks source link
hacktoberfest module puppet supported windows-puppet-module

readme

windows_env

Donated by Vox Pupuli

This module manages (system and user) Windows environment variables.

Installation

Install from puppet forge:

puppet module install puppet/windows_env

Install from git (do this in your modulepath):

git clone https://github.com/puppetlabs/puppetlabs-windows_env windows_env

Changes

CHANGELOG.md

Compatibility

This module is currently tested against Puppet 4.10 and latest Puppet 5 releases. You can see the range of supported Puppet versions in the metadata.json.

Usage

Parameters

ensure

Standard ensure, valid values are absent or present. Defaults to present.

variable (namevar)

The name of the environment variable. This will be inferred from the title if not given explicitly. The title can be of either the form {variable}={value} (the fields will be split on the first =) or just {variable}.

value (namevar)

The value of the environment variable. How this will treat existing content depends on mergemode.

user (namevar)

The user whose environment will be modified. Default is undef, i.e. system environment. The user can be local or domain, as long as they have a local profile (typically C:\users\{username} on Vista+). There is no awareness of network profiles in this module; knowing how changes to the local profile will affect a distributed profile is up to you.

separator

How to split entries in environment variables with multiple values (such as PATH or PATHEXT) . Default is ';'.

mergemode

Specifies how to treat content already in the environment variable, and how to handle deletion of variables. Default is insert.

Valid values:

type

The type of registry value to use. Default is undef for existing keys (i.e. don't change the type) and REG_SZ when creating new keys.

Valid values:

broadcast_timeout

Specifies how long (in ms) to wait (per window) for refreshes to go through when environment variables change. Default is 100ms. This probably doesn't need changing unless you're having issues with the refreshes taking a long time (they generally happen nearly instantly). Note that this only works for the user that initiated the puppet run; if puppet runs in the background, updates to the environment will not propagate to logged in users until they log out and back in or refresh their environment by some other means.

Examples


    # Title type #1. Variable name and value are extracted from title, splitting on '='.
    # Default 'insert' mergemode is selected and default 'present' ensure is selected,
    # so this will add 'C:\code\bin' to PATH, merging it neatly with existing content.
    windows_env { 'PATH=C:\code\bin': }

    # Title type #2. Variable name is derived from the title, but not value (because there is no '=').
    # This will remove the environment variable 'BADVAR' completely.
    windows_env { 'BADVAR':
      ensure    => absent,
      mergemode => clobber,
    }

    # Title type #3. Title doesn't set parameters (because both 'variable' and 'value' have
    # been supplied manually).
    # This will create a new environment variable 'MyVariable' and set its value to 'stuff'.
    # If the variable already exists, its value will be replaced with 'stuff'.
    windows_env {'random_title':
      ensure    => present,
      variable  => 'MyVariable',
      value     => 'stuff',
      mergemode => clobber,
    }

    # Variables with type => 'REG_EXPAND_SZ' allow other environment variables to be used
    # by enclosing them in percent symbols.
    windows_env { 'JAVA_HOME=%ProgramFiles%\Java\jdk1.6.0_02':
      type => 'REG_EXPAND_SZ',
    }

    # Create an environment variable for 'Administrator':
    windows_env { 'KOOLVAR':
      value => 'hi',
      user  => 'Administrator',
    }

    # Create an environment variable for 'Domain\FunUser':
    windows_env { 'Funvar':
      value => 'Funval',
      user  => 'Domain\FunUser',
    }

    # Creates (if needed) an enviroment variable 'VAR', and sticks 'VAL:VAL2' at
    # the beginning. Separates with : instead of ;. The broadcast_timeout change
    # probably won't make any difference.
    windows_env { 'title':
      ensure            => present,
      mergemode         => prepend,
      variable          => 'VAR',
      value             => ['VAL', 'VAL2'],
      separator         => ':',
      broadcast_timeout => 2000,
    }

    # Exec doStuff.bat whenever environment variable KOOLVAR changes.
    # Note that if you have multiple windows_env resources managing one
    # variable, you'll need to either subscribe to all of them or combine
    # the windows_env resources into one (by passing an array to 'value')
    # and subscribing to that one resource.
    exec { 'C:\doStuff.bat':
      subscribe   => Windows_env['KOOLVAR'],
      refreshonly => true,
    }

Facts

windows_env

A structured fact which lists the following Windows environment variables

Note that the names will appear as uppercase in the fact, for example the windir environment variable will appears as WINDIR in the fact

Examples

    $app_data = $facts['windows_env']['APPDATA']

    # Output the AppData path in the puppet log
    notify { $app_data: }

Acknowledgements

The puppet-windows-path module by Bastian Krol was the starting point for this module. puppetlabs-windows_env got migrated from badgerious to Vox Pupuli.

License

This codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of AGPL, BSD-2, BSD-3, GPL2.0, LGPL, MIT and MPL Licensing.

Transfer notice

This module was previously maintained by Vox Pupuli. It was migrated to Puppet/Perforce in 2023.