First the cmdlets we need are in the server manager module so import that:

Import-Module ServerManager

Create your windows features xml or text file with the one of the following commands from a reference server:

Get-WindowsFeature | ? { $_.Installed } | Export-Clixml .\Features.xml

OR

Get-WindowsFeature | ? { $_.Installed } | Select Name | ForEach-Object { $_.Name } | Out-File .\Features.txt

To install these features:

$(Import-Clixml .\Features.xml) | Add-WindowsFeature

OR

$(Get-Content .\Features.txt) | Add-WindowsFeature

I prefer the TXT file and a Sort for an easy way to compare the files to easily compare of two servers.  Therefore my final scripts:

Export:

Import-Module ServerManager
Get-WindowsFeature | 
  ? { $_.Installed } | 
  Sort-Object Name | 
  Select Name | 
  ForEach-Object { $_.Name } | 
  Out-File .\Features.txt

Import:

Import-Module ServerManager
$(Get-Content .\Features.txt) | 
  Add-WindowsFeature

..and you should be all set.

PowerShell gives us the ability to quickly come up with an certificate object that is quite common on the Windows side: System.Security.Cryptography.X509Certificates.X509Certificate2.  To get there you can use the “cert” mount like this:

cd Cert:\CurrentUser\My

This allows you to get all certificates in your current user store and enumerate them as individual X509Certificate2 objects.  You can see them all once you’re here with a “DIR” or “Get-ChildItem” command to get a complete list of everything in the container.

To get a specific one stored into a variable use the handy Where-Object cmdlet like this:

$Cert = Get-ChildItem | where{ $_.Thumbprint -eq "DDC843EE6EFF730D4F5B87E2EF1212FB77223B27" }

If you want to confirm the type do a quick Get-Member (I do this so often to keep a bead on what I have available to me with a given object all the time)

$Cert | gm

Now, lets export the public certificate out as a base64 PEM with headers you’ll need to add them to the RawData property of the $Cert object:

$out = New-Object String[] -ArgumentList 3
$OutputFile = "C:\Temp\MyCertAsPEM.CER"

$out[0] = "-----BEGIN CERTIFICATE-----"
$out[1] = [System.Convert]::ToBase64String($Cert.PublicKey.EncodedKeyValue.RawData, "InsertLineBreaks")
$out[2] = "-----END CERTIFICATE-----"

[System.IO.File]::WriteAllLines($OutputFile,$out)

The above takes in account that you might have a private key and limits the output file to the public key only.

So, what about that pesky private key? Stay tuned..

Using a mix of the Security.Principal and Security.AccessControl .NET Classes you can couple this with your file share create class and get a complete set up of a file share; or, just use it to set NTFS permissions without all the file share portions in the previous post to set NTFS permissions on their own.

using System.Security.Principal;
using System.Security.AccessControl;

        public static void GrantNTFSPermissions(string FolderPath, string Domain, string Group)
        {
            // Create a new DirectoryInfo object.
            DirectoryInfo directoryInfo = new DirectoryInfo(FolderPath);

            // Get a DirectorySecurity object that represents the 
            // current security settings.
            DirectorySecurity directorySecurity = directoryInfo.GetAccessControl();

            // Add the FileSystemAccessRule to the security settings. 
            directorySecurity.AddAccessRule(
                new FileSystemAccessRule(
                    new NTAccount(Domain, Group), 
                    FileSystemRights.Modify | FileSystemRights.ReadAndExecute | FileSystemRights.ListDirectory | FileSystemRights.Read | FileSystemRights.Write, 
                    InheritanceFlags.ContainerInherit | InheritanceFlags.ObjectInherit, PropagationFlags.None,
                    AccessControlType.Allow)
                );

            // Set the new access settings.
            directoryInfo.SetAccessControl(directorySecurity);

        }

Important Note:  Passing mulitple values separated with a “|” to the FileSystemAccessRule class constructor’s parameters, allows you to set multiple options at once over mutliple calls/rewrites.

Using the ManagmentClass class (someone might be regretting the naming here) we can expose WMI in .NET.  Then, we can operate on methods of the Windows Managment Interface to create shares in C# code.

Like all Windows API work, this isn’t super clear throughout MSDN or the Internet.  I also find that Windows API return codes are a pain.  When I operate in that old schools space I try to take the next step and get a return code description method created.

Below, we create a security descriptor and share using .NET and WMI objects (with some return code flare).

Enjoy!

1) Figure out who you want access to your share.  This must be done with the use of of a Win32_SecurityDescriptor in WMI:

        private static ManagementBaseObject SecurityDescriptor()
        {
            NTAccount account = new NTAccount("NT Authority", "Everyone");
            SecurityIdentifier sid = (SecurityIdentifier)account.Translate(typeof(SecurityIdentifier));
            byte[] sidArray = new byte[sid.BinaryLength];
            sid.GetBinaryForm(sidArray, 0);
            ManagementObject Trustee = new ManagementClass(new ManagementPath("Win32_Trustee"), null);
            Trustee["Domain"] = "NT Authority";
            Trustee["Name"] = "Everyone";
            Trustee["SID"] = sidArray;
            ManagementObject AdminACE = new ManagementClass(new ManagementPath("Win32_Ace"), null);
            AdminACE["AccessMask"] = 2032127;
            AdminACE["AceFlags"] = 3;
            AdminACE["AceType"] = 0;
            AdminACE["Trustee"] = Trustee;
            ManagementObject SecurityDescriptor = new ManagementClass(new ManagementPath("Win32_SecurityDescriptor"), null);
            SecurityDescriptor["ControlFlags"] = 4; //SE_DACL_PRESENT
            SecurityDescriptor["DACL"] = new object[] { AdminACE };
            return SecurityDescriptor;
        }

It’s never easy with security….

So for an explaination of the above; first, you look up your principle using NTAccount then create a Win32_Trustee from that principal.

note:  this method can *easily* be parameterized for a domain:

        private static ManagementBaseObject SecurityDescriptor(string domain, string user)
        {
            NTAccount account = new NTAccount(domain, user);
            SecurityIdentifier sid = (SecurityIdentifier)account.Translate(typeof(SecurityIdentifier));

[...]

Then, you estable what access controll entry (ACE) you want to grant to the principal(s) using the Win32_Ace object.  The SecurityDescriptor method above includes it all.  Side note: ACL and ACE’s are the most confusing things to code in Windows for me, bar none.  It’s not easy, play with the code to taste if you need specific access and don’t forget to review the AccessMask and AceTypes to limit down from full control as needed.  To add multiple add them as comma separated DACL’s like so:

SecurityDescriptor["DACL"] = new object[] { AdminACE, MyACE, YourACE, OurACE };

2) Finally, create your share

First, create your ManagmentClass object and parameters (using your above security principal(s)) for the “Create” method of the Win32_Share.  If anything funky happens decode the response code description.

        public static void CreateShare(string FolderPath, string ShareName, string Description)
        {
            //create a ManagementClass object
            ManagementClass managementClass = new ManagementClass("Win32_Share");

            //create ManagementBaseObjects for in and out parameters
            ManagementBaseObject inParams = managementClass.GetMethodParameters("Create");
            ManagementBaseObject outParams;

            // Set the input parameters
            inParams["Description"] = Description;
            inParams["Name"] = ShareName;
            inParams["Path"] = FolderPath;
            inParams["Type"] = 0x0; // Disk Drive

            //invoke the method
            outParams = managementClass.InvokeMethod("Create", inParams, null);

            //check to see if the method invocation was successful
            uint rVal = (uint)(outParams.Properties["ReturnValue"].Value);
            if (rVal != 0 && rVal != 22) //ok if it already exists
            {
                throw new Exception(String.Format("Unable to share directory. \nReturn Code: {0} \nDescription: {1}", rVal, getCreateShareReturnCodeDescription(rVal)));
            }
        }

        private static string getCreateShareReturnCodeDescription(uint returnValue)
        {
            switch (returnValue)
            {
                case 0:
                    return "Success";
                case 2:
                    return "Access Denied";
                case 8:
                    return "Unknown Failure";
                case 9:
                    return "Invalid Name";
                case 10:
                    return "Invalid Level";
                case 21:
                    return "Invalid Parameter";
                case 22:
                    return "Duplicate Share";
                case 23:
                    return "Redirect Path";
                case 24:
                    return "Unknown Device or Directory";
                case 25:
                    return "Net Name Not Found";
            }
            return "Unknown";
        }

Write-EventLog : The source name "MyScript" does not exist on computer "localhost".

Here’s a simple way to get around that do that:

PS C:> New-Eventlog -LogName "Application"  -Source "MyScript"

Change “MyScript” to whatever you want the source element to reflect in your event log.

A more robust way of doing check, create if needed, then write and event can be seen here:

$ErrorActionPreference = "SilentlyContinue"
if(!(Get-Eventlog -LogName $LogName -Source $Source)){
     New-Eventlog -LogName "Application"  -Source "MyScript" | Out-Null
}
$ErrorActionPreference = "Continue"
Write-EventLog -LogName "Application" -Source "MyScript" -EntryType "Information" -EventId 0 -Message "Script Started."

First, I need to explain the “SilentlyContinue”.  At least in 2.0, the Get-EventLog cmdlet has problems throwing exceptions.  It doesn’t throw the exceptions correctly to be in a proper try/catch as discussed here.  It appears to throw a PowerShell error that can’t be properly try/catched.  After troubleshooting for a few hours, tracing the exception all over, I settled on a workaround.  I set the $ErrorActionPreference variable to “SilentlyContinue” and test for a NULL return from Get-EventLog.  If it’s return is NULL I create the log/source pair for logging and continue on my way.  Any following Write-EventLog executions using the same LogName/Source pairing will log without the source error since you’ve created it on the machine from now to the end of time.

If you want to expand to include some permissions catching I suggest this approach:

$ErrorActionPreference = "SilentlyContinue"
if(!(Get-Eventlog -LogName $LogName -Source $Source)){
     $ErrorActionPreference = "Continue"
     try {
          New-Eventlog -LogName "Application"  -Source "MyScript" | Out-Null
          Write-EventLog -LogName "Application" -Source MyScript" -EntryType "Information" -EventId 0 -Message "Script Started."
     }

     catch [System.Security.SecurityException] {
          Write-Error "Error:  Run as elevated user.  Unable to write or read to event logs."
     }
}
$ErrorActionPreference = "Continue"

I wanted to try and parameterize all of the options that the Write-Event cmdlet could do a little differently so the invocation of it within a script could be more standardized and much cleaner.  So, I extended my working through integrating my own Write-EventLog cmdlet further to exposes all of the power around the cmdlet without getting hung up on errors and unknowns.  Completed function script can be downloaded from here as well as viewed below:

Function Write-Event {
	<#
		.SYNOPSIS
			Write-Event function writes messages to the event log.

		.DESCRIPTION
			Write-Event function writes messages to the event log 
			after creating the logname and source if not already defined.

		.PARAMETER  $Message
			The message you want displayed in the event log body. 
			Required.

		.PARAMETER  $EventId
			The entryid number you wanted displayed in the event log. 
			Default is 0.

		.PARAMETER  $Source
			The source of the event log you wanted displayed in the event log. 
			Default is the PowerShell script name the function was invoked from.

		.PARAMETER  $LogName
			The log that you want the event loged in. Default is the Application log.
			If the Log and source pair do not exist on the machine this scirpt is 
			invoked on the pair will be created.

		.EXAMPLE
			PS C:\> Write-Event -Message "Process Started." -EntryId 0 -Information

		.EXAMPLE
			PS C:\> Write-Event "Process Started." -Information

		.EXAMPLE
			PS C:\> Write-Event "Process Failed." -EntryId 161 -Error

		.EXAMPLE
			PS C:\> Write-Event "Process Started."

		.INPUTS
			System.String,System.Int32,System.String,System.String,System.Switch,System.Switch

		.OUTPUTS
			None

		.NOTES
			Additional information about the function go here.

		.LINK

http://jeffmurr.com/blog

	#>
	[CmdletBinding()]	
	param(
		[Parameter(Position=0, Mandatory=$true)]
		[ValidateNotNullOrEmpty()]
		[System.String]
		$Message,

		[Parameter(Position=1, Mandatory=$false)]
		[ValidateNotNullOrEmpty()]
		[System.Int32]
		$EventId = 0,

		[Parameter(Position=2, Mandatory=$false)]
		[System.String]
		$Source = "PowerShellScript",

		[Parameter(Position=3, Mandatory=$false)]
		[ValidateNotNullOrEmpty()]
		[System.String]
		$LogName = "Application",

		[Switch]
		$Information,

		[Switch]
		$Warning,

		[Switch]
		$Error
	)

	$ErrorActionPreference = "SilentlyContinue"
	if(!(Get-Eventlog -LogName $LogName -Source $Source)){
		$ErrorActionPreference = "Continue"
		try {New-Eventlog -LogName $LogName -Source $Source | Out-Null}
		catch [System.Security.SecurityException] {
			Write-Error "Error:  Run as elevated user.  Unable to write or read to event logs."
		}
	}

	If ($Warning.IsPresent){	
		try { Write-EventLog -LogName $LogName -Source $Source -EntryType "Warning" -EventId $EventId -Message $Message | Out-Null}
		catch [System.Security.SecurityException] {
			Write-Error "Error:  Run as elevated user.  Unable to write or read to event logs."
		}
	}
	ElseIf ($Error.IsPresent) {
		try { Write-EventLog -LogName $LogName -Source $Source -EntryType "Error" -EventId $EventId -Message $Message | Out-Null}
		catch [System.Security.SecurityException] {
			Write-Error "Error:  Run as elevated user.  Unable to write or read to event logs."
		}	
	}
	Else {
		try { Write-EventLog -LogName $LogName -Source $Source -EntryType "Information" -EventId $EventId -Message $Message | Out-Null}
		catch [System.Security.SecurityException] {
			Write-Error "Error:  Run as elevated user.  Unable to write or read to event logs."
		}
	}
}

Get to writing to the event log!

To do this in the blog, I’ll I created a self-signed x.509 certificate and a CN of “PowerShellCert”.  I will use the public portion of the certificate in a file that’s base64 .cer to encrypt the sections. That certificate I’ll place in the Windows key store and referenced by thumbprint for decryption.  For the actual work, I’ll import the CA trusted certificate into the same key store, replace the thumbprint with that CA trusted one and make sure the certificate is trusted either by the user or machine the script is running.

Here’s the command used with the makecert utility to create a 2048 length cert:

C:\Program Files\Microsoft SDKs\Windows\v7.1>makecert.exe -r -pe -n "CN=PowerShellCert" -ss my -sr localmachine -eku 1.3.6.1.5.5.7.3.2 -len 2048 -e 01/01/2030 C:\Scripts\PowerShell\Asymmetrical-Encryption\PowerShellAsymmetrical.cer

Here’s the encryption function:

Function Encrypt-Asymmetric {
	[CmdletBinding()]
	[OutputType([System.String])]
	param(
		[Parameter(Position=0, Mandatory=$true)][ValidateNotNullOrEmpty()][System.String]
		$ClearText,
		[Parameter(Position=1, Mandatory=$true)][ValidateNotNullOrEmpty()][ValidateScript({Test-Path $_ -PathType Leaf})][System.String]
		$PublicCertFilePath
	)
    # Encrypts a string with a public key
    $PublicCert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($PublicCertFilePath)
    $ByteArray = [System.Text.Encoding]::UTF8.GetBytes($ClearText)
	$EncryptedByteArray = $PublicCert.PublicKey.Key.Encrypt($ByteArray,$true)
	$Base64String = [Convert]::ToBase64String($EncryptedByteArray)

	Return $Base64String 
}

…here’s the decryption function:

Function Decrypt-Asymmetric
{
	[CmdletBinding()]
	[OutputType([System.String])]
	param(
		[Parameter(Position=0, Mandatory=$true)][ValidateNotNullOrEmpty()][System.String]
		$EncryptedBase64String,
		[Parameter(Position=1, Mandatory=$true)][ValidateNotNullOrEmpty()][System.String]
		$CertThumbprint
	)
    # Decrypts cipher text using the private key
    # Assumes the certificate is in the LocalMachine\My (Personal) Store
    $Cert = Get-ChildItem cert:\LocalMachine\My | where { $_.Thumbprint -eq $CertThumbprint }
	if($Cert) {
	    $EncryptedByteArray = [Convert]::FromBase64String($EncryptedBase64String)
	    $ClearText = [System.Text.Encoding]::UTF8.GetString($Cert.PrivateKey.Decrypt($EncryptedByteArray,$true))
    }
	Else {Write-Error "Certificate with thumbprint: $CertThumbprint not found!"}

	Return $ClearText
}

To Encrypt clear text:

PS C:\>Encrypt-Asymmetric -ClearText "CLEAR TEXT DATA" -PublicCertFilePath "C:\Scripts\PowerShell\Asymmetrical-Encryption\PowerShellAsymmetricalTest.cer"

To Decrypt clear text:

PS C:\>Decrypt-Asymmetric -EncryptedBase64String $Base64String -CertThumbprint "83D2D68907681EF3D823B23DEE24B0CBB3FA3C51"

To find your Certificate’s thumbprint (assuming you gave it the same name as I did above):

PS C:\> Get-ChildItem cert:\LocalMachine\My | where { $_.Subject -eq "CN=PowerShellCert" } | select Thumbprint

Now, encryption keys can be garded under the Windows key store.

For Starters

Here’s the script that gets my my report from a local computer:

Get-WmiObject -Class Win32_LogicalDisk -Filter "DriveType=3" |
Select-Object Name, FileSystem,FreeSpace,BlockSize,Size |
ForEach-Object {
	$_.BlockSize=(($_.FreeSpace)/($_.Size))*100;$_.FreeSpace=($_.FreeSpace/1GB);$_.Size=($_.Size/1GB);$_
	} |
Format-Table @{n='Server';e={$env:COMPUTERNAME}}, @{n='Disk';e={$_.Name}}, @{n='FS';e={$_.FileSystem}},@{n='Capacity (GB)';e={'{0:N3}' -f $_.Size}},@{n='GB Free';e={'{0:N2}'-f $_.FreeSpace}}, @{n='% Free';e={'{0:N2}'-f $_.BlockSize}} -AutoSize

Do it Remote:

Keep in mind the entire script can be wrapped around a “foreach” statement and pass in the ComputerName parameter for remote execution.

$ComputerNames = @("Server1", "Server2", "Server3")

foreach ($ComputerName in $ComputerNames) {

	Get-WmiObject -ComputerName $ComputerName -Class Win32_LogicalDisk -Filter "DriveType=3" |
	Select-Object Name, FileSystem,FreeSpace,BlockSize,Size |
	ForEach-Object {
		$_.BlockSize=(($_.FreeSpace)/($_.Size))*100;$_.FreeSpace=($_.FreeSpace/1GB);$_.Size=($_.Size/1GB);$_
		} |
	Format-Table @{n='Server';e={$ComputerName}}, @{n='Disk';e={$_.Name}}, @{n='FS';e={$_.FileSystem}},@{n='Capacity (GB)';e={'{0:N3}' -f $_.Size}},@{n='GB Free';e={'{0:N2}'-f $_.FreeSpace}}, @{n='% Free';e={'{0:N2}'-f $_.BlockSize}} -AutoSize

}

Report What You Found:

Afterward, sprinkle in the export type you’d like (file, CSV, etc.) to deliver.

$ComputerNames = @("Server1", "Server2", "Server3")

$DiskSpaceReport = foreach ($ComputerName in $ComputerNames) {

	Get-WmiObject -Class Win32_LogicalDisk -Filter "DriveType=3" |
	Select-Object Name, FileSystem,FreeSpace,BlockSize,Size |
	ForEach-Object {
		$_.BlockSize=(($_.FreeSpace)/($_.Size))*100;$_.FreeSpace=($_.FreeSpace/1GB);$_.Size=($_.Size/1GB);$_
		} |
	Format-Table @{n='Server';e={$ComputerName}}, @{n='Disk';e={$_.Name}}, @{n='FS';e={$_.FileSystem}},@{n='Capacity (GB)';e={'{0:N3}' -f $_.Size}},@{n='GB Free';e={'{0:N2}'-f $_.FreeSpace}}, @{n='% Free';e={'{0:N2}'-f $_.BlockSize}} -AutoSize

}

$DiskSpaceReport | Export-Csv
$DiskSpaceReport | Out-File
$DiskSpaceReport | Out-GridView

The key difference between the two data types is how they’re stored. VARCHAR is stored as regular 8-bit data, NVARCHAR strings are stored in the database as UTF-16.

UTF-8 (UCS Transformation Format—8-bit) is a variable-width encoding that can represent every character in the Unicode character set. It was designed for backward compatibility with ASCII and to avoid the complications of endianness and byte order marks in UTF-16 and UTF-32.

UTF-8 has become the dominant character encoding.  Over half of all internet pages are encoded this way, the Internet Mail Consortium (IMC) recommends that all e-mail programs be able to display and create mail using UTF-8, and UTF-8 is also increasingly being used as the default character encoding in operating systems, programming languages, APIs, and software applications.

UTF-8 is [or continues to be] kind of a big deal… The others, not so much anymore.

Storage

NVARCHAR strings have the same length restrictions as its VARCHAR brother — 8,000 bytes. However, since NVARCHARs use two bytes for each character, that means a given NVARCHAR can only hold 4,000 characters (not bytes) maximum. The amount of storage needed for NVARCHAR entities is going to be twice whatever you’d allocate for a plain old VARCHAR.  Therefore, most don’t want to use NVARCHAR universally, and may want to fall back on VARCHAR — which takes up less space per row — whenever possible.

How it bit me…

I have some data that’s MD5 hased using a C# function much like this example from MSDN that I needed to validate at my data layer (SQL Server 2008 R2).  However, I was getting different values that should have matched since I was providing the same intput.

Here’s the function using the MD5 class

static string GetMd5Hash(MD5 md5Hash, string input)
        {

            // Convert the input string to a byte array and compute the hash. 
            byte[] data = md5Hash.ComputeHash(Encoding.UTF8.GetBytes(input));

            // Create a new Stringbuilder to collect the bytes 
            // and create a string.
            StringBuilder sBuilder = new StringBuilder();

            // Loop through each byte of the hashed data  
            // and format each one as a hexadecimal string. 
            for (int i = 0; i < data.Length; i++)
            {
                sBuilder.Append(data[i].ToString("x2"));
            }

            // Return the hexadecimal string. 
            return sBuilder.ToString();
        }

The code is storing the returned string object in a column along with some salted details for a password.  Somehow a few of the values were not syncing up with the input correctly.  To test I used input and the  HASHBYTES function to convert and compare to stored values with original inputs’ HASED values to find the culprits.  But, what I found was nothing matched!  I went back to simple data to troubleshoot and found that I was getting different values for “FOO” from using the C# method vs. the SQL method!

Here’s an example:

C#

MD5 md5Hash = MD5.Create();
string input = "FOO";
string results = GetMd5Hash(md5Hash, input);
#results = 901890A8E9C8CF6D5A1A542B229FEBFF

SQL

DECLARE @nvarchar nvarchar(400) 

SET @nvarchar = 'FOO'

SELECT CONVERT(VARCHAR(32), HASHBYTES( 'MD5', @nvarchar ), 2)
--RESULT:  4676C8342EF52153F898C2EAAD1C528D

The Problem

The HASHBYTES built-in function indicates it will take an input of varchar, nvarchar, or varbinary to be hashed.  What is easy to overlook is that the encoding of datatype matters.  

Even though it clearly shows in the C# code and example that it is encoding to UTF-8, I didn’t catch it until after I pulled out a few remaining hairs that the encoding of the variables in storage were causing my problem.  SQL ambiguates  the conversion of nvarchar and varchar on the fly, displaying them both as unincoded strings, post conversion when you select on them.  So, the difference its transparent when inspecting the result sets.  At least that makes me “feel” like less of an idiot.

Solution

Depending on how your variable is stored within SQL will dictate the output of your hash, regardless of algorithm since the binary data presented to the function will be different per data type.

Therefore, if you’re wondering why your HASHED values of any encryption algorithm differ from their clear text counter parts.  Ensure your encoding of your data type is the same as the original source.

For a proof, play with the below and modify the datatypes of both the conversion and variables and see how encryption and hashing are always done at the byte level.

 DECLARE @varchar varchar(400) 
 DECLARE @nvarchar nvarchar(400) 

 SET @varchar = 'FOO'
 SET @nvarchar = 'FOO'

 SELECT CONVERT(VARCHAR(32), HASHBYTES( 'MD5', @varchar ), 2)
--RESULT:  901890A8E9C8CF6D5A1A542B229FEBFF
 SELECT CONVERT(VARCHAR(32), HASHBYTES( 'MD5', @nvarchar ), 2)
--RESULT: 4676C8342EF52153F898C2EAAD1C528D

The idea is a good one.  Align with a standard in your latest technologies methods used to manage yourself, making you more usable by others.

In this post I’ll offer a quick WinRM configuration PowerShell script to get this feature configured on a Windows 2008, R2, and Windows 2012 server.  I’ll also offer feedback on the security objection and what I think is the best solution for a native Windows environment since I’ve hand to handle these often in my line of work.

Configuration Simplified

Get right to it for those not wanting to read any more.  Open a PowerShell Console as Administrator on both the client and server, servers and execute:

Write-Host "Configuring WinRM for remote deployment..."
Enable-PSRemoting -Force 
winrm set winrm/config/client `@`{TrustedHosts=`"*`"`}

More detail…

For PowerShell, WinRM is the basis of many cmdlets performing remote commands and tasks.  This includes Enter-PSSession and Invoke-Command.  These cmdlets offer powerful abilities to perform tasks on a remote computer both synchronously and in parallel, asynchronously to an array object of server names.

Believe it or not (from this lengthy write up), Microsoft wanted taking advantage of the protocol easier and less of a burden to implement.  As a result, WinRM.exe comes with a “-quickconfig” option for quick local configuration of itself, complete with a set of Microsoft’s best practice defaults.  Almost too good, and I’ll get to that below.

Therefore, the easiest thing to do is to go to a cmd prompt as an admin and run to get it all started:

WinRM quickconfig

This will set up your local service with everything to get started.  Essentially, turning on the lights.

Powershell’s flavor of this command is rolled up into  Set-WSManQuickConfig.  However, these both only modify the config of the service.  For the windows firewall, Microsoft gave us another cmdlet that’s a wrapper for Set-WSManQuickConfig.  Enable-PSRemoting cmdlet performs a few other functions as well as executing the Set-WSManQuickConfig.  Things like configuring the Windows firewall (in 2.0 it creates the exception, in 3.0 it creates a rule).

If you ride the defaults of these configurations with regards to network port, any external firewalls between your client and server will need to allow tcp 5986 bidirectional for WinRM 2.0 and above, 443 for WinRM 1.1.

Even after you run the “WinRM -quickconfig” or “Enable-PSRemoting”, you’ll find commands attempted remotely like Invoke-Command or Enter-PSSession will still fail complaining about a configuration error.  The reason is that you’ve only turned on the lights, you haven’t told the bouncer who is allowed in.  Be default, these tools do not trust anyone to connect other than…localhost.  The list of allowed servers is listed in the “TrustedHost” property of WinRM configuration.  Both of these tools the default TrustedHost list is blank.

Therefore, lets get back to the PowerShell.  Its a quick and dirty solution that’s wide open and will that need to be executed on both machines you want to configure to talk remote to one another:

Write-Host "Configuring WinRM for remote deployment..."
Enable-PSRemoting -Force 
winrm set winrm/config/client `@`{TrustedHosts=`"*`"`} 
winrm set winrm/config/winrs `@`{MaxMemoryPerShellMB=`"2048`"`}

As you can guess, “*” is everyone and may not be good enough for your needs.  Below we discuss more security aspects of a quick configuration.

Locking it down

There are complex scripts on the internet that allow for the setup of servers, even doing it remotely.  Out of the box both the WinRM and the cmdlets leave you with blank TrustedHosts.  Servers that will send or receive commands from other hosts must either have a white listed “*” or the specific servernames/IP in this list before you can connect.

The next script creates a list of servers passed as a CSV file and establishes it as your TrustedHost property.  As long as a column within your CSV file contains “Server” as a heading, those values will be included in the trusted hosts configuration and applied to the machine’s TrustedHost configuration of WinRM.

param(
	[Parameter(Position=0, Mandatory=$true)]
	[ValidateNotNullOrEmpty()]
	[System.String]
	$CSVFilePath
)

function Get-ServerList {
	param(
		$CSVFilePath
	)

	$Servers = Import-Csv $CSVFilePath
	$Servers | % {$List += $_.Server + ","}

	Return $List.Substring(0,$List.Length - 1)

}

function Configure-WinRM {
	param(
		$ServerList
	)
	Write-Host "Configuring WinRM for remote deployment..."
	Enable-PSRemoting -Force 
	winrm set winrm/config/client `@`{TrustedHosts=`"$ServerList`"`}  
	winrm set winrm/config/winrs `@`{MaxMemoryPerShellMB=`"2048`"`}
}

Configure-WinRm -ServerList $(Get-ServerList -CSVFilePath $CSVFilePath)

Note:  In both examples within the explanation, I’ve up the MaxMemoryPerShellMB.  This is optional; however, I’ve found that many tools that I may need or objects that I create are heavier than the default 150 MB amount.  I’ve found that upping it to 2048 will mitigate my running out of remote memory during processing large commands like regasm or installation packages.  Mis-configuration usually results in an obfuscated -1 exit code or just instability.  It wasn’t until I popped open process explorer that I found I was hitting a limit that most bigger executables require more of.  Totally up to you, but it is part of my server buildout now along with a correct server.csv list and features.

The Remaining Security Concerns (For Windows Environments)

TrustedHosts means only these computers can connect.  Security engineers will wonder what those connections are passing, even if its in a protected zone, between the servers listed and if that’s secure.

First the obvious, SSL is an option for WinRM.  However, I caution configuring it if your talking Windows to Windows. When asked, if you should configure SSL for security loving systems folks it can be tempting to think it is better.  The balance between and security, support and use is something we all have to deal with constantly.  In banking and healthcare it constantly audited, as it should be and I understand, layers is the answer to security.  But, WinRM with WS-Management encrypts all content transmitted over the network using Kerberos and these NTLM (machine) keys.  With Windows, a minimum of 128 bit encryption (Windows 7/2008 and up) is already in place with most later OS’s pushing the AES 256 button now.

The only thing that HTTPS will do is encrypt commands differently, that can be watered down.  Not to mention give a shelf life to your configuration the length of the validity of your certificates, before they expire.  I applaud the extensiblility, but its truly overkill in a windows environment and making something that needs to remain easy too complex; hence me leaving it out of the configuration and discussing it here.

Now, if you’re leaving a Windows environment, yes; install and configure if you’re using a non Windows product to manage a Windows machine.  That’s part of the the initiative behind WS-Management, uniform cross platform communication.  Everyone OS doesn’t have the same encryption methods as Windows baked in.  For that, I’ll have to cover another day.

No problem.  Here’s a quick demo on how it can be done.

Our plan of attack will be to build a web form project using Visual Studio 2012 and .NET Framework 4.5.  It will execute server side and scripts of PowerShell commands using the framework’s PowerShell class from the System.Management.Automation name space.  The response I’ll handle as a string, and paint it to a Text box

Here we go…

First, create the Empty Web Application called PowerShellExecution.

Next, add a New Item… of Default web form named “Default.aspx” to the solution to align with the demo content below.

Now, copy and paste over the default Default.aspx code that’s generated with the below for the quick UI test:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="PowerShellExecution.Default" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title></title>
</head>
<body>
<form id="form1" runat="server">
    <div>
        <table>
            <tr><td>&nbsp;</td><td><h1 align="left">PowerShell Command Harness</h1></td></tr>
            <tr><td>&nbsp;</td><td>&nbsp;</td></tr>
            <tr><td>&nbsp;</td><td>PowerShell Command</td></tr>
            <tr><td>
                <br />
                </td><td>
                <asp:TextBox ID="Input" runat="server" TextMode="MultiLine" Width="433px" Height="73px" ></asp:TextBox>
            </td></tr>
            <tr><td>
                &nbsp;</td><td>
                <asp:Button ID="ExecuteCode" runat="server" Text="Execute" Width="200" onclick="ExecuteCode_Click" />
            </td></tr>
                <tr><td>&nbsp;</td><td><h3>Result</h3></td></tr>
                <tr><td>
                    &nbsp;</td><td>
                    <asp:TextBox ID="ResultBox" TextMode="MultiLine" Width="700" Height="200" runat="server"></asp:TextBox>
                </td></tr>
        </table>
    </div>
</form>
</body>
</html>

Next, to get the System.Management.Automation name space included in our solution we need to install the System.Mangement.Automation package.  To do that, under the Tools menu select Library Package Manager >> Package Manager Console

…within the Package Manager Console execute “Install-Package System.Management.Automation”

After a successful execution of that package install, you’ll want to add the reference to your Default.aspx.cs file:

using System.Management.Automation;

I’m going to use a button’s onclick action to invoke the method that will perform the magic of submitting and reading the response from my PowerShell.  The remaining item to address, that may vary on your circumstance, is how to handle the response from the PowerShell.

Remember, everything in PowerShell is returned as an object.  We need to display our object back on the page as a string for this demo.  You’ll need to be mindful of that when executing, as well as how or what you’re wanting your results displayed on the page.

To ensure that happens for me, I am going manage the output of my PowerShell execution by building a string out of the objects returned.  I’ll paint those string casted results in a TextBox control called “ResultBox” using the StringBuilder class within in the System.Text name space.  Therefore, I need to reference that name space as well in my code behind.

using System.Text;

Below is my complete Default.aspx.cs code for the purposes of this demo.  It includes the above references  I discussed, the default page load, and especially the onclick method to support the execution details submitted to the Input control using the PowerShell class.

I sprinkled in comments for context:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Management.Automation;
using System.Text;

namespace PowerShellExecution
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {

        }

        protected void ExecuteCode_Click(object sender, EventArgs e)
        {
            // Clean the Result TextBox
            ResultBox.Text = string.Empty;

            // Initialize PowerShell engine
            var shell = PowerShell.Create();

            // Add the script to the PowerShell object
            shell.Commands.AddScript(Input.Text);

            // Execute the script
            var results = shell.Invoke();

            // display results, with BaseObject converted to string
            // Note : use |out-string for console-like output
            if (results.Count > 0)
            {
                // We use a string builder ton create our result text
                var builder = new StringBuilder();

                foreach (var psObject in results)
                {
                    // Convert the Base Object to a string and append it to the string builder.
                    // Add \r\n for line breaks
                    builder.Append(psObject.BaseObject.ToString() + "\r\n");
                }

                // Encode the string in HTML (prevent security issue with 'dangerous' caracters like < >
                ResultBox.Text = Server.HtmlEncode(builder.ToString());
            }
        }
    }
}

Copy and paste that in and you’re ready to test…

Once rendered in your browser, type into the “PowerShell Command” window Get-Service | Out-String (or your favorite cmdlet for a test).

Remember, port everything to the Out-String cmdlet so it can be handled properly by the StringBuilder class.  Otherwise, you’ll get stringbuilder output of the data type details of the objects returned by your cmdlet – one long get-member call, most likely not what you’re after.

If you’re wondering if you can run scripts that are on the local file system of the server, the answer is yes.  Simply pass the script location an parameters in string form to the AddScript() method within Default.aspx.cs using double slashes format.

//shell.Commands.AddScript(Input.Text);
shell.Commands.AddScript("C:\\Scripts\\PowerShell\\PowerShellScript.ps1");

Contents of this test PowerShellScript.ps1 (same as what was used in the Input control):

Get-Service | Out-String

(I removed the Input box control and test again the solution below)

Note: To run this on a server, the ApplicationPool hosting your application will have to have administrator rights.

There you have it, a quick server side PowerShell web method.