Monday, 18 September 2017

Introduction

When you build up your own library of functions, it’s really useful to have them always available on your machine without you having to load script files etc. This is where creating your own PowerShell module comes in handy. You can have all your functions available in this module and just take it around wherever you go.

Today, I’m going to write a simple function and then create my own module which includes this function.

How to build a PowerShell module

So, this is really not as hard as it seems. The basic steps are below:

3 - Create a module manifest

We now need a module manifest so that our module can be loaded automatically and so that PowerShell knows which functions to provide to the user. To create a module manifest, you need to use the New-ModuleManifest cmdlet. The module manifest file is a .psd1 file.

We now have a module manifest which includes information about our module and very importantly which functions to export and allow the user to access. The FunctionsToExport parameter lists which functions we want to provide to users, i.e. which functions we want to export. It’s all nice and simple really.

You should now be able to import your module and use all the functions you’ve exported. In Server 2012 and later, you don’t need to even import it - Windows Server just imports it as you call one of the functions. See below for our function in action:

So, there we have it - that's how you create PowerShell modules but manual steps I hear you say? Well, you can just write your own function that will package up your module for you and create the manifest and you can even save that function in another module.

Monday, 4 September 2017

Introduction

Sometimes you can’t find the DSC resource you need built into Windows. For example, let’s say you want to deploy a certificate from your CA - the DSC resource just doesn’t exist but then there’s GitHub. I’ll demo how you can search for and install the xCertificate DSC resource then how to use it in your configuration.

Find DSC Resources

GitHub is a great repository for DSC resources which are not yet included in Windows. You can go to GitHub and download the additional DSC resources you need or you can just search for them using PowerShell:

Find-Module -Tag dsc

You can also filter by name e.g.

Find-Module -Tag dsc -Name *cert*

Our module is called xCertificate. Now, that was quite easy. Let’s move on.

Install DSC Resource

The DSC resource is actually part of a module which we need to install. To do this, we simply run the command below. It will prompt you to install a NuGet module if you don’t already have it - this is used to get modules from GitHub:

Install-Module xCertificate -Force

We can check our module is installed too:

Get-Module xCertificate -ListAvailable

You need to install the module on the server you’re writing your configuration on and also on the target server (the one that will receive the configuration). In upcoming articles, I’ll explain how to pull configurations using SMB or HTTPS. Using a pull server, you not only have a central repository for configurations but also have a central repository for the modules which are pulled as well. How good is that!?

To save time and install the module on a remote computer (contchidsc01), we can use remote PowerShell to install the NuGet Package Provider and xCertificate module:

Deploy a certificate with DSC

Okay, so we now have all the pre-requisites we need. We have the DSC resource on our development machine and our target server. Let’s go ahead and write a DSC configuration. If you’re not familiar with this then go back and review part 1. You’ll see I’m using parameters in my configuration - if you’re not familiar with this, go and review part 3.

The plan is to deploy a new certificate to our target server, contchidsc01. The details are below:

You’ll see we’re using our new xCertificate module and calling a new resource called xCertReq. The xCertReq DSC resource is what we need to request a certificate from the CA. There are other DSC resources available in the module and you can find all the documentation on GitHub here.

This line below simply gets the FQDN of the computer and saves it as $ComputerFqdn. We use it to add it to the certificate names:

Now, that’s a lot of info because we’re using the -Verbose switch on the Start-DscConfiguration cmdlet. If you look closely at the blue section, you’ll see DSC doing this:

Locate the CA

Call certutil to ping the CA to check it’s online

Check for a certificate which matches the names we’ve requested

Create a certificate request

Install the certificate

At the end, in white, Test-DscConfiguration runs and states that our target machine is in the desired state so let’s check we have the correct certificate installed on our target machine:

Connect to remote PowerShell on the target computer:

Enter-PSSession contchidsc01

Open up the local computer certificate store:

cd Cert:\LocalMachine\My\

List the certificates:

dir

Now we have our certificate installed!

Conclusion

We’re learning quite a lot about DSC. We’re now able to find the DSC resources we need to do almost anything we need to do and we know how to find the documentation, download the modules and use the included DSC resources. So far, we’ve been pushing configurations using Start-DscConfiguration but in the upcoming posts, we’ll look at configuring SMB or HTTPS pull servers.

Sunday, 3 September 2017

Introduction

So, we’ve learnt a bit about the basics of DSC with a simple configuration using the File DSC resource in part 1 and then moved on to discuss other DSC resources you can find built into Windows in part 2.

In this post, I’ll show you how you can integrate parameters when creating DSC configurations and also how you can set up dependencies between different DSC resources in your configuration.

When we run this, we can see that the HKEY_Local_Machine\Software\DSCTest key is created then the DSCTestGood value is created and set to True and the type is set to REG_SZ, (string).

So, there we have it. PowerShell parameters. Now, let’s say you need to deploy a number of different registry keys and values to a number of machines and you have it all in a CSV. Well, now you can do that quite easily - all using the same configuration.

PowerShell DSC DependsOn

Let’s say we need to copy a zip file to a target machine and then extract that zip file to a folder. Now, clearly we don’t want DSC to try extract a zip file before it’s been copied over because that would be rather dumb. Here’s where we can specify the order that DSC Resources are processed in a configuration - by using the DependsOn parameter which is built into DSC resources.

We’ll use the File DSC resource to copy the zip file over then we’ll use the Archive DSC resource to extract it but we’ll specify that the Archive DSC resource depends on the File DSC resource:

When we run this configuration and push it out, we see that our zip file is copied then extracted:

We can also look at the output from Start-DscConfiguration and we’ll see that the File DSC resource is run before the Archive DSC resource:

So, now you can get your configuration to apply DSC resources in order and ensure dependencies are met.

Conclusion

That’s DSC working with parameters and dependencies. I hope you’re starting to get into PowerShell DSC as much as I am! Next up, we’ll look at how to find, install and use DSC modules that are not build into Windows.

Saturday, 2 September 2017

Introduction

In part 1, we went through how to make a simple configuration using the File DSC resource and then how to push it out to a single computer. In this part, we’ll go through how to learn about the available DSC resources and demo a few of them.

List DSC Resources

Windows has a number of DSC resources built in and you can view the list by using Get-DscResource:

Get-DscResource -Module PSDesiredStateConfiguration

Get help for a DSC Resource

Now, let’s say you think you need to use the Service DSC resource but you don’t know the syntax, you can use Get-DscResource:

Get-DscResource Service -Syntax

You can also use Get-DscResource to get information about what properties you can set:

Get-DscResource Service | % Properties

Service DSC Resource Example

As we’ve just seen the syntax of how to use this DSC resource, let’s start with this.

My target machine has the Windows Audio service stopped and the service is set to manual start:

Get-Service Audiosrv | fl *

I want to set this to start automatically and to also start the service so the configuration I’d use is below. (Remember to import the correct module that has your DSC resource - in our case it’s the PSDesiredStateConfiguration module):

Conclusion

As you can see, you can do a lot with PowerShell DSC and these are just a few of the built in DSC resources you can use. There’s a lot more on GitHub and we’ll come to this in part 4. Stay tuned for part 3 where we’ll start using parameters and a setting called DependsOn.

Monday, 28 August 2017

Introduction

PowerShell DSC. What’s that? DSC stands for Dynamic State Configuration. It sounds like it could get a little complicated but if you’re just starting out using PowerShell to deploy configurations to machines then you’ll probably be lost in long scripts which check whether your configuration is correct then takes the steps to correct it.

You would have to write out the check statements and then write out all the logic to install the feature or copy the file etc.

With PowerShell DSC, you just state what you want your configuration to look like and DSC just “makes it so” and that’s the beauty of DSC.

Advantages of PowerShell DSC

As explained above, you need to write less code. That’s great but there’s more.

1) You can read through your code easier

This is called a configuration document. Rather than having a long script with if statements and lots of logic, you now just have a simpler script which states what you want the configuration to look like.

2) Look for configuration drift

DSC allows you to check a server against a configuration document to make sure there hasn’t been any changes.

3) Auto-remediation

DSC periodically checks a server’s configuration against the configuration document and then can be set to automatically restore the configuration to what it should be

4) Remote execution

You can deploy a configuration to remote machines and you can apply the same configuration to many machines

5) Centralised repository

You can configure your servers to pull their configuration from a central repository. This saves you having to copy scripts around and helps you manage versioning.

6) Works with workgroup servers

You’re not tied down to Kerberos authentication! You can deploy configurations to remote machines which are not on the domain.

7) Different teams can manage different configurations

This is called partial configurations. For example it allows your DBAs to manage the SQL related configuration while your systems team can manage the networking and your developers manage IIS.

8) One to many deployment

You can deploy the same configuration to more than one server at a time.

As you can see, DSC is really the best thing since sliced bread! It saves so much time and is a very elegant and efficient way to deploy configurations.

PowerShell DSC Example

Let’s take a look at a quick example. Let’s say we just want to make sure that an install file is copied to C:\Software on our server.

Server to configure: contlonsql01

Source file: \\contchisql01\Software\Installer.msi

Destination file: C:\Software\Installer.msi

Here’s what we’d write out to make this happen. Things to note:

configuration. This specifies that this is a PowerShell DSC configuration and the name is Configuration1.

Import-DscResource -ModuleName PSDesiredStateConfiguration. Perhaps you guessed it already but this imports the DSC resources from the DSC module. We’ll go into resources and modules another time so don’t worry about this line for now.

node is an array of servers we want to configure.

File. This specifies that we will be asking DSC to do a file or folder operation and we tell it what we want - i.e. we want to ensure that installer.msi is present which means it needs to be copied from the source location to the destination location.

Push a DSC configuration

Now we need to push the configuration to the machine. To do this we need to create a Management Object File or MOF file and we simply run the configuration and specify an output path for the MOF file:

Configuration1 -OutputPath C:\DS

Let’s take a look at the contents of C:\DSC

Note that the MOF file is named after the node specified in the configuration. If you have specified more than one node then you’ll get one MOF file per node.
We then deploy the configuration by using Start-DscConfiguration

Start-DscConfiguration -Path C:\DSC

Note that you don’t really get much output here. You just see that a job’s been started. if you want to get the output of the job, you can run use Get-Job:

Get-Job 11

So, it’s completed and we can confirm our install.msi file has been copied over:

We can also use Test-DscConfiguration to check our target machine configuration against the configuration we deployed to it:

Test-DscConfiguration -Path C:\DSC

Conclusion

So, that’s just a quick intro into PowerShell DSC. It’s such a great way to configure your servers and definitely the way of the future. In the next post, I’ll talk through DSC resources - these define what types of configuration settings you can make e.g. file, windows features, registry changes etc. Click here for part 2 to continue the DSC journey.

Saturday, 26 August 2017

Introduction

So, another rather standard day but made a little more interesting with some new tips on getting your PowerShell functions to provide some more feedback. We’re going to look at how to get your script to use the -Verbose and -Debug parameters.

Simple function

Okay, so our simple function is below. It just takes a Message parameter of and outputs Welcome <message> in green.

function Welcome { param( [string]$Message )

Write-Host Welcome $message -ForegroundColor Green }

We can run the function as below:

Welcome -Message "to my blog!"

Nothing really that interesting here. Let’s move on.

Add -Verbose and -Debug to a PowerShell function

Here I’m adding another part to the script - [cmdletbinding()]. This automatically adds the -Verbose and -Debug parameters to the script and does all the logic behind it. By default, Write-Verbose doesn’t actually produce an output.

#Verbose - this is only shown if the -Verbose switch is used Write-Verbose -Message "This is verbose output"

#Debug - this causes the script to halt at this point Write-Debug "This is debugging information"

#Actual function Write-Host Welcome $message -ForegroundColor Green }

We can now run the function and specify the -Verbose parameter and we can see we’re now getting the output from Write-Verbose:

Welcome -Message "to my blog!" -Verbose

Let’s test out -Debug now. Debug is useful for when you’re debugging your script (who would have thought). Basically, it outputs Write-Debug, pauses the script and asks for you to either continue running it or to halt it. Write-Debug could contain more than just text. For example, if you want to check the value of a variable before it’s used, you can use Write-Debug to output the variable and then prompt you to either continue or halt the script.

Welcome -Message "to my blog!" -Debug

I selected Y and so it continued running the rest of the script:

So, there you have it. How to add -Verbose and -Debug into your functions.

Tuesday, 22 August 2017

Problem

Okay, so here’s the problem. You want to migrate VMs from VMware vSphere 5 or 6 or whatever to Hyper-V 2016 but you can’t find a tool to use because you want near-zero downtime. You search around and find some options:

Sysinternals Disk2Vhd

Great tool and free! The problem is that you need a lot of downtime because it converts the entire disk and you cannot sync changes after the conversion is done so you need downtime from the time you start the conversion.

Microsoft Virtual Machine Converter

Another good tool but no longer supports the later versions of vSphere or Hyper-V. In fact, the tool itself is not supported as of June 3rd 2017. See more here. However, even if you do use it, you still cannot do the incremental sync that you need.

Third party tools to migrate VMware to Hyper-V

There’s some very useful tools that you can use but these come at a cost but will literally do near-zero downtime conversions. Have a look at Quest, Double-Take or PlateSpin.

Solution

So, I found a neat little workaround for this. Basically, use Veeam. Now, you need both Veeam Agent for Windows and Veeam Backup and Replication (and you can get free trials for both). The steps are below:

Install Veeam Agent for Windows on your VM

Install Veeam Backup and Replication on a backup server

Add your host into Veeam Backup and Replication

Create a backup repository in Veeam Backup and Replication

Back up your VM to a Veeam Repository on the backup server using Veeam Agent for Windows

Prevent users accessing the server to make changes

Do an incremental backup of your VM and shut it down

Use Veeam Backup and Replication to rescan the repository

Use Veeam Backup and Replication to do an Instant Restore of your VM onto a Hyper-V host and select to power on the VM

Re-enable user access

Use Veeam Backup and Replication to migrate the VM onto production storage (using the Instant Restore wizard)

The advantages of doing this are that you minimize downtime by doing incremental backups and then doing an instant restore. If you’re not familiar with this, Veeam Backup and Replication creates dummy VHD and VM configuration files on the Hyper-V storage which actually reference the backup server storage and the VM runs off the backup server storage. To improve performance, you may want to add faster disks and use 10Gb networking on your backup servers.
If you are a hosting provider then you really don’t want tenant VMs with access to the backup server so you can use the Veeam Cloud Connect Gateway (part of the Veeam Cloud Connect suite). This only requires a single port to be open from the tenant network - it’s generally used to back up VMs over the internet so it was designed with that security in mind.
I hope this helps people out as it looks like MS aren’t really providing a solution to do this just yet.

Saturday, 4 March 2017

Overview

So, you get an escalated call from the helpdesk saying someone’s lost their private key. So, we only had one copy of that. Now what?
Well, here’s where key archival comes into play. You configure your CA to enable key archival and then you specify that your certificate templates have key archival enabled and now your private keys are copied to your CA so you can recover them when needed!

How to enable key archival

Identify a user to serve as the key recovery agent. In this case, we'll use the account LITWARE\Administrator.

Open your Certification Authority snap-in, right click Certificate Templates and click Manage. You now see a list of certificate templates:

Configure the key recovery agent certificate template with Read and Enroll permissions for the key recovery agent (LITWARE\Administrator). You do this on the Security tab:

Now we need to configure the CA to use issue the new certificate template. Right click Certificate Templates, click New then click Certificate Templates to Issue

Select your new Key Recovery Agent 2 certificate and click OK

Now we need to enroll the Administrator account for the Key Recovery Agent 2 certificate. To do this, open up certmgr.msc and click on PersonalClick on Action > All Tasks > Request New Certificate

Click next

Click to select the Key Recovery Agent 2 certificate and then click Enroll to finish the wizard:

Note that it didn't issue the certificate - the status is Enrollment pending. Now, go back to your CA snap-in and click on Pending Requests. You should see a pending request for the certificate you just enrolled.

Right click the certificate, click on All Tasks and then Issue. The certificate is now issued.
Now, right click the CA and go to Properties and select the Recovery Agents tab. Select Archive the key, select the Number of recovery agents to use (one in our case):

Click Add and select the certificate which was issued to your chosen user:

Click OK twice and you're then prompted to restart the AD CS services so go ahead and click Yes

So, we've now created our Key Recovery Agent certificate template, issued it to our Key Recovery Agent and configured the CA to use a Key Recovery Agent. We're not protected against key loss just yet because the certificate templates that are issued out need to have key archival enabled.
Right click on a certificate template which you need to enable key archival for, duplicate it, give it a name, go to Properties and then to the Request Handling tab. Tick Archive subject's encryption private key:

On the Superseded Templates tab, add all the certificate templates that you want to be replaced by your new one then click OK:

This doesn't protect against loss of private keys for certificates which have already been issued so in this case, you need to get the clients to reenroll these. Right click on your original certificate and select Reenroll All Certificate Holders:

Go for an 8hr coffee break or just sit and stare at the screen…….

Go to Issued Certificates in the CA snap-in and add the Archived Key column. Eventually, you should start to see new certificates issued and you can see that the key is archived: