mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-07-22 21:00:22 -07:00
new module: win_path (#20073)
This commit is contained in:
parent
712be24a74
commit
b2a16379c8
7 changed files with 435 additions and 1 deletions
|
@ -65,7 +65,10 @@ options:
|
|||
- process
|
||||
- user
|
||||
author: "Jon Hawkesworth (@jhawkesworth)"
|
||||
notes:
|
||||
notes:
|
||||
- This module is best-suited for setting the entire value of an
|
||||
environment variable. For safe element-based management of
|
||||
path-like environment vars, use the M(win_path) module.
|
||||
- This module does not broadcast change events.
|
||||
This means that the minority of windows applications which can have
|
||||
their environment changed without restarting will not be notified and
|
||||
|
|
158
lib/ansible/modules/windows/win_path.ps1
Normal file
158
lib/ansible/modules/windows/win_path.ps1
Normal file
|
@ -0,0 +1,158 @@
|
|||
#!powershell
|
||||
# This file is part of Ansible
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# WANT_JSON
|
||||
# POWERSHELL_COMMON
|
||||
|
||||
Set-StrictMode -Version 2
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
$system_path = "System\CurrentControlSet\Control\Session Manager\Environment"
|
||||
$user_path = "Environment"
|
||||
|
||||
# list/arraylist methods don't allow IEqualityComparer override for case/backslash/quote-insensitivity, roll our own search
|
||||
Function Get-IndexOfPathElement ($list, [string]$value) {
|
||||
$idx = 0
|
||||
$value = $value.Trim('"').Trim('\')
|
||||
ForEach($el in $list) {
|
||||
If ([string]$el.Trim('"').Trim('\') -ieq $value) {
|
||||
return $idx
|
||||
}
|
||||
|
||||
$idx++
|
||||
}
|
||||
|
||||
return -1
|
||||
}
|
||||
|
||||
# alters list in place, returns true if at least one element was added
|
||||
Function Add-Elements ($existing_elements, $elements_to_add) {
|
||||
$last_idx = -1
|
||||
$changed = $false
|
||||
|
||||
ForEach($el in $elements_to_add) {
|
||||
$idx = Get-IndexOfPathElement $existing_elements $el
|
||||
|
||||
# add missing elements at the end
|
||||
If ($idx -eq -1) {
|
||||
$last_idx = $existing_elements.Add($el)
|
||||
$changed = $true
|
||||
}
|
||||
ElseIf ($idx -lt $last_idx) {
|
||||
$existing_elements.RemoveAt($idx) | Out-Null
|
||||
$existing_elements.Add($el) | Out-Null
|
||||
$last_idx = $existing_elements.Count - 1
|
||||
$changed = $true
|
||||
}
|
||||
Else {
|
||||
$last_idx = $idx
|
||||
}
|
||||
}
|
||||
|
||||
return $changed
|
||||
}
|
||||
|
||||
# alters list in place, returns true if at least one element was removed
|
||||
Function Remove-Elements ($existing_elements, $elements_to_remove) {
|
||||
$count = $existing_elements.Count
|
||||
|
||||
ForEach($el in $elements_to_remove) {
|
||||
$idx = Get-IndexOfPathElement $existing_elements $el
|
||||
$result.removed_idx = $idx
|
||||
If ($idx -gt -1) {
|
||||
$existing_elements.RemoveAt($idx)
|
||||
}
|
||||
}
|
||||
|
||||
return $count -ne $existing_elements.Count
|
||||
}
|
||||
|
||||
# PS registry provider doesn't allow access to unexpanded REG_EXPAND_SZ; fall back to .NET
|
||||
Function Get-RawPathVar ($scope) {
|
||||
If ($scope -eq "user") {
|
||||
$env_key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey($user_path)
|
||||
}
|
||||
ElseIf ($scope -eq "machine") {
|
||||
$env_key = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey($system_path)
|
||||
}
|
||||
|
||||
return $env_key.GetValue($var_name, "", [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
|
||||
}
|
||||
|
||||
Function Set-RawPathVar($path_value, $scope) {
|
||||
If ($scope -eq "user") {
|
||||
$var_path = "HKCU:\" + $user_path
|
||||
}
|
||||
ElseIf ($scope -eq "machine") {
|
||||
$var_path = "HKLM:\" + $system_path
|
||||
}
|
||||
|
||||
Set-ItemProperty $var_path -Name $var_name -Value $path_value -Type ExpandString | Out-Null
|
||||
|
||||
return $path_value
|
||||
}
|
||||
|
||||
$parsed_args = Parse-Args $args -supports_check_mode $true
|
||||
|
||||
$result = @{changed=$false}
|
||||
|
||||
$var_name = Get-AnsibleParam $parsed_args "name" -Default "PATH"
|
||||
$elements = Get-AnsibleParam $parsed_args "elements" -FailIfEmpty $result
|
||||
$state = Get-AnsibleParam $parsed_args "state" -Default "present" -ValidateSet "present","absent"
|
||||
$scope = Get-AnsibleParam $parsed_args "scope" -Default "machine" -ValidateSet "machine","user"
|
||||
|
||||
$check_mode = Get-AnsibleParam $parsed_args "_ansible_check_mode" -Default $false
|
||||
|
||||
If ($elements -is [string]) {
|
||||
$elements = @($elements)
|
||||
}
|
||||
|
||||
If ($elements -isnot [Array]) {
|
||||
Fail-Json $result "elements must be a string or list of path strings"
|
||||
}
|
||||
|
||||
$current_value = Get-RawPathVar $scope
|
||||
$result.path_value = $current_value
|
||||
|
||||
# TODO: test case-canonicalization on wacky unicode values (eg turkish i)
|
||||
# TODO: detect and warn/fail on unparseable path? (eg, unbalanced quotes, invalid path chars)
|
||||
# TODO: detect and warn/fail if system path and Powershell isn't on it?
|
||||
|
||||
$existing_elements = New-Object System.Collections.ArrayList
|
||||
|
||||
# split on semicolons, accounting for quoted values with embedded semicolons (which may or may not be wrapped in whitespace)
|
||||
$pathsplit_re = [regex] '((?<q>\s*"[^"]+"\s*)|(?<q>[^;]+))(;$|$|;)'
|
||||
|
||||
ForEach ($m in $pathsplit_re.Matches($current_value)) {
|
||||
$existing_elements.Add($m.Groups['q'].Value) | Out-Null
|
||||
}
|
||||
|
||||
If ($state -eq "absent") {
|
||||
$result.changed = Remove-Elements $existing_elements $elements
|
||||
}
|
||||
ElseIf ($state -eq "present") {
|
||||
$result.changed = Add-Elements $existing_elements $elements
|
||||
}
|
||||
|
||||
# calculate the new path value from the existing elements
|
||||
$path_value = [String]::Join(";", $existing_elements.ToArray())
|
||||
$result.path_value = $path_value
|
||||
|
||||
If ($result.changed -and -not $check_mode) {
|
||||
Set-RawPathVar $path_value $scope | Out-Null
|
||||
}
|
||||
|
||||
Exit-Json $result
|
87
lib/ansible/modules/windows/win_path.py
Normal file
87
lib/ansible/modules/windows/win_path.py
Normal file
|
@ -0,0 +1,87 @@
|
|||
#!/usr/bin/python
|
||||
#
|
||||
# Copyright 2016 Red Hat | Ansible
|
||||
#
|
||||
# This file is part of Ansible
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# This is a windows documentation stub. Actual code lives in the .ps1
|
||||
# file of the same name
|
||||
|
||||
ANSIBLE_METADATA = {'status': ['preview'],
|
||||
'supported_by': 'core',
|
||||
'version': '1.0'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: win_path
|
||||
version_added: "2.3"
|
||||
short_description: Manage Windows path environment variables
|
||||
description:
|
||||
- Allows element-based ordering, addition, and removal of Windows path environment variables.
|
||||
options:
|
||||
name:
|
||||
description:
|
||||
- Target path environment variable name
|
||||
default: PATH
|
||||
elements:
|
||||
description:
|
||||
- A single path element, or a list of path elements (ie, directories) to add or remove.
|
||||
- When multiple elements are included in the list (and C(state) is C(present)), the elements are guaranteed to appear in the same relative order in the resultant path value.
|
||||
- Variable expansions (eg, C(%VARNAME%)) are allowed, and are stored unexpanded in the target path element.
|
||||
- Any existing path elements not mentioned in C(elements) are always preserved in their current order.
|
||||
- New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering.
|
||||
- Paths are compared in a case-insensitive fashion, and trailing backslashes are ignored for comparison purposes. However, note that trailing backslashes in YAML require quotes.
|
||||
required: true
|
||||
state:
|
||||
description:
|
||||
- Whether the path elements specified in C(elements) should be present or absent.
|
||||
choices:
|
||||
- present
|
||||
- absent
|
||||
scope:
|
||||
description:
|
||||
- The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope).
|
||||
choices:
|
||||
- machine
|
||||
- user
|
||||
default: machine
|
||||
author: "Matt Davis (@nitzmahone)"
|
||||
notes:
|
||||
- This module is for modifying indidvidual elements of path-like
|
||||
environment variables. For general-purpose management of other
|
||||
environment vars, use the M(win_environment) module.
|
||||
- This module does not broadcast change events.
|
||||
This means that the minority of windows applications which can have
|
||||
their environment changed without restarting will not be notified and
|
||||
therefore will need restarting to pick up new environment settings.
|
||||
User level environment variables will require an interactive user to
|
||||
log out and in again before they become available.
|
||||
'''
|
||||
|
||||
EXAMPLES = r'''
|
||||
- name: Ensure that system32 and Powershell are present on the global system path, and in the specified order
|
||||
win_path:
|
||||
elements:
|
||||
- %SystemRoot%\system32
|
||||
- %SystemRoot%\system32\WindowsPowerShell\v1.0
|
||||
|
||||
- name: Ensure that C:\Program Files\MyJavaThing is not on the current user's CLASSPATH
|
||||
win_path
|
||||
name: CLASSPATH
|
||||
elements: C:\Program Files\MyJavaThing
|
||||
scope: user
|
||||
state: absent
|
||||
'''
|
Loading…
Add table
Add a link
Reference in a new issue