PowerShell Server 2022
Version 22.0 [Build 8375]

Introduction

Thank you for choosing our PowerShell Server product, a powerful SSH solution that enables administrators and other IT professionals to securely manage remote Windows machines through a lightweight PowerShell command-line interface.

PowerShell Server is a full-featured SSH 2.0 server that enables Windows Desktops and Servers with a secure remote entry point to a Windows PowerShell Host. This gives users the power to securely manage Windows remotely through PowerShell from any standard SSH client, including: PuTTY, OpenSSH, iPhone, Blackberry, Linux/Unix machines, as well as our own SSH client solutions.

Packed with advanced capabilities like GSSAPI authentication (NTLM), SFTP and SCP secure file transfer, secure SSH tunnels, and SSH 2.0 support, PowerShell Server is an enterprise-class remote Windows management solution.

Features

  • Support for Secure Shell (SSH) Version 2.0.
  • Run as a Windows Service or as a standalone user application.
  • Securely connect to Windows PowerShell remotely from any standard SSH client, including: iPhone, Blackberry, Linux/Unix machine, etc.
  • Public Key, Password, and GSSAPI Authentication (NTLM) support.
  • Strong 3DES encryption, message integrity checking, secure secret key exchange.
  • SFTP file transfer.
  • Secure SCP file transfer.
  • SSH tunnel support.
  • Unlimited concurrent remote connections (depending on license level).
  • An easy-to-use, lightweight and secure PowerShell Remoting alternative to WinRM.
  • SSH-enabled cmdlets for scriptable access to PowerShell Server
  • SSH-enabled Components for programmatic access to PowerShell Server from multiple languages and environments.

Additional Information

You will always find the latest information about PowerShell Server at our web site: www.nsoftware.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@nsoftware.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@nsoftware.com.

Thank You!

Thank you for choosing PowerShell Server. We realize that you have a choice among utilities, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Authentication

PowerShell Server supports three authentication mechanisms: Username/Password, Public Key Authentication, and GSSAPI Authentication (NTLM/Kerberos).

Password Authentication

Clients connecting to the server need to provide a username and password combination. The credentials are then verified using Windows Authentication mechanisms to make sure they match a valid local account on the server or on a domain trusted by it.

Connecting clients are also authorized by checking membership of the specified user in a special Group. The local/domain security group used for authorization can be selected under the Security tab in the server user interface.

Public Key Authentication

If Public Key Authentication is enabled in the server user interface, connections to the server can also authenticate using the standard public key authentication mechanism supported by the SSH protocol instead of presenting a password.

With Public Key Authentication, connecting clients only need to present a username and demonstrate that they have a private key matching a public key known by the server.

When using Public Key Authentication, the server has no way to match public keys with actual Windows local/domain users, and so the username presented by the client is essentially ignored. To control which connections are allowed, the server will look into the certificate store selected in the configuration for a certificate with a public key matching the private key presented by the client connection. If one is found, the connection will be allowed; otherwise it will be denied.

It is important, therefore, to make sure that the selected certificate store does not contain certificates for people you do not want to allow access to your server.

GSSAPI Authentication (NTLM/Kerberos)

NTLM or Kerberos authentication can be enabled through the server user interface by enabling GSSAPI Authentication.

Note that when using Kerberos as an authentication mechanism, it is recommended that PowerShell Server be run as a service. When not running as a service and instead running under a user account, the default SPN (Service Principal Name) format of host/machine@domain used may result in errors. In that case, a new SPN should be registered (for instance ssh/machine) with the domain controller, and the KerberosSPN registry setting for PowerShell Server must be set. Additionally any connecting SSH client will need to be configured to use the newly defined SPN.

Impersonation

By default, when a new connection is made to the server and the user is authenticated, the server will try to impersonate the user's account so that any actions or commands the user runs on the connection are executed using the user's own credentials.

Impersonation, however, is a bit more complex and how it works depends on what specific options are configured on the server.

Impersonation and Public Key Authentication: Impersonation is never done, regardless of server settings, for connections authenticated using a Public Key. This is because the user specified in the connection is not validated or matched to a windows account. Because of this, any commands run under such a connection will always execute with the credentials of the user the server process is running as.

Interactive Logons: When authenticating connections with username/password, the server will attempt to logon the user to verify his/her credentials. By default, the server will attempt what is known as a "Network Logon", which is more secure because it restricts the authenticated credentials to accessing local resources. This means that, by default, connections will very likely be allowed access only to resources in the local machine that PowerShell Server is running and not any remote network resources (like shared folders, or other servers).

If you want authenticated connections to have access to remote network resources under the credentials used for authentication, then the server needs to authenticate users in a different way, by doing an "Interactive Logon" instead. This can be enabled at the server level by setting the UseInteractiveLogon option to 1 in the Windows registry and restarting the server process. See the configuration section for more details.

Disabling Impersonation: There are some cases where you may want to completely disable the server from impersonating the user credentials, regardless of the kind of logon used. This is necessary in cases when you're running into problems with commands or cmdlets that don't support impersonation (some will fail if impersonation is enabled and others might even crash the server). To disable impersonation, you can set the NoImpersonation option to 1 in the Windows Registry and restart the server process. See the configuration section for more details.

Process Isolation

When running as a service PowerShell Server will create a new process as the authenticated user. The PowerShell runspace will be hosted in this process. This is a configurable option on the Other tab and is enabled by default when running as a service. It is recommended to leave this option enabled when running as a service. If this option is disabled and a user connects and starts a new process, that new process will assume the identity of the service Log On account instead of the authenticated user due to the Windows APIs that PowerShell calls when a new process is started. By isolating the process this problem can be avoided. The Process Isolation option is only applicable when running PowerShell Server as a service.

The Authentication tab controls authentication options.

Below are the available options for this tab:

  • Security Group: This is the name of a Windows group used for authorizing access to the server. Only users who are members of this group will be allowed access. This can be a group in the local machine or a group on the domain.
  • Enable Password Authentication: This specifies whether or not Password authentication is allowed. This is enabled by default.

    Note that when using Password Authentication, the recommended format for user authentication is "DOMAIN\Username".

  • Enable GSSAPI Authentication: This allows GSSAPI authentication for connecting clients. This is enabled by default in licensed versions.
    • Supported Mechanisms: Specifies the authentication mechanism used. Possible values are All, Kerberos, NTLM. The default value is NTLM.
    Note that when using Kerberos as an authentication mechanism, it is recommended that PowerShell Server be run as a service. When not running as a service and instead running under a user account, the default SPN (Service Principal Name) format of host/machine@domain used may result in errors. In that case, a new SPN should be registered (for instance ssh/machine) with the domain controller, and the KerberosSPN registry setting for PowerShell Server must be set. Additionally any connecting SSH client will need to be configured to use the newly defined SPN.
  • Logon Type: Controls the type of logon performed by the application when attempting to authenticate users. Possible values are:
    • Network Logon: Regular network logon is performed. This is more secure, but access to remote network resources is prohibited.
    • Interactive Logon: Interactive logon is performed. This is less secure, but allows access to remote network resources.
    The default value is Network Logon.

Public Key Authentication

  • Enable Public Key authentication: If checked, clients will be able to authenticate using a public key instead of a username/password. When using Public Key Authentication, no impersonation of the logged on user will be done by the server, so all commands will run in the context of the user the server process is running under. Clients connecting to the server using any certificate found in the selected store will be granted access. Public Key Authentication can be configured to use either the Windows certificate store or a keys file on disk.
  • Windows Store Based Public Key Authentication: When selected the client's public key is validated against the certificates in the Windows certificate store specified by the following options:
    • Store Type: Tells the server to look for client certificates in the Machine or User stores.
    • Store Name: Tells the server to look for client certificates under the selected store.
  • File Based Public Key Authentication: If selected, the client client's public key is validated against a list of SSH public keys in the specified file. The file path indicated may contain the %USERNAME% macro, which will resolve to the name of the user being authenticated. The file must contain one key per line. The keys must be in the following format: ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

    When File Based Public Key Authentication is used you can also control the IP addresses from which the key may be used by using the "from" keyword in the SSH public keys file. Please see the following examples:

    • Only accept connections using the specified public key from 192.168.1.12: from="192.168.1.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.30 - 192.168.1.39: from="192.168.1.3?" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.100 - 192.168.1.199: from="192.168.1.1??" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.0.12 - 192.168.255.12 (must end in .12): from="192.168.*.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.0 - 192.168.1.255 EXCEPT 192.168.1.12: from="192.168.1.*,!192.168.1.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

    As demonstrated above, the special characters "?", "!", and "*" may be used to specify an IP address pattern that is to be matched.

    Note that when File Based Public Key Authentication is enabled, similar settings to define the allowed public keys are available in the registry, as documented on the Authorized Keys page.

    Note: Only IPv4 addresses are currently supported. Hostname matching and IPv6 address matching are currently not supported.

Supported Clients

PowerShell Server supports interactive terminal connections as well as remote command execution (Sexec/SSH Exec); both options are found in most SSH clients. Interactive terminal connections provide a way to execute PowerShell commands with an experience similar (if somewhat simplified) to that of working on the local Windows PowerShell prompt.

Features

The interactive terminal mode supports the following features:

  • A "dumb terminal" mode for non supported clients.
  • Client-side Cmdlets include Connect-PowerShellServer, Invoke-PowerShellServer, and Disconnect-PowerShellServer, which trigger the server to XML serialize objects before sending them to the client. When these objects are received by the client side cmdlet, they are de-serialized back into PSObject instances. These cmdlets are available in the NetCmdlets product.
  • A basic VT100+ terminal emulation mode that includes command history using the up/down arrow keys and basic command line editing: cursor movement, backspace/delete and insert/replace mode, most PowerShell host output commands, colorized output, and most of the basic host input commands.

Supported Clients

Any SSH client can connect to PowerShell Server and execute commands. Interactive terminal connections have been tested with a variety of clients and will work with any of the following clients:

  • Putty on Windows
  • Connect-PowerShellServer, Invoke-PowerShellServer, and Disconnect-PowerShellServer Cmdlets included in NetCmdlets.
  • PSClient in IP*Works! SSH
  • Any SSH client on a mobile device.
  • OpenSSH with XTerm, gnome-terminal, Konsole.

By default, the VT100+ emulation support will be enabled for any clients identifying themselves as vt* terminals (e.g. vt100, vt220 and so on) or as xterm. Other clients will be connected using the dumb terminal mode. This behavior can be controlled using the SupportedTerminals registry key (see the Registry Keys section for more details).

Other clients might work with the VT100+ emulation, provided they identify themselves properly during connection establishment and that they support (and enable by default) the VT100 Auto-Wrap mode.

Profile Execution

PowerShell Server will use the host-agnostic profile scripts (e.g. profile.ps1) and Server-specific named profiles that are only run for PowerShell Server connections. You can also see what host you're running in (PowerShell Server or regular PowerShell) by checking the value of $NSShellId.

NameDescription
nsoftware.PowerShell_profile.ps1Used only for interactive sessions.
nsoftware.PSExec_profile.ps1Used for only for exec and PowerShell Server cmdlet connections.

Profiles will first be loaded from the "%SystemRoot%\System32\WindowsPowerShell\v1.0" location and then the "%UserProfile%\Documents\WindowsPowerShell" location.

Running PowerShell Server

Getting Started

The first time you run PowerShell Server, you should switch to the Server Certificate tab and select the X.509 Digital Certificate to be used by the server to protect the SSH connections. By default, the setup will install and configure the application to use the included test certificate, testcert.pfx. From the Security tab, you will also need to configure the Security Group to be used to control which users can connect to the service.

You can also go to the Connection tab and select the TCP port on which the server will listen for incoming connections.

Once you have configured these options, press the Save Changes button in the toolbar to save your changes.

At this point, you should be ready to start the server and listen for SSH connections on the selected TCP port (port 22 by default).

To control the listener, use the Start, Restart and Stop buttons in the toolbar.

If the Run as a Service option is not selected, then the SSH listener will be run in-process inside the PowerShell Server application running in your desktop. This means that to be able to connect remotely to your machine, you must be logged in and the PowerShell Server application must be running (and the listener started). This mode of operation can be very convenient for desktop use.

However, for servers, it is better to enable the Run as a Service option. In this mode of operation, the SSH listener (and any connected PowerShell sessions) are not run on the desktop. Instead, a Windows Service is configured, which can run all the time even if no users are logged on at the server console. When this option is enabled, the Start/Restart/Stop buttons in the PowerShell user interface actually control the Windows Service.

Command Line Parameters

You may start and stop the Windows Service from the command line by specifying the "servicestart" and "servicestop" command line parameters. For instance:

  • To start the service: PowerShellServer.exe /servicestart
  • To stop the service: PowerShellServer.exe /servicestop

When not running as a Windows Service the "start", "stop", "restart", and "exit" command line parameters may be used if the AdminServiceEnabled registry key is set to 1 (True).

  • To start PowerShell Server: PowerShellServer.exe /start
  • To stop PowerShell Server: PowerShellServer.exe /stop
  • To restart PowerShell Server: PowerShellServer.exe /restart
  • To close PowerShell Server: PowerShellServer.exe /exit

Additional command line parameters:

  • To retrieve the maximum number of connections: PowerShellServer.exe /GetMaxConnections

Server Configuration

The different tabs in the PowerShell Server UI allow basic configuration of the server.

Please be aware that configuration changes will not take effect until you click the Save Changes button in the PowerShell Server toolbar, which will save the settings to the Windows registry.

Service

The Service tab controls whether or not the server is run as a Windows service and also provides status output.

Below are the available options for this tab:

  • Run as a Windows Service: If checked, the server will run as a Windows Service.
  • Status: This will show information about connecting clients. To configure the verbosity of the logs set the Log Mode on the Other tab.

Sessions

The Sessions tab provides a way to manage current connections.

If enabled, session management allows you to view and disconnect users that are connected to the SSH server.

The sessions tab contains a list of currently connected clients. This list consists of the connected client's IP Address, logged in Username, and the amount of time they have been connected. This tab also contains the ability to disconnect selected users from the server.

This functionality can be enabled and disabled using the Enable Sessions Management checkbox.

SSH Admin Service

When running the server as a service a special SSH administration service is hosted on port 8122 (default). This is exposed as a way for the user application (UI running in the system tray) to communicate with the SSH process that is actually accepting connections. The use of this service is transparent to you as the user. You do not need to take any special steps to use this, it is handled by the application.

You may optionally connect to this service directly using the AdminServiceUser and AdminServicePassword credentials defined in the registry to manually manage sessions.

The SSH administration service is only used for session management functionality and is only accessible from the local machine by default. Additionally it restricts the available commands to only those used for session management. The following Registry Keys settings define the SSH administration service configuration:

  • AdminCommandRegex: A regular expression that defines what commands are allowed in the admin service. The default value restricts commands to those listed below. The default value is

    ^(Get-PSSConnections|Disconnect-PSSClient -ConnectionId \d+|Start-SSHDaemon|Stop-SSHDaemon|Restart-SSHDaemon|Stop-PowerShellServer|Exit)$

  • AdminServicePort: The port on which the SSH admin service listens. The default is 8122.
  • AdminServiceUser: A username specifically for accessing the SSH admin service. The default is randomly generated during setup.
  • AdminServicePassword: A corresponding password specifically for accessing the SSH admin service. The default is randomly generated during setup.
  • AdminLocalOnly: Controls whether the SSH admin service is accessible remotely. The default is 1 (True).

By default, only the following commands are allowed when connected to the SSH administration service:

  • Get-PSSConnections
  • Disconnect-PSSClient -ConnectionId <Id>
  • Start-SSHDaemon
  • Stop-SSHDaemon
  • Restart-SSHDaemon
  • Stop-PowerShellServer
  • Exit

If a command is entered which does not match the RegEx defined by AdminCommandRegex an error is reported.

The Get-PSSConnections cmdlet will return one object for each connection. The properties of the object include ConnectionId, ConnectionTime (as a TimeSpan), IPAddress, and User. For instance:

PS C:\ProgramData> Get-PSSConnections ConnectionId ConnectionTime IPAddress User ------------ -------------- --------- -------- 12547953 00:00:35.4295000 127.0.0.1 machine\user1 11429296 00:00:22.5110000 127.0.0.1 machine\user2

Server Settings

The Server Settings tab is used to configure the listening port, server banner, server key/certificate, and SSH tunnel support.

Below are the available options for this tab:

  • SSH Port: The port on which the server accepts incoming SSH connections.
  • Enable SSH Tunnel Support: Whether SSH tunnels are currently enabled.
  • Enable SSH Reverse Tunnel Support: Whether SSH reverse tunnels are currently enabled.
  • Login Banner: The banner presented to connecting clients.
  • Server Key: The host key used to identify the server; the Select Certificate/Key option should be used to select a key.

The server can use certificates stored in the User/Machine certificate stores in Windows as well as certificates stored in .PFX, .PEM, or .PPK files.

By default a test certificate is already configured. Before moving to production it is strongly recommended that you replace this test certificate.

SFTP

The SFTP tab holds settings related to the SFTP Server functionality in PowerShell Server.

Below are the available options for this tab:

  • Enable SFTP Support: Allows SFTP clients to connect and transfer files to and from the server.
  • Enable Secure Copy Protocol (SCP) Support: Enables file transfer via SCP. This can be used with the Send-PowerShellServerFile and Get-PowerShellServerFile cmdlets included in the NetCmdlets product, or with any other command line SCP client.
  • SFTP Root Directory: The absolute path to the root directory for SFTP users. By default the "windir" environment variable will be used to determine the root directory (typically "C:\").

    The special value "$user" may be included in the path which will be resolved to the username of the authenticated user (without Domain or Machine information). When "$user" is included in the path if the directory does not exist it will be automatically created.

  • SCP Root Directory: The absolute path to the default directory for SCP users. By default the SFTP Root Directory will be used.

Authentication

PowerShell Server supports three authentication mechanisms: Username/Password, Public Key Authentication, and GSSAPI Authentication (NTLM/Kerberos).

Password Authentication

Clients connecting to the server need to provide a username and password combination. The credentials are then verified using Windows Authentication mechanisms to make sure they match a valid local account on the server or on a domain trusted by it.

Connecting clients are also authorized by checking membership of the specified user in a special Group. The local/domain security group used for authorization can be selected under the Security tab in the server user interface.

Public Key Authentication

If Public Key Authentication is enabled in the server user interface, connections to the server can also authenticate using the standard public key authentication mechanism supported by the SSH protocol instead of presenting a password.

With Public Key Authentication, connecting clients only need to present a username and demonstrate that they have a private key matching a public key known by the server.

When using Public Key Authentication, the server has no way to match public keys with actual Windows local/domain users, and so the username presented by the client is essentially ignored. To control which connections are allowed, the server will look into the certificate store selected in the configuration for a certificate with a public key matching the private key presented by the client connection. If one is found, the connection will be allowed; otherwise it will be denied.

It is important, therefore, to make sure that the selected certificate store does not contain certificates for people you do not want to allow access to your server.

GSSAPI Authentication (NTLM/Kerberos)

NTLM or Kerberos authentication can be enabled through the server user interface by enabling GSSAPI Authentication.

Note that when using Kerberos as an authentication mechanism, it is recommended that PowerShell Server be run as a service. When not running as a service and instead running under a user account, the default SPN (Service Principal Name) format of host/machine@domain used may result in errors. In that case, a new SPN should be registered (for instance ssh/machine) with the domain controller, and the KerberosSPN registry setting for PowerShell Server must be set. Additionally any connecting SSH client will need to be configured to use the newly defined SPN.

Impersonation

By default, when a new connection is made to the server and the user is authenticated, the server will try to impersonate the user's account so that any actions or commands the user runs on the connection are executed using the user's own credentials.

Impersonation, however, is a bit more complex and how it works depends on what specific options are configured on the server.

Impersonation and Public Key Authentication: Impersonation is never done, regardless of server settings, for connections authenticated using a Public Key. This is because the user specified in the connection is not validated or matched to a windows account. Because of this, any commands run under such a connection will always execute with the credentials of the user the server process is running as.

Interactive Logons: When authenticating connections with username/password, the server will attempt to logon the user to verify his/her credentials. By default, the server will attempt what is known as a "Network Logon", which is more secure because it restricts the authenticated credentials to accessing local resources. This means that, by default, connections will very likely be allowed access only to resources in the local machine that PowerShell Server is running and not any remote network resources (like shared folders, or other servers).

If you want authenticated connections to have access to remote network resources under the credentials used for authentication, then the server needs to authenticate users in a different way, by doing an "Interactive Logon" instead. This can be enabled at the server level by setting the UseInteractiveLogon option to 1 in the Windows registry and restarting the server process. See the configuration section for more details.

Disabling Impersonation: There are some cases where you may want to completely disable the server from impersonating the user credentials, regardless of the kind of logon used. This is necessary in cases when you're running into problems with commands or cmdlets that don't support impersonation (some will fail if impersonation is enabled and others might even crash the server). To disable impersonation, you can set the NoImpersonation option to 1 in the Windows Registry and restart the server process. See the configuration section for more details.

Process Isolation

When running as a service PowerShell Server will create a new process as the authenticated user. The PowerShell runspace will be hosted in this process. This is a configurable option on the Other tab and is enabled by default when running as a service. It is recommended to leave this option enabled when running as a service. If this option is disabled and a user connects and starts a new process, that new process will assume the identity of the service Log On account instead of the authenticated user due to the Windows APIs that PowerShell calls when a new process is started. By isolating the process this problem can be avoided. The Process Isolation option is only applicable when running PowerShell Server as a service.

The Authentication tab controls authentication options.

Below are the available options for this tab:

  • Security Group: This is the name of a Windows group used for authorizing access to the server. Only users who are members of this group will be allowed access. This can be a group in the local machine or a group on the domain.
  • Enable Password Authentication: This specifies whether or not Password authentication is allowed. This is enabled by default.

    Note that when using Password Authentication, the recommended format for user authentication is "DOMAIN\Username".

  • Enable GSSAPI Authentication: This allows GSSAPI authentication for connecting clients. This is enabled by default in licensed versions.
    • Supported Mechanisms: Specifies the authentication mechanism used. Possible values are All, Kerberos, NTLM. The default value is NTLM.
    Note that when using Kerberos as an authentication mechanism, it is recommended that PowerShell Server be run as a service. When not running as a service and instead running under a user account, the default SPN (Service Principal Name) format of host/machine@domain used may result in errors. In that case, a new SPN should be registered (for instance ssh/machine) with the domain controller, and the KerberosSPN registry setting for PowerShell Server must be set. Additionally any connecting SSH client will need to be configured to use the newly defined SPN.
  • Logon Type: Controls the type of logon performed by the application when attempting to authenticate users. Possible values are:
    • Network Logon: Regular network logon is performed. This is more secure, but access to remote network resources is prohibited.
    • Interactive Logon: Interactive logon is performed. This is less secure, but allows access to remote network resources.
    The default value is Network Logon.

Public Key Authentication

  • Enable Public Key authentication: If checked, clients will be able to authenticate using a public key instead of a username/password. When using Public Key Authentication, no impersonation of the logged on user will be done by the server, so all commands will run in the context of the user the server process is running under. Clients connecting to the server using any certificate found in the selected store will be granted access. Public Key Authentication can be configured to use either the Windows certificate store or a keys file on disk.
  • Windows Store Based Public Key Authentication: When selected the client's public key is validated against the certificates in the Windows certificate store specified by the following options:
    • Store Type: Tells the server to look for client certificates in the Machine or User stores.
    • Store Name: Tells the server to look for client certificates under the selected store.
  • File Based Public Key Authentication: If selected, the client client's public key is validated against a list of SSH public keys in the specified file. The file path indicated may contain the %USERNAME% macro, which will resolve to the name of the user being authenticated. The file must contain one key per line. The keys must be in the following format: ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

    When File Based Public Key Authentication is used you can also control the IP addresses from which the key may be used by using the "from" keyword in the SSH public keys file. Please see the following examples:

    • Only accept connections using the specified public key from 192.168.1.12: from="192.168.1.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.30 - 192.168.1.39: from="192.168.1.3?" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.100 - 192.168.1.199: from="192.168.1.1??" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.0.12 - 192.168.255.12 (must end in .12): from="192.168.*.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822
    • Only accept connections using the specified public key for the IP Address range 192.168.1.0 - 192.168.1.255 EXCEPT 192.168.1.12: from="192.168.1.*,!192.168.1.12" ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

    As demonstrated above, the special characters "?", "!", and "*" may be used to specify an IP address pattern that is to be matched.

    Note that when File Based Public Key Authentication is enabled, similar settings to define the allowed public keys are available in the registry, as documented on the Authorized Keys page.

    Note: Only IPv4 addresses are currently supported. Hostname matching and IPv6 address matching are currently not supported.

ASP

The ASP tab holds PowerShell ASP related settings.

Below are the available options for this tab:

  • Enable PowerShell ASP: Whether the PowerShell ASP web server will be listening or not.
  • Max Connections: Maximum number of concurrent connections to the PowerShell ASP web server.
  • Log Mode: Specifies the level of detail to log about the server execution.
  • Enable Plain Text: If checked, the server will listen for plain text connections on the specified port.
  • Plain Text Port: The TCP port the server will listen on for plain text connections.
  • Enable SSL: If checked, the server will listen for SSL connections on the specified port.
  • SSL Port: The TCP port the server will listen on for SSL connections.
  • SSL Server Certificate: SSL certificate used by the server.

Note that additional PowerShell ASP specific settings are available in the registry, as documented on the RegistryKeys page.

PowerShell ASP is an ASP-like template language for Web Applications. PowerShell ASP templates contain a mixture of markup (HTML, XML or whatever you want to generate) and inline PowerShell script. You can use PowerShell ASP inside your existing applications, or create complete applications from scratch based only on PowerShell ASP pages.

PowerShell ASP also allows you to generate and serve RSS and Atom feeds from PowerShell scripts executed on an ASP.NET Web Server. Feeds are generated automatically based on the objects returned by the execution of the PowerShell script in a PowerShell pipeline.

Tunnels

The Tunnels tab holds the configuration for SSL and SSH Reverse Tunnel related settings. The information provided in the list is as follows:

  • Tunnel Name provides a friendly name for the tunnel.
  • Type indicates the type of tunnel. Plaintext, SSL, and SSH Reverse Tunnels are supported.
  • Listening Host indicates where the tunnel is listening.
  • Forwarding host indicates where the tunnel is directing its traffic.
  • SSH Server is the SSH server that PowerShell Server will connect to in order to establish the SSH Reverse Tunnel.
  • User is the username PowerShell Server will use to authenticate to the SSH server.
  • Status indicates whether the tunnel is Enabled or Disabled.
Clicking the Add... or Edit buttons will present a form that can be used to create a new tunnel, or edit an existing one, and clicking Delete will remove the selected tunnel.

Note that granular control for tunnels is available via the registry, where the reconnection logic, as well as other settings can be modified. These registry keys are documented on the SSL Tunnels and SSH Reverse Tunnels pages.

SSH Reverse Tunnels

SSH Reverse Tunnels provide a way to allow connections to network resources that would not typically be accessible. For example, a device behind a firewall that would not typically be accessible to the outside world, can be accessed through a SSH Reverse Tunnel. The client connects to the publicly accessible port on the SSH host and traffic is forwarded to the endpoint inside the network protected by the firewall.

In the above diagram, assume that PowerShell Server and the host identified by Server are on the same network, isolated from the Client. SSH Host is accessible by the Client. For the sake of clarity, assume that Port XXXX is 7777, but any open port may be used.

PowerShell Server connects to a SSH Host and requests that the incoming traffic on Port 7777 be forwarded back to PowerShell Server, which will then be directed to Server. Once this tunnel has been established, Client will then be able to connect to SSH Host on Port 7777 in order to communicate with Server.

When adding or editing a SSH Reverse Tunnel the following settings are available:

  • Enabled indicates whether the tunnel should be active or not.
  • Tunnel Name provides a friendly name for the tunnel.
  • Tunnel Type indicates the type of tunnel. Plaintext, SSL, and SSH Reverse Tunnels are supported.
  • Remote SSH Host is the SSH server that PowerShell Server will connect to in order to establish the SSH Reverse Tunnel.
  • Remote SSH Port is the port on which communication with the SSH server will take place. Most servers use port 22, which is the default value.
  • AuthMode is the type of authentication that will be attempted when logging in to the server. Password and Public Key authentication are supported.
  • Username is the username PowerShell Server will use to authenticate to the SSH server.
  • Password is the password PowerShell Server will use to authenticate to SSH server when using Password authentication.
  • SSH Client Key is the certificate PowerShell Server will use to authenticate to the SSH server during Public Key authentication.
  • Server Fingerprint indicates the SSH host key fingerprint of the server. This value is read-only and purely informational.
  • Listening Port indicates the port on which the SSH server will listen for the tunneled traffic.
  • Forwarding Host is the host where the tunneled traffic will be forwarded.
  • Forwarding Port is the port to which the tunneled traffic will be forwarded.

Once the necessary information has been entered, the Test SSH Connection button may be used to test the connection to the SSH server in order to verify the validity of the information provided.

SSL Tunnels

SSL Tunnels support outgoing connections to both SSL and plaintext hosts, and can receive both SSL and plaintext incoming connection attempts. These settings can be used in any combination, allowing for secure connections to what would otherwise be plaintext resources, and vice versa.

When adding or editing an SSL Tunnel the following settings are available:

  • Enabled indicates whether the tunnel should be active or not.
  • Tunnel Name provides a friendly name for the tunnel.
  • Tunnel Type indicates the type of tunnel. SSL (or plaintext) and SSH Reverse Tunnels are supported.
  • Secure Server (SSL) determines whether incoming connections must negotiate SSL.
  • Certificate specifies a certificate with private key used when accepting incoming SSL connections.
  • Listening Port indicates the port on which the server will listen for the tunneled traffic.
  • Forwarding Host is the host where the tunneled traffic will be forwarded.
  • Forwarding Port is the port to which the tunneled traffic will be forwarded.
  • Server Certificate is the forwarding host's public certificate; this can be detected and accepted on-the-fly by testing the outgoing connection.
  • Accept Any Server Certificate determines whether the tunnel will automatically trust any certificate presented by the forwarding host.

The Test Connection button can be used to verify outgoing connection settings. During a connection test, the option to accept server certificates is available if the forwarding host presents a certificate that is not already trusted (and the Accept Any Server Certificate option is not enabled). This will automatically update the outgoing connection settings.

Other

Other

  • Write log to a file: If checked, the server will write all trace information to the file specified in the File box.
  • Log Mode: Specifies how much information to log to the status window about the server execution.
  • Rotate log file every X days: If enabled, the log file will be rotated after the specified number of days. When a log is rotated the old log will be renamed to the format "logname-yyyy-MM-dd".
  • Delete log files older than X days: If enabled, log files older than the specified number of days will be deleted. This is only applicable to log files archived when "Rotate log file every X days" is enabled.
  • Execute PowerShell profiles on connection: If checked, the server will execute any profile scripts found on each connection. Otherwise, no profile scripts will be executed.
  • Enable Impersonation: If checked, the PowerShell Runspace will be created by impersonating the user that authenticated. This is enabled by default. Disabling this means that the PowerShell Runspace will always be created under the account that started the PowerShell Server regardless of the user that is connecting.
  • Use IPV6: Controls whether IPv4 or IPv6 is used when listening. Connecting clients will need to connect using the appropriate IP version.
  • Isolate Sessions: When Isolate Sessions is checked, a new process is launched to host the PowerShell Runspace as the logged in user. When not checked, PowerShell server will impersonate the logged in user (if the Enable Impersonation setting is selected). It is generally recommended to enable this feature.
    • Note: This functionality only applies when running as a service.
    • Note: Isolated Sessions are not supported on Windows XP and Windows Server 2003.
  • Idle Session Timeout (minutes): If a connection is idle for more than the specified number of minutes it will automatically be disconnected by PowerShell Server.
    • Note: Specifying a value of 0 indicates that connections should not be disconnected due to idleness.
  • Wire Encoding: Controls the encoding used by the server on the wire for text sent and received by the server. By default, the server will use ISO-8859-1 (Latin-1) encoding.

Registry Keys

Configuration options for PowerShell Server are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16. This registry key holds settings that are available for PowerShell Server globally. Additional registry keys are available for settings related directly to specific SSL Tunnels, SSH Reverse Tunnels, as well as various other settings.

The tree structure of these registry keys is described below:

The following values can be configured within the root HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16 registry key:

NameTypeDescription
AdminCommandRegexStringRegular Expression used to restrict the commands available to the SSH admin service. The default value is:

^(Get-PSSConnections|Disconnect-PSSClient -ConnectionId \d+|Start-SSHDaemon|Stop-SSHDaemon|Restart-SSHDaemon|Stop-PowerShellServer|Exit)$
AdminServicePortDWORDPort to be used for administrative service connection. The default value is 8122.
AdminServiceUserStringUsername for administrative service connection. The default value is randomly generated during setup.
AdminServicePasswordStringPassword for administrative service connection. The default value is randomly generated during setup.
AdminLocalOnlyDWORDRestricts access to the SSH administration service to the local machine. The default is 1 (True). If set to 0 (False), connections are allowed from outside the local machine. The user must still authenticate using AdminServiceUser and AdminServicePassword. Refer to Sessions for more information.
AdminClientRetryCountDWORDSpecifies the number of attempts to connect to the SSH administration service from the UI before failing. The default is 3. This should never need to be adjusted.
AdminClientRetryDelayDWORDThe delay between retry attempts to connect to the SSH administration service from the UI. The value is in milliseconds and the default is 1000. This should never need to be adjusted.
AdminServiceEnabledDWORDThis setting may be set to enable SSH administrative functions when running as a standalone application (not as a Windows service). By default the SSH administration service will only be enabled when running as a Windows service. Set this value to 1 (True) to enable the SSH administration service at all times (whether running as a Windows service or not). The benefit of enabling this is to allow administration of the server via command line parameters.

See the Sessions page for more details regarding the behavior of the Admin Service, and Running PowerShell Server for the available command line parameters when AdminServiceEnabled is 1.
AllowedClientsStringThis setting defines a comma-separated list of host names or IPv4 addresses that may access the server. The wildcard character "*" is supported. The default value is "*" and all connections are accepted.

When a client connects, the client's address is checked against the list defined here. If there is no match, the client will be disconnected.

AuthMaxAttemptsStringSpecifies the maximum number of connection retries allowed from a client with invalid login credentials. By default this value is set to 3.
BannerStringSets the Login Banner message, which is displayed to the client after successfully authenticating. This can also be set in the interface using the "Login Banner" field.
DeleteLogDaysDWORDThe number of days after which old log files will be deleted. This is only applicable when RotateLogDays is set to a positive value.
EnableCompressionDWORDCan be used to enable use of the zlib compression algorithm on SSH connections.

  • 0 - Off: No compression will be used (Default).
  • 1 - On: Zlib compression will be enabled, if requested by the SSH client.

EnableSCPDWORDCan be used to enable SCP support.

  • 0 - Off (default)
  • 1 - On

EnableSessionManagementDWORDCan be used to enable sessions management.

  • 0 - Off
  • 1 - On (default)

EnableSexecDWORDCan be used to disable SExec connections

  • 0 - Off
  • 1 - On (default)

EnableShellDWORDCan be used to disable Shell connections.

  • 0 - Off
  • 1 - On (default)

EnableSFTPDWORDCan be used to enable SFTP support.

  • 0 - Off (default)
  • 1 - On

EnableSSHReverseTunnelDWORDCan be used to enable SSH Reverse Tunnel support.

  • 0 - Off (default)
  • 1 - On

EnableSSHServerDWORDCan be used to disable all SSH server functionality. When disabled no SSH server will be started. This may be used in cases such as only wishing to enable SSL Tunnel functionality.

  • 0 - Off
  • 1 - On (default)

EnableSSHTunnelDWORDCan be used to enable SSH Tunnel support.

  • 0 - Off (default)
  • 1 - On

EnableWebServerDWORDCan be used to enable the PowerShellASP Web Server.

  • 0 - Off (default)
  • 1 - On

ExecShellIdStringThe ID given to the PowerShell Host Shell for SExec sessions. By default this will be nsoftware.PSExec.
FirewallTypeDWORDThe type of firewall for the SSH Tunnel to connect through. Applicable values include the following:

  • 0 - No firewall (default setting)
  • 1 - Connect through a tunneling proxy.
  • 2 - Connect through a SOCKS4 proxy.
  • 3 - Connect through a SOCKS5 proxy.

FirewallHostStringThe name of IP address of the firewall that the SSH Tunnel will connect through.
FirewallPortDWORDThe TCP port for the FirewallHost.
FirewallUserStringA user name if authentication is to be used when connecting through a firewall.
FirewallPasswordStringPassword to be used if authentication is to be used when connecting through a firewall.
GSSAPIAuthEnabled DWORDSpecifies if GSS-API authentication is accepted.

  • 0 - Off
  • 1 - On (default)

GSSAPIMechanismsDWORDUsed to set the allowable GSS-API authentication mechanisms.

  • 0 - All
  • 1 - Kerberos
  • 2 - NTLM (default)

IdleSessionTimeoutDWORDThe number of minutes after which an idle connection should be terminated.
InteractiveShellIdStringThe ID given to the PowerShell Host Shell for interactive sessions. By default this will be nsoftware.PowerShell.
IsolatedSessionsDWORDControls whether isolated sessions will be used when PowerShell Server is running as a service.

  • 0 - Off: PowerShell will impersonate the logged in user (if NoImpersonation is off).
  • 1 - On: The PowerShell Runspace will run from the logged in user account.(default)

Note that this is only applicable when PowerShell Server is running as a service.

KerberosSPNStringThe Service Principal Name for the Kerberos Domain Controller. If the Service Principal Name cannot be automatically determined, it should be set here. This will usually be in the form "host/fqdn.of.sshhost[@REALM]" where REALM is the fully qualified (DNS) name of the kerberos realm (or Windows Active Directory domain name).
LocalHostStringThe local IP address of the interface to which the server will bind. By default the server will listen on the default interface for the system.
LogSSHPacketsDWORDSpecifies whether or not raw SSH packets are included in the log.

  • 0 - Off (default)
  • 1 - On

LogToFileStringThe full path to the log file.
MatchSSHPublicKeyToUsernameDWORDControls whether public keys are tied to a specified user name. This is only applicable when using file based public key authentication. Possible values are:

0 - Off: Public keys are not tied to a specific username (Default).

1 - On: Public keys are tied to a specific username.

By default when a user authenticates using public key authentication the server will check the key presented by the user against the list of keys in the specified file. If the key is found the authentication succeeds. This setting allows you to validate that the user presents both the expected key and username during authentication. If this setting is enabled the server will check the comment of the public key specified in the file and match it to the username provided during authentication. This check is not case sensitive. To specify a username to be associated with a specific key, include the username in place of the comments in the public key. For instance:

Unmodified public key: ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

Public key modified to be associated with a specific username: ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= DOMAIN\Username

MaxConnectionsDWORDSpecifies the maximum number of connections that are allowed. By default the number of allowed connections is determined by the license that is installed. This setting may be specified to further restrict the number of connections. The server will restrict the number of connections to whichever is the lesser value between this setting and the number of allowed connections for the license.
MaxNumRowsInLogDWORDControls how many lines will be shown in the Status window in the Service tab of the PowerShell Server User Interface. If this value is exceeded, the oldest lines will be removed as new lines are added. The default value is 1000.
NoImpersonationDWORDCan be used to disable impersonation of the username used in the connection.

  • 0 - Off: Clients will be impersonated (Default).
  • 1 - On: Clients will not be impersonated.

PasswordAuthEnabledDWORDMay be set to disable password authentication. This is enabled by default.

  • 0 - Off: Password authentication is not allowed.
  • 1 - On: Password authentication is enabled (Default).

PreserveFileTimeDWORDDetermines if filetime preservation is supported. If a client requests filetime preservation (typically by setting a "-p" parameter) this setting controls whether or not it is respected.

  • 0 - Off: Filetime preservation options are ignored.
  • 1 - On: Filetime preservation is supported (Default).

PromptForRegPermissionsDWORDWhen the server is running under an account that does not have write permissions to the registry location where these settings are stored the user will be prompted to change the permissions. If this value is set to 0 the user will not be prompted again. Possible values are:

  • 0 - Off: The user will not be prompted to modify registry permissions.
  • 1 - On: The user is prompted to modify registry permissions when needed (Default).

PSTraceLevelDWORDControls the trace level of the logging from the application. Possible values are:

  • 0 - Off: Nothing is logged.
  • 1 - Error: Only errors are logged.
  • 2 - Warning: Errors and warnings are logged.
  • 3 - Info: Errors, warnings and informational messages are logged (default value).
  • 4 - Verbose: All messages, including those useful for debugging and troubleshooting are logged.

PubKeyAuthEnabledDWORDControls if the server will allow clients to authenticate using Public Keys:

  • 0 - Off: No public key authentication; clients can only connect using a password.
  • 1 - On: Public key authentication requests will be accepted.

PubKeyAuthCertStoreTypeDWORDSpecifies the type of certificate store where the allowed public keys can be found.

  • 0 - User: Use the User certificate store.
  • 1 - Machine: Use the Machine certificate store.

PubKeyAuthCertStoreStringSpecifies the certificate store where the allowed public keys can be found.
ReverseTunnelPortMapStringA map defining port ranges to be used by specific users when opening a reverse tunnel. By default when this setting is unspecified any user may request any port to be opened when opening a reverse tunnel. If this setting is specified the server will restrict the port ranges on a per-user basis to the ranges defined here. The value should be a semicolon separate list of username and port range pairs in the format: DOMAIN\user1=5000-5500;DOMAIN\user2=4444

The port range may either be a single port, or a range like "5000-5500". If no range is defined for a user the reverse tunnel request will be reject.
RotateLogDaysDWORDThe number of days after which the log file will be rotated. Old log files will be renamed to the format "logname-yyyy-MM-dd". When set to a positive value DeleteLogDays is applicable.
RunAsAServiceDWORDIndicates if the server needs to be executed as a windows service (1) or in-process inside the PowerShell User Interface (0).
RunProfilesDWORDControls whether the server will run profile scripts. Possible values are:

  • 0 - Off: No profile scripts will execute.
  • 1 - On: Any profile scripts found will be executed.

SCPDefaultDirStringThe absolute path to the default directory for SCP users. By default the SFTPRootDir will be used.
SecurityGroupStringName of the Windows group used to control access.
ServerSSHVersionStringStringThis setting specifies the version string value that is sent to all connecting clients. This may be set to specify server specific information. When setting a custom value, it must contain "SSH-2.0-" as this is a standard format that specifies the supported SSH version.
SFTPHomeDirMapStringA map defining user specific SFTP home directories. By default all users are placed into SFTPRootDir when logging on. This setting allows for a user to be assigned a specific directory. The value should be a semicolon separate list of username and home directory pairs in the format: DOMAIN\user1=C:\user1;DOMAIN\user2=C:\user2 The user value must include the domain or machine name as appropriate (DOMAIN\user1 or MACHINE\user1). If the directory specified does not exist the user will be placed into the default SFTPRootDir,. If a user connects and no mapping is present for that user the login attempt will be denied.
SFTPRootDirStringThe absolute path to the root directory for SFTP users. By default the "windir" environment variable will be used to determine the root directory (typically "C:\").

The special value "$user" may be included in the path which will be resolved to the username of the authenticated user (without Domain or Machine information). When "$user" is included in the path if the directory does not exist it will be automatically created.

ShowHiddenFilesDWORDWhether hidden files and folders are displayed during directory listings. The default is true.
SSHCertSubjectStringSubject of the SSH certificate used by the server. Example: "CN=NEWTON".
SSHStoreTypeDWORDIndicates where to find the SSH certificate. Possible values are:

  • 0 - User store
  • 1 - Machine Store
  • 2 - PFX File
  • 4 - PEM File

SSHStoreStringIf SSHStoreType is either 0 or 1, the SSHStore value defines the specific store where the certificate can be found. Possible values include: My, Root, Trust, CA, TrustedPublisher, Disallowed, AuthRoot, TrustedPeople.
SSHStorePasswordStringThe password for the specified certificate store.
SSHEncryptionAlgorithmsStringSpecifies a name-list of the allowed SSH encryption algorithms. This list should be ordered based on preference and comma-delimited, with the first algorithm in the list being the most preferred. To disable an encryption algorithm, remove it from this list. Note: The algorithm which is actually selected during key exchange is the first algorithm to appear in the client's list that the server supports.

Valid values are:

aes256-ctr256-bit AES encryption in CTR mode
aes256-cbc256-bit AES encryption in CBC mode
aes192-ctr192-bit AES encryption in CTR mode
aes192-cbc192-bit AES encryption in CBC mode
aes128-ctr128-bit AES encryption in CTR mode
aes128-cbc128-bit AES encryption in CBC mode
3des-ctr192-bit (3-key) triple DES encryption in CTR mode
3des-cbc192-bit (3-key) triple DES encryption in CBC mode
cast128-cbcCAST-128 encryption
blowfish-cbcBlowfish encryption
arcfourARC4 encryption
arcfour128128-bit ARC4 encryption
arcfour256256-bit ARC4 encryption
aes256-gcm@openssh.com256-bit AES encryption in GCM mode.
aes128-gcm@openssh.com128-bit AES encryption in GCM mode.
chacha20-poly1305@openssh.comChaCha20 with Poly1305-AES encryption.

The default is:

aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,arcfour256,arcfour128,arcfour,cast128-cbc,aes256-gcm@openssh.com,aes128-gcm@openssh.com,chacha20-poly1305@openssh.com
SSHKeyRenegotiationThresholdDWORDThis property allows you to specify the threshold, in the number of bytes, for the SSH Key Renegotiation. The default value for this property is set to 1 GB (1073741824).

For example, to set the threshold to 500mb you would use the value 524288000.

SSHMacAlgorithmsStringSpecifies the SSH MAC algorithms presented during the SSH handshake. Algorithms not on this list will be disabled on the server. The list should be ordered based on preference and comma-delimited, with the first algorithm in the list being the most preferred.

Valid values are:

  • hmac-sha1
  • hmac-md5
  • hmac-sha1-96
  • hmac-md5-96
  • hmac-sha2-256
  • hmac-sha2-256-96
  • hmac-sha2-512
  • hmac-sha2-512-96
  • hmac-ripemd160
  • hmac-ripemd160-96
  • hmac-sha2-256-etm@openssh.com
  • hmac-sha2-512-etm@openssh.com
The default is:

hmac-sha2-256,hmac-sha2-512,hmac-sha1,hmac-md5,hmac-ripemd160,hmac-sha1-96,hmac-md5-96,hmac-sha2-256-96,hmac-sha2-512-96,hmac-ripemd160-96,hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com
SSHKeyExchangeAlgorithmsStringSpecifies the Key Exchange algorithms presented during the SSH handshake. Algorithms not on this list will be disabled on the server. The list should be ordered based on preference and comma-delimited, with the first algorithm in the list being the most preferred.

Valid values are:

  • curve25519-sha256
  • curve25519-sha256@libssh.org
  • diffie-hellman-group1-sha1
  • diffie-hellman-group14-sha1
  • diffie-hellman-group14-sha256
  • diffie-hellman-group16-sha512
  • diffie-hellman-group18-sha512
  • diffie-hellman-group-exchange-sha256
  • diffie-hellman-group-exchange-sha1
  • ecdh-sha2-nistp256
  • ecdh-sha2-nistp384
  • ecdh-sha2-nistp521
The default is:

curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group14-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha256,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,ecdh-sha2-nistp256,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,ecdh-sha2-nistp384,ecdh-sha2-nistp521
SSHPortDWORDThe TCP port the server will listen in for connections.
SSHPublicKeyEnabledDWORDControls if file based public key authentication is enabled or not. This depends on PubKeyAuthEnabled being set as well. The file to use is contained in the SSHPublicKeyFileName setting.

  • 0 - Off: Windows store based public key authentication will be used. (default)
  • 1 - On: File based public key authentication will be used.

SSHPublicKeyFileNameStringThe key file to use for file based public key authentication. Note that the file path indicated may contain the %USERNAME% macro, which will resolve to the name of the user being authenticated.
SSLTunnelCertStoreStringThe certificate store where the SSL certificate can be found.

If SSLTunnelCertStoreType is either 0 or 1, this value defines the specific store where the certificate can be found. Otherwise, this value should be set to a path on disk.

Possible values when SSLTunnelCertStoreType is 0 or 1 include: My, Root, Trust, CA, TrustedPublisher, Disallowed, AuthRoot, TrustedPeople.

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelCertStoreTypeDWORDSpecifies the type of certificate store where the SSL certificate can be found. Possible values are:

  • 0 - User store
  • 1 - Machine Store
  • 2 - PFX File
  • 4 - PEM File

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelCertStorePasswordStringThe password for the certificate store defined in SSLTunnelCertStore, if required.

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelCertSubjectStringThe subject of the certificate used during SSL negotiation. Example: "CN=NEWTON".

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelEnabledCipherSuitesStringThe enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLTunnelEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons. For instance "CALG_AES_256;CALG_3DES". Possible values are:

  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelCipherStrengthDWORDThe minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities.

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelEnabledProtocolsDWORDUsed to enable/disable the supported SSL/TLS versions.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelUseInternalSecurityAPIDWORDIndicates whether or not SSL Tunnels should use the system security libraries or an internal implementation.

By default, the tunnel will use the system security libraries to perform cryptographic functions. Setting this to 1 (True) tells the application to use the internal implementation instead of using the system's security API.

Note that this setting is static and will apply to all SSL Tunnels

SSLTunnelProviderStringThe name of the security provider to use.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

The special value "Internal" picks the internal SSL implementation. This does not rely on any system libraries. This is equivalent to setting SSLTunnelUseInternalSecurityAPI to True.

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SSLTunnelSecurityFlagsDWORDFlags that control certificate verification

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

Note that when set here, and not in the tunnel specific registry keys (as described on the SSL Tunnels page), the value for this setting will be used for all tunnels. The tunnel specific settings may be used to override this value.

SupportedTerminalsStringMaps client terminal identification strings to the type of interactive terminal offered by PowerShell Server (VT100, Dumb terminal). This should be a string with the following format:

"<idstring>=vt100|dummy,<idstring>=vt100|dummy...".

For example, to map any client with a terminal identification string beginning with VT to the VT100+ emulation, you can configure this as:

"vt*=vt100"

Any id string not found here will always get the "dumb" terminal by default. The default configuration for this option is:

"vt*=vt100,xterm=vt100"

SvcLogFileStringIf present, the trace information generated by the server will be written to the specified file.
SyslogDaemonHostStringWhen running as a Windows service the SSH process will send log messages to the UI process. These are the messages which are logged in the Service tab. By default this communication happens on the loopback adapter of the system. If you wish to send these log messages to a different host instead of the UI process you may set this to the hostname or IP address of the destination to which the Syslog messages will be sent. Syslog facility 23 is used to identify messages from PowerShell Server and filter out any other syslog traffic.
SyslogDaemonPortDWORDWhen running as a Windows service the SSH process will send log messages to the UI process. These are the messages which are logged in the Service tab. By default this communication happens on the loopback adapter of the system on port 514. If this port is in use or you wish to use a different port you may specify this here. This specifies the port on which the UI process will listen for incoming log messages and also the port from which the log messages are sent from the SSH process.
UseFIPSCompliantAPIDWORDDetermines if only FIPS compliant algorithms and API calls are made during SSH or SSL sessions. This is false by default. Possible values:

  • 0 - Off: Non-FIPS compliant algorithms are allowed (default).
  • 1 - On: Only FIPS compliant algorithms are allowed, and cryptographic calls are made only to FIPS compliant APIs.

UseIPv6DWORDControls whether IPv4 or IPv6 is used when listening. Connecting clients will need to connect using the appropriate IP version. Possible values are:

  • 0 - Off: IPv4 is used (default).
  • 1 - On: IPv6 is used.

UseInteractiveLogonDWORDControls the type of logon performed by the application when attempting to authenticate users. Possible values are:

  • 0 - Off: Regular network logon is performed. More secure, but can't access remote network resources.
  • 1 - On: Interactive logon is performed. Less secure, but allows access to remote network resources.

UserAuthBannerStringSets the User Authentication Banner, which is displayed to the client before they provide authentication, for example before a password prompt.
UseSTAThreadDWORDControls which type of threading apartment is used for runspaces created by the server. Possible values are:

  • 0 - Off: Runspaces are created as a multi-threaded apartment (MTA) (default).
  • 1 - On: Runspaces are created as a single-threaded apartment (STA).

WireEncodingStringControls the encoding used by the server on the wire for text sent and received by the server. By default, the server will use ISO-8859-1 (Latin-1) encoding.

Authorized Keys

PowerShell Server may be configured with public keys to accept from within the registry as an alternative to File Based Public Key Authentication. The public keys PowerShell Server is configured to accept can be found in the Windows Registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16\AuthorizedKeys. This location holds a String value containing the public keys that may be used to authenticate. The name of the String value is not used, but it is recommended to set this to the name of the user that the public key corresponds to for organizational purposes. In order for this configuration setting to be used, the server must be set to use File Based Public Key Authentication. If this key exists in the registry, its values will be used, otherwise the file specified in the GUI will be used.

SSH Reverse Tunnels

Configuration options for the SSH Reverse Tunnel functionality included in PowerShell Server are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16\SSHReverseTunnels. This location will hold a registry key for each SSH Reverse Tunnel that is created. The registry key for each tunnel can be configured with the following options:

TunnelEnabledDWORDCan be used to enable or disable the SSH Reverse Tunnel.

0 - Disabled.

1 - Enabled. (default)

TunnelForwardingHostStringIndicates the host through which the tunneled traffic will be forwarded.
TunnelForwardingPortDWORDIndicates the port on which the tunneled traffic will be forwarded.
TunnelListeningAddressStringIndicates the interface on the remote SSH server where the tunnel will be listening.
TunnelListeningPortDWORDIndicates the port on which the remote SSH server should listen for traffic.
TunnelNameStringA friendly name for the SSH Reverse Tunnel.
SSHReverseTunnelServerHostStringThe SSH server that PowerShell Server will connect to in order to establish the SSH Reverse Tunnel.
SSHReverseTunnelServerPortDWORDThe port on which communication with the SSH server will take place. By default, port 22 will be used.
SSHReverseTunnelUserStringThe username PowerShell Server will use to authenticate to the SSH server.
SSHReverseTunnelPasswordStringThe password PowerShell Server will use to authenticate to SSH server during Password authentication.
SSHReverseTunnelCompressionAlgorithmsStringA comma-separated list containing all allowable compression algorithms. During the SSH handshake, this list will be used to negotiate the compression algorithm to be used between the client and server. This list is used for both directions: client to server and server to client. When negotiating algorithms, each side sends a list of all algorithms it supports or allows. The algorithm chosen for each direction is the first algorithm to appear in the sender's list that the receiver supports, so it is important to list multiple algorithms in preferential order. If no algorithm can be agreed upon, the component will raise an error and the connection will be aborted.

At least one supported algorithm must appear in this list. The following compression algorithms are supported by the component:

  • zlib
  • zlib@openssh.com
  • none

The default value is: "none,zlib".
SSHReverseTunnelEncryptionAlgorithmsStringSpecifies the allowed SSH Encryption Algorithms in a comma-delimited list. During the SSH handshake, this list will be used to negotiate the encryption algorithm to be used between the client and server. This list is used for both directions: client to server and server to client. When negotiating algorithms, each side sends a list of all algorithms it supports or allows. The algorithm chosen for each direction is the first algorithm to appear in the sender's list that the receiver supports, so it is important to list multiple algorithms in preferential order. If no algorithm can be agreed upon, the component will raise an error and the connection will be aborted. Valid values are:

aes256-ctr256-bit AES encryption in CTR mode
aes256-cbc256-bit AES encryption in CBC mode
aes192-ctr192-bit AES encryption in CTR mode
aes192-cbc192-bit AES encryption in CBC mode
aes128-ctr128-bit AES encryption in CTR mode
aes128-cbc128-bit AES encryption in CBC mode
3des-ctr192-bit (3-key) triple DES encryption in CTR mode
3des-cbc192-bit (3-key) triple DES encryption in CBC mode
cast128-cbcCAST-128 encryption
blowfish-cbcBlowfish encryption
arcfourARC4 encryption
arcfour128128-bit ARC4 encryption
arcfour256256-bit ARC4 encryption
aes256-gcm@openssh.com256-bit AES encryption in GCM mode.
aes128-gcm@openssh.com128-bit AES encryption in GCM mode.

The default is: aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,arcfour256,arcfour128,arcfour,cast128-cbc,aes256-gcm@openssh.com,aes128-gcm@openssh.com

SSHReverseTunnelCertStoreTypeDWORDSpecifies the type of certificate store where the public key can be found for Public Key Authentication. Can be one of the following values:

0 - User store

1 - Machine Store

2 - PFX File

4 - PEM File

SSHReverseTunnelCertStorePasswordStringThe password for the specified certificate store.
SSHReverseTunnelCertStoreStringThe certificate store where the public key can be found for Public Key Authentication.

If SSHReverseTunnelCertStoreType is either 0 or 1, this value defines the specific store where the certificate can be found. Otherwise, this value should be set to a path on disk.

Possible values when SSHReverseTunnelCertStoreType is 0 or 1 include: My, Root, Trust, CA, TrustedPublisher, Disallowed, AuthRoot, TrustedPeople.

SSHReverseTunnelCertSubjectStringThe subject of the certificate used during Public Key Authentication. Example: "CN=NEWTON".
SSHReverseTunnelAutoReconnectDWORDWhether PowerShell Server will attempt to re-establish the SSH Reverse Tunnel in the event that it is disconnected. Possible values are:

ValueDescription
0Off
1 (default)The connection will be retried the number of times defined by SSHReverseTunnelAutoRetryCount.

SSHReverseTunnelAutoRetryCountDWORDThe number of times PowerShell Server will attempt to reestablish the SSH Reverse Tunnel in the event that it is disconnected. This value is only used when SSHReverseTunnelAutoReconnect is set to 1. The default value is 10. A value of 0 indicates infinite reconnect attempts.
SSHReverseTunnelAutoRetryIntervalDWORDThe number of seconds PowerShell Server will wait between attempts to reestablish the SSH Reverse Tunnel.

This value is only used when SSHReverseTunnelAutoReconnect is set to 1.

The default value is 5.

TunnelFirewallTypeDWORDThe type of firewall for the SSL Tunnel to connect through. Applicable values include the following:

0 - No firewall (default setting)

1 - Connect through a tunneling proxy.

2 - Connect through a SOCKS4 proxy.

3 - Connect through a SOCKS5 proxy.

TunnelFirewallHostStringThe name of IP address of the firewall that the SSH Tunnel will connect through.
TunnelFirewallPortDWORDThe TCP port for the TunnelFirewallHost.
TunnelFirewallUserStringA user name if authentication is to be used when connecting through a firewall.
TunnelFirewallPasswordStringPassword to be used if authentication is to be used when connecting through a firewall.

SSL Tunnels

Configuration options for the SSL Tunnel functionality included in PowerShell Server are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16\SSLTunnels. This location will hold a registry key for each SSL Tunnel that is created. The registry key for each tunnel can be configured with the following options:

TunnelEnabledDWORDCan be used to enable or disable the SSH Reverse Tunnel.

0 - Disabled.

1 - Enabled. (default)

TunnelForwardingHostStringIndicates the host that the tunneled traffic will be forwarded.
TunnelForwardingPortDWORDIndicates the port on which the tunneled traffic will be forwarded.
TunnelListeningAddressStringIndicates the interface on the remote SSH server where the tunnel will be listening.
TunnelListeningPortDWORDIndicates the port on which the remote SSH server should listen for traffic.
TunnelNameStringA Friendly name for the SSH Reverse Tunnel.
SSLEnabledDWORDWhether the tunnel will be secured with SSL, or simply a plaintext tunnel.

0 - Disabled.

1 - Enabled. (default)

SSLTunnelCertStoreTypeDWORDSpecifies the type of certificate store where the SSL certificate can be found. Can be one of the following values:

0 - User store

1 - Machine Store

2 - PFX File

4 - PEM File

SSLTunnelCertStoreStringThe certificate store where the SSL certificate can be found.

If SSLTunnelCertStoreType is either 0 or 1, this value defines the specific store where the certificate can be found. Otherwise, this value should be set to a path on disk.

Possible values when SSLTunnelCertStoreType is 0 or 1 include: My, Root, Trust, CA, TrustedPublisher, Disallowed, AuthRoot, TrustedPeople.

SSLTunnelCertStorePasswordStringThe password for the certificate store defined in SSLTunnelCertStore, if required.
SSLTunnelCertSubjectStringThe subject of the certificate used during SSL negotiation for incoming connections. Example: "CN=NEWTON".
SSLTunnelEnabledCipherSuitesStringThe enabled cipher suites to be used in SSL negotiation for incoming connections.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLTunnelEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when SSLTunnelUseInternalSecurityAPI is False (default) (one example per line): * CALG_AES_256 CALG_AES_256;CALG_3DES Possible values when SSLTunnelUseInternalSecurityAPI is False (default) include:

  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when SSLTunnelUseInternalSecurityAPI is True (one example per line): * TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA Possible values when SSLTunnelUseInternalSecurityAPI is True include:
  • TLS_DH_ANON_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DH_ANON_WITH_3DES_EDE_CBC_SHA
  • TLS_DH_ANON_WITH_AES_128_CBC_SHA
  • TLS_DH_ANON_WITH_AES_128_CBC_SHA256
  • TLS_DH_ANON_WITH_AES_256_CBC_SHA
  • TLS_DH_ANON_WITH_AES_256_CBC_SHA256
  • TLS_DH_ANON_WITH_DES_CBC_SHA
  • TLS_DH_ANON_WITH_RC4_128_MD5
  • TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

SSLTunnelEnabledCipherSuites is used together with SSLTunnelCipherStrength.

SSLTunnelCipherStrengthDWORDThe minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities.

SSLTunnelEnabledProtocolsDWORDUsed to enable/disable the supported security protocols for incoming SSL connections.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

SSLTunnelProviderStringThe name of the security provider to use for incoming SSL connections.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

The special value "Internal" picks the internal SSL implementation. This does not rely on any system libraries. This is equivalent to setting SSLTunnelUseInternalSecurityAPI to True.

SSLTunnelSecurityFlagsDWORDFlags that control certificate verification for incoming SSL connections.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

SSLTunnelUseInternalSecurityAPIDWORDWhether to use the internal security implementation rather than system libraries for incoming SSL connections.

By default the component will use the system security libraries to perform cryptographic functions. When set to False, calls to unmanaged code will be made. In environments where this is not desirable, set this setting to True to use a completely managed security implementation.

TunnelFirewallTypeDWORDThe type of firewall for the SSL Tunnel to connect through. Applicable values include the following:

0 - No firewall (default setting)

1 - Connect through a tunneling proxy.

2 - Connect through a SOCKS4 proxy.

3 - Connect through a SOCKS5 proxy.

TunnelFirewallHostStringThe name or IP address of the firewall that the SSH Tunnel will connect through.
TunnelFirewallPortDWORDThe TCP port for the TunnelFirewallHost.
TunnelFirewallUserStringA user name if authentication is to be used when connecting through a firewall.
TunnelFirewallPasswordStringPassword to be used if authentication is to be used when connecting through a firewall.
TunnelForwardingEnableSSLDWORDWhether the tunnel's outgoing connection will be secured with SSL.

0 - Disabled. (default)

1 - Enabled.

TunnelForwardingAcceptAnyServerCertDWORDWhether to automatically trust any public certificate presented by the forwarding host during outgoing SSL connections.

This setting can be used as an alternative to specifying the particular public certificate presented by the forwarding host.

TunnelForwardingSSLCertStoreTypeDWORDSpecifies the type of certificate store where the forwarding hosts's public certificate can be found. Can be one of the following values:

0 - User store

1 - Machine Store

2 - PFX File

4 - PEM File

8 - Public Key File

9 - Public Key Blob

TunnelForwardingSSLCertStoreStringThe certificate store containing the forwarding host's public certificate.

If SSLTunnelCertStoreType is either 0 or 1, this value defines the specific store where the certificate can be found. Otherwise, this value should be set to a path on disk.

Possible values when TunnelForwardingSSLCertStoreType is 0 or 1 include: My, Root, Trust, CA, TrustedPublisher, Disallowed, AuthRoot, TrustedPeople.

TunnelForwardingSSLCertStorePasswordStringThe password for the certificate store defined in TunnelForwardingSSLCertStore, if required.
TunnelForwardingSSLCertSubjectStringThe subject of the forwarding host's public certificate. Example: "CN=NEWTON".
TunnelForwardingReuseSSLSessionDWORDWhether to reuse SSL sessions for outgoing connections.
TunnelForwardingSSLCipherStrengthDWORDThe minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities.

TunnelForwardingSSLEnabledProtocolsDWORDThe SSL/TLS protocols to use during outgoing SSL connections.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

TunnelForwardingSSLProviderStringThe name of the security provider to use during outgoing SSL connections.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

The special value "Internal" picks the internal SSL implementation. This does not rely on any system libraries. This is equivalent to setting SSLTunnelUseInternalSecurityAPI to True.

TunnelForwardingSSLSecurityFlagsDWORDFlags that control certificate verification during outgoing SSL connections.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

TunnelForwardingSSLEnabledCipherSuitesStringThe cipher suites to be used in the outgoing SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLTunnelEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when TunnelForwardingSSLUseInternalSecurityAPI is False (default) (one example per line): * CALG_AES_256 CALG_AES_256;CALG_3DES Possible values when TunnelForwardingSSLUseInternalSecurityAPI is False (default) include:

  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when TunnelForwardingSSLUseInternalSecurityAPI is True (one example per line): * TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA Possible values when TunnelForwardingSSLUseInternalSecurityAPI is True include:
  • TLS_DH_ANON_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DH_ANON_WITH_3DES_EDE_CBC_SHA
  • TLS_DH_ANON_WITH_AES_128_CBC_SHA
  • TLS_DH_ANON_WITH_AES_128_CBC_SHA256
  • TLS_DH_ANON_WITH_AES_256_CBC_SHA
  • TLS_DH_ANON_WITH_AES_256_CBC_SHA256
  • TLS_DH_ANON_WITH_DES_CBC_SHA
  • TLS_DH_ANON_WITH_RC4_128_MD5
  • TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

TunnelForwardingSSLEnabledCipherSuites is used together with TunnelForwardingSSLCipherStrength.

TunnelForwardingSSLUseInternalSecurityAPIDWORDWhether to use the internal security implementation rather than system libraries for outgoing SSL connections.

By default the component will use the system security libraries to perform cryptographic functions. When set to False, calls to unmanaged code will be made. In environments where this is not desirable, set this setting to True to use a completely managed security implementation.

Trusted SSH Host Keys

Information regarding the SSH Hosts that PowerShell Server is configured to trust is stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\16\TrustedSSHHostKeys. This location will hold a string value for each host, named with the format [host]:[port], and the value being the fingerprint of the server. When connecting to the server, if the fingerprint isn't found in the registry with the correctly formatted name, the connection will be aborted and an error will be logged. If the connection was attempted due to the Test SSH Connection button being clicked in the Tunnels tab, a prompt will appear, providing an opportunity to trust the server, which will add the server's fingerprint to the registry so it will be trusted in the future.

SFTP Scripting

By default, the SFTP Server will act as a standard SFTP server and provide file management functionality for the specified root directory. In some cases, it may be desirable to implement advanced functionality. PowerShell Server provides an advanced SFTP scripting technique where a PowerShell script can be used to customize the SFTP functions.

This functionality can be enabled by pointing the SFTP Root Directory option on the Other tab to a PowerShell script.

Required Functions

The following functions must be implemented in the specified PowerShell script to control the corresponding SFTP functionality. Note that the below examples exhibit default functionality, and can be modified to suit your implementation's specific needs.

The following examples make use of a $sftpRoot variable and these helper functions: $sftpRoot = "C:\temp" function Get-UnixTime($time) { return [long]($time - [DateTime]'1970/01/01 12:00:00 AM').TotalSeconds } function Resolve-SFTPPath($vpath) { return [IO.Path]::Combine($sftpRoot, $vpath.Substring(1)) }

Confirm-DirList - Called when listing the contents of a directory. function Confirm-DirList($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: directory virtual path # out: # $sftpArgs.statusCode: operation result # $sftpArgs.fileList: string[] with just filenames $path = Resolve-SFTPPath $sftpArgs.path if ( -not (test-path $path) ) { $sftpArgs.statusCode = $SSH_FXS_NO_SUCH_PATH return } $sftpArgs.fileList = Get-ChildItem $path | %{ $_.Name } $sftpArgs.statusCode = $SSH_FXS_OK }

Confirm-DirCreate - Called when creating a directory. function Confirm-DirCreate($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: directory virtual path # $sftpArgs.attrs: directory attributes # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK $path = Resolve-SFTPPath $sftpArgs.path New-Item -Path $path -ItemType Directory }

Confirm-DirRemove - Called when removing a directory. function Confirm-DirRemove($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: directory virtual path # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK $path = Resolve-SFTPPath $sftpArgs.path Remove-Item -Path $path -force }

Confirm-FileOpen - Called when opening a file. function Confirm-FileOpen($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: file virtual path # $sftpArgs.desiredAccess: desired file access # $sftpArgs.flags: file open flags # $sftpArgs.attrs: file attributes # out: # $sftpArgs.statusCode: operation result # $sftpArgs.physicalPath: physical path to file the server will handle $physicalPath = Resolve-SFTPPath $sftpArgs.path $flags = $sftpArgs.flags if ( -not ($flags -band $SSH_V3_FXF_CREAT) ) { # opening existing file if ( -not (test-path $physicalPath) ) { $sftpArgs.statusCode = $SSH_FXS_NO_SUCH_FILE; return } } else { # creating a new file if ( -not (test-path $physicalPath) ) { New-Item -Path $physicalPath -ItemType File } } $sftpArgs.physicalPath = $physicalPath $sftpArgs.statusCode = $SSH_FXS_OK }

Confirm-FileClose - Called when closing a file. function Confirm-FileClose($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: file or directory virtual path # $sftpArgs.statusCode: operation result # $sftpArgs.physicalPath: physical path of the opened file # you could for example grab the contents here and delete it $sftpArgs.statusCode = $SSH_FXS_OK }

Confirm-FileRemove - Called when removing a file. function Confirm-FileRemove($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: file virtual path # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK $path = Resolve-SFTPPath $sftpArgs.path if ( -not (test-path $path) ) { $sftpArgs.statusCode = $SSH_FXS_NO_SUCH_PATH return } Remove-Item $path }

Confirm-FileRename - Called when renaming a file. function Confirm-FileRename($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: original file virtual path # $sftpArgs.newPath: new file virtual path # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK $path = Resolve-SFTPPath $sftpArgs.path if ( -not (test-path $path) ) { $sftpArgs.statusCode = $SSH_FXS_NO_SUCH_PATH return } $newPath = Resolve-SFTPPath $sftpArgs.newPath Write-Debug -Message "Moving $path to $newPath" Move-Item $path $newPath }

Confirm-GetAttributes - Called when retrieving a file's attributes. function Confirm-GetAttributes($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: directory virtual path # $sftpArgs.flags: flags for this operation # $sftpArgs.attrs: file attributes to return, as a hashtable # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK $path = Resolve-SFTPPath $sftpArgs.path if ( -not (test-path $path) ) { $sftpArgs.statusCode = $SSH_FXS_NO_SUCH_PATH return } $file = Get-Item $path $acl = Get-ACL $path $attrs = $sftpArgs.attrs $attrs.creationTime = Get-UnixTime($file.CreationTimeUtc) $attrs.isDir = $file.PSIsContainer $attrs.modifiedTime = Get-UnixTime($file.LastWriteTimeUtc) $attrs.accessTime = Get-UnixTime($file.LastAccessTimeUtc) $attrs.size = $file.Length $attrs.ownerId = $acl.Owner $attrs.groupId = $acl.Group }

Confirm-SetAttributes - Called when setting a file's attributes. function Confirm-SetAttributes($sftpArgs) { # $sftpArgs.connectionId: connection id # $sftpArgs.user: username # $sftpArgs.path: file virtual path # $sftpArgs.attrs: file attributes # out: # $sftpArgs.statusCode: operation result $sftpArgs.statusCode = $SSH_FXS_OK }

Error Codes

The following SFTP Error Codes may be useful if you need to return an error from one of the above functions: $SSH_FXS_OK = 0 $SSH_FXS_EOF = 1 $SSH_FXS_NO_SUCH_FILE = 2 $SSH_FXS_PERMISSION_DENIED = 3 $SSH_FXS_FAILURE = 4 $SSH_FXS_BAD_MESSAGE = 5 $SSH_FXS_NO_CONNECTION = 6 $SSH_FXS_CONNECTION_LOST = 7 $SSH_FXS_OP_UNSUPPORTED = 8 $SSH_FXS_INVALID_HANDLE = 9 $SSH_FXS_NO_SUCH_PATH = 10 $SSH_FXS_FILE_ALREADY_EXISTS = 11 $SSH_FXS_WRITE_PROTECT = 12 $SSH_FXS_NO_MEDIA = 13 $SSH_FXS_NO_SPACE_ON_FILESYSTEM = 14 $SSH_FXS_QUOTA_EXCEEDED = 15 $SSH_FXS_UNKNOWN_PRINCIPAL = 16 $SSH_FXS_LOCK_CONFLICT = 17 $SSH_FXS_DIR_NOT_EMPTY = 18 $SSH_FXS_NOT_A_DIRECTORY = 19 $SSH_FXS_INVALID_FILENAME = 20 $SSH_FXS_LINK_LOOP = 21 $SSH_FXS_CANNOT_DELETE = 22 $SSH_FXS_INVALID_PARAMETER = 23 $SSH_FXS_FILE_IS_A_DIRECTORY = 24 $SSH_FXS_BYTE_RANGE_LOCK_CONFLICT = 25 $SSH_FXS_BYTE_RANGE_LOCK_REFUSED = 26 $SSH_FXS_DELETE_PENDING = 27 $SSH_FXS_FILE_CORRUPT = 28 $SSH_FXS_OWNER_INVALID = 29 $SSH_FXS_GROUP_INVALID = 30 $SSH_FXS_NO_MATCHING_BYTE_RANGE_LOCK = 31 # File open flags $SSH_V3_FXF_READ = 0x00000001 $SSH_V3_FXF_WRITE = 0x00000002 $SSH_V3_FXF_APPEND = 0x00000004 $SSH_V3_FXF_CREAT = 0x00000008 $SSH_V3_FXF_TRUNC = 0x00000010 $SSH_V3_FXF_EXCL = 0x00000020 $SSH_V4_FXF_TEXT = 0x00000040

PowerShell ASP

The ASP tab holds PowerShell ASP related settings.

Below are the available options for this tab:

  • Enable PowerShell ASP: Whether the PowerShell ASP web server will be listening or not.
  • Max Connections: Maximum number of concurrent connections to the PowerShell ASP web server.
  • Log Mode: Specifies the level of detail to log about the server execution.
  • Enable Plain Text: If checked, the server will listen for plain text connections on the specified port.
  • Plain Text Port: The TCP port the server will listen on for plain text connections.
  • Enable SSL: If checked, the server will listen for SSL connections on the specified port.
  • SSL Port: The TCP port the server will listen on for SSL connections.
  • SSL Server Certificate: SSL certificate used by the server.

Note that additional PowerShell ASP specific settings are available in the registry, as documented on the RegistryKeys page.

PowerShell ASP is an ASP-like template language for Web Applications. PowerShell ASP templates contain a mixture of markup (HTML, XML or whatever you want to generate) and inline PowerShell script. You can use PowerShell ASP inside your existing applications, or create complete applications from scratch based only on PowerShell ASP pages.

PowerShell ASP also allows you to generate and serve RSS and Atom feeds from PowerShell scripts executed on an ASP.NET Web Server. Feeds are generated automatically based on the objects returned by the execution of the PowerShell script in a PowerShell pipeline.

ASP.NET Intrinsic Objects

Besides running standard PowerShell scripts, you can interact with the HTTP runtime through the use of the ASP.NET intrinsic objects like HttpRequest and HttpResponse. Because of the threading model used by PowerShell, those objects are not directly accessible through HttpContext.Runtime.

  • $Request: Contains the HttpRequest object.
  • $Server: Contains the HttpServerUtility object.
  • $Session: Contains the HttpSessionState object.
  • $Application: Contains the HttpApplicationState object.
  • $Response: Contains the HttpResponse object. You can write directly to the response stream from code if you want, or you can use write-host and friends as well.
  • $Cache: Contains the HttpCache object.
  • $Context: The HttpContext object associated with the current request.

These objects are used in exactly the same way as in regular ASP.NET applications.

Here is an example script that will dump all the values in the HttpRequest object to a simple HTML page:

<% $request.params | %{ write-output "$_ = $($request[$_])<br/>" } %>

You can see this sample uses the PowerShell Write-Output cmdlet to generate the output

Authoring PowerShell ASP Pages

PowerShell ASP pages are simple text files with the *.ps1x extension that contain markup as well as snippets of regular PowerShell code. Unlike ASP.NET, there is no code behind model for PowerShell ASP pages: in this sense they resemble the classic ASP model.

Here is a very simple PowerShell ASP page:

<html> <body> <h1> Hello <%= $request['name'] %>! </h1> </body> </html>

As you can see, everything is HTML markup except the <%= %> section, which means "evaluate this PowerShell expression and print the result". The expression, in this case, is using the intrinsic ASP.NET Request object to get an input parameter named "name" from the query string (or form-data) of the URL.

You can also create full code blocks that include any other kind of PowerShell expression or flow control construct, and even intermingle that with markup code. For example, here is a simple page that will present the list of running processes on the machine:

<html> <body> <table> <tr><td>ID</td><td>Name</td></tr> <% get-process | %{ %> <tr> <td><%=$_.Id%></td> <td><%=$_.ProcessName%></td> </tr> <% } %> </table> </body> </html>

Configuring PowerShell ASP

PowerShell ASP can be easily configured in IIS 6 and up. Details of the procedure to do so are included below. Additional functionality is also discussed in separate sections on this page.

IIS 7 and IIS 8 Integrated Pipeline Mode

  1. Create a new ASP.NET Web Site or Application.
  2. Add a reference to PowerShellASP.dll, or copy it to your web site's ./bin folder.
  3. Register the PowerShell ASP HttpHandlers in your Web.config file: <system.webServer> <handlers> <add name='PowerShellASP' path='*.ps1x' verb='GET,POST' type='nsoftware.PSHandler, nsoftware.PowerShellASP'/> <add name='PowerShellRSS' path='*.rs1x' verb='GET,POST' type='nsoftware.PSRSSHandler, nsoftware.PowerShellASP'/> <add name='PowerShellRSSAtom' path='*.as1x' verb='GET,POST' type='nsoftware.PSRSSHandler, nsoftware.PowerShellASP'/> </handlers> </system.webServer>

IIS 6

  1. Create a new ASP.NET Web Site or Application.
  2. Add a reference to PowerShellASP.dll, or copy it to your web site's ./bin folder.
  3. Register the PowerShell ASP HttpHandlers in your Web.config file: <httpHandlers> <add verb='GET,POST' path='*.ps1x' type='nsoftware.PSHandler, nsoftware.PowerShellASP'/> <add verb='GET,POST' path='*.rs1x' type='nsoftware.PSRSSHandler, nsoftware.PowerShellASP'/> <add verb='GET,POST' path='*.as1x' type='nsoftware.PSRSSHandler, nsoftware.PowerShellASP'/> </httpHandlers>
  4. If you have not done so before, configure the *.ps1x and *.rs1x extensions to be mapped to the ASP.NET ISAPI extension library in your IIS application.

Additional Settings

This section describes additional settings that can be used to alter the default behavior of PowerShell ASP. The settings listed below can be specified in the "appSettings" section of the web.config. For instance: <?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0"> <system.web> ... </system.web> <system.webServer> ... </system.webServer> <appSettings> <add key="PSASPRunspaceQueueSize" value="10"/> <add key="PSASPRunProfiles" value="true"/> <add key="PSASPProfile" value="../profile.ps1"/> </appSettings> </configuration>

SettingDescription
PSASPRunspaceQueueSizeSpecifies the number of PowerShell Runspaces to pre-create. When a client connects, a pre-created runspace will be used. This can reduce overhead as runspaces are not created on demand. The runspace is always destroyed when a client disconnects, and runspaces are pre-created to maintain the number of pre-created runspaces specified here. The default value is 1.
PSASPRunProfilesWhen set to true, PowerShell ASP will attempt to load and run profiles automatically. See the "Profile Execution" help page for more detail.
PSASPProfileSpecifies the location of a custom PowerShell profile to load.

Profile Execution

PowerShell ASP will not attempt to load any profiles by default. There are two options for loading profiles with PowerShell ASP.

Dot Sourcing

Dot sourcing can be used to load any profile. For example: ./profiles/YourProfile.ps1

PSASPRunProfiles Setting

When this setting is specified in the appSettings section of the web.config, PowerShell ASP will attempt to load and run profiles automatically. PowerShell ASP will use the host-agnostic profile scripts (e.g. profile.ps1) and Server-specific named profiles that are only run for PowerShell ASP connections named "nsoftware.PowerShellASP_profile.ps1".

Profiles will first be loaded from the "%SystemRoot%\System32\WindowsPowerShell\v1.0" location and then the "%UserProfile%\Documents\WindowsPowerShell" location.

To enable this option in the web.config file add the key "PSASPRunProfiles" to the appSettings sections with a value of "true". For instance: <?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0"> <system.web> ... </system.web> <system.webServer> ... </system.webServer> <appSettings> <add key="PSASPRunProfiles" value="true"/> </appSettings> </configuration>

PSASPProfile

When this setting is specified in the appSetting section of the web.config, PowerShell ASP will attempt to load the profile from the location specified as the value of the key. Note that the PSASPRunProfiles setting also needs to be set to true in order for the profile to be loaded. Both paths relative the web directory and absolute paths are allowed. For example: <?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0"> <system.web> ... </system.web> <system.webServer> ... </system.webServer> <appSettings> <add key="PSASPRunProfiles" value="true"/> <add key="PSASPProfile" value="../profile.ps1"/> </appSettings> </configuration>

This would cause PowerShell ASP to load the script named "profile.ps1" one directory up from the web directory to be loaded.

Diagnosing PowerShell ASP Scripts

PowerShell ASP offers some basic diagnostics facilities that can help you troubleshoot problems with PowerShell ASP itself or your own scripts. These are:

Request logging

You can enable some basic tracing and logging of request processing. This can be useful in troubleshooting issues where PowerShell ASP itself might appear to be working incorrectly or with unexpected results. To enable request logging and write the log to a file, edit your Web.Config file and add the following lines to it:

<system.diagnostics> <switches> <add name='psasp-log' value='4'/> </switches> <trace autoflush='true'> <listeners> <remove name='Default'/> <add name='TextFile' type='System.Diagnostics.TextWriterTraceListener' initializeData='c:\temp\psasp.log' /> </listeners> </trace> </system.diagnostics>

Validating Page Translation

Sometimes you may run into situations in which a PowerShell ASP page (*.ps1x) is generating unexpected HTML output or with unexpected formatting. In those cases, it can be useful to verify how PowerShell ASP is translating the script into the raw PowerShell code that is executed.

You can configure PowerShell ASP to write the translated page script into a file, by adding the following lines to your Web.Config file:

<system.diagnostics> <switches> <add name='psasp-files' value='4'/> </switches> </system.diagnostics>

With this option enabled, PowerShell ASP will write a file right next to your *.ps1x script with the same file name and the extension *.ps1x.tmp. To do this successfully, the application user must have write permissions to the web folder, so it is recommended that you only enable this option in restricted environments for debugging your scripts.

Concurrent Connection Limit Reporting

The concurrent connection limit is governed by the currently installed license. This limit is reported in each response in the HTTP header "X-PowerShellASP-Connection-Limit".

Generating RSS Feeds

Feed Scripts are regular PowerShell scripts, but with the .rs1x and .as1x extension. When the scripts are executed by PowerShell Server, the objects returned to the pipeline by the script are automatically converted to RSS items, based on these rules:

  • Each object returned by the pipeline becomes one RSS item.
  • If the object is just a regular primitive value, like a string or number, its value is used as the title of the RSS entry.
  • If the object is an array, then each item in the array is written as a <value> element in the RSS entry
  • If the object is a hashtable, then each key/value pair in it is written as an element in the RSS entry, using the key as the element name.

Here's an example script that would generate 3 RSS entries:

# A simple value translates into an item with only a title "This is a simple Item" #An array translates into a single item (but no title) ,('an', 'array') # a hashtable allows you to set your own element names @{ 'name' = 'John'; Value = 'Doe' }

Customizing RSS Entry Generation

If you need finer control over how the objects returned by your scripts get translated into RSS entries, return hashtable objects instead. These allow you to specify the names and values of the elements in the RSS feed entry. They also allow you to override values for some basic RSS entry properties by prefixing the keys with 'rss:' or 'atom:'.

Here is an example that generates a feed from the list of files in the C: drive, and customizes how the entries are translated:

ls c:\ | %{ @{ 'rss:id' = "urn:$($_.Name)"; 'rss:updated' = $_.LastWriteTime.ToString('R'); 'rss:title' = $_.Name; 'fullname' = $_.FullName; 'size' = $_.Length; 'directory' = $_.PSIsContainer; 'Mode' = $_.Mode; } }

Overriding Feed Attributes

By default, PowerShell ASP will provide some basic information about your script in the feed metadata. For example, the title of the feed will be the file name of your *.rs1x script.

You can customize the values of these attributes by calling the Set-FeedAttr function from within your script. The arguments you need to provide are the name of the attribute and its value.

set-feedattr 'rss:title' 'This is a sample feed' set-feedattr 'rss:link' 'http://my.feed.url/'

Generating Atom feeds

PowerShell ASP will generate RSS feeds by default for .rs1x scripts and ATOM feeds for .as1x scripts You can force RSS generation for an ATOM feed by appending "?@rss" to the Query String in the feed URL. Likewise, you can force ATOM generation for an RSS feed by appending "?@atom" to the Query String in the feed URL.

Security

PowerShell ASP is fully integrated into the ASP.NET Pipeline. Because of this, you can use the standard ASP.NET mechanisms for securing access to your scripts and pages.

Impersonation

One issue that is important to understand, however, is how impersonation of users logging into your PowerShell ASP-enabled web site works.

By default, your PowerShell ASP scripts will never run in the context of the users logged on to the application, regardless of how you configure the impersonate attribute of the <identity> element in your Web.Config file.

This happens because PowerShell executes all scripts and pipelines in a secondary thread that is not integrated into the regular ASP.NET thread pool, and thus does not inherit the security and impersonation of the original thread processing the HTTP request.

If this is a feature you absolutely need (it's not generally recommended), you can change this behavior so that the impersonation context flows between the right threads. This can only be done at a global level, by editing the main aspnet.config configuration file for the .NET 2.0 framework, which can be found in the %WINDIR%\Microsoft .NET\Framework\v2.0.50727\ directory.

For details about the changes necessary to enable this feature, visit: http://blogs.msdn.com/powershell/archive/2007/09/10/impersonation-and-hosting-powershell.aspx

RegistryKeys

PowerShellASP Specific Registry Keys

Configuration options for the PowerShell ASP server included in PowerShell Server are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\ASP\16. The following values can be configured:

NameTypeDescription
DefaultDocumentsStringA comma delimited list of default documents for the PowerShell ASP site. If no specific document is specified, the first document from this list that is found in the URL's path will be served to the client.
EnableCacheRunspaceDWORDWhether the runspace will be cached for use in future requests. This will allow variables to be stored and accessed again later in a different request. The default value is 0 (False).
MaxConnectionsDWORDThe maximum number of concurrent connections. The default is 25.
PlainPortDWORDThe TCP port on which the server will listen for plaintext connections. The default value is 8181.
SSLCertPasswordStringThe password of the SSL server certificate.
SSLCertStoreStringThe store that holds the SSL server certificate.
SSLCertSubjectStringThe subject of the SSL server certificate.
SSLPortDWORDThe TCP port on which the server will listen for SSL connections. The default value is 8282.
TraceLevelDWORDControls the trace level of the logging from the application. Can be one of the following values:

0 - Off: Nothing is logged.

1 - Error: Only errors are logged.

2 - Warning: Errors and warnings are logged.

3 - Info (default): Errors, warnings and informational messages are logged.

4 - Verbose: All messages, including those useful for debugging and troubleshooting are logged.

UsePlainDWORDWhether or not plaintext connections are accepted. The default value is 1 (True).
UseSSLDWORDWhether or not SSL connections are accepted. The default value is 0 (False).

Copyright (c) 2022 /n software inc. - All rights reserved.
PowerShell Server 2022 - Version 22.0 [Build 8375]