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 tools, 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.

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\22. 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:

• HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShell\Server\22
  • Authorized Keys
  • SSH Reverse Tunnels
  • SSL Tunnels
  • Trusted SSH Host Keys

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

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\22\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\22\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:

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\22\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:

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\22\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 SFTP 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 if ($file.PSIsContainer -eq "true") { $attrs.fileType = 2 } else { $attrs.fileType = 1 } $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>

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: https://devblogs.microsoft.com/powershell/impersonation-and-hosting-powershell/

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\22. The following values can be configured: