diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
commit | 8a754e0858d922e955e71b253c139e071ecec432 (patch) | |
tree | 527d16e74bfd1840c85efd675fdecad056c54107 /lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 | |
parent | Initial commit. (diff) | |
download | ansible-core-8a754e0858d922e955e71b253c139e071ecec432.tar.xz ansible-core-8a754e0858d922e955e71b253c139e071ecec432.zip |
Adding upstream version 2.14.3.upstream/2.14.3upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 b/lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 new file mode 100644 index 0000000..f0cb440 --- /dev/null +++ b/lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 @@ -0,0 +1,390 @@ +# Copyright (c), Michael DeHaan <michael.dehaan@gmail.com>, 2014, and others +# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause) + +Set-StrictMode -Version 2.0 +$ErrorActionPreference = "Stop" + +Function Set-Attr($obj, $name, $value) { + <# + .SYNOPSIS + Helper function to set an "attribute" on a psobject instance in PowerShell. + This is a convenience to make adding Members to the object easier and + slightly more pythonic + .EXAMPLE + Set-Attr $result "changed" $true +#> + + # If the provided $obj is undefined, define one to be nice + If (-not $obj.GetType) { + $obj = @{ } + } + + Try { + $obj.$name = $value + } + Catch { + $obj | Add-Member -Force -MemberType NoteProperty -Name $name -Value $value + } +} + +Function Exit-Json($obj) { + <# + .SYNOPSIS + Helper function to convert a PowerShell object to JSON and output it, exiting + the script + .EXAMPLE + Exit-Json $result +#> + + # If the provided $obj is undefined, define one to be nice + If (-not $obj.GetType) { + $obj = @{ } + } + + if (-not $obj.ContainsKey('changed')) { + Set-Attr -obj $obj -name "changed" -value $false + } + + Write-Output $obj | ConvertTo-Json -Compress -Depth 99 + Exit +} + +Function Fail-Json($obj, $message = $null) { + <# + .SYNOPSIS + Helper function to add the "msg" property and "failed" property, convert the + PowerShell Hashtable to JSON and output it, exiting the script + .EXAMPLE + Fail-Json $result "This is the failure message" +#> + + if ($obj -is [hashtable] -or $obj -is [psobject]) { + # Nothing to do + } + elseif ($obj -is [string] -and $null -eq $message) { + # If we weren't given 2 args, and the only arg was a string, + # create a new Hashtable and use the arg as the failure message + $message = $obj + $obj = @{ } + } + else { + # If the first argument is undefined or a different type, + # make it a Hashtable + $obj = @{ } + } + + # Still using Set-Attr for PSObject compatibility + Set-Attr -obj $obj -name "msg" -value $message + Set-Attr -obj $obj -name "failed" -value $true + + if (-not $obj.ContainsKey('changed')) { + Set-Attr -obj $obj -name "changed" -value $false + } + + Write-Output $obj | ConvertTo-Json -Compress -Depth 99 + Exit 1 +} + +Function Add-Warning($obj, $message) { + <# + .SYNOPSIS + Helper function to add warnings, even if the warnings attribute was + not already set up. This is a convenience for the module developer + so they do not have to check for the attribute prior to adding. +#> + + if (-not $obj.ContainsKey("warnings")) { + $obj.warnings = @() + } + elseif ($obj.warnings -isnot [array]) { + throw "Add-Warning: warnings attribute is not an array" + } + + $obj.warnings += $message +} + +Function Add-DeprecationWarning($obj, $message, $version = $null) { + <# + .SYNOPSIS + Helper function to add deprecations, even if the deprecations attribute was + not already set up. This is a convenience for the module developer + so they do not have to check for the attribute prior to adding. +#> + if (-not $obj.ContainsKey("deprecations")) { + $obj.deprecations = @() + } + elseif ($obj.deprecations -isnot [array]) { + throw "Add-DeprecationWarning: deprecations attribute is not a list" + } + + $obj.deprecations += @{ + msg = $message + version = $version + } +} + +Function Expand-Environment($value) { + <# + .SYNOPSIS + Helper function to expand environment variables in values. By default + it turns any type to a string, but we ensure $null remains $null. +#> + if ($null -ne $value) { + [System.Environment]::ExpandEnvironmentVariables($value) + } + else { + $value + } +} + +Function Get-AnsibleParam { + <# + .SYNOPSIS + Helper function to get an "attribute" from a psobject instance in PowerShell. + This is a convenience to make getting Members from an object easier and + slightly more pythonic + .EXAMPLE + $attr = Get-AnsibleParam $response "code" -default "1" + .EXAMPLE + Get-AnsibleParam -obj $params -name "State" -default "Present" -ValidateSet "Present","Absent" -resultobj $resultobj -failifempty $true + Get-AnsibleParam also supports Parameter validation to save you from coding that manually + Note that if you use the failifempty option, you do need to specify resultobject as well. +#> + param ( + $obj, + $name, + $default = $null, + $resultobj = @{}, + $failifempty = $false, + $emptyattributefailmessage, + $ValidateSet, + $ValidateSetErrorMessage, + $type = $null, + $aliases = @() + ) + # Check if the provided Member $name or aliases exist in $obj and return it or the default. + try { + + $found = $null + # First try to find preferred parameter $name + $aliases = @($name) + $aliases + + # Iterate over aliases to find acceptable Member $name + foreach ($alias in $aliases) { + if ($obj.ContainsKey($alias)) { + $found = $alias + break + } + } + + if ($null -eq $found) { + throw + } + $name = $found + + if ($ValidateSet) { + + if ($ValidateSet -contains ($obj.$name)) { + $value = $obj.$name + } + else { + if ($null -eq $ValidateSetErrorMessage) { + #Auto-generated error should be sufficient in most use cases + $ValidateSetErrorMessage = "Get-AnsibleParam: Argument $name needs to be one of $($ValidateSet -join ",") but was $($obj.$name)." + } + Fail-Json -obj $resultobj -message $ValidateSetErrorMessage + } + } + else { + $value = $obj.$name + } + } + catch { + if ($failifempty -eq $false) { + $value = $default + } + else { + if (-not $emptyattributefailmessage) { + $emptyattributefailmessage = "Get-AnsibleParam: Missing required argument: $name" + } + Fail-Json -obj $resultobj -message $emptyattributefailmessage + } + } + + # If $null -eq $value, the parameter was unspecified by the user (deliberately or not) + # Please leave $null-values intact, modules need to know if a parameter was specified + if ($null -eq $value) { + return $null + } + + if ($type -eq "path") { + # Expand environment variables on path-type + $value = Expand-Environment($value) + # Test if a valid path is provided + if (-not (Test-Path -IsValid $value)) { + $path_invalid = $true + # could still be a valid-shaped path with a nonexistent drive letter + if ($value -match "^\w:") { + # rewrite path with a valid drive letter and recheck the shape- this might still fail, eg, a nonexistent non-filesystem PS path + if (Test-Path -IsValid $(@(Get-PSDrive -PSProvider Filesystem)[0].Name + $value.Substring(1))) { + $path_invalid = $false + } + } + if ($path_invalid) { + Fail-Json -obj $resultobj -message "Get-AnsibleParam: Parameter '$name' has an invalid path '$value' specified." + } + } + } + elseif ($type -eq "str") { + # Convert str types to real Powershell strings + $value = $value.ToString() + } + elseif ($type -eq "bool") { + # Convert boolean types to real Powershell booleans + $value = $value | ConvertTo-Bool + } + elseif ($type -eq "int") { + # Convert int types to real Powershell integers + $value = $value -as [int] + } + elseif ($type -eq "float") { + # Convert float types to real Powershell floats + $value = $value -as [float] + } + elseif ($type -eq "list") { + if ($value -is [array]) { + # Nothing to do + } + elseif ($value -is [string]) { + # Convert string type to real Powershell array + $value = $value.Split(",").Trim() + } + elseif ($value -is [int]) { + $value = @($value) + } + else { + Fail-Json -obj $resultobj -message "Get-AnsibleParam: Parameter '$name' is not a YAML list." + } + # , is not a typo, forces it to return as a list when it is empty or only has 1 entry + return , $value + } + + return $value +} + +#Alias Get-attr-->Get-AnsibleParam for backwards compat. Only add when needed to ease debugging of scripts +If (-not(Get-Alias -Name "Get-attr" -ErrorAction SilentlyContinue)) { + New-Alias -Name Get-attr -Value Get-AnsibleParam +} + +Function ConvertTo-Bool { + <# + .SYNOPSIS + Helper filter/pipeline function to convert a value to boolean following current + Ansible practices + .EXAMPLE + $is_true = "true" | ConvertTo-Bool +#> + param( + [parameter(valuefrompipeline = $true)] + $obj + ) + + process { + $boolean_strings = "yes", "on", "1", "true", 1 + $obj_string = [string]$obj + + if (($obj -is [boolean] -and $obj) -or $boolean_strings -contains $obj_string.ToLower()) { + return $true + } + else { + return $false + } + } +} + +Function Parse-Args { + <# + .SYNOPSIS + Helper function to parse Ansible JSON arguments from a "file" passed as + the single argument to the module. + .EXAMPLE + $params = Parse-Args $args +#> + [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "", Justification = "Cannot change the name now")] + param ($arguments, $supports_check_mode = $false) + + $params = New-Object psobject + If ($arguments.Length -gt 0) { + $params = Get-Content $arguments[0] | ConvertFrom-Json + } + Else { + $params = $complex_args + } + $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false + If ($check_mode -and -not $supports_check_mode) { + Exit-Json @{ + skipped = $true + changed = $false + msg = "remote module does not support check mode" + } + } + return $params +} + + +Function Get-FileChecksum($path, $algorithm = 'sha1') { + <# + .SYNOPSIS + Helper function to calculate a hash of a file in a way which PowerShell 3 + and above can handle +#> + If (Test-Path -LiteralPath $path -PathType Leaf) { + switch ($algorithm) { + 'md5' { $sp = New-Object -TypeName System.Security.Cryptography.MD5CryptoServiceProvider } + 'sha1' { $sp = New-Object -TypeName System.Security.Cryptography.SHA1CryptoServiceProvider } + 'sha256' { $sp = New-Object -TypeName System.Security.Cryptography.SHA256CryptoServiceProvider } + 'sha384' { $sp = New-Object -TypeName System.Security.Cryptography.SHA384CryptoServiceProvider } + 'sha512' { $sp = New-Object -TypeName System.Security.Cryptography.SHA512CryptoServiceProvider } + default { Fail-Json @{} "Unsupported hash algorithm supplied '$algorithm'" } + } + + If ($PSVersionTable.PSVersion.Major -ge 4) { + $raw_hash = Get-FileHash -LiteralPath $path -Algorithm $algorithm + $hash = $raw_hash.Hash.ToLower() + } + Else { + $fp = [System.IO.File]::Open($path, [System.IO.Filemode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite); + $hash = [System.BitConverter]::ToString($sp.ComputeHash($fp)).Replace("-", "").ToLower(); + $fp.Dispose(); + } + } + ElseIf (Test-Path -LiteralPath $path -PathType Container) { + $hash = "3"; + } + Else { + $hash = "1"; + } + return $hash +} + +Function Get-PendingRebootStatus { + <# + .SYNOPSIS + Check if reboot is required, if so notify CA. + Function returns true if computer has a pending reboot +#> + $featureData = Invoke-CimMethod -EA Ignore -Name GetServerFeature -Namespace root\microsoft\windows\servermanager -Class MSFT_ServerManagerTasks + $regData = Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager" "PendingFileRenameOperations" -EA Ignore + $CBSRebootStatus = Get-ChildItem "HKLM:\\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing" -ErrorAction SilentlyContinue | + Where-Object { $_.PSChildName -eq "RebootPending" } + if (($featureData -and $featureData.RequiresReboot) -or $regData -or $CBSRebootStatus) { + return $True + } + else { + return $False + } +} + +# this line must stay at the bottom to ensure all defined module parts are exported +Export-ModuleMember -Alias * -Function * -Cmdlet * |