< Back
Set-DbaCmConnection
Post
NAME Set-DbaCmConnection
SYNOPSIS
Configures a connection object for use in remote computer management.
SYNTAX
Set-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>] [-Credential
<Pscredential>] [-OverrideExplicitCredential <Switch>] [-OverrideConnectionPolicy <Switch>]
[-DisabledConnectionTypes <Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
[-DisableBadCredentialCache <Switch>] [-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>]
[-EnableCredentialFailover <Switch>] [-WindowsCredentialsAreBad <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-AddBadCredential
<System.Management.Automation.PSCredential[]>] [-RemoveBadCredential
<System.Management.Automation.PSCredential[]>] [-ClearBadCredential <Switch>] [-ClearCredential <Switch>]
[-ResetCredential <Switch>] [-ResetConnectionStatus <Switch>] [-ResetConfiguration <Switch>] [-EnableException
<Switch>] [<CommonParameters>]
Set-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
[-UseWindowsCredentials <Switch>] [-OverrideExplicitCredential <Switch>] [-OverrideConnectionPolicy <Switch>]
[-DisabledConnectionTypes <Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
[-DisableBadCredentialCache <Switch>] [-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>]
[-EnableCredentialFailover <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-AddBadCredential
<System.Management.Automation.PSCredential[]>] [-RemoveBadCredential
<System.Management.Automation.PSCredential[]>] [-ClearBadCredential <Switch>] [-ClearCredential <Switch>]
[-ResetCredential <Switch>] [-ResetConnectionStatus <Switch>] [-ResetConfiguration <Switch>] [-EnableException
<Switch>] [<CommonParameters>]
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.
PARAMETERS
-AddBadCredential [<System.Management.Automation.PSCredential[]>]
Adds credentials to the bad credential cache.
These credentials will not be used when connecting to the target remote computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimDCOMOptions [<Microsoft.Management.Infrastructure.Options.DComSessionOptions>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimWinRMOptions [<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ClearBadCredential [<Switch>]
Clears the cache of credentials that didn't worked.
Will be applied before adding entries to the credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ClearCredential [<Switch>]
Clears the cache of credentials that worked.
Will be applied before adding entries to the credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ComputerName [<Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
The computer to build the connection object for.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-Credential [<Pscredential>]
The credential to register.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableBadCredentialCache [<Switch>]
Will prevent the caching of credentials if set to true.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCimPersistence [<Switch>]
Will prevent Cim-Sessions to be reused.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCredentialAutoRegister [<Switch>]
Will prevent working credentials from being automatically cached
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisabledConnectionTypes [<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
Explicitly disable connection types.
These types will then not be used for connecting to the computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableCredentialFailover [<Switch>]
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).
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideConnectionPolicy [<Switch>]
Setting this will configure the connection policy override.
By default, global configurations enforce, which connection type is available at all and which is disabled.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideExplicitCredential [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-RemoveBadCredential [<System.Management.Automation.PSCredential[]>]
Removes credentials from the bad credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetConfiguration [<Switch>]
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".
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetConnectionStatus [<Switch>]
Restores all connection status to default, as if no connection protocol had ever been tested.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetCredential [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-UseWindowsCredentials [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-WindowsCredentialsAreBad [<Switch>]
Will prevent the windows credentials of the currently logged on user from being used for the remote connection.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
NOTES
Tags: ComputerManagement, CIM
Author: Friedrich Weinmann (@FredWeinmann)
Website: https://dbatools.io
Copyright: (c) 2018 by dbatools, licensed under MIT
License: MIT https://opensource.org/licenses/MIT
-------------------------- 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.
RELATED LINKS
https://dbatools.io/set-DbaCmConnection
SYNOPSIS
Configures a connection object for use in remote computer management.
SYNTAX
Set-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>] [-Credential
<Pscredential>] [-OverrideExplicitCredential <Switch>] [-OverrideConnectionPolicy <Switch>]
[-DisabledConnectionTypes <Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
[-DisableBadCredentialCache <Switch>] [-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>]
[-EnableCredentialFailover <Switch>] [-WindowsCredentialsAreBad <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-AddBadCredential
<System.Management.Automation.PSCredential[]>] [-RemoveBadCredential
<System.Management.Automation.PSCredential[]>] [-ClearBadCredential <Switch>] [-ClearCredential <Switch>]
[-ResetCredential <Switch>] [-ResetConnectionStatus <Switch>] [-ResetConfiguration <Switch>] [-EnableException
<Switch>] [<CommonParameters>]
Set-DbaCmConnection [-ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
[-UseWindowsCredentials <Switch>] [-OverrideExplicitCredential <Switch>] [-OverrideConnectionPolicy <Switch>]
[-DisabledConnectionTypes <Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
[-DisableBadCredentialCache <Switch>] [-DisableCimPersistence <Switch>] [-DisableCredentialAutoRegister <Switch>]
[-EnableCredentialFailover <Switch>] [-CimWinRMOptions
<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>] [-CimDCOMOptions
<Microsoft.Management.Infrastructure.Options.DComSessionOptions>] [-AddBadCredential
<System.Management.Automation.PSCredential[]>] [-RemoveBadCredential
<System.Management.Automation.PSCredential[]>] [-ClearBadCredential <Switch>] [-ClearCredential <Switch>]
[-ResetCredential <Switch>] [-ResetConnectionStatus <Switch>] [-ResetConfiguration <Switch>] [-EnableException
<Switch>] [<CommonParameters>]
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.
PARAMETERS
-AddBadCredential [<System.Management.Automation.PSCredential[]>]
Adds credentials to the bad credential cache.
These credentials will not be used when connecting to the target remote computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimDCOMOptions [<Microsoft.Management.Infrastructure.Options.DComSessionOptions>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-CimWinRMOptions [<Microsoft.Management.Infrastructure.Options.WSManSessionOptions>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ClearBadCredential [<Switch>]
Clears the cache of credentials that didn't worked.
Will be applied before adding entries to the credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ClearCredential [<Switch>]
Clears the cache of credentials that worked.
Will be applied before adding entries to the credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ComputerName [<Sqlcollaborative.Dbatools.Parameter.DbaCmConnectionParameter[]>]
The computer to build the connection object for.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-Credential [<Pscredential>]
The credential to register.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableBadCredentialCache [<Switch>]
Will prevent the caching of credentials if set to true.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCimPersistence [<Switch>]
Will prevent Cim-Sessions to be reused.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisableCredentialAutoRegister [<Switch>]
Will prevent working credentials from being automatically cached
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-DisabledConnectionTypes [<Sqlcollaborative.Dbatools.Connection.ManagementConnectionType>]
Explicitly disable connection types.
These types will then not be used for connecting to the computer.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableCredentialFailover [<Switch>]
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).
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-EnableException [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideConnectionPolicy [<Switch>]
Setting this will configure the connection policy override.
By default, global configurations enforce, which connection type is available at all and which is disabled.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-OverrideExplicitCredential [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-RemoveBadCredential [<System.Management.Automation.PSCredential[]>]
Removes credentials from the bad credential cache.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetConfiguration [<Switch>]
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".
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetConnectionStatus [<Switch>]
Restores all connection status to default, as if no connection protocol had ever been tested.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-ResetCredential [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-UseWindowsCredentials [<Switch>]
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.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
-WindowsCredentialsAreBad [<Switch>]
Will prevent the windows credentials of the currently logged on user from being used for the remote connection.
Required? false
Position? named
Default value
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
NOTES
Tags: ComputerManagement, CIM
Author: Friedrich Weinmann (@FredWeinmann)
Website: https://dbatools.io
Copyright: (c) 2018 by dbatools, licensed under MIT
License: MIT https://opensource.org/licenses/MIT
-------------------------- 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.
RELATED LINKS
https://dbatools.io/set-DbaCmConnection