Getting Started With PowerShell Server

Introduction

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.

This tutorial will guide you through setting up PowerShell Server and how to use many of the options.

Contents

1. Setting up PowerShell Server
   • Running as a Windows Service
   • Secure Copy Protocol (SCP)
   • SSH Tunnel
   • SFTP Server
   • PowerShell Profile Execution
2. Authentication
   • Password Authentication
   • Public Key Authentication
   • GSSAPI Authentication (NTLM/Kerberos)
3. PowerShell ASP
   • PowerShell ASP Web Server
   • Authoring PowerShell ASP Pages
   • Hosting PowerShell ASP in IIS
   • PowerShell Panel
4. Additional Information

Setting up PowerShell Server

The first time you run PowerShell Server, you should first switch to the Server Settings tab to 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. Alternatively, you can generate a new certificate, or select a previously generated one.

You will also need to configure the Security Group to be used to control which users can connect to the service. This can be done from the Authentication tab.

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. The Start, Restart and Stop buttons can be used to control whether the server is listening or not.

Running as a Windows Service

If the Run as a Windows Service option in the Service tab is NOT selected, the SSH listener will be run in-process inside the PowerShell Server application. 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 Windows 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.

The Windows Service can also be controlled from the command line by specifying the servicestart or servicestop command line parameters. For example, to start the service:

PowerShellServer.exe /servicestart

And to stop the service:

SSH Tunnel

By checking the Enable SSH Tunnel Support option in the Server Settings tab, you can allow SSH tunnels to be created through the server. This allows clients that support creating SSH Tunnels to establish a tunnel through PowerShell Server. This is a common approach to secure an otherwise unsecured connection to a resource.

SFTP Server

To enable the SFTP server, check the Enable SFTP Support checkbox in the SFTP tab. Using this, any SFTP client will be able to connect and transfer files to and from the server.

By default the SFTP root directory will use the ‘windir’ environment variable. Typically this is C:\. You can set the SFTP root directory in the Root Directory Settings section on the SFTP tab.

Secure Copy Protocol (SCP)

In the SFTP tab, the Enable Secure Copy Protocol (SCP) Support checkbox controls whether file transfer via SCP is enabled or not. This can be used with the Send-PowerShellServerFile and Get-PowerShellServerFile CmdLets, which are included in NetCmdlets, or with other command line SCP clients.

PowerShell Profile Execution

PowerShell Profiles to be executed upon connecting can be specified via the Execute PowerShell Profiles on Connection setting on the Other tab. The following profiles can be specified:

• nsoftware.PowerShell_profile.ps1 – Used only for interactive sessions.
• nsoftware.PSExec_profile.ps1 – Used 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.

Authentication

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

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 Connection tab in the server user interface.

GSSAPI Authentication (NTLM/Kerberos)

NTLM or Kerberos authentication can be enabled by checking Enable GSSAPI Authentication under the Security tab and choosing the desired Supported Mechanisms.

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.

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.

PowerShell Server supports file based public key authentication similar to OpenSSH. That is, you would specify a public key file generated using a tool such as PuTTYgen. This can be setup as follows:

1. Check the Enable Public Key Authentication checkbox on the Security tab and select the File Based Public Key Authentication option.
2. Select a key file that contains a list of SSH public keys. The file must contain one key per line, and should be formatted as follows:

   ssh-rsa AAAAB3NzaC1yc2EA...rPFBe7Pnc= rsa-key-20110822

3. Connect using a private key that corresponds to one of the public keys in the specified file.

Windows Store based public key authentication is also supported by selecting the Windows Store Based Public Key Authentication option and choosing the desired store type and name.

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.

PowerShell ASP

PowerShell ASP is an ASP-like template language for Web Applications. PowerShell ASP templates contain a mixture of markup (HTML, XML or whatever you wish 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.

PowerShell ASP Web Server

You can enable the PowerShell ASP Web Server by checking Enable PowerShell ASP on the ASP tab. Under this tab you can also specify the maximum number of connections that can be made to the server, as well as port numbers that the web server will listen on.

Once the Web Server is enabled, simply place pages in the root folder (i.e. the ‘www’ folder located in your install directory) as you would any other web server.

PowerShell ASP pages can also be hosted using IIS instead of from the PowerShell Server, which is discussed in the Hosting PowerShell ASP in IIS section.

Authoring PowerShell ASP Pages

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

Here is a very simple PS1X page:

As you can see, everything is HTML markup right until 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 query data coming in the query string 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:

RSS and Atom feeds can also be generated using PowerShell ASP pages. Please see the PowerShell Server reference file for more information.

Hosting PowerShell ASP in IIS

PowerShell ASP pages may be hosted directly in IIS. To accomplish this you will simply need to add PowerShell ASP as a HttpHandler in your Web.config file.

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>

PowerShell Panel

PowerShell Panel is an easy-to-use ASP.NET Panel Web control for integrating PowerShell content into ASP.NET pages and applications. This allows you to use a mix of HTML and inline PowerShell script to rapidly create dynamic content regions.

To use the PowerShell Panel, simply add a reference to the nsoftware.PowerShellASP.dll assembly to your application, or copy it to your website’s ./bin folder. Then, in the ASP.NET page or control you want to use the PowerShell Panel, add the following code to register the control:

Then, simply write your PowerShell ASP script directly into the panel:

PowerShell Panel – Using Alternate Syntax

Sometimes you might want to avoid having to do so much escaping of HTML when writing your PowerShell ASP scripts in PowerShellPanel controls, particularly of < and > characters. To facilitate this, you can set the UseAlternateDelimiters property of the PowerShellPanel control to true.

After doing this,PowerShellPanel will use the [% and %] sequences as delimiters for code blocks instead of thedelimiters normally used. With this, the example above could be written like this instead:

Additional Information

Additional documentation is available in the PowerShell Server Reference file, which can be accessed through the Contents option under the Help dropdown in the top right corner of the UI.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.