functions/Set-DbaCmConnection.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
function Set-DbaCmConnection {
<#
 .SYNOPSIS
  Configures a connection object for use in remote computer management.
  
 .DESCRIPTION
  Configures a connection object for use in remote computer management.
  This function will either create new records for computers that have no connection registered so far, or it will configure existing connections if already present.
   
  As such it can be handy in making bulk-edits on connections or manually adjusting some settings.
  
 .PARAMETER ComputerName
  The computer to build the connection object for.
  
 .PARAMETER Credential
  The credential to register.
  
 .PARAMETER UseWindowsCredentials
  Whether using the default windows credentials is legit.
  Not setting this will not exclude using windows credentials, but only not pre-confirm them as working.
  
 .PARAMETER OverrideExplicitCredential
  Setting this will enable the credential override.
  The override will cause the system to ignore explicitly specified credentials, so long as known, good credentials are available.
  
 .PARAMETER OverrideConnectionPolicy
  Setting this will configure the connection policy override.
  By default, global configurations enforce, which connection type is available at all and which is disabled.
  
 .PARAMETER DisabledConnectionTypes
  Exlicitly disable connection types.
  These types will then not be used for connecting to the computer.
  
 .PARAMETER DisableBadCredentialCache
  Will prevent the caching of credentials if set to true.
  
 .PARAMETER DisableCimPersistence
  Will prevent Cim-Sessions to be reused.
  
 .PARAMETER DisableCredentialAutoRegister
  Will prevent working credentials from being automatically cached
  
 .PARAMETER EnableCredentialFailover
  Will enable automatic failing over to known to work credentials, when using bad credentials.
  By default, passing bad credentials will cause the Computer Management functions to interrupt with a warning (Or exception if in silent mode).
  
 .PARAMETER WindowsCredentialsAreBad
  Will prevent the windows credentials of the currently logged on user from being used for the remote connection.
  
 .PARAMETER CimWinRMOptions
  Specify a set of options to use when connecting to the target computer using CIM over WinRM.
  Use 'New-CimSessionOption' to create such an object.
  
 .PARAMETER CimDCOMOptions
  Specify a set of options to use when connecting to the target computer using CIM over DCOM.
  Use 'New-CimSessionOption' to create such an object.
  
 .PARAMETER AddBadCredential
  Adds credentials to the bad credential cache.
  These credentials will not be used when connecting to the target remote computer.
  
 .PARAMETER RemoveBadCredential
  Removes credentials from the bad credential cache.
  
 .PARAMETER ClearBadCredential
  Clears the cache of credentials that didn't worked.
  Will be applied before adding entries to the credential cache.
  
 .PARAMETER ClearCredential
  Clears the cache of credentials that worked.
  Will be applied before adding entries to the credential cache.
  
 .PARAMETER ResetCredential
  Resets all credential-related caches:
  - Clears bad credential cache
  - Removes last working credential
  - Un-Confirms the windows credentials as working
  - Un-Confirms the windows credentials as not working
   
  Automatically implies the parameters -ClearCredential and -ClearBadCredential. Using them together is redundant.
  Will be applied before adding entries to the credential cache.
  
 .PARAMETER ResetConnectionStatus
  Restores all connection stati to default, as if no connection protocol had ever been tested.
  
 .PARAMETER ResetConfiguration
  Restores the configuration back to system default.
  Configuration elements are the basic behavior controlling settings, such as whether to cache bad credentials, etc.
  These can be configured globally using the dbatools configuration system and overridden locally on a per-connection basis.
  For a list of all available settings, use "Get-DbaConfig -Module ComputerManagement".
  
 .PARAMETER EnableException
  By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
  This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
  Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
   
 .EXAMPLE
  Get-DbaCmConnection sql2014 | Set-DbaCmConnection -ClearBadCredential -UseWindowsCredentials
   
  Retrieves the already existing connection to sql2014, removes the list of not working credentials and configures it to default to the credentials of the logged on user.
  
 .EXAMPLE
  Get-DbaCmConnection | Set-DbaCmConnection -RemoveBadCredential $cred
  Removes the credentials stored in $cred from all connections' list of "known to not work" credentials.
  Handy to update changes in privilege.
  
 .EXAMPLE
  Get-DbaCmConnection | Export-Clixml .\connections.xml
  Import-Clixml .\connections.xml | Set-DbaCmConnection -ResetConfiguration
   
  At first, the current cached connections are stored in an xml file. At a later time - possibly in the profile when starting the console again - those connections are imported again and applied again to the connection cache.
   
  In this example, the configuration settings will also be reset, since after reimport those will be set to explicit, rather than deriving them from the global settings.
  In many cases, using the default settings is desirable. For specific settings, use New-DbaCmConnection as part of the profile in order to explicitly configure a connection.
#>

    [CmdletBinding(DefaultParameterSetName = 'Credential')]
    param (
        [Parameter(ValueFromPipeline = $true)]
        [Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]]
        $ComputerName = $env:COMPUTERNAME,

        [Parameter(ParameterSetName = "Credential")]
        [PSCredential]
        $Credential,

        [Parameter(ParameterSetName = "Windows")]
        [switch]
        $UseWindowsCredentials,

        [switch]
        $OverrideExplicitCredential,
        
        [switch]
        $OverrideConnectionPolicy,

        [Sqlcollaborative.Dbatools.Connection.ManagementConnectionType]
        $DisabledConnectionTypes = 'None',

        [switch]
        $DisableBadCredentialCache,

        [switch]
        $DisableCimPersistence,

        [switch]
        $DisableCredentialAutoRegister,

        [switch]
        $EnableCredentialFailover,

        [Parameter(ParameterSetName = "Credential")]
        [switch]
        $WindowsCredentialsAreBad,

        [Microsoft.Management.Infrastructure.Options.WSManSessionOptions]
        $CimWinRMOptions,

        [Microsoft.Management.Infrastructure.Options.DComSessionOptions]
        $CimDCOMOptions,

        [System.Management.Automation.PSCredential[]]
        $AddBadCredential,

        [System.Management.Automation.PSCredential[]]
        $RemoveBadCredential,

        [switch]
        $ClearBadCredential,

        [switch]
        $ClearCredential,

        [switch]
        $ResetCredential,

        [switch]
        $ResetConnectionStatus,

        [switch]
        $ResetConfiguration,

        [switch]
        [Alias('Silent')]$EnableException
    )

    BEGIN {
        Write-Message -Level InternalComment -Message "Starting execution"
        Write-Message -Level Verbose -Message "Bound parameters: $($PSBoundParameters.Keys -join ", ")"

        $disable_cache = Get-DbaConfigValue -Name 'ComputerManagement.Cache.Disable.All' -Fallback $false
    }
    PROCESS {
        foreach ($connectionObject in $ComputerName) {
            if (-not $connectionObject.Success) { Stop-Function -Message "Failed to interpret computername input: $($connectionObject.InputObject)" -Category InvalidArgument -Target $connectionObject.InputObject -Continue }
            Write-Message -Level VeryVerbose -Message "Processing computer: $($connectionObject.Connection.ComputerName)"

            $connection = $connectionObject.Connection

            if ($ResetConfiguration) {
                Write-Message -Level Verbose -Message "Resetting the configuration to system default"

                $connection.RestoreDefaultConfiguration()
            }

            if ($ResetConnectionStatus) {
                Write-Message -Level Verbose -Message "Resetting the connection status"

                $connection.CimRM = 'Unknown'
                $connection.CimDCOM = 'Unknown'
                $connection.Wmi = 'Unknown'
                $connection.PowerShellRemoting = 'Unknown'

                $connection.LastCimRM = New-Object System.DateTime(0)
                $connection.LastCimDCOM = New-Object System.DateTime(0)
                $connection.LastWmi = New-Object System.DateTime(0)
                $connection.LastPowerShellRemoting = New-Object System.DateTime(0)
            }

            if ($ResetCredential) {
                Write-Message -Level Verbose -Message "Resetting credentials"

                $connection.KnownBadCredentials.Clear()
                $connection.Credentials = $null
                $connection.UseWindowsCredentials = $false
                $connection.WindowsCredentialsAreBad = $false
            }
            else {
                if ($ClearBadCredential) {
                    Write-Message -Level Verbose -Message "Clearing bad credentials"

                    $connection.KnownBadCredentials.Clear()
                    $connection.WindowsCredentialsAreBad = $false
                }

                if ($ClearCredential) {
                    Write-Message -Level Verbose -Message "Clearing credentials"

                    $connection.Credentials = $null
                    $connection.UseWindowsCredentials = $false
                }
            }

            foreach ($badCred in $RemoveBadCredential) {
                $connection.RemoveBadCredential($badCred)
            }

            foreach ($badCred in $AddBadCredential) {
                $connection.AddBadCredential($badCred)
            }

            if (Test-Bound "Credential") { $connection.Credentials = $Credential }
            if ($UseWindowsCredentials) {
                $connection.Credentials = $null
                $connection.UseWindowsCredentials = $UseWindowsCredentials
            }
            if (Test-Bound "OverrideExplicitCredential") { $connection.OverrideExplicitCredential = $OverrideExplicitCredential }
            if (Test-Bound "DisabledConnectionTypes") { $connection.DisabledConnectionTypes = $DisabledConnectionTypes }
            if (Test-Bound "DisableBadCredentialCache") { $connection.DisableBadCredentialCache = $DisableBadCredentialCache }
            if (Test-Bound "DisableCimPersistence") { $connection.DisableCimPersistence = $DisableCimPersistence }
            if (Test-Bound "DisableCredentialAutoRegister") { $connection.DisableCredentialAutoRegister = $DisableCredentialAutoRegister }
            if (Test-Bound "EnableCredentialFailover") { $connection.DisableCredentialAutoRegister = $EnableCredentialFailover }
            if (Test-Bound "WindowsCredentialsAreBad") { $connection.WindowsCredentialsAreBad = $WindowsCredentialsAreBad }
            if (Test-Bound "CimWinRMOptions") { $connection.CimWinRMOptions = $CimWinRMOptions }
            if (Test-Bound "CimDCOMOptions") { $connection.CimDCOMOptions = $CimDCOMOptions }
            if (Test-Bound "OverrideConnectionPolicy") { $connection.OverrideConnectionPolicy = $OverrideConnectionPolicy }
            
            if (-not $disable_cache) {
                Write-Message -Level Verbose -Message "Writing connection to cache"
                [Sqlcollaborative.Dbatools.Connection.ConnectionHost]::Connections[$connectionObject.Connection.ComputerName] = $connection
            }
            else { Write-Message -Level Verbose -Message "Skipping writing to cache, since the cache has been disabled!" }
            $connection
        }
    }
    END {
        Write-Message -Level InternalComment -Message "Stopping execution"
    }
}