Windows Server 2019 Automation with PowerShell Cookbook - Third Edition

This recipe assumes you have set up the VM farm for this book as described in the Preface to the book. In particular, this recipe uses a Windows Server 2019 host running as a domain controller (DC1), a Windows 10 client computer (CL1), plus two domain-joined servers (SRV1, SRV2).

Your client system should be Windows 10 Enterprise or Professional. Once you have installed the operating system, you should customize it with some artifacts used throughout this book, as follows:

#   Set execution Policy
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force
#   Create Local Foo folder
New-Item C:\Foo -ItemType Directory -Force
#   Create basic profile and populate
New-Item $profile -Force -ErrorAction SilentlyContinue
'# Profile file created by recipe' | OUT-File $profile
'# Profile for $(hostname)'        | OUT-File $profile -Append
''                                 | OUT-File $profile -Append
'#  Set location'                  | OUT-File $profile -Append
'Set-Location -Path C:\Foo'        | OUT-File $profile -Append
''                                 | OUT-File $profile -Append
'# Set an alias'                   | Out-File $Profile -Append
'Set-Alias gh get-help'            | Out-File $Profile -Append
'###  End of profile'              | Out-File $Profile -Append
# Now view profile in Notepad
Notepad $Profile
# And update Help
Update-Help -Force

These steps create the C:\Foo folder, create a profile, and update the PowerShell help information. You can add other customizations to these steps, such as adding VS Code or other third-party modules.

This recipe installs the RSAT tools on both a Windows 10 domain-joined computer (CL1) and on several Windows 2019 servers. The recipe also displays the results of the installation. You begin, in step 1, by getting all the commands available on the Windows 10 host and display a count.

Depending on the specific version of Windows 10 you use and what tools you may have already added to the client, the counts may be different. Here is what the output of this step looks like:

As you can see, 1528 total commands existed prior to adding the RSAT tools. In step 2, you examine the different types of command that make up that total, as shown here:

PowerShell includes aliases, functions, filters, and cmdlets as commands. Adding the RSAT tools increases the number of commands available. In step 3, you display a count of the modules installed currently, which looks like the following:

In step 4, you obtain the hardware platform and the Windows 10 version, which looks like this:

In step 5, you create a URL for downloading the RSAT tools. Different versions exist for different hardware platforms (for example, x86 and amd64) and for major Windows 10 versions (1709 and 1803). In step 6, you display the URL, which looks like this:

In step 7, you use the Background Intelligent Transfer Service (BITS) to retrieve the URL and store it as C:\Foo\Rsat.msu. The transfer produces no output.

In step 8, you check the Authenticode digital signature of the downloaded file to ensure the file was transferred correctly and has not been tampered with, which looks like this:

In step 9, you run the downloaded file that installs the RSAT tools. Aside from the message that the script is installing the RSAT tools, PowerShell runs this silently and there is no additional output from this step.

In Step 10, you determine that CL1 now has a total of 1270 commands, as shown:

In step 11, you discover the number of RSAT tools and the total of modules now available on CL1, as shown:

In step 12, you display the modules that were added to CL1, which looks like this:

The preceding steps complete the task of installing the RSAT tools on a Windows 10 client. In some cases, you may also want to install the relevant tools on some or all of your servers.

In this part of the recipe, you are installing the RSAT tools onto server SRV1. You then compare the tools added to SRV1 with what is available on other servers (for example, DC1 and SRV2). In this case, DC1 is a domain controller with other features added during creation of the DC1 server. SRV2, on the other hand, starts as just a domain-joined server with no additional tools.

In step 13, you determine the features available on the three servers—this produces no output. In step 14, you display a count of the features and RSAT features available on each server, which looks like this:

In step 15, you install the RSAT tools remotely on SRV1. To complete the installation, you also reboot the server if the installation requires a reboot. The output looks like the following:

In step 16, you determine the features now available on the three servers, producing no output, and finally, in step 17, you display the results, as follows:

In step 1, you saw that there were 1528 commands loaded on CL1 while in step 4 you saw that you had 77 modules on your system. PowerShell gets commands primarily from modules, although older PowerShell snap-ins also contain cmdlets. If you wish to use a command contained in a snap-in, you have to load the snap-in explicitly by using Add-PSSnapin. PowerShell can only auto-load commands found in modules.

In step 4 and step 5, you calculate and display a URL to download the RSAT tools. These recipe steps work for two versions of Windows 10 and for two hardware platforms. The URLs and versions of Windows 10 available may have changed by the time you read this. Also, the recipe caters just for Windows 10 versions 1709 and 1803. Download files for earlier versions are not available in the same way as for later versions. And for versions later than 1893, the mechanism may change again.

In step 15, when you displayed the results of adding features to SRV1, the output looked different if the formatting had been done on the server. On the server, PowerShell is able to display XML that states how to format output from WindowsFeature cmdlets. Windows 10 does not display XML, hence the list output in this step.

This recipe uses SRV1—a domain-joined server that you partially configured in the Installing RSAT Tools on Windows 10 and Windows Server 2019 recipe.

In step 1, you review the cmdlets contained in the PackageManagement module, which looks like this:

In step 2, you review the package providers installed by default in Windows Server 2019, which looks like this:

In step 3, you examined the packages downloaded by the msu provider. In this case, you only see one update, but you may see more, and it looks like this:

In step 4, you examine details of the NuGet provider. If the provider doesn't exist, then using the -ForceBootstrap parameter installs the provider without asking for confirmation, like this:

In step 5, you search for additional package providers, like this:

In step 6, you install the Chocolatey package provider, which looks like this:

In step 7, you examine the list of package providers now available to confirm that the Chocolatey provider is available, which looks like this:

In step 8, you check to see how many packages are available to download from Chocolatey, as follows:

In step 6, you installed the Chocolatey package provider. To see more details about what Install-PackageProvider is doing, run this step with the -Verbose flag.

This recipe runs on the SRV1 server. The recipe also assumes you have performed the previous recipes in this chapter. In particular, you should have added the latest version of the NuGet package provider to your system. If you have not already done so, ensure the provider is installed by performing the following:

Install-PackageProvider -Name NuGet -ForceBootstrap

This recipe uses the cmdlets in the PowerShellGet module to demonstrate how you can obtain and leverage modules and other PowerShell resources from the public PSGallery site (https://www.powershellgallery.com/).

In step 1, you review the commands contained in the PowerShellGet module, which looks like this:

Because the NuGet package provider is required to use the PowerShell Gallery, you need to have this provider loaded. In step 2, you check the version of the provider, which looks like this:

PowerShellGet requires NuGet provider version 2.8.5.201 or newer to interact with NuGet-based repositories, including PSGallery. In this case, you have a later version of the NuGet provider.

In step 3, you check what version of PowerShellGet is currently installed on SRV1, which looks like this:

In step 4, you install the latest version of the PowerShellGet module from PSGallery, which produces no output. In step 5, you view the versions of PowerShellGet that are now available on SRV1, like this:

In step 6, you examine the repositories PowerShell knows about (thus far), like this:

In step 7, you examine other providers contained in the PSGallery, which you can download and use as needed:

To discover some of the things you can find using PowerShellGet, in step 8 you get the commands in the module that use the Find verb, like this:

There are a variety of resources you can obtain from the PSGallery. In step 9, step 10, and step 11, you get the command, modules, and DSC resources respectively that are in the PSGallery. This generates no output. In step 12, you display those counts, which looks like this:

In step 13, you install the TreeSize module from the PSGallery, which generates no output. In step 14, you look at the commands contained in the module (there is only one), then you run the command, which looks like this:

In step 15, you remove the module—this generates no output.

In some cases, you may wish to download the module to a separate folder to enable you to test the module before formally installing it. In step 16, you create a folder in your home drive, generating no output. Next, in step 17, you save the module into that folder and look at what's in the downloaded files folder, which looks like this:

In step 18, you load the module from the download folder. Using the -Verbose switch enables you to see what Import-Module is actually doing. The output is as follows:

Once you have imported the module you can then use either the Get-Treesize function or its alias, TreeSize.

In step 3, you discover that the version of the PowerShellGet module on the host is version 1.0.0.1 which ships with Windows 10. Since the initial release of Windows 10, PowerShellGet has become a community-developed project, based at GitHub. The latest version of the module is available both from GitHub or via PSGallery, with the latter being easier to work with for most IT pros. Visit the GitHub site to get more information: https://github.com/PowerShell/PowerShellGet.

In step 4, you added the latest version of the PowerShellGet module onto your system and in step 5, you saw you now had two versions. PowerShell, by default, uses the later version, unless you explicitly load an earlier version prior to using the commands in the module.

In this recipe, you downloaded, used, and removed the TreeSize module—one of thousands of modules you can freely download and use. Other popular modules in the PSGallery include:

For most IT pros, PSGallery is the go-to location for obtaining useful modules that avoid you having to re-invent the wheel. In some cases, you may develop a particularly useful module (or script or DSC resource), which you can publish to the PSGallery to share with others.

See https://docs.microsoft.com/en-us/powershell/gallery/concepts/publishing-guidelines for guidelines regarding publishing to the PSGallery. And, while you are looking at that page, consider implementing best practices in any production script you develop.

This recipe runs on the SRV1 server.

You begin this recipe, in step 1, by creating the folder you are going to use to hold your repository, in this case C:\RKRepo, as follows:

In step 2, you share this folder, like so:

In step 3, you create the repository in the shared folder, which produces no output. In step 4, you view the repositories configured on the system, like this:

You next create a simple module to be published into your repository. You begin, in step 5, by creating a working folder for your module, then in step 6 you create a very simple script module with a single function. Neither step produces any output.

In step 7, you test the module by importing it from the working module folder. By using the -Verbose switch, you can observe how PowerShell imports the module, then you invoke the Get-HelloWorld function via its alias GHW, as follows:

Although the module works as-is, you need a manifest in order to publish the module. In step 8, you create a very simple module manifest and store it in the module folder. In step 9, you publish the module. None of these three steps produce any output.

With the module published, in step 10 you can use Find-Module to discover what is in the repository, like this:

The repository is just a file share holding a set of one or more NuGet packages. As you can see in step 11, our repository has just one item published, as shown here:

In step 2, you create a share that allows everyone full access to the repository. In a corporate environment, you should review the access to the repository. Perhaps you should give authenticated users read access, and grant write access to a smaller group of administrators.

As you can see in step 11, a PowerShellGet repository is just a file share that holds NuGet packages. One approach might be to keep your module source in your source code repository and publish it to the internal PowerShellGet repository as needed.

Run this recipe on the Windows 10 client (CL1) you used in the earlier Installing RSAT Tools on Windows 10 and Server 2019 recipe.

In step 1, you create a self-signed code-signing certificate which you store in the current user's personal certificate store (also known as Cert:\CurrentUser\My). Since you store the certificate in $Cert, there is no output from this step. In step 2, you examine the code-signing certificates in the current user's personal certificate store, like this:

In step 3, you create a very simple PowerShell script, which you store in C:\Foo\Signed.ps1. Then you display the file's details, like this:

Now that you have a script, in step 4 you sign it. Note that this generates a status error of UnknownError (which means the signing certificate is not trusted). The output of this step looks like this:

In step 5, you view the script file and note the file is considerably larger (due to the length of the digital signature), which looks like this:

In step 6, you test the script to validate the signature, like this:

As you can see, the underlying reason for the UnknownError status is that the signing certificate is not trusted. You can configure Windows to trust your signed certificate by copying your self-signed certificate into the Root CA store (either for the current user or for the computer).

In step 7, you copy your self-signed certificate into the current user's Root CA store, using the .NET Framework. Copying a certificate into the root store produces no console output, but does generate a pop-up message, which looks like this:

Now that the signing certificate is trusted, in step 8 you re-sign the script, which produces no output. In step 9, you test the re-signed script, as shown here:

PowerShell's certificate provider does not support copying a certificate into the root CA store. You can overcome this limitation by dipping down into the .NET framework as shown in step 7, although this does generate a pop-up dialog box as shown previously.

Once you complete the steps in this recipe, you can experiment with an execution policy and make changes and observe the results. After signing the script, for example, as you did in step 8, try updating the script and running it with an execution policy set to AllSigned.

Establishing a secure code-signing environment can be a lot of work. Once you have the code-signing certificate, you need to keep it secure (for example on a smart card that is locked in a safe with highly limited access). Then you need procedures to enable the organization's scripts to be signed. Creating the infrastructure to manage the whole process, including dealing with the smart cards and the safe, is possibly overkill for many.

If you release PowerShell scripts commercially or publicly (for example via GitHub or PSGallery), signing what you publish is probably a good thing to do, preferably with a public CA-issued certificate.

See https://www.globalsign.com/en/blog/the-importance-of-code-signing-redux for some thoughts on the importance of code signing in general.

Whether or not you deploy code signing, it's useful to know how to do it.

Before you use the recipe, you need to create the domain accounts and groups that you use in this recipe. This includes a user (JerryG) and a security group (RKDnsAdmins) which contains the user, with both of these under an Organizational Unit (IT). You installed the RSAT tools in the Installing RSAT Tools on Windows 10 recipe on CL1—so you can run this step on either CL1 or on DC1. Creating these AD objects looks like this:

# Create an IT OU
$DomainRoot = 'DC=Reskit,DC=Org'
New-ADOrganizationalUnit -Name IT -Path $DomainRoot
# Create a user - JerryG in the OU
$OURoot = "OU=IT,$DomainRoot"
$PW     = 'Pa$$w0rd'
$PWSS   = ConvertTo-SecureString  -String $PW -AsPlainText -Force
$NUHT   = @{Name                  = 'Jerry Garcia'
            SamAccountName        = 'JerryG'
            AccountPassword       = $PWSS
            Enabled               = $true
            PasswordNeverExpires  = $true
            ChangePasswordAtLogon = $false
            Path                  = $OURoot
}
New-ADUser @NUHT
# Create ReskitDNSAdmins security universal group in the OU
$NGHT  = @{
  Name        = 'RKDnsAdmins '
  Path        = $OURoot
  GroupScope  = 'Universal'
  Description = 'RKnsAdmins group for JEA'
}
New-ADGroup -Name RKDnsAdmins -Path $OURoot -GroupScope Universal
# Add JerryG to the ReskitAdmin's group
Add-ADGroupMember -Identity 'RKDNSADMINS' -Members 'JerryG'
# Create JEA Transcripts folder
New-Item -Path C:\foo\JEATranscripts -ItemType Directory

This recipe sets up a JEA endpoint on DC1 and then uses that to demonstrate how JEA works. The recipe relies on a user (JerryG), who is a member of a group (RKDnsAdmins) in the IT organizational unit within the Reskit.Org domain. The recipe provides the user with the commands necessary to do the job of a DNS administrator, and no more.

In step 1, you create a temporary folder on DC1 that is to hold the role capabilities file, which you define in step 2. In step 3, you create a module manifest in the module folder. Then, in step 4, you create a folder for the Role Capacities folder inside the module and copy the previously created .PSRC file into this new folder. In step 5, you create the JEA session configuration file. There is no output from these five steps.

In step 6, you test the session configuration file, as shown here:

This step returns a value of True, which means the session configuration file can be used to create a JEA session.

With all the prerequisites in place, in step 7 you register the JEA endpoint, like this:

In step 8, you check to see what commands (including aliases, functions, cmdlets, and applications) a user would have if they used this JEA endpoint. Because the role capabilities folder was set up to enable the user to have access to all the DNS server commands, there are a large number of DNS cmdlets available which are not shown simply to conserve space, like this:

The final task is to discover what a user can do in a JEA session. In step 9, you create a credential object for the JerryG user and in step 10 you define hash tables for later use. These two steps produce no output.

In step 11, you invoke a script block that invokes the JEA-defined function Get-HW, which looks like this:

In step 12, you calculate how many DNS commands are available within an RKDNSAdmins JEA session, like this:

In step 13, you examine the contents of the JEA transcripts folder, which you defined as part of the session configuration file (for example in step 5). You can see the two transcripts created in response to the two calls to Invoke-Command (in step 11 and step 12), like this:

In step 14, you examine the contents of the first transcript (a result of step 11). In the transcript header, you can see that user RESKIT\JerryG remoted in as a virtual RunAs user using the RKDnsAdmins JEA endpoint on DC1. In the body of the transcript, you can see the call to the Get-HW function and the response. This transcript looks like this:

If you compare this output with the output of step 11, you can see that the transcript is a more detailed examination of precisely what happened in the remote JEA session.

The DNSServer module, which the recipe gives the RDDnsAdmins JEA endpoint access to, includes three aliases. Since these aliases are not explicitly allowed in the role capabilities file, they are not available in the JEA session.

In this recipe, you used Invoke-Command to run two simple script blocks in a JEA session. Once you have JEA set up on DC1 (or any other server for that matter), you can enter a JEA session like this:

#  Enter a JEA session and see what you can do
$ICMHT = @{
  ComputerName   = 'Localhost'
  Credential     = $Cred    # Reskit\JerryG
  ConfigurationName = 'RKDnsAdmins'
}
Enter-PSSession @ICMHT

Once in the remoting session, you can explore what commands are available to the JerryG user.

In this recipe, you examined the transcripts generated by each remoting session. In addition to transcripts, PowerShell also logs the use of a JEA endpoint in the event log. For more information on event log entries and the general topic of auditing and reporting on JEA, see: https://docs.microsoft.com/en-us/powershell/jea/audit-and-report.

In this recipe, you used some of the key lock-down features provided by JEA. But there is more! For a fuller look at the things you can do with JEA and how to go about them, look at the JEA documentation beginning at: https://docs.microsoft.com/en-us/powershell/jea/overview.