New-PSSession

Creates a persistent connection to a local or remote computer. The New-PSSession cmdlet creates a PowerShell session (PSSession) on a local or remote computer. When you create a PSSession, PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run multiple commands that share data, such as a function or the value of a variable. To run commands in a PSSession, use the Invoke-Command cmdlet. To use the PSSession to interact directly with a remote computer, use the Enter-PSSession cmdlet. For more information, see about_PSSessions. You can run commands on a remote computer without creating a PSSession by using the ComputerName parameters of Enter-PSSession or Invoke-Command. When you use the ComputerName parameter, PowerShell creates a temporary connection that is used for the command and is then closed.

New-PSSession [[-ComputerName] <String[]>] [-Credential <PSCredential>] [-Name <String[]>] [-EnableNetworkAccess] [-ConfigurationName <String>] [-Port <Int32>] [-UseSSL] [-ApplicationName <String>] [-ThrottleLimit <Int32>] [-SessionOption <PSSessionOption>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <String>] [<CommonParameters>]

New-PSSession [-Credential <PSCredential>] [-Name <String[]>] [-EnableNetworkAccess] [-ConfigurationName <String>] [-ThrottleLimit <Int32>] [-ConnectionUri] <Uri[]> [-AllowRedirection] [-SessionOption <PSSessionOption>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <String>] [<CommonParameters>]

New-PSSession -Credential <PSCredential> [-Name <String[]>] [-ConfigurationName <String>] [-VMId] <Guid[]> [-ThrottleLimit <Int32>] [<CommonParameters>]

New-PSSession -Credential <PSCredential> [-Name <String[]>] [-ConfigurationName <String>] -VMName <String[]> [-ThrottleLimit <Int32>] [<CommonParameters>]

New-PSSession [[-Session] <PSSession[]>] [-Name <String[]>] [-EnableNetworkAccess] [-ThrottleLimit <Int32>] [<CommonParameters>]

New-PSSession [-Name <String[]>] [-ConfigurationName <String>] -ContainerId <String[]> [-RunAsAdministrator] [-ThrottleLimit <Int32>] [<CommonParameters>]

Its page in the reference: New-PSSession.

Show its 19 parameters

-AllowRedirectionIndicates that this cmdlet allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the ConnectionURI parameter, the remote destination can return an instruction to redirect to a different URI. By default, PowerShell does not redirect connections, but you can use this parameter to enable it to redirect the connection. You can also limit the number of times the connection is redirected by changing the MaximumConnectionRedirectionCount session option value. Use the MaximumRedirection parameter of the New-PSSessionOption cmdlet or set the MaximumConnectionRedirectionCount property of the $PSSessionOption preference variable. The default value is 5.

-ApplicationNameSpecifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the ConnectionURI parameter in the command. The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see about_Preference_Variables. The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the URLPrefix property of a listener on the remote computer.

-AuthenticationSpecifies the mechanism that is used to authenticate the user's credentials. The acceptable values for this parameter are: - Default - Basic - Credssp - Digest - Kerberos - Negotiate - NegotiateWithImplicitCredential The default value is Default. For more information about the values of this parameter, see AuthenticationMechanism Enumeration. CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.

-CertificateThumbprintSpecifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts. To get a certificate, use the Get-Item or Get-ChildItem command in the PowerShell Cert: drive.

-ComputerNameSpecifies an array of names of computers. This cmdlet creates a persistent connection (PSSession) to the specified computer. If you enter multiple computer names, New-PSSession creates multiple PSSession objects, one for each computer. The default is the local computer. To use an IP address in the value of the ComputerName parameter, the command must include the Credential parameter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see "How to Add a Computer to the Trusted Host List" in about_Remote_Troubleshooting. To include the local computer in the value of the ComputerName parameter, start Windows PowerShell by using the Run as administrator option.

-ConfigurationNameSpecifies the session configuration that is used for the new PSSession. Enter a configuration name or the fully qualified resource URI for a session configuration. If you specify only the configuration name, the following schema URI is prepended: http://schemas.microsoft.com/PowerShell. The session configuration for a session is located on the remote computer. If the specified session configuration does not exist on the remote computer, the command fails. The default value is the value of the $PSSessionConfigurationName preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. For more information, see about_Preference_Variables.

-ConnectionUriSpecifies a URI that defines the connection endpoint for the session. The URI must be fully qualified. The format of this string is as follows: <Transport>://<ComputerName>:<Port>/<ApplicationName> The default value is as follows: http://localhost:5985/WSMAN If you do not specify a ConnectionURI, you can use the UseSSL, ComputerName, Port, and ApplicationName parameters to specify the ConnectionURI values. Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS. To use the default ports for PowerShell remoting, specify port 5985 for HTTP or 5986 for HTTPS. If the destination computer redirects the connection to a different URI, PowerShell prevents the redirection unless you use the AllowRedirection parameter in the command.

-ContainerIdSpecifies an array of IDs of containers. This cmdlet starts an interactive session with each of the specified containers. Use the docker ps command to get a list of container IDs. For more information, see the help for the docker ps command.

-CredentialSpecifies a user account that has permission to do this action. The default is the current user. Credentials are stored in a PSCredential object and the password is stored as a SecureString. NOTE: For more information about SecureString data protection, see How secure is SecureString?.

-EnableNetworkAccessIndicates that this cmdlet adds an interactive security token to loopback sessions. The interactive token lets you run commands in the loopback session that get data from other computers. For example, you can run a command in the session that copies XML files from a remote computer to the local computer. A loopback session is a PSSession that originates and ends on the same computer. To create a loopback session, omit the ComputerName parameter or set its value to dot (.), localhost, or the name of the local computer. By default, this cmdlet creates loopback sessions by using a network token, which might not provide sufficient permission to authenticate to remote computers. The EnableNetworkAccess parameter is effective only in loopback sessions. If you use EnableNetworkAccess when you create a session on a remote computer, the command succeeds, but the parameter is ignored. You can also enable remote access in a loopback session by using the CredSSP value of the Authentication parameter, which delegates the session credentials to other computers. …

-NameSpecifies a friendly name for the PSSession. You can use the name to refer to the PSSession when you use other cmdlets, such as Get-PSSession and Enter-PSSession. The name is not required to be unique to the computer or the current session.

-PortSpecifies the network port on the remote computer that is used for this connection. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985, which is the WinRM port for HTTP, and 5986, which is the WinRM port for HTTPS. Before using another port, you must configure the WinRM listener on the remote computer to listen at that port. Use the following commands to configure the listener: 1. winrm delete winrm/config/listener?Address=*+Transport=HTTP 2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="<port-number>"} Do not use the Port parameter unless you must. The port setting in the command applies to all computers or sessions on which the command runs. An alternate port setting might prevent the command from running on all computers.

-RunAsAdministratorIndicates that the PSSession runs as administrator.

-SessionSpecifies an array of PSSession objects that this cmdlet uses as a model for the new PSSession. This parameter creates new PSSession objects that have the same properties as the specified PSSession objects. Enter a variable that contains the PSSession objects or a command that creates or gets the PSSession objects, such as a New-PSSession or Get-PSSession command. The resulting PSSession objects have the same computer name, application name, connection URI, port, configuration name, throttle limit, and Secure Sockets Layer (SSL) value as the originals, but they have a different display name, ID, and instance ID (GUID).

-SessionOptionSpecifies advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. The default values for the options are determined by the value of the $PSSessionOption preference variable, if it is set. Otherwise, the default values are established by options set in the session configuration. The session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. For information about the $PSSessionOption preference variable, see about_Preference_Variables. For more information about session configurations, see about_Session_Configurations.

-ThrottleLimitSpecifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0 (zero), the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer.

-UseSSLIndicates that this cmdlet uses the SSL protocol to establish a connection to the remote computer. By default, SSL is not used. WS-Management encrypts all PowerShell content transmitted over the network. The UseSSL parameter offers an additional protection that sends the data across an HTTPS connection instead of an HTTP connection. If you use this parameter, but SSL is not available on the port that is used for the command, the command fails.

-VMIdSpecifies an array of virtual machine IDs. This cmdlet starts a PowerShell Direct interactive session with each of the specified virtual machines. For more information, see Virtual Machine automation and management using PowerShell. Use Get-VM to see the virtual machines that are available on your Hyper-V host.

-VMNameSpecifies an array of names of virtual machines. This cmdlet starts a PowerShell Direct interactive session with each of the specified virtual machines. For more information, see Virtual Machine automation and management using PowerShell. Use Get-VM to see the virtual machines that are available on your Hyper-V host.