AzStackHci.EnvironmentChecker

1.2100.2385.192

AzStackHciStandaloneObservability/package/bin/ObsDep/content/Powershell/Common/NetworkHelpers.psm1

<###################################################
 # #
 # Copyright (c) Microsoft. All rights reserved. #
 # #
 ##################################################>

function Test-NetworkIPv4Address
{
    [CmdletBinding()]
    Param
    (
        [Parameter(Mandatory=$true)]
        [System.String] $IPv4Address
    )

    $byte = "(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"

    # composing a pattern (IPv4 address):
    $IPv4Template = "^($byte\.){3}$byte$"

    return $IPv4Address -match $IPv4Template
}

function Get-NetworkMgmtIPv4FromECEForAllHosts
{
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory = $true)]
        [CloudEngine.Configurations.EceInterfaceParameters] $Parameters
    )

    [System.Collections.Hashtable] $retValArray = @{}

    $physicalMachinesPublicConfig = $Parameters.Roles["BareMetal"].PublicConfiguration
    $allHostNodesInfo = $physicalMachinesPublicConfig.Nodes.Node

    foreach ($node in $allHostNodesInfo.Name)
    {
        $nodeIP = Get-NetworkMgmtIPv4FromECEForHost -Parameters $Parameters -HostName $node
        $retValArray.Add($node, $nodeIP)
    }

    return $retValArray
}

function Get-NetworkMgmtIPv4FromECEForHost
{
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory = $true)]
        [CloudEngine.Configurations.EceInterfaceParameters] $Parameters,

        [Parameter(Mandatory = $true)]
        [System.String] $HostName
    )

    [System.String] $retVal = $null

    $physicalMachinesPublicConfig = $Parameters.Roles["BareMetal"].PublicConfiguration
    $physicalNodesHostNameMgmtIPInfo = $physicalMachinesPublicConfig.PublicInfo.PhysicalNodes.HostNameMgmtIPInfo
    $physicalNodesV2NicInfo = $physicalMachinesPublicConfig.PublicInfo.PhysicalNodesV2.NetworkAdaptersInformation

    # Depending on whether this function is called at PreDeploy stage or Deploy stage, and whether the V3 answer file or the older answer file is used,
    # there are 3 possible ways to get the management IP for a node.
    # At PreDeploy stage:
    # If V3 answer file is used, PhysicalNodesV2.NetworkAdaptersInformation should have the data and should be used.
    # If older answer file is used, PhysicalNodesV2.NetworkAdaptersInformation is empty, PhysicalNodes.HostNameMgmtIPInfo is also empty, so HostNIC is used for back-compat reason.
    # At Deploy stage,
    # If V3 answer file is used, PhysicalNodes.HostNameMgmtIPInfo should have the data and should be used. (PhysicalNodesV2.NetworkAdaptersInformation is empty.)
    # If older answer file is used, PhysicalNodesV2.NetworkAdaptersInformation is empty, PhysicalNodes.HostNameMgmtIPInfo is also empty, so HostNIC is used for back-compat reason.
    #
    # Note: PhysicalNodesV2.NetworkAdaptersInformation and PhysicalNodes.HostNameMgmtIPInfo should have same IP info for same hosts. If not, it is the answer file problem.
    if ([System.String]::IsNullOrWhiteSpace($physicalNodesHostNameMgmtIPInfo) -and [System.String]::IsNullOrWhiteSpace($physicalNodesV2NicInfo))
    {
        $allHostNodesInfo = $physicalMachinesPublicConfig.Nodes.Node
        [System.Xml.XmlElement[]] $currentHostInfo = $allHostNodesInfo | Where-Object { $_.Name -like $HostName }
        [System.Xml.XmlElement[]] $adapterInfo = $currentHostInfo.NICs.NIC | Where-Object { $_.Name -eq 'HostNIC' }

        # Expecting only 1 HostNIC item in ECE config
        if ($adapterInfo.Count -eq 1)
        {
            $retVal = $adapterInfo[0].IPv4Address.Split('/')[0]
        }
        Trace-Execution "[Get-NetworkMgmtIPv4FromECEForHost]: retrieved IP [ $retVal ] for node $($HostName) via HostNIC info."
    }
    elseif ([System.String]::IsNullOrWhiteSpace($physicalNodesV2NicInfo))
    {
        $currentHostNameIPInfo = ($physicalNodesHostNameMgmtIPInfo | ConvertFrom-Json) | Where-Object { $_.Name -eq $HostName }
        $retVal = $currentHostNameIPInfo.IPv4Address
        Trace-Execution "[Get-NetworkMgmtIPv4FromECEForHost]: retrieved IP [ $retVal ] for node $($HostName) via PhysicalNodes.HostNameMgmtIPInfo."
    }
    else
    {
        $currentHostNameIPInfo = ($physicalNodesV2NicInfo | ConvertFrom-Json) | Where-Object { $_.Name -eq $HostName }
        $retVal = $currentHostNameIPInfo.IPv4Address
        Trace-Execution "[Get-NetworkMgmtIPv4FromECEForHost]: retrieved IP [ $retVal ] for node $($HostName) via PhysicalNodesV2.NetworkAdaptersInformation."
    }

    if (-not (Test-NetworkIPv4Address -IPv4Address $retVal))
    {
        $retVal = $null
    }

    return $retVal
}

function Test-IPConnection {
    [CmdLetBinding()]
    param(
        [Parameter(Mandatory = $True)]
        [string]
        $IP,

        [int]
        $TimeoutInSeconds = 1
    )

    try {
        return Test-NetConnection -ComputerName $IP -WarningAction SilentlyContinue -InformationLevel Quiet
    } catch {
        Trace-Warning "Pinging $IP failed with the following error: $_.ToString()"
        return $false
    }
}

function ConvertTo-SubnetMask {
    [CmdLetBinding()]
    param(
        [Parameter(Mandatory = $True)]
        [ValidateRange(0, 32)]
        [UInt32]
        $PrefixLength
    )

    $byteMask = ([Convert]::ToUInt32($(("1" * $PrefixLength).PadRight(32, "0")), 2))
    $bytes = [BitConverter]::GetBytes($byteMask)
    [Array]::Reverse($bytes)
    $ipAddress = New-Object System.Net.IPAddress -ArgumentList (, $bytes)
    return $ipAddress.IPAddressToString
}

function ConvertTo-PrefixLength {
    [CmdLetBinding()]
    param(
        [Parameter(Mandatory = $True)]
        [System.Net.IPAddress]
        $SubnetMask
    )

    $Bits = "$($SubnetMask.GetAddressBytes() | ForEach-Object {[Convert]::ToString($_, 2)})" -Replace '[\s0]'
    $Bits.Length
}

# Convert IP address to UInt32 to use for IP transformation (compare, increment, mask, etc.).
# Note that an existing 'Address' property of [System.Net.IPAddress] is unusable as it has byte order reversed.
function ConvertFrom-IPAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress
    )

    $bytes = $IPAddress.GetAddressBytes()
    [Array]::Reverse($bytes)

    return [BitConverter]::ToUInt32($bytes, 0)
}

# Note that this function returns IPAdrress string representation, not [System.Net.IPAddress].
# String representation is more usable for validation as it is more easy to compare.
function ConvertTo-IPAddress {
    param (
        [Parameter(Mandatory=$true)]
        [UInt32]
        $Value
    )

    $bytes = [BitConverter]::GetBytes($Value)
    [Array]::Reverse($bytes)

    # Construct new IPAddress object from byte array.
    # ', ' construct is used to wrap $bytes array into another array to prevent treating each byte as a separate argument.
    $ipAddress = New-Object System.Net.IPAddress -ArgumentList (, $bytes)

    return $ipAddress.IPAddressToString
}

function Get-NetworkAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress,

        [Parameter(Mandatory=$true)]
        [UInt32]
        $PrefixLength
    )

    $value = ConvertFrom-IPAddress $IPAddress

    $networkMask = [Convert]::ToUInt32(("1" * $PrefixLength).PadRight(32, "0"), 2)
    $transformedValue = $value -band $networkMask

    return (ConvertTo-IPAddress $transformedValue)
}

function Get-BroadcastAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress,

        [Parameter(Mandatory=$true)]
        [UInt32]
        $PrefixLength
    )

    $value = ConvertFrom-IPAddress $IPAddress

    $hostMask = [Convert]::ToUInt32("1" * (32 - $PrefixLength), 2)
    $transformedValue = $value -bor $hostMask

    return (ConvertTo-IPAddress $transformedValue)
}

function Get-RangeEndAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress,

        [Parameter(Mandatory=$true)]
        [UInt32]
        $PrefixLength
    )

    $value = ConvertFrom-IPAddress $IPAddress

    $hostMask = [Convert]::ToUInt32("1" * (32 - $PrefixLength), 2)
    $transformedValue = $value -bor $hostMask
    $transformedValue--

    return (ConvertTo-IPAddress $transformedValue)
}

function Add-IPAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress,

        [Parameter(Mandatory=$true)]
        [Int]
        $Addend
    )

    $value = ConvertFrom-IPAddress $IPAddress

    $transformedValue = $value + $Addend

    return (ConvertTo-IPAddress $transformedValue)
}

function Get-GatewayAddress {
    param (
        [Parameter(Mandatory=$true)]
        [System.Net.IPAddress]
        $IPAddress,

        [Parameter(Mandatory=$true)]
        [UInt32]
        $PrefixLength
    )

    $networkAddress = Get-NetworkAddress $IPAddress $PrefixLength
    return (Add-IPAddress $networkAddress 1)
}

# Returns two IP addresses delimiting the addressable part of the scope and the prefix length, e.g. 10.0.0.1, 10.0.0.254, 24 for 10.0.0.0/24.
function Get-ScopeRange {
    param (
        [Parameter(Mandatory=$true)]
        [string]
        $Scope
    )

    $scopeIP, $prefixLength = $Scope -split '/'
    $networkAddress = Get-NetworkAddress $scopeIP $prefixLength
    $scopeStart = Add-IPAddress $networkAddress 1
    $broadcastAddress = Get-BroadcastAddress $scopeIP $prefixLength
    $scopeEnd = Add-IPAddress $broadcastAddress -1
    return $scopeStart, $scopeEnd, $prefixLength
}

function Get-MacAddressString {
    param (
        [System.Net.NetworkInformation.PhysicalAddress]
        $MacAddress
    )

    $originalOfs = $ofs
    $ofs = '-'
    $macAddressString = "$($MacAddress.GetAddressBytes() | ForEach-Object {'{0:X2}' -f $_})"
    $ofs = $originalOfs
    return $macAddressString
}

function NormalizeIPv4Subnet
{
    param(
        [Parameter(Mandatory=$true)][string]$cidrSubnet
        )
    # $cidrSubnet is IPv4 subnet in CIDR format, such as 192.168.10.0/24
    $subnet, $prefixLength = $cidrSubnet.Split('/')

    $addr = $null
    if (([System.Net.IPAddress]::TryParse($subnet, [ref]$addr) -ne $true) -or ($addr.AddressFamily -ne [System.Net.Sockets.AddressFamily]::InterNetwork)) {
        throw "$subnet is not a valid IPv4 address."
    }

    if ($prefixLength -lt 0 -or $prefixLength -gt 32) {
        throw "$prefixLength is not a valid IPv4 subnet prefix-length."
    }

    $networkAddress = Get-NetworkAddress $subnet $prefixLength

    return $networkAddress.ToString() + '/' + $prefixLength
}

function Get-NetworkNameForCluster
{
    param(
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ClusterName,

        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]
        $NetworkName
    )

    if (($NetworkName -eq 'External') -or ($NetworkName -eq 'InternalVip'))
    {
        return $NetworkName
    }

    # AzS, single cluster only, it always has clusterId == 's-cluster', while cluster name is provided at deployment time.
    # In order to keep backward compatibility, we don't change the function interface for now.
    return "s-cluster-$NetworkName"
}

function Get-NetworkDefinitionForCluster
{
    param(
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ClusterName,

        [CloudEngine.Configurations.EceInterfaceParameters]
        $Parameters
    )

    $clusterRole = $Parameters.Roles["Cluster"].PublicConfiguration
    $clusterId = ($clusterRole.Clusters.Node | ? Name -eq $ClusterName).Id

    $networkRole = $Parameters.Roles["Network"].PublicConfiguration
    return $networkRole.NetworkDefinitions.Node | Where-Object { $_.RefClusterId -ieq $clusterId }
}

function Get-NetworkDefinitions
{
    param(
        [Parameter(Mandatory=$true)]
        [CloudEngine.Configurations.EceInterfaceParameters]
        $Parameters
    )

    $networkRole = $Parameters.Roles["Network"].PublicConfiguration
    return $networkRole.NetworkDefinitions.Node
}

function Get-NetworkSchemaVersion
{
    param (
        [Parameter(Mandatory=$true)]
        [CloudEngine.Configurations.EceInterfaceParameters]
        $Parameters
   )

    $cloudRole = $Parameters.Roles["Cloud"].PublicConfiguration
    return ($cloudRole.PublicInfo.NetworkConfiguration.Version).Id
}

function IsNetworkSchemaVersion2021
{
    param (
        [Parameter(Mandatory=$true)]
        [CloudEngine.Configurations.EceInterfaceParameters]
        $Parameters
   )

   return (Get-NetworkSchemaVersion($Parameters)) -eq "2021"
}

function Check-IPAddressFormat
{
    param(
        [Parameter(Mandatory=$true)]
        [string] $IPAddress
    )

    $addr = $null
    return ([System.Net.IPAddress]::TryParse($IPAddress, [ref] $addr)) -and
        ($addr.AddressFamily -eq [System.Net.Sockets.AddressFamily]::InterNetwork)
}

function Check-PortFormat
{
    param(
        [Parameter(Mandatory=$true)]
        [string] $Port
    )

    return ([bool]($Port -as [int]) -and ($Port -In 0..65535))
}

function Check-ProxyParameters
{
    param(
        [Parameter(Mandatory=$true)]
        [AllowNull()]
        [AllowEmptyString()]
        [string] $IPAddress1,
        [Parameter(Mandatory=$true)]
        [AllowNull()]
        [AllowEmptyString()]
        [string] $IPAddress2,
        [Parameter(Mandatory=$true)]
        [AllowNull()]
        [AllowEmptyString()]
        [string] $Port
    )

    return ($IPAddress1 -and $IPAddress2 -and $Port -and (Check-IPAddressFormat -IPAddress $IPAddress1) -and (Check-IPAddressFormat -IPAddress $IPAddress2) -and (Check-PortFormat -Port $Port))
}

Export-ModuleMember -Function Add-IPAddress
Export-ModuleMember -Function Check-IPAddressFormat
Export-ModuleMember -Function Check-PortFormat
Export-ModuleMember -Function Check-ProxyParameters
Export-ModuleMember -Function ConvertFrom-IPAddress
Export-ModuleMember -Function ConvertTo-IPAddress
Export-ModuleMember -Function ConvertTo-PrefixLength
Export-ModuleMember -Function ConvertTo-SubnetMask
Export-ModuleMember -Function Get-BroadcastAddress
Export-ModuleMember -Function Get-GatewayAddress
Export-ModuleMember -Function Get-MacAddressString
Export-ModuleMember -Function Get-NetworkAddress
Export-ModuleMember -Function Get-NetworkDefinitionForCluster
Export-ModuleMember -Function Get-NetworkDefinitions
Export-ModuleMember -Function Get-NetworkSchemaVersion
Export-ModuleMember -Function Get-NetworkNameForCluster
Export-ModuleMember -Function Get-RangeEndAddress
Export-ModuleMember -Function Get-ScopeRange
Export-ModuleMember -Function IsNetworkSchemaVersion2021
Export-ModuleMember -Function NormalizeIPv4Subnet
Export-ModuleMember -Function Test-IPConnection
Export-ModuleMember -Function Test-NetworkIPv4Address
Export-ModuleMember -Function Get-NetworkMgmtIPv4FromECEForAllHosts
Export-ModuleMember -Function Get-NetworkMgmtIPv4FromECEForHost

# SIG # Begin signature block
# MIInpAYJKoZIhvcNAQcCoIInlTCCJ5ECAQExDzANBglghkgBZQMEAgEFADB5Bgor
# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG
# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCBPiMbtVZ1km4KS
# o7o4E5Q5tgC4P75NkAEVU6Ax7Yeg4aCCDYUwggYDMIID66ADAgECAhMzAAADTU6R
# phoosHiPAAAAAANNMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYTAlVTMRMwEQYD
# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy
# b3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25p
# bmcgUENBIDIwMTEwHhcNMjMwMzE2MTg0MzI4WhcNMjQwMzE0MTg0MzI4WjB0MQsw
# CQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9u
# ZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYDVQQDExVNaWNy
# b3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
# AQDUKPcKGVa6cboGQU03ONbUKyl4WpH6Q2Xo9cP3RhXTOa6C6THltd2RfnjlUQG+
# Mwoy93iGmGKEMF/jyO2XdiwMP427j90C/PMY/d5vY31sx+udtbif7GCJ7jJ1vLzd
# j28zV4r0FGG6yEv+tUNelTIsFmmSb0FUiJtU4r5sfCThvg8dI/F9Hh6xMZoVti+k
# bVla+hlG8bf4s00VTw4uAZhjGTFCYFRytKJ3/mteg2qnwvHDOgV7QSdV5dWdd0+x
# zcuG0qgd3oCCAjH8ZmjmowkHUe4dUmbcZfXsgWlOfc6DG7JS+DeJak1DvabamYqH
# g1AUeZ0+skpkwrKwXTFwBRltAgMBAAGjggGCMIIBfjAfBgNVHSUEGDAWBgorBgEE
# AYI3TAgBBggrBgEFBQcDAzAdBgNVHQ4EFgQUId2Img2Sp05U6XI04jli2KohL+8w
# VAYDVR0RBE0wS6RJMEcxLTArBgNVBAsTJE1pY3Jvc29mdCBJcmVsYW5kIE9wZXJh
# dGlvbnMgTGltaXRlZDEWMBQGA1UEBRMNMjMwMDEyKzUwMDUxNzAfBgNVHSMEGDAW
# gBRIbmTlUAXTgqoXNzcitW2oynUClTBUBgNVHR8ETTBLMEmgR6BFhkNodHRwOi8v
# d3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NybC9NaWNDb2RTaWdQQ0EyMDExXzIw
# MTEtMDctMDguY3JsMGEGCCsGAQUFBwEBBFUwUzBRBggrBgEFBQcwAoZFaHR0cDov
# L3d3dy5taWNyb3NvZnQuY29tL3BraW9wcy9jZXJ0cy9NaWNDb2RTaWdQQ0EyMDEx
# XzIwMTEtMDctMDguY3J0MAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQELBQADggIB
# ACMET8WuzLrDwexuTUZe9v2xrW8WGUPRQVmyJ1b/BzKYBZ5aU4Qvh5LzZe9jOExD
# YUlKb/Y73lqIIfUcEO/6W3b+7t1P9m9M1xPrZv5cfnSCguooPDq4rQe/iCdNDwHT
# 6XYW6yetxTJMOo4tUDbSS0YiZr7Mab2wkjgNFa0jRFheS9daTS1oJ/z5bNlGinxq
# 2v8azSP/GcH/t8eTrHQfcax3WbPELoGHIbryrSUaOCphsnCNUqUN5FbEMlat5MuY
# 94rGMJnq1IEd6S8ngK6C8E9SWpGEO3NDa0NlAViorpGfI0NYIbdynyOB846aWAjN
# fgThIcdzdWFvAl/6ktWXLETn8u/lYQyWGmul3yz+w06puIPD9p4KPiWBkCesKDHv
# XLrT3BbLZ8dKqSOV8DtzLFAfc9qAsNiG8EoathluJBsbyFbpebadKlErFidAX8KE
# usk8htHqiSkNxydamL/tKfx3V/vDAoQE59ysv4r3pE+zdyfMairvkFNNw7cPn1kH
# Gcww9dFSY2QwAxhMzmoM0G+M+YvBnBu5wjfxNrMRilRbxM6Cj9hKFh0YTwba6M7z
# ntHHpX3d+nabjFm/TnMRROOgIXJzYbzKKaO2g1kWeyG2QtvIR147zlrbQD4X10Ab
# rRg9CpwW7xYxywezj+iNAc+QmFzR94dzJkEPUSCJPsTFMIIHejCCBWKgAwIBAgIK
# YQ6Q0gAAAAAAAzANBgkqhkiG9w0BAQsFADCBiDELMAkGA1UEBhMCVVMxEzARBgNV
# BAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jv
# c29mdCBDb3Jwb3JhdGlvbjEyMDAGA1UEAxMpTWljcm9zb2Z0IFJvb3QgQ2VydGlm
# aWNhdGUgQXV0aG9yaXR5IDIwMTEwHhcNMTEwNzA4MjA1OTA5WhcNMjYwNzA4MjEw
# OTA5WjB+MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UE
# BxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSgwJgYD
# VQQDEx9NaWNyb3NvZnQgQ29kZSBTaWduaW5nIFBDQSAyMDExMIICIjANBgkqhkiG
# 9w0BAQEFAAOCAg8AMIICCgKCAgEAq/D6chAcLq3YbqqCEE00uvK2WCGfQhsqa+la
# UKq4BjgaBEm6f8MMHt03a8YS2AvwOMKZBrDIOdUBFDFC04kNeWSHfpRgJGyvnkmc
# 6Whe0t+bU7IKLMOv2akrrnoJr9eWWcpgGgXpZnboMlImEi/nqwhQz7NEt13YxC4D
# dato88tt8zpcoRb0RrrgOGSsbmQ1eKagYw8t00CT+OPeBw3VXHmlSSnnDb6gE3e+
# lD3v++MrWhAfTVYoonpy4BI6t0le2O3tQ5GD2Xuye4Yb2T6xjF3oiU+EGvKhL1nk
# kDstrjNYxbc+/jLTswM9sbKvkjh+0p2ALPVOVpEhNSXDOW5kf1O6nA+tGSOEy/S6
# A4aN91/w0FK/jJSHvMAhdCVfGCi2zCcoOCWYOUo2z3yxkq4cI6epZuxhH2rhKEmd
# X4jiJV3TIUs+UsS1Vz8kA/DRelsv1SPjcF0PUUZ3s/gA4bysAoJf28AVs70b1FVL
# 5zmhD+kjSbwYuER8ReTBw3J64HLnJN+/RpnF78IcV9uDjexNSTCnq47f7Fufr/zd
# sGbiwZeBe+3W7UvnSSmnEyimp31ngOaKYnhfsi+E11ecXL93KCjx7W3DKI8sj0A3
# T8HhhUSJxAlMxdSlQy90lfdu+HggWCwTXWCVmj5PM4TasIgX3p5O9JawvEagbJjS
# 4NaIjAsCAwEAAaOCAe0wggHpMBAGCSsGAQQBgjcVAQQDAgEAMB0GA1UdDgQWBBRI
# bmTlUAXTgqoXNzcitW2oynUClTAZBgkrBgEEAYI3FAIEDB4KAFMAdQBiAEMAQTAL
# BgNVHQ8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBRyLToCMZBD
# uRQFTuHqp8cx0SOJNDBaBgNVHR8EUzBRME+gTaBLhklodHRwOi8vY3JsLm1pY3Jv
# c29mdC5jb20vcGtpL2NybC9wcm9kdWN0cy9NaWNSb29DZXJBdXQyMDExXzIwMTFf
# MDNfMjIuY3JsMF4GCCsGAQUFBwEBBFIwUDBOBggrBgEFBQcwAoZCaHR0cDovL3d3
# dy5taWNyb3NvZnQuY29tL3BraS9jZXJ0cy9NaWNSb29DZXJBdXQyMDExXzIwMTFf
# MDNfMjIuY3J0MIGfBgNVHSAEgZcwgZQwgZEGCSsGAQQBgjcuAzCBgzA/BggrBgEF
# BQcCARYzaHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraW9wcy9kb2NzL3ByaW1h
# cnljcHMuaHRtMEAGCCsGAQUFBwICMDQeMiAdAEwAZQBnAGEAbABfAHAAbwBsAGkA
# YwB5AF8AcwB0AGEAdABlAG0AZQBuAHQALiAdMA0GCSqGSIb3DQEBCwUAA4ICAQBn
# 8oalmOBUeRou09h0ZyKbC5YR4WOSmUKWfdJ5DJDBZV8uLD74w3LRbYP+vj/oCso7
# v0epo/Np22O/IjWll11lhJB9i0ZQVdgMknzSGksc8zxCi1LQsP1r4z4HLimb5j0b
# pdS1HXeUOeLpZMlEPXh6I/MTfaaQdION9MsmAkYqwooQu6SpBQyb7Wj6aC6VoCo/
# KmtYSWMfCWluWpiW5IP0wI/zRive/DvQvTXvbiWu5a8n7dDd8w6vmSiXmE0OPQvy
# CInWH8MyGOLwxS3OW560STkKxgrCxq2u5bLZ2xWIUUVYODJxJxp/sfQn+N4sOiBp
# mLJZiWhub6e3dMNABQamASooPoI/E01mC8CzTfXhj38cbxV9Rad25UAqZaPDXVJi
# hsMdYzaXht/a8/jyFqGaJ+HNpZfQ7l1jQeNbB5yHPgZ3BtEGsXUfFL5hYbXw3MYb
# BL7fQccOKO7eZS/sl/ahXJbYANahRr1Z85elCUtIEJmAH9AAKcWxm6U/RXceNcbS
# oqKfenoi+kiVH6v7RyOA9Z74v2u3S5fi63V4GuzqN5l5GEv/1rMjaHXmr/r8i+sL
# gOppO6/8MO0ETI7f33VtY5E90Z1WTk+/gFcioXgRMiF670EKsT/7qMykXcGhiJtX
# cVZOSEXAQsmbdlsKgEhr/Xmfwb1tbWrJUnMTDXpQzTGCGXUwghlxAgEBMIGVMH4x
# CzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRt
# b25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01p
# Y3Jvc29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMTECEzMAAANNTpGmGiiweI8AAAAA
# A00wDQYJYIZIAWUDBAIBBQCgga4wGQYJKoZIhvcNAQkDMQwGCisGAQQBgjcCAQQw
# HAYKKwYBBAGCNwIBCzEOMAwGCisGAQQBgjcCARUwLwYJKoZIhvcNAQkEMSIEIAlF
# ENJWi5x7qhm0KN0UnCYW1krA/8EiUiOMU87mSWWSMEIGCisGAQQBgjcCAQwxNDAy
# oBSAEgBNAGkAYwByAG8AcwBvAGYAdKEagBhodHRwOi8vd3d3Lm1pY3Jvc29mdC5j
# b20wDQYJKoZIhvcNAQEBBQAEggEAhsKwGSCLVFR/v4QgJ8eHX6wkNA7Eu+5qi9gR
# efcNI5Cxosvcf06s8wMo0B9wWh2jHD0o+UWOxFxA3mJbzqLw6S4qW2chrkdLSmpd
# n2Y0MWFBtZYQ4tj3sdnc47LH2vu4QyyjNuxWxxXitQqq6uuL7IVbjkEEn86Zcb7Q
# /S04ZsbQEYyix/Jun3cvSPkWmyMs7tl9HWBv0a6b0cWS1wGZ4nkheD6nVsGIG/sf
# vrN5IKtsOTJL6y0wjS3dpGSvDFjcUhEyqMl7klkgg6g74c4JPp2iWvyJ0dHCHPb2
# 1qd449eg4g6WtRTR0HwdSCw2xSTzAsS4eA8sItGsBpY4nJ/+G6GCFv8wghb7Bgor
# BgEEAYI3AwMBMYIW6zCCFucGCSqGSIb3DQEHAqCCFtgwghbUAgEDMQ8wDQYJYIZI
# AWUDBAIBBQAwggFRBgsqhkiG9w0BCRABBKCCAUAEggE8MIIBOAIBAQYKKwYBBAGE
# WQoDATAxMA0GCWCGSAFlAwQCAQUABCBX3dHgf3rorKjuNWRyH72EKrqN2mxYXg1Z
# spBDnhDj1QIGZK/4exneGBMyMDIzMDcxMzE5Mjc0Ny4xODZaMASAAgH0oIHQpIHN
# MIHKMQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMH
# UmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSUwIwYDVQQL
# ExxNaWNyb3NvZnQgQW1lcmljYSBPcGVyYXRpb25zMSYwJAYDVQQLEx1UaGFsZXMg
# VFNTIEVTTjpENkJELUUzRTctMTY4NTElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUt
# U3RhbXAgU2VydmljZaCCEVYwggcMMIIE9KADAgECAhMzAAABx/sAoEpb8ifcAAEA
# AAHHMA0GCSqGSIb3DQEBCwUAMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNo
# aW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29y
# cG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEw
# MB4XDTIyMTEwNDE5MDEzNVoXDTI0MDIwMjE5MDEzNVowgcoxCzAJBgNVBAYTAlVT
# MRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQK
# ExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJTAjBgNVBAsTHE1pY3Jvc29mdCBBbWVy
# aWNhIE9wZXJhdGlvbnMxJjAkBgNVBAsTHVRoYWxlcyBUU1MgRVNOOkQ2QkQtRTNF
# Ny0xNjg1MSUwIwYDVQQDExxNaWNyb3NvZnQgVGltZS1TdGFtcCBTZXJ2aWNlMIIC
# IjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr0LcVtnatNFMBrQTtG9P8ISA
# PyyGmxNfhEzaOVlt088pBUFAIasmN/eOijE6Ucaf3c2bVnN/02ih0smSqYkm5P3Z
# wU7ZW202b6cPDJjXcrjJj0qfnuccBtE3WU0vZ8CiQD7qrKxeF8YBNcS+PVtvsqhd
# 5YW6AwhWqhjw1mYuLetF5b6aPif/3RzlyqG3SV7QPiSJends7gG435Rsy1HJ4Xnq
# ztOJR41I0j3EQ05JMF5QNRi7kT6vXTT+MHVj27FVQ7bef/U+2EAbFj2X2AOWbvgl
# YaYnM3m/I/OWDHUgGw8KIdsDh3W1eusnF2D7oenGgtahs+S1G5Uolf5ESg/9Z+38
# rhQwLgokY5k6p8k5arYWtszdJK6JiIRl843H74k7+QqlT2LbAQPq8ivQv0gdclW2
# aJun1KrW+v52R3vAHCOtbUmxvD1eNGHqGqLagtlq9UFXKXuXnqXJqruCYmfwdFMD
# 0UP6ii1lFdeKL87PdjdAwyCiVcCEoLnvDzyvjNjxtkTdz6R4yF1N/X4PSQH4Flgs
# lyBIXggaSlPtvPuxAtuac/ITj4k0IRShGiYLBM2Dw6oesLOoxe07OUPO+qXXOcJM
# VHhE0MlhhnxfN2B1JWFPWwQ6ooWiqAOQDqzcDx+79shxA1Cx0K70eOBplMog27gY
# oLpBv7nRz4tHqoTyvA0CAwEAAaOCATYwggEyMB0GA1UdDgQWBBQFUNLdHD7BAF/V
# U/X/eEHLiUSSIDAfBgNVHSMEGDAWgBSfpxVdAF5iXYP05dJlpxtTNRnpcjBfBgNV
# HR8EWDBWMFSgUqBQhk5odHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2Ny
# bC9NaWNyb3NvZnQlMjBUaW1lLVN0YW1wJTIwUENBJTIwMjAxMCgxKS5jcmwwbAYI
# KwYBBQUHAQEEYDBeMFwGCCsGAQUFBzAChlBodHRwOi8vd3d3Lm1pY3Jvc29mdC5j
# b20vcGtpb3BzL2NlcnRzL01pY3Jvc29mdCUyMFRpbWUtU3RhbXAlMjBQQ0ElMjAy
# MDEwKDEpLmNydDAMBgNVHRMBAf8EAjAAMBMGA1UdJQQMMAoGCCsGAQUFBwMIMA0G
# CSqGSIb3DQEBCwUAA4ICAQDQy5c8ogP0y8xAsLVca07wWy1mT+nqYgAFnz2972kN
# O+KJ7AE4f+SVbvOnkeeuOPq3xc+6TS8g3FuKKYEwYqvnRHxX58tjlscZsZeKnu7f
# GNUlpNT9bOQFHWALURuoXp8TLHhxj3PEq9jzFYBP2YNMLol70ojY1qpze3nMMJfp
# durdBBpaOLlJmRNTLhxd+RJGJQbY1XAcx6p/FigwqBasSDUxp+0yFPEBB9uBE3KI
# LAtq6fczGp4EMeon6YmkyCGAtXMKDFQQgdP/ITe7VghAVbPTVlP3hY1dFgc+t8YK
# 2obFSFVKslkASATDHulCMht+WrIsukclEUP9DaMmpq7S0RLODMicI6PtqqGOhdna
# RltA0d+Wf+0tPt9SUVtrPJyO7WMPKbykCRXzmHK06zr0kn1YiUYNXCsOgaHF5ImO
# 2ZwQ54UE1I55jjUdldyjy/UPJgxRm9NyXeO7adYr8K8f6Q2nPF0vWqFG7ewwaAl5
# ClKerzshfhB8zujVR0d1Ra7Z01lnXYhWuPqVZayFl7JHr6i6huhpU6BQ6/VgY0cB
# iksX4mNM+ISY81T1RYt7fWATNu/zkjINczipzbfg5S+3fCAo8gVB6+6A5L0vBg39
# dsFITv6MWJuQ8ZZy7fwlFBZE4d5IFbRudakNwKGdyLGM2otaNq7wm3ku7x41UGAm
# kDCCB3EwggVZoAMCAQICEzMAAAAVxedrngKbSZkAAAAAABUwDQYJKoZIhvcNAQEL
# BQAwgYgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQH
# EwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xMjAwBgNV
# BAMTKU1pY3Jvc29mdCBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eSAyMDEwMB4X
# DTIxMDkzMDE4MjIyNVoXDTMwMDkzMDE4MzIyNVowfDELMAkGA1UEBhMCVVMxEzAR
# BgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1p
# Y3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3Rh
# bXAgUENBIDIwMTAwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDk4aZM
# 57RyIQt5osvXJHm9DtWC0/3unAcH0qlsTnXIyjVX9gF/bErg4r25PhdgM/9cT8dm
# 95VTcVrifkpa/rg2Z4VGIwy1jRPPdzLAEBjoYH1qUoNEt6aORmsHFPPFdvWGUNzB
# RMhxXFExN6AKOG6N7dcP2CZTfDlhAnrEqv1yaa8dq6z2Nr41JmTamDu6GnszrYBb
# fowQHJ1S/rboYiXcag/PXfT+jlPP1uyFVk3v3byNpOORj7I5LFGc6XBpDco2LXCO
# Mcg1KL3jtIckw+DJj361VI/c+gVVmG1oO5pGve2krnopN6zL64NF50ZuyjLVwIYw
# XE8s4mKyzbnijYjklqwBSru+cakXW2dg3viSkR4dPf0gz3N9QZpGdc3EXzTdEonW
# /aUgfX782Z5F37ZyL9t9X4C626p+Nuw2TPYrbqgSUei/BQOj0XOmTTd0lBw0gg/w
# EPK3Rxjtp+iZfD9M269ewvPV2HM9Q07BMzlMjgK8QmguEOqEUUbi0b1qGFphAXPK
# Z6Je1yh2AuIzGHLXpyDwwvoSCtdjbwzJNmSLW6CmgyFdXzB0kZSU2LlQ+QuJYfM2
# BjUYhEfb3BvR/bLUHMVr9lxSUV0S2yW6r1AFemzFER1y7435UsSFF5PAPBXbGjfH
# CBUYP3irRbb1Hode2o+eFnJpxq57t7c+auIurQIDAQABo4IB3TCCAdkwEgYJKwYB
# BAGCNxUBBAUCAwEAATAjBgkrBgEEAYI3FQIEFgQUKqdS/mTEmr6CkTxGNSnPEP8v
# BO4wHQYDVR0OBBYEFJ+nFV0AXmJdg/Tl0mWnG1M1GelyMFwGA1UdIARVMFMwUQYM
# KwYBBAGCN0yDfQEBMEEwPwYIKwYBBQUHAgEWM2h0dHA6Ly93d3cubWljcm9zb2Z0
# LmNvbS9wa2lvcHMvRG9jcy9SZXBvc2l0b3J5Lmh0bTATBgNVHSUEDDAKBggrBgEF
# BQcDCDAZBgkrBgEEAYI3FAIEDB4KAFMAdQBiAEMAQTALBgNVHQ8EBAMCAYYwDwYD
# VR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBTV9lbLj+iiXGJo0T2UkFvXzpoYxDBW
# BgNVHR8ETzBNMEugSaBHhkVodHRwOi8vY3JsLm1pY3Jvc29mdC5jb20vcGtpL2Ny
# bC9wcm9kdWN0cy9NaWNSb29DZXJBdXRfMjAxMC0wNi0yMy5jcmwwWgYIKwYBBQUH
# AQEETjBMMEoGCCsGAQUFBzAChj5odHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtp
# L2NlcnRzL01pY1Jvb0NlckF1dF8yMDEwLTA2LTIzLmNydDANBgkqhkiG9w0BAQsF
# AAOCAgEAnVV9/Cqt4SwfZwExJFvhnnJL/Klv6lwUtj5OR2R4sQaTlz0xM7U518Jx
# Nj/aZGx80HU5bbsPMeTCj/ts0aGUGCLu6WZnOlNN3Zi6th542DYunKmCVgADsAW+
# iehp4LoJ7nvfam++Kctu2D9IdQHZGN5tggz1bSNU5HhTdSRXud2f8449xvNo32X2
# pFaq95W2KFUn0CS9QKC/GbYSEhFdPSfgQJY4rPf5KYnDvBewVIVCs/wMnosZiefw
# C2qBwoEZQhlSdYo2wh3DYXMuLGt7bj8sCXgU6ZGyqVvfSaN0DLzskYDSPeZKPmY7
# T7uG+jIa2Zb0j/aRAfbOxnT99kxybxCrdTDFNLB62FD+CljdQDzHVG2dY3RILLFO
# Ry3BFARxv2T5JL5zbcqOCb2zAVdJVGTZc9d/HltEAY5aGZFrDZ+kKNxnGSgkujhL
# mm77IVRrakURR6nxt67I6IleT53S0Ex2tVdUCbFpAUR+fKFhbHP+CrvsQWY9af3L
# wUFJfn6Tvsv4O+S3Fb+0zj6lMVGEvL8CwYKiexcdFYmNcP7ntdAoGokLjzbaukz5
# m/8K6TT4JDVnK+ANuOaMmdbhIurwJ0I9JZTmdHRbatGePu1+oDEzfbzL6Xu/OHBE
# 0ZDxyKs6ijoIYn/ZcGNTTY3ugm2lBRDBcQZqELQdVTNYs6FwZvKhggLNMIICNgIB
# ATCB+KGB0KSBzTCByjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24x
# EDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlv
# bjElMCMGA1UECxMcTWljcm9zb2Z0IEFtZXJpY2EgT3BlcmF0aW9uczEmMCQGA1UE
# CxMdVGhhbGVzIFRTUyBFU046RDZCRC1FM0U3LTE2ODUxJTAjBgNVBAMTHE1pY3Jv
# c29mdCBUaW1lLVN0YW1wIFNlcnZpY2WiIwoBATAHBgUrDgMCGgMVAOIASP0JSbv5
# R23wxciQivHyckYooIGDMIGApH4wfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldh
# c2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBD
# b3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIw
# MTAwDQYJKoZIhvcNAQEFBQACBQDoWnbzMCIYDzIwMjMwNzEzMjExMzIzWhgPMjAy
# MzA3MTQyMTEzMjNaMHYwPAYKKwYBBAGEWQoEATEuMCwwCgIFAOhadvMCAQAwCQIB
# AAIBEQIB/zAHAgEAAgIRyDAKAgUA6FvIcwIBADA2BgorBgEEAYRZCgQCMSgwJjAM
# BgorBgEEAYRZCgMCoAowCAIBAAIDB6EgoQowCAIBAAIDAYagMA0GCSqGSIb3DQEB
# BQUAA4GBAB1FSRPydnvEFFfS60yPFo/F0snKBYdo/suq0DveDx1PND4wIaakYkeE
# 5Z92fDfIwBpb0ozlzxDuc1Xb15Zy05G/mE1iAYGL83U9jDVCUiGpB8vaU7mzeX+X
# +TNZd4Av+Lj9BJ+SpvihXCYrRqgG7DLLm9HF7Bvij0gGW1UhyW+RMYIEDTCCBAkC
# AQEwgZMwfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNV
# BAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQG
# A1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIwMTACEzMAAAHH+wCgSlvy
# J9wAAQAAAccwDQYJYIZIAWUDBAIBBQCgggFKMBoGCSqGSIb3DQEJAzENBgsqhkiG
# 9w0BCRABBDAvBgkqhkiG9w0BCQQxIgQgNqbdA8XLknmgaDP48aZpKIqLzukLzDM+
# vI9o31ER6okwgfoGCyqGSIb3DQEJEAIvMYHqMIHnMIHkMIG9BCBH5+Xb4lKyRQs5
# 5Vgtt4yCTsd0htESYCyPC1zLowmSyTCBmDCBgKR+MHwxCzAJBgNVBAYTAlVTMRMw
# EQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVN
# aWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0
# YW1wIFBDQSAyMDEwAhMzAAABx/sAoEpb8ifcAAEAAAHHMCIEIHgkbe5TwCZ1EPqy
# IWn3w1iAUlqH9tQPaST/ZdO6j7HQMA0GCSqGSIb3DQEBCwUABIICABz7eSiW91J5
# mc9PGJ8BGFxuhlNWUPb+xJgxUffsKg+qtJTOfAwMJXxNLrPB1JbXYYtpySzHzIbY
# pKbebnYohJ9QE5mmPVNI7CjfJ+APEhT2W1IV5GKLxmfaEhffQ/iekXHFRA+a98ry
# hvNJVHaKe6eOvGVMuu4cN71eBZ869RUkFfmB5+dlx54qBvIy72bE4WSd14GCOETx
# K806Tqv6C/RPHw7zETD317nA/0iakRuiBVS+ab2C4ulkR5OotNOYaOKaQ/DtkBWi
# tBhXz0XBNVnegCyPJUj9Wjj0U9+toKzbnYYQGOXVcMeywxT82Qqy5lXNoC7OmcxE
# pybo64NGCzEDn8DXq/WTA97ZZn5rdHTTOBlbLDdYy68HwlxUSaIdqxJMtnFF7esS
# s+5WpHu1CqwTvaQVwkWQsyudUH9B/N3yUal+5r+vOuesBuR2SbwpKyWac799jUc5
# J03Pmp4I/5LKney+T4Np6PGyOuWPHw96TqhBxJqreNON6q7lbXEx4tY0BkK25N+2
# SAw2Sa6GCuBtOakG6YXjOUZ08YgkG3P9CgUFFsMEjJOvw3Bw2VaCw7YwLJLfZ9jJ
# bgdgaz73SMUDJ5rRJ+QYZ/pUgUjEbVLoxwMA2YtvfZJtPBXz5RZmm3UYJWIXhpik
# MpKxU8VT9Lja8CqGX16rwnEoYVzPxwQH
# SIG # End signature block