diff --git a/private/functions/Get-DecryptedObject.ps1 b/private/functions/Get-DecryptedObject.ps1 index dd892409397..4dba3cf6e68 100644 --- a/private/functions/Get-DecryptedObject.ps1 +++ b/private/functions/Get-DecryptedObject.ps1 @@ -8,6 +8,12 @@ function Get-DecryptedObject { This is necessary because SQL Server does not allow retrieval of plaintext passwords for security reasons. By leveraging the service master key and the encryption mechanism used by SQL Server, this function can extract the actual passwords for credentials and linked servers. + Two connections to the instance are needed and both are established from the machine running the command: + - The dedicated admin connection (DAC) passed in as SqlInstance, needed to read master.sys.syslnklgns and sys.sysobjvalues. Callers open it with Connect-DbaInstance -DedicatedAdminConnection, so it is a remote DAC and the instance needs remote admin connections enabled and its DAC port reachable. + - PowerShell remoting to the Windows host, needed to unprotect the service master key with the entropy stored in the registry. + + Up to dbatools 2.7 this function opened a local DAC itself from inside the PowerShell remoting session, which did not need remote admin connections. That was removed in #10174 so that one DAC can be opened early and shared across all commands that need it, because SQL Server only allows one DAC per instance. + This function is used by the following public functions: - Copy-DbaCredential - Copy-DbaDbMail diff --git a/public/Copy-DbaCredential.ps1 b/public/Copy-DbaCredential.ps1 index 37bdbd198ff..e5439ec0cf1 100644 --- a/public/Copy-DbaCredential.ps1 +++ b/public/Copy-DbaCredential.ps1 @@ -8,7 +8,14 @@ function Copy-DbaCredential { This is essential for server migrations, disaster recovery setup, or environment synchronization where you need to move service accounts, proxy credentials, or linked server authentication without having to reset passwords or contact application teams for credentials. - The function requires sysadmin privileges on both servers, Windows administrator access, and DAC enabled on the source instance. It supports filtering by credential name or identity and can handle cryptographic provider credentials used for Extensible Key Management (EKM). + It supports filtering by credential name or identity and can handle cryptographic provider credentials used for Extensible Key Management (EKM). + + Decrypting the stored passwords needs sysadmin privileges on both servers plus two connections to the source instance, so make sure both are possible: + + - A dedicated admin connection (DAC), which this command opens from the machine you run it on. That makes it a remote DAC, so the source instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. + - PowerShell remoting to the Windows host of the source instance, used to read the service master key out of the registry. This needs Windows administrator rights on that host. + + Use -ExcludePassword to skip password decryption entirely; neither connection is opened then. Credit: Based on password decryption techniques by Antti Rantasaari (NetSPI, 2014) https://blog.netspi.com/decrypting-mssql-database-link-server-passwords/ @@ -16,7 +23,7 @@ function Copy-DbaCredential { .PARAMETER Source Source SQL Server. You must have sysadmin access and server version must be SQL Server version 2005 or higher. - You must be able to open a dedicated admin connection (DAC) to the source SQL Server. + Unless -ExcludePassword is used, you must be able to open a dedicated admin connection (DAC) to the source SQL Server from the machine you run this command on. .PARAMETER SourceSqlCredential Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential). @@ -61,6 +68,7 @@ function Copy-DbaCredential { .PARAMETER ExcludePassword Copies credential definitions without the actual password values. Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the copy then needs neither. .PARAMETER Force Overwrites existing credentials on the destination server by dropping and recreating them with the source values. @@ -89,7 +97,7 @@ function Copy-DbaCredential { - PowerShell Version 3.0 - Administrator access on Windows - sysadmin access on SQL Server. - - DAC access enabled for local (default) + - unless -ExcludePassword is used: a remote dedicated admin connection (DAC) to the source instance, and Windows administrator access to its host over PowerShell remoting .OUTPUTS PSCustomObject (MigrationObject type) diff --git a/public/Copy-DbaDbMail.ps1 b/public/Copy-DbaDbMail.ps1 index 05197409494..afe7e8e98f1 100644 --- a/public/Copy-DbaDbMail.ps1 +++ b/public/Copy-DbaDbMail.ps1 @@ -10,6 +10,13 @@ function Copy-DbaDbMail { The function preserves all SMTP authentication details including encrypted passwords, handles name conflicts with optional force replacement, and can enable Database Mail on the destination if it's enabled on the source. You can migrate specific component types or the entire configuration in one operation. + Decrypting the stored passwords needs two connections to the source instance, so make sure both are possible: + + - A dedicated admin connection (DAC), which this command opens from the machine you run it on. That makes it a remote DAC, so the source instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. + - PowerShell remoting to the Windows host of the source instance, used to read the service master key out of the registry. This needs Windows administrator rights on that host. + + Use -ExcludePassword to skip password decryption entirely; neither connection is opened then. + .PARAMETER Source Specifies the source SQL Server instance containing the Database Mail configuration to copy. The function reads all mail profiles, accounts, mail servers, and configuration values from this instance. You must have sysadmin privileges to access the MSDB database where Database Mail settings are stored. @@ -44,6 +51,7 @@ function Copy-DbaDbMail { .PARAMETER ExcludePassword Copies credential definitions without the actual password values. Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the copy then needs neither. .PARAMETER 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. @@ -68,7 +76,7 @@ function Copy-DbaDbMail { Copyright: (c) 2018 by dbatools, licensed under MIT License: MIT https://opensource.org/licenses/MIT - Requires: sysadmin access on SQL Servers + Requires: sysadmin access on SQL Servers, and unless -ExcludePassword is used a remote dedicated admin connection (DAC) to the source instance plus Windows administrator access to its host over PowerShell remoting .OUTPUTS PSCustomObject (MigrationObject) diff --git a/public/Copy-DbaLinkedServer.ps1 b/public/Copy-DbaLinkedServer.ps1 index be33cee85ce..9af265efe94 100644 --- a/public/Copy-DbaLinkedServer.ps1 +++ b/public/Copy-DbaLinkedServer.ps1 @@ -10,6 +10,13 @@ function Copy-DbaLinkedServer { When upgrading from older versions to SQL Server 2025+, MSOLEDBSQL is changed to MSOLEDBSQL19 and provider string for encrypt and trustservercertificate settings is added if not already included to ensure compatibility with the breaking changes in the new driver. + Decrypting the stored passwords needs two connections to the source instance, so make sure both are possible: + + - A dedicated admin connection (DAC), which this command opens from the machine you run it on. That makes it a remote DAC, so the source instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. + - PowerShell remoting to the Windows host of the source instance, used to read the service master key out of the registry. This needs Windows administrator rights on that host. + + Use -ExcludePassword to skip password decryption entirely; neither connection is opened then. + Credit: Password decryption techniques provided by Antti Rantasaari (NetSPI, 2014) - https://blog.netspi.com/decrypting-mssql-database-link-server-passwords/ .PARAMETER Source @@ -55,6 +62,7 @@ function Copy-DbaLinkedServer { .PARAMETER ExcludePassword Copies linked server definitions without migrating stored passwords or sensitive authentication data. Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the copy then needs neither. Linked servers will be created but authentication credentials will need to be reconfigured. .PARAMETER WhatIf @@ -94,7 +102,7 @@ function Copy-DbaLinkedServer { Copyright: (c) 2018 by dbatools, licensed under MIT License: MIT https://opensource.org/licenses/MIT - Requires: sysadmin access on SQL Servers + Requires: sysadmin access on SQL Servers, and unless -ExcludePassword is used a remote dedicated admin connection (DAC) to the source instance plus Windows administrator access to its host over PowerShell remoting Limitations: This just copies the SQL portion. It does not copy files (i.e. a local SQLite database, or Microsoft Access DB), nor does it configure ODBC entries. .LINK diff --git a/public/Export-DbaCredential.ps1 b/public/Export-DbaCredential.ps1 index be73268157d..0f18e9d94ce 100644 --- a/public/Export-DbaCredential.ps1 +++ b/public/Export-DbaCredential.ps1 @@ -6,9 +6,14 @@ function Export-DbaCredential { .DESCRIPTION Exports SQL Server credentials to T-SQL files containing CREATE CREDENTIAL statements that can recreate the credentials on another instance. By default, this includes decrypted passwords, making it perfect for migration scenarios where you need to move credentials between servers. - The function generates executable T-SQL scripts that DBAs can run to recreate credentials during migrations, disaster recovery, or when setting up new environments. When passwords are included, the function requires sysadmin privileges and remote Windows registry access to decrypt the stored secrets. + The function generates executable T-SQL scripts that DBAs can run to recreate credentials during migrations, disaster recovery, or when setting up new environments. - Use the ExcludePassword parameter to export credential definitions without sensitive data for documentation or security-conscious scenarios. + Decrypting the stored passwords needs sysadmin privileges plus two connections to the instance, so make sure both are possible: + + - A dedicated admin connection (DAC), which this command opens from the machine you run it on. That makes it a remote DAC, so the instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. + - PowerShell remoting to the Windows host of the instance, used to read the service master key out of the registry. This needs Windows administrator rights on that host. + + Use the ExcludePassword parameter to export credential definitions without sensitive data for documentation or security-conscious scenarios. Neither connection above is opened then. .PARAMETER SqlInstance The target SQL Server instance or instances. @@ -40,6 +45,7 @@ function Export-DbaCredential { .PARAMETER ExcludePassword Exports credential definitions without the actual password values, replacing them with placeholder text. Use this for documentation purposes or when you need credential structure without sensitive data for security reviews. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the export then needs neither. .PARAMETER Append Adds the exported credential scripts to an existing file instead of overwriting it. @@ -62,6 +68,10 @@ function Export-DbaCredential { Copyright: (c) 2018 by dbatools, licensed under MIT License: MIT https://opensource.org/licenses/MIT + Requires: + - sysadmin access on SQL Server + - unless -ExcludePassword is used: a remote dedicated admin connection (DAC) to the instance, and Windows administrator access to its host over PowerShell remoting + .LINK https://dbatools.io/Export-DbaCredential diff --git a/public/Export-DbaInstance.ps1 b/public/Export-DbaInstance.ps1 index 04e3944116b..4c5904d463a 100644 --- a/public/Export-DbaInstance.ps1 +++ b/public/Export-DbaInstance.ps1 @@ -47,6 +47,10 @@ function Export-DbaInstance { 1. Default behavior creates new timestamped folders for historical archiving 2. Using -Force overwrites files in the same location, ideal for scheduled exports that feed into version control systems + Exporting credentials and linked servers includes their stored passwords. Decrypting those needs a dedicated admin connection (DAC) to the instance, which this command opens from the machine you run it on, plus PowerShell remoting to the Windows host of the instance. Because the DAC is opened remotely, the instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. As SQL Server only allows one DAC per instance, this command opens a single one and hands it to both export operations instead of letting each open its own. See Export-DbaCredential and Export-DbaLinkedServer for the details. + + Use -ExcludePassword, or exclude both Credentials and LinkedServers, if no DAC should be opened at all. + For more granular control, please use one of the -Exclude parameters and use the other functions available within the dbatools module. .PARAMETER SqlInstance @@ -110,6 +114,7 @@ function Export-DbaInstance { .PARAMETER ExcludePassword Omits passwords from exported scripts for logins, credentials, and linked servers, replacing them with placeholder text. Essential for security compliance when export scripts will be stored in version control or shared with other team members. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the export then needs neither. .PARAMETER ScriptingOption Provides a Microsoft.SqlServer.Management.Smo.ScriptingOptions object to customize script generation behavior. diff --git a/public/Export-DbaLinkedServer.ps1 b/public/Export-DbaLinkedServer.ps1 index 4b1a1022081..0a1045b3d6c 100644 --- a/public/Export-DbaLinkedServer.ps1 +++ b/public/Export-DbaLinkedServer.ps1 @@ -4,7 +4,14 @@ function Export-DbaLinkedServer { Generates T-SQL scripts to recreate linked server configurations with their login credentials. .DESCRIPTION - Creates executable T-SQL scripts from existing linked server definitions, including remote login mappings and passwords. Perfect for migrating linked servers between environments, creating disaster recovery scripts, or documenting your linked server landscape. When passwords are included, the function accesses the local registry to decrypt stored credentials, so the generated scripts contain actual working passwords rather than placeholder values. + Creates executable T-SQL scripts from existing linked server definitions, including remote login mappings and passwords. Perfect for migrating linked servers between environments, creating disaster recovery scripts, or documenting your linked server landscape. When passwords are included, the function decrypts the stored credentials so the generated scripts contain actual working passwords rather than placeholder values. + + Decrypting those passwords needs two connections to the instance, so make sure both are possible: + + - A dedicated admin connection (DAC), which this command opens from the machine you run it on. That makes it a remote DAC, so the instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. + - PowerShell remoting to the Windows host of the instance, used to read the service master key out of the registry. This needs Windows administrator rights on that host. + + Use -ExcludePassword to skip password decryption entirely; neither connection is opened then. .PARAMETER SqlInstance Source SQL Server. You must have sysadmin access and server version must be SQL Server version 2005 or higher. @@ -40,6 +47,7 @@ function Export-DbaLinkedServer { .PARAMETER ExcludePassword Excludes actual passwords from the exported script, replacing them with placeholder values for security purposes. Use this when sharing scripts across environments or with team members where you need the linked server structure but want to protect sensitive credentials. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the export then needs neither. .PARAMETER Append Adds the exported linked server scripts to an existing file instead of overwriting it. @@ -62,6 +70,10 @@ function Export-DbaLinkedServer { Copyright: (c) 2018 by dbatools, licensed under MIT License: MIT https://opensource.org/licenses/MIT + Requires: + - sysadmin access on SQL Server + - unless -ExcludePassword is used: a remote dedicated admin connection (DAC) to the instance, and Windows administrator access to its host over PowerShell remoting + .LINK https://dbatools.io/Export-DbaLinkedServer diff --git a/public/Start-DbaMigration.ps1 b/public/Start-DbaMigration.ps1 index 8eedb493bbf..f3cdbce291b 100644 --- a/public/Start-DbaMigration.ps1 +++ b/public/Start-DbaMigration.ps1 @@ -36,6 +36,10 @@ function Start-DbaMigration { By default, databases will be migrated to the destination SQL Server's default data and log directories. You can override this by specifying -ReuseSourceFolderStructure. Filestreams and filegroups are also migrated. Safety is emphasized. + Migrating credentials, database mail accounts and linked servers includes their stored passwords. Decrypting those needs a dedicated admin connection (DAC) to the source instance, which this command opens from the machine you run it on, plus PowerShell remoting to the Windows host of that instance. Because the DAC is opened remotely, the source instance needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. As SQL Server only allows one DAC per instance, this command opens a single one and hands it to all three copy operations instead of letting each open its own. See Copy-DbaCredential, Copy-DbaDbMail and Copy-DbaLinkedServer for the details. + + Use -ExcludePassword, or exclude all three of Credentials, DatabaseMail and LinkedServers, if no DAC should be opened at all. + .PARAMETER Source Specifies the source SQL Server instance to migrate from. Accepts server name, server\instance, or connection string formats. This is the instance where all databases, logins, and server objects currently exist. @@ -161,6 +165,7 @@ function Start-DbaMigration { .PARAMETER ExcludePassword Copies credentials, linked servers, and other objects without the actual password values. Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the migration then needs neither. .PARAMETER Force Overwrites existing objects on the destination server without prompting for confirmation. diff --git a/public/Sync-DbaAvailabilityGroup.ps1 b/public/Sync-DbaAvailabilityGroup.ps1 index 6c7508229b1..46e1f5c33c6 100644 --- a/public/Sync-DbaAvailabilityGroup.ps1 +++ b/public/Sync-DbaAvailabilityGroup.ps1 @@ -28,7 +28,9 @@ function Sync-DbaAvailabilityGroup { The command copies ALL objects of each enabled type - it doesn't filter based on which objects are actually used by the availability group databases. Use the exclusion parameters to limit scope when needed. - Copying credentials, database mail accounts and linked servers includes the stored passwords, and decrypting those requires a dedicated admin connection (DAC) to the primary. As SQL Server only allows one DAC per instance, this command opens a single DAC and hands it to all three of those copy operations instead of letting each of them open its own. Use -ExcludePassword if no DAC should be opened at all. + Copying credentials, database mail accounts and linked servers includes the stored passwords, and decrypting those requires a dedicated admin connection (DAC) to the primary plus PowerShell remoting to its Windows host. As SQL Server only allows one DAC per instance, this command opens a single DAC and hands it to all three of those copy operations instead of letting each of them open its own. Use -ExcludePassword if no DAC should be opened at all. + + The DAC is opened from the machine you run this command on, which makes it a remote DAC: the primary needs remote admin connections enabled (Set-DbaSpConfigure -Name RemoteDacConnectionsEnabled -Value 1) and its DAC port has to be reachable from that machine - TCP port 1434 for a default instance, or the dynamically assigned port published by the SQL Server Browser service for a named instance. .PARAMETER Primary The primary replica SQL Server instance for the availability group. This is the source server from which all server-level objects will be copied. @@ -95,6 +97,7 @@ function Sync-DbaAvailabilityGroup { .PARAMETER ExcludePassword Copies credentials, linked servers, and other objects without the actual password values. Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration. + Also use it when the dedicated admin connection or PowerShell remoting described above is not available, because the sync then needs neither. .PARAMETER Force Drops and recreates existing objects on secondary replicas instead of skipping them.