Introduction

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 tutorial will guide you through setting up this functionality within PowerShell Server as well as the PowerShell functions that are required within the script.

Chapter Listing

1. Setup
2. Script
   • Required Functions
   • Error Codes
3. Additional Information

Setup

To use a PowerShell Script to control SFTP functionality, simply point the SFTP Root Directory under the Other tab to the location of a PowerShell script.

Script

The script used in this tutorial can be downloaded here.

Below is the path variable and some additional functions that are used by the example functions listed below.

  $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))
  }

Required Functions

Below is a list of functions that must be implemented in the PowerShell script to control the corresponding SFTP functionality. Note that these are just examples of default functionality, and can be modified to suit your implementation’s specific needs.

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-ItemProperty $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

Additional Information

The sample script used in this tutorial can be downloaded here.

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

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.

Chapter Listing

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
   • PowerShell Panel
4. Additional Information

Setting up PowerShell Server

The first time you run PowerShell Server, you should first switch to the Server Key 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 Security 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 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:

  PowerShellServer.exe /servicestop

Secure Copy Protocol (SCP)

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 the community edition of NetCmdLets, or with other command line SCP clients.

SSH Tunnel

By checking the Enable SSH Tunnel Support, 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. 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 SFTP Settings section on the Other tab.

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.

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.

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.

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 PowerShell 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. Please see the PowerShell Server reference file for more information.

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:

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

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:

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

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

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:

  <%@ Register Assembly="nsoftware.PowerShellASP" Namespace="nsoftware" TagPrefix="cc1" %>

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

  <cc1:PowerShellPanel ID="PSPanel1" runat="server">
    <asp:Label ID="Label2" ForeColor="Red" runat="server" Text="&lt;%= $request.PhysicalApplicationPath %&gt;" />
    <ol>
   &lt;% ls 'c:\' | %{ %&gt;
      <li>&lt;%= $_.Name %&gt;</li>
   &lt;% } %&gt;
    </ol>
  </cc1:PowerShellPanel>

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:

<cc1:PowerShellPanel ID="PSPanel1" runat="server"
      UseAlternateDelimiters='true'>
   <asp:Label ID='Label1' ForeColor="Red" runat="server" Text="[%= $request.PhysicalApplicationPath %]" />
   <ol>
   [% ls 'c:\' | %{ %]
      <li>[%= $_.Name %]</li>
   [% } %]
   </ol>
</cc1:PowerShellPanel>

Additional Information

Additional documentation is available in the PowerShell Server V6 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.

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 (On) in the Windows registry and restarting the server process. To do this follow these steps:

1. From the registry editor navigate to “HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShellServer”
2. Create a new DWORD named “UseInteractiveLogon” with a value of 1

More details on configuring the PowerShell Server via registry settings can be found in the help documentation under the “Server Configuration” section.

For details on using Isolated Sessions and Impersonation with PowerShell Server, please see this article.

]]> http://www.powershellserver.com/accessing-remote-network-resources/feed/ 0 http://www.powershellserver.com/list-current-sessions-of-machines-on-an-active-directory-domain/ http://www.powershellserver.com/list-current-sessions-of-machines-on-an-active-directory-domain/#comments Thu, 15 Nov 2012 14:15:25 +0000 andret http://e2/i/?p=1406

Requirements:

• PowerShell Server
• PSTerminalServices

<h2>Current session information</h2>

<div>
<table>
<tr><th>Server</th><th>SessionID</th><th>State</th><th>UserName</th><th>WindowStationName</th></tr>
<%
Import-Module PSTerminalServices

#List machines on a domain
$strCategory = "computer"

$objDomain = New-Object System.DirectoryServices.DirectoryEntry

$objSearcher = New-Object System.DirectoryServices.DirectorySearcher
$objSearcher.SearchRoot = $objDomain
$objSearcher.Filter = ("(objectCategory=$strCategory)")

$colProplist = "name"
foreach ($i in $colPropList){$null = $objSearcher.PropertiesToLoad.Add($i)}

$colResults = $objSearcher.FindAll()

#Iterate through the results and get session information for each machine
foreach ($objResult in $colResults)
{
	$objComputer = $objResult.Properties; 
	
	$sessionInfo = Get-TSSession -ComputerName $objComputer.name -ErrorAction SilentlyContinue -ErrorVariable myError

	if($sessionInfo)
	{
		foreach($tempInfo in $sessionInfo)
		{
		%>
		<tr><td><%= $tempInfo.Server.ServerName %></td><td><%= $tempInfo.SessionId %></td><td><%= $tempInfo.State %></td><td><%= $tempInfo.UserName %></td><td><%= $tempInfo.WindowStationName %></td></tr>
		<%
		}
	}
	else #an error occurred
	{
	%>
	<tr><td><% $objComputer.name; %><td colspan=4>Error: <%= $myError[0] %></td></tr>
	<%
	}	
} %>
</table>
</div>
</body>
</html>	

The Get-ChildItem command in PowerShell is used to get a listing of files to use as enclosures in the feed.

<%
# This example demonstrates how to generate an RSS Feed from a call to the Get-ChildItem cmdlet (dir). # To tailor to your specific needs, set the following values: $mediadir = 'C:\Testing\media';
$virtualdirectory = 'media';

# Check for user input $dir = $request['path']
if ( $dir -eq $null ) {
   $dir = $mediadir;
}

#Set the feed title and other basic feed attributes set-feedattr 'rss:title' "PowerShellASP Get-RSS Sample";
set-feedattr 'rss:link' "http://www.nsoftware.com";
set-feedattr 'rss:description' "This example uses PowerShellASP to generate an RSS feed using PowerShell cmdlets.";

ls $dir | %{
   @{
      'rss:updated' = $_.LastWriteTime.ToString('R');
      'rss:title' = "Podcast episode: $($_.Name)";
      'rss:enclosure@url' = "http://" + $request.servervariables["SERVER_NAME"] + ":" + $request.servervariables["SERVER_PORT"] + "/$virtualdirectory/" + $_.Name; 
      'rss:enclosure@length' = $_.Length;
      'rss:enclosure@type' = "audio/mp3";
   }
}
%>

That is all there is to it. A couple of lines of script produces an RSS formatted feed of data produced by PowerShell.

Enabling SCP

By default, the PowerShell Server does not allow SCP connections. This is easily enabled in the server interface using the following steps:

On the Connection tab simply check the box that says “Enable Secure Copy Protocol (SCP) Support”.
Then click Save Changes and Restart to restart the server with this change.
That is all that is required to enable SCP support. Now you can connect using any of the methods described below.

SCP From PowerShell Server Cmdlets

The community edition of NetCmdlets (netcmdlets.com) are several cmdlets designed to work with PowerShell Server, including Get-PowerShellServerFile and Send-PowerShellServerFile. These two cmdlets will allow you to send and receive files from PowerShell Server when SCP is enabled. The usage is very simple. For example:

Uploading a File

PS> Send-PowerShellServerFile -Server YourServer -RemoteFile C:\temp\test.txt 
-LocalFile C:\downloads\test.txt

Downloading a File

PS> Get-PowerShellServerFile -Server YourServer -RemoteFile C:\uploads\test.txt 
-LocalFile C:\temp\test.txt

Notes:

The default authentication mechanism when using the Send-PowerShellServerFile and Get-PowerShellServerFile cmdlets is GSSAPI using NTLM and Kerberos.

When the client and server machine are on the same domain, and the user is a member of the appropriate security group, this means that no explicit authentication parameters are required. While this is convenient, if you need to use regular password authentication and specify the user and password when connecting this can be done by specifying the AuthMode, User, and Password parameters. For instance:

PS> Send-PowerShellServerFile -Server YourServer -AuthMode password -User MyUser
-Password MyPassword -RemoteFile C:\temp\test.txt -LocalFile C:\downloads\test.txt

SCP From Linux

The command line SCP client in Linux can also be used to send and get files.

Uploading a File

test@server:~/> scp -oUser=DOMAIN\\user ./test.txt hostname:c:\\temp\\test.txt

Downloading a File

test@server:~/> scp -oUser=DOMAIN\\user hostname:c:\\temp\\test.txt ./test.txt

Notes:

In the above examples two special requirements are demonstrated.

• When using SCP on Linux and need to authenticate with a windows domain
  username you must explicitly set the username using -oUser as above.
• Paths containing backslashes must be escaped with another backslash.

The credential parameter in Powershell taks a PSCredential object. Normally you would prompt a user to enter the information in a dialog and then save the response as a PSCredential object using the Get-Credential cmdlet. Of course in PowerShell ASP that’s not an option. We can get around this by just setting the credentials manually in a PowerShell script:

$securePassword = ConvertTo-SecureString "Password" -AsPlainText -force 
$credential = New-Object System.Management.Automation.PsCredential("domain\username",$securePassword)

After speicfiying your credentails you can then use them in your call to create a New-PSSession Using the PowerShell script below.

$session = New-PSSession -computername hostname -credential $cred

Below is an example of a complete PowerShell ASP page:

<% 
$securePassword = ConvertTo-SecureString "Password" -AsPlainText -force 
$credential = New-Object System.Management.Automation.PsCredential("domain\username",$securePassword)  
$session = New-PSSession -computername hostname -credential $cred 
$command = {ls} 
$res = Invoke-Command -session $session -scriptblock $command 
foreach($item in $res){ 	
	Write-Host("Mode: " + $item.Mode) 
	Write-Host("Last Write Time: " + $item.LastWriteTime) 
	Write-Host("Length: " + $item.Length) 
	Write-Host("Name: " + $item.Name) 
	Write-Host("<hr/>") 
}	 
%> 

PS> [Environment]::GetEnvironmentVariable("UserName")

or

PS> $env:UserName

May return the Machine name instead of the expected Username. The reason for this is that both of those calls check environment variables which may or may not have information on your particular session depending on server settings. Instead use:

PS> [Environment]::UserName

This will call the the GetUserName() api, which is aware of your particular session and will return the current user even when Impersonation is active.

With PowerShell Server, you are not limited to Windows machines and you do not need WinRM or any other software besides the PowerShell Server itself and any SSH client. The “client” machine (i.e. where the commands are being sent from) can be anything: a Linux machine, a handheld device in the field, your cell phone, a Windows machine, a PHP App, etc. If you are not familiar with SSH (“Secure Shell”), it is the most commonly used protocol for remote connections between computers since it is secure and flexible.

The community edition of NetCmdlets(netcmdlets.com) includes a set of cmdlets designed to connect and execute commands on PowerShell Server. While any SSH client can connect and send commands to the PowerShell Server, these cmdlets bring another level of power to the user by enabling the receipt of actual PSObjects from the PowerShell Server through the SSH connection similar to WinRM remoting. These cmdlets are the Connect-PowerShellServer, Disconnect-PowerShellServer, and Invoke-PowerShellServer cmdlets. The first two are used to create and remove SSH protected runspaces, and the latter is used to execute PowerShell commands over that connection and receive PSObjects back from the PowerShell Server.

PowerShell Remoting + WinRM

With PowerShell Remoting via WinRM, you are limited to Windows machines communicating over the web services stack.

Similarities

1. Both allow execution of PowerShell cmdlets on a remote Windows machine.
2. Both are encrypted and secure. PowerShell server operates over an SSH (Secure Shell) connection and PowerShell Remoting works over HTTPS.
3. Both require PowerShell to be installed on the remote Windows machine.
4. Both require security and authentication, albeit in different ways. In both cases a security certificate is used to identify the server. In the case of PowerShell server, connecting users securely authenticate using select Windows security groups defined on the server machine. When using WinRM, by default the credentials are the currently logged in user but these can also be changed to use a remote account.

Differences

1. As mentioned before, both require PowerShell on the remote machine but each requires a different “server piece”. PowerShell Remoting requires WinRM on the remote machine, and PowerShell Server requires itself to be installed on the remote machine.
2. The use of PowerShell Remoting requires PowerShell and WinRM to be installed on the client machine (the machine where the commands are being sent from). There is essentially no client-side software requirement for using PowerShell Server since SSH clients exist virtually everywhere: Windows, *nix, mobile devices, Web Applications, etc. As long as it can establish an SSH connection, a client machine can connect and cmdlets can be executed.

There are two steps to enabling FIPS compliant mode in the PowerShell Server.

1. Enable FIPS mode on the Operating System
2. Enable FIPS mode for the PowerShell Server

After performing both steps be sure to stop and restart the PowerShell Server for changes to take effect.

Enable FIPS mode on the Operating System

To enable FIPS mode on the Operating System you will need to set the “System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing” setting. This can be enabled via a Group Policy, or via the Local Security Policy. For simplicity this article will only discuss enabling this setting in the Local Security Policy. Follow the steps below to enable this setting.

1. Open the Control Panel
2. Within the Control Panel select Administrative Tools
3. Select Local Security Policy. This will open an editor.
4. In the editor expand the tree on the left to “Security Settings | Local Policies | Security Options”
5. In the policy list on the right find “System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing”. Double click this policy and change the value from “Disabled” to “Enabled”.

Your setting should look like this:

Enable FIPS mode on the PowerShell Server

To enable FIPS mode on the PowerShell server you will need to add a new registry key value to inform the PowerShell Server to run in FIPS mode. To do this follow these steps:

1. Launch the registry editor (regedit)
2. Browse to the path:

   HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\PowerShellServer

3. Add a new DWORD value named “UseFIPSCompliantAPI”
4. Set the value data of the new DWORD value to “1″ to enable FIPS compliant mode in the PowerShell Server

Note: You may disable FIPS compliant mode by setting UseFIPSCompliant to “0″ or by simply deleting the DWORD value.

After performing both steps be sure to stop and restart the PowerShell Server for changes to take effect.