Cmdlets

Choose a cmdlet from the list on the left or search for a specific cmdlet. Choose a cmdlet from the list or search for a specific cmdlet.
About Help  Providers
 

Test-ComputerSecureChannel

Test-ComputerSecureChannel

microsoft.powershell.commands.management.dll

Synopsis

Tests and repairs the secure channel between the local computer and its domain.

Syntax

Test-ComputerSecureChannel [-Credential] [-Repair] [-Server] [-Confirm] [-WhatIf] [<CommonParameters>]

Detailed Description

The Test-ComputerSecureChannel cmdlet verifies that the secure channel between the local computer and its domain is working correctly by checking the status of its trust relationships. If a connection fails, you can use the Repair parameter to try to restore it.

Test-ComputerSecureChannel returns "True" if the secure channel is working correctly and "False" if it is not. This result lets you use the cmdlet in conditional statements in functions and scripts. To get more detailed test results, use the Verbose parameter.

This cmdlet works much like NetDom.exe. Both NetDom and Test-ComputerSecureChannel use the NetLogon service to perform the actions.

Parameters

-Repair <SwitchParameter>

Removes and then rebuilds the secure channel established by the NetLogon service. Use this parameter to try to restore a connection that has failed the test (returned "False".)

To use this parameter, the current user must be a member of the Administrators group on the local computer.

Aliases

None

Required?

false

Position

named

Default value

False

Accept pipeline input?

false

Accept wildcard characters?

false

-Server <String>

Uses the specified domain controller to run the command. If this parameter is omitted, Test-ComputerSecureChannel selects a default domain controller for the operation.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-Credential <PSCredential>

Runs the command with the permissions of the specified user. Type a user-name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one that the Get-Credential cmdlet returns. By default, the cmdlet uses the credentials of the current user.

The Credential parameter is designed for use in commands that use the Repair parameter to repair the secure channel between the computer and the domain.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-Confirm <SwitchParameter>

Prompts you for confirmation before running the cmdlet.

Aliases

None

Required?

false

Position

named

Default value

false

Accept pipeline input?

false

Accept wildcard characters?

false

-WhatIf <SwitchParameter>

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Aliases

None

Required?

false

Position

named

Default value

false

Accept pipeline input?

false

Accept wildcard characters?

false

Input Type

None

Return Type

System.Boolean

Notes

To run a Test-ComputerSecureChannel command on Windows Vista and later versions of Windows, open Windows PowerShell with the "Run as administrator" option.

Test-ComputerSecureChannel is implemented by using the I_NetLogonControl2 function, which controls various aspects of the Netlogon service.

Examples

-------------------------- EXAMPLE 1 --------------------------

This command tests the secure channel between the local computer and the domain to which it is joined.

PS C:\>test-computersecurechannel
True

-------------------------- EXAMPLE 2 --------------------------

This command specifies a preferred domain controller for the test.

PS C:\>test-computersecurechannel -server DCName.fabrikam.com
True

-------------------------- EXAMPLE 3 --------------------------

This command resets the secure channel between the local computer and its domain.

PS C:\>Test-ComputerSecureChannel -repair
True

-------------------------- EXAMPLE 4 --------------------------

This command uses the Verbose common parameter to request detailed messages about the operation. For more information about the Verbose parameter, see about_CommonParameters.

PS C:\>test-computerSecureChannel -verbose
VERBOSE: Performing operation "Test-ComputerSecureChannel" on Target "SERVER01".
True
VERBOSE: "The secure channel between 'SERVER01' and 'net.fabrikam.com' is alive and working correctly."

-------------------------- EXAMPLE 5 --------------------------

This example shows how to use Test-ComputerSecureChannel to test a connection before running a script that requires the connection.

The first command uses the Set-Alias cmdlet to create an alias for the cmdlet name. This saves space and prevents typing errors.

The If statement checks the value that Test-ComputerSecureChannel returns before running a script.

PS C:\>set-alias tcsc test-computersecurechannel
if (!(tcsc))
{write-host "Connection failed. Reconnect and retry."}
else { &(.\get-servers.ps1) }

Online Version
Checkpoint-Computer
Reset-ComputerMachinePassword
Restart-Computer
Stop-Computer