New-PSSessionOption

Creates an object that contains advanced options for a PSSession. PowerShell reference

From the PowerShell reference 23 parameters

What it does

from the PowerShell reference, CC BY 4.0

Creates an object that contains advanced options for a PSSession. The New-PSSessionOption cmdlet creates an object that contains advanced options for a user-managed session (PSSession). You can use the object as the value of the SessionOption parameter of cmdlets that create a PSSession, such as New-PSSession, Enter-PSSession, and Invoke-Command. Without parameters, New-PSSessionOption generates an object that contains the default values for all of the options. Because every property can be edited, you can use the resulting object as a template and create standard option objects for your enterprise. You can also save a SessionOption object in the $PSSessionOption preference variable. The values of this variable establish new default values for the session options. They are effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a SessionOption object in a cmdlet that creates a session. For more information about the $PSSessionOption preference variable, see about_Preference_Variables. When you use a SessionOption object in a cmdlet that creates a session, 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 more information about session configurations, see about_Session_Configurations.

New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachineProfile] [-Culture <CultureInfo>] [-UICulture <CultureInfo>] [-MaximumReceivedDataSizePerCommand <Int32>] [-MaximumReceivedObjectSize <Int32>] [-OutputBufferingMode <OutputBufferingMode>] [-MaxConnectionRetryCount <Int32>] [-ApplicationArguments <PSPrimitiveDictionary>] [-OpenTimeout <Int32>] [-CancelTimeout <Int32>] [-IdleTimeout <Int32>] [-ProxyAccessType <ProxyAccessType>] [-ProxyAuthentication <AuthenticationMechanism>] [-ProxyCredential <PSCredential>] [-SkipCACheck] [-SkipCNCheck] [-SkipRevocationCheck] [-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16] [-IncludePortInSPN] [<CommonParameters>]

Create a default session option

New-PSSessionOptionIdentify

Configure a session by using a session option object

$pso = New-PSSessionOption -Culture "fr-FR" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

Identify

Start an interactive session

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)Identify

Modify a session option object

$a = New-PSSessionOption
$a.OpenTimeout

Identify

Create a preference variable

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000Identify

Fulfill the requirements for a remote session configuration

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

Identify

Make arguments available to a remote session

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Identify

Its page in the reference: New-PSSessionOption.

Parameters

23 in the PowerShell reference

Show its 23 parameters

-ApplicationArgumentsSpecifies a PrimitiveDictionary that's sent to the remote session. Commands and scripts in the remote session, including startup scripts in the session configuration, can find this dictionary in the ApplicationArguments property of the $PSSenderInfo automatic variable. You can use this parameter to send data to the remote session. IMPORTANT: Since this property contains data explicitly provided by the client, using this for security decisions could allow attackers to bypass authorization controls. Never use this data for trust decisions. Validate all user input when used for other application logic. For more information, see about_Hash_Tables, about_Session_Configurations, and about_Automatic_Variables.

-CancelTimeoutDetermines how long PowerShell waits for a cancel operation (<kbd>CTRL</kbd>+<kbd>C</kbd>) to finish before ending it. Enter a value in milliseconds. The default value is 60000 (one minute). A value of 0 (zero) means no time-out; the command continues indefinitely.

-CultureSpecifies the culture to use for the session. Enter a culture name in <languagecode2>-<country/regioncode2> format (like ja-JP), a variable that contains a CultureInfo object, or a command that gets a CultureInfo object. The default value is $null, and the culture that is set in the operating system is used in the session.

-IdleTimeoutDetermines how long the session stays open if the remote computer does not receive any communication from the local computer. This includes the heartbeat signal. When the interval expires, the session closes. The idle time-out value is of significant importance if you intend to disconnect and reconnect to a session. You can reconnect only if the session has not timed out. Enter a value in milliseconds. The minimum value is 60000 (1 minute). The maximum is the value of the MaxIdleTimeoutMs property of the session configuration. The default value, -1, does not set an idle time-out. The session uses the idle time-out that is set in the session options, if any. If none is set (-1), the session uses the value of the IdleTimeoutMs property of the session configuration or the WSMan shell time-out value (WSMan:<ComputerName>\Shell\IdleTimeout), whichever is shortest. If the idle time-out set in the session options exceeds the value of the MaxIdleTimeoutMs property of the session configuration, the command to create a session fails. The IdleTimeoutMs value of the default Microsoft.PowerShell session configuration is 7200000 milliseconds (2 hours). …

-IncludePortInSPNIncludes the port number in the Service Principal Name (SPN) used for Kerberos authentication, for example, HTTP://<ComputerName>:5985. This option allows a client that uses a non-default SPN to authenticate against a remote computer that uses Kerberos authentication. The option is designed for enterprises where multiple services that support Kerberos authentication are running under different user accounts. For example, an IIS application that allows for Kerberos authentication can require the default SPN to be registered to a user account that differs from the computer account. In such cases, PowerShell remoting cannot use Kerberos to authenticate because it requires an SPN that is registered to the computer account. To resolve this problem, administrators can create different SPNs, such as by using Setspn.exe, that are registered to different user accounts and can distinguish between them by including the port number in the SPN. For more information, see Setspn Overview. This parameter was introduced in Windows PowerShell 3.0.

-MaxConnectionRetryCountSpecifies the number of times that PowerShell attempts to make a connection to a target machine if the current attempt fails due to network issues. The default value is 5. This parameter was added for PowerShell version 5.0.

-MaximumReceivedDataSizePerCommandSpecifies the maximum number of bytes that the local computer can receive from the remote computer in a single command. Enter a value in bytes. By default, there is no data size limit. This option is designed to protect the resources on the client computer.

-MaximumReceivedObjectSizeSpecifies the maximum size of an object that the local computer can receive from the remote computer. This option is designed to protect the resources on the client computer. Enter a value in bytes. In Windows PowerShell 2.0, if you omit this parameter, there is no object size limit. Beginning in Windows PowerShell 3.0, if you omit this parameter, the default value is 209715200 bytes (or 200MB).

-MaximumRedirectionDetermines how many times PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection. This option is used in the session only when the AllowRedirection parameter is used in the command that creates the session.

-NoCompressionTurns off packet compression in the session. Compression uses more processor cycles, but it makes transmission faster.

-NoEncryptionTurns off data encryption.

-NoMachineProfilePrevents loading the user's Windows user profile. As a result, the session might be created faster, but user-specific registry settings, items such as environment variables, and certificates are not available in the session.

-OpenTimeoutDetermines how long the client computer waits for the session connection to be established. When the interval expires, the command to establish the connection fails. Enter a value in milliseconds. The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the command continues indefinitely.

-OperationTimeoutDetermines the maximum time WinRM waits for positive connection tests from a live connection before initiating a connection time-out. For more information on WinRM, see the Windows Remote Management Documentation. OperationTimeout does _not_ impose a time limit on commands or processes running in a remote session and does _not_ affect other remoting protocols like SSH. The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out.

-OutputBufferingModeDetermines how command output is managed in disconnected sessions when the output buffer becomes full. If the output buffering mode is not set in the session or in the session configuration, the default value is Block. Users can also change the output buffering mode when disconnecting the session. If you omit this parameter, the value of the OutputBufferingMode of the SessionOption object is None. A value of Block or Drop overrides the output buffering mode transport option set in the session configuration. The acceptable values for this parameter are: - Block. When the output buffer is full, execution is suspended until the buffer is clear. - Drop. When the output buffer is full, execution continues. As new output is saved, the oldest output is discarded. - None. No output buffering mode is specified. For more information about the output buffering mode transport option, see New-PSTransportOption. This parameter was introduced in Windows PowerShell 3.0.

-ProxyAccessTypeDetermines which mechanism is used to resolve the hostname. The acceptable values for this parameter are: - IEConfig - WinHttpConfig - AutoDetect - NoProxyServer - None The default value is None. For information about the values of this parameter, see ProxyAccessType Enumeration.

-ProxyAuthenticationSpecifies the authentication method that is used for proxy resolution. The acceptable values for this parameter are: - Basic - Digest - Negotiate The default value is Negotiate. For more information about the values of this parameter, see AuthenticationMechanism Enumeration.

-ProxyCredentialSpecifies the credentials to use for proxy authentication. Enter a variable that contains a PSCredential object or a command that gets a PSCredential object, such as a Get-Credential command. If this option is not set, no credentials are specified.

-SkipCACheckSpecifies that when it connects over HTTPS, the client does not validate that the server certificate is signed by a trusted certification authority (CA). Use this option only when the remote computer is trusted by using another mechanism, such as when the remote computer is part of a network that is physically secure and isolated or when the remote computer is listed as a trusted host in a WinRM configuration.

-SkipCNCheckSpecifies that the certificate common name (CN) of the server does not have to match the hostname of the server. This option is used only in remote operations that use the HTTPS protocol. Use this option only for trusted computers.

-SkipRevocationCheckDoes not validate the revocation status of the server certificate.

-UICultureSpecifies the UI culture to use for the session. Valid values include: - A culture name in <languagecode2>-<country/regioncode2> format, such as ja-JP - A variable that contains a CultureInfo object - A command that gets a CultureInfo object, such as Get-Culture The default value is $null, and the UI culture that is set in the operating system when the session is created.

-UseUTF16Indicates that this cmdlet encodes the request in UTF16 format instead of UTF8 format.

New-PSSessionOption

What it does

Parameters

See also