commands

Clear

Set-DbaCmConnection


Author	Friedrich Weinmann (@FredWeinmann)
Availability	Windows, Linux, macOS

Want to see the source code for this command? Check out Set-DbaCmConnection on GitHub.
Want to see the Bill Of Health for this command? Check out 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.

Syntax

Set-DbaCmConnection
    [-ComputerName <DbaCmConnectionParameter[]>]
    [-Credential <PSCredential>]
    [-OverrideExplicitCredential]
    [-OverrideConnectionPolicy]
    [-DisabledConnectionTypes {None | CimRM | CimDCOM | Wmi | PowerShellRemoting}]
    [-DisableBadCredentialCache]
    [-DisableCimPersistence]
    [-DisableCredentialAutoRegister]
    [-EnableCredentialFailover]
    [-WindowsCredentialsAreBad]
    [-CimWinRMOptions <WSManSessionOptions>]
    [-CimDCOMOptions <DComSessionOptions>]
    [-AddBadCredential <PSCredential[]>]
    [-RemoveBadCredential <PSCredential[]>]
    [-ClearBadCredential]
    [-ClearCredential]
    [-ResetCredential]
    [-ResetConnectionStatus]
    [-ResetConfiguration]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Set-DbaCmConnection
    [-ComputerName <DbaCmConnectionParameter[]>]
    [-UseWindowsCredentials]
    [-OverrideExplicitCredential]
    [-OverrideConnectionPolicy]
    [-DisabledConnectionTypes {None | CimRM | CimDCOM | Wmi | PowerShellRemoting}]
    [-DisableBadCredentialCache]
    [-DisableCimPersistence]
    [-DisableCredentialAutoRegister]
    [-EnableCredentialFailover]
    [-CimWinRMOptions <WSManSessionOptions>]
    [-CimDCOMOptions <DComSessionOptions>]
    [-AddBadCredential <PSCredential[]>]
    [-RemoveBadCredential <PSCredential[]>]
    [-ClearBadCredential]
    [-ClearCredential]
    [-ResetCredential]
    [-ResetConnectionStatus]
    [-ResetConfiguration]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> 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: 2

PS C:\> 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: 3

PS C:\> Get-DbaCmConnection | Export-Clixml .\connections.xml
PS C:\> 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 re-import 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.

Optional Parameters

-ComputerName

The computer to build the connection object for.


Alias
Required	False
Pipeline	true (ByValue)
Default Value	$env:COMPUTERNAME

-Credential

The credential to register.


Alias
Required	False
Pipeline	false
Default Value

-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.


Alias
Required	False
Pipeline	false
Default Value	False

-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.


Alias
Required	False
Pipeline	false
Default Value	False

-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.


Alias
Required	False
Pipeline	false
Default Value	False

-DisabledConnectionTypes

Explicitly disable connection types. These types will then not be used for connecting to the computer.


Alias
Required	False
Pipeline	false
Default Value	None

-DisableBadCredentialCache

Will prevent the caching of credentials if set to true.


Alias
Required	False
Pipeline	false
Default Value	False

-DisableCimPersistence

Will prevent Cim-Sessions to be reused.


Alias
Required	False
Pipeline	false
Default Value	False

-DisableCredentialAutoRegister

Will prevent working credentials from being automatically cached


Alias
Required	False
Pipeline	false
Default Value	False

-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).


Alias
Required	False
Pipeline	false
Default Value	False

-WindowsCredentialsAreBad

Will prevent the windows credentials of the currently logged on user from being used for the remote connection.


Alias
Required	False
Pipeline	false
Default Value	False

-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.


Alias
Required	False
Pipeline	false
Default Value

-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.


Alias
Required	False
Pipeline	false
Default Value

-AddBadCredential

Adds credentials to the bad credential cache. These credentials will not be used when connecting to the target remote computer.


Alias
Required	False
Pipeline	false
Default Value

-RemoveBadCredential

Removes credentials from the bad credential cache.


Alias
Required	False
Pipeline	false
Default Value

-ClearBadCredential

Clears the cache of credentials that didn't worked. Will be applied before adding entries to the credential cache.


Alias
Required	False
Pipeline	false
Default Value	False

-ClearCredential

Clears the cache of credentials that worked. Will be applied before adding entries to the credential cache.


Alias
Required	False
Pipeline	false
Default Value	False

-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.


Alias
Required	False
Pipeline	false
Default Value	False

-ResetConnectionStatus

Restores all connection status to default, as if no connection protocol had ever been tested.


Alias
Required	False
Pipeline	false
Default Value	False

-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-DbatoolsConfig -Module ComputerManagement".


Alias
Required	False
Pipeline	false
Default Value	False

-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.


Alias
Required	False
Pipeline	false
Default Value	False

-WhatIf

If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.


Alias	wi
Required	False
Pipeline	false
Default Value

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.


Alias	cf
Required	False
Pipeline	false
Default Value