DEV Community: Adam the Automator

How to Set up the PAL Tool for Windows Performance Monitoring

Adam the Automator — Fri, 15 Jan 2021 20:26:02 +0000

This article was written by Jeff Stokes. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

Windows performance counters can get unwieldy quickly. Although powerful, performance counters are notoriously complex. Even before you begin to create performance counters, it's sometimes impossible to know which ones to create to find what you're looking for in the first place! Thankfully, you have the PAL Tool.

Introducing the open-source Performance Analysis of Logs (PAL) Tool. using the PAL tool, you can investigate performance problems and download performance counter logs.

The PAL tool provides useful insights based on known thresholds. It works by providing a handy configuration GUI and then running a PowerShell script (PAL.ps1) to parse and analyze performance counter log files.

In this article, you're going to learn how to download the PAL tool, install it and then how to use it to perform system performance analysis of logs generated from data collector sets.

Prerequisites

If you'd like to follow along in this article, be sure you have the following prerequisites in place before starting.

Any modern version of Windows - We'll be using Windows Server in this article.
.NET Framework 4.7.2 installed
An existing performance counter log - We'll be using the log created from a previous ATA article entitled Windows Performance Monitoring: Saving Time with Templates <LINKHERE>

Downloading and Installing the PAL Tool

To get started, visit the PAL Tool download from GitHub. You can do so by visiting the releases section. In this article, we'll be using version 2.8.1.

Find the MSI installer called PAL_Setup_x_x_x.msi in the Assets section in the GitHub repo as shown below. Once downloaded, run the installer accepting all defaults.

Setting up the PAL Tool

Once the PAL tool is installed, it's time for the fun stuff! Let's now run through an example of using this handy tool to extract useful, applicable data from a performance counter log to check on server performance.

First, click the Start menu button, type PAL, and click PAL when it appears in the results. You'll see an example of what the PAL Wizard looks like below. Click Next to begin the PAL Wizard and go to the Counter Log tab.

2. On the Counter Log tab is where you will tell PAL where the performance counter log is located and if you'd like to limit the analyzation to only a specific timeframe as as shown below.

The optional Date/Time Range is there only if you want to specify a time inside your BLG file. Leave it unchecked for now.

3. Click Browse, navigate to the location of a BLG file you'd like to analyze, and open it. For this example, we have a Windows performance counter called GIBSON_System_33920.blg that I created earlier.

4. With the BLG file selected, click Next to go to the Threshold File tab.

There are many different options for Threshold Files. The default is System Overview. Since this is just a demonstration without a specific metric to analyze in mind, keep the Title set to System Overview but feel free to play around with this.

5. Click Next to go to the Questions tab as you can see below. The Questions tab is used for finding memory threshold limit breaches in x86 installs of Windows. It’s safe to skip this step.

6. Click Next to go to the Options tab as shown below. The Options tab is used to break the log file into multiple files organized by chronological time. Usually the default, Auto, is fine.

7. Click Next to go to the Reports tab as shown below. The Reports tab is where you specify directories for report generation.

By default, PAL creates a PAL Reports folder within your My Documents folder for Windows performance counter reports. This is useful if you tend to assist different groups/companies/teams and don’t want to mix the results data. As you can see below, an HTML Report is going to be generated in the folder path provided.

8. Click Next to go to the Queue tab as shown below. The Queue tab is where you can read what is going on under the hood with PAL. This will be a read-only field presenting the PowerShell script (PAL.ps1) PAL is executing against the log file with a variety of variables defined.

If you were analyzing several traces, the Queue would reflect the individual commands being executed on each selected BLG file.

9. Click Next to go to the Execute tab as shown below. The Execute tab is the last step in the PAL Wizard. Select Start analysis of the queue, Execute as a low priority process, and leave the Number of processing threads to its default.

10. Click Finish to execute the PowerShell script.

When configuration is completed, the PAL tool will execute a PowerShell script which opens a PowerShell window where you'll the see the script running. You can see an example of this below.

Eventually the processing window will display that the script is generating the HTML report and graphs.

When the script is completed, your default browser will open a new window with the html-based report as shown below.

The report is broken into 30 time slices, and also broken out by problem category (Disk, Memory, CPU, Network, etc). The report is interactive so you can click around the various links to navigate around and see what kind of useful information you can find.

Most categories will have some friendly text at the category header explaining why the counter is relevant, what the thresholds are, and sometimes a MSDN or TechNet link for further reading. You can see below an example of what it says for Memory Available MBytes.

Summary

In this article, you learned about the handy PAL Tool. Using this free, open-source tool is a great way to perform analysis of logs, parse and extract actionable data from your performance monitor logs.

Now that you're through this demonstration, start capturing other types of performance counter log and inspecting them with the PAL Tool to see what other benefits you can get from this useful tool!

Saving Time with Windows PerfMon Templates

Adam the Automator — Fri, 15 Jan 2021 20:20:48 +0000

This article was written by Jeff Stokes. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

Do you rely on Windows Performance Monitor to discover the root cause of Windows performance monitoring issues? Are you still struggling with creating lots of performance monitors at once or simply need a way to automate the process? If so, in this article, you're going to learn how to create perfmon templates and data collector set templates!

In this article, you’ll learn how to do Windows Performance Monitoring by building XML performance monitoring templates to save yourself valuable time.

How Templates Work in Windows Performance Monitoring

Windows Performance Monitor (perfmon) is a native Windows tool for administrators to specify attributes like performance counters, event tracing for Windows events, and system configuration items. Once the attributes are set, perfmon captures data into one of several formats: binary log, SQL, Data Source Name (DSN), or CSV.

Only capture the data you need via performance monitoring. If not, you risk negatively affecting the performance of your servers!

Perfmon captures data from parameters set in data collector sets which control things like the log directory, log schedules, and any stop conditions. It is these data collector sets or groups of parameters that define what to log and when is how you can save time with templates.

Templates, stored as XML, allow you to capture all of the parameters needed to query performance counters and to create data collections. Once you have that template, you can then easily transfer that data collector set to other machines.

You can create perfmon templates from existing data collector sets and can be imported. These tasks are what you're primarily going to learn in this article.

Prerequisites

If you'd like to follow along with this tutorial, please be sure you have the following prerequisites in place.

Windows Server - We'll be using Windows Server 2019 in this article
7-zip to unzip some sample templates

Creating PerfMon Templates

Before you can leverage performance monitor templates for Windows performance monitoring, you must first create them. Creating a template consists of creating a data collector set as usual and then saving the settings as a template. The process is surprisingly simple.

To create a perfmon template, on your Windows Server machine:

Open up Windows Performance Monitor (perfmon) via perfmon.msc or by opening up via the start menu.
In the left pane, expand Data Collector Sets and click on User Defined. This allows you to customize the kind of data you'll be collecting.
Right-click on User Defined and click New —> Data Collector Set to open the Create New Data Collector Set window as shown below. Type a Name for your data collector set, click Create manually (Advanced), and click Next. Note the Create from a template (Recommended) option. This is the same place you'll go when importing a template later.

4. In the next screen, you'll be prompted to select what kind of data you'd like to collect as shown below. These options are up to you. Once you do this, click on Finish and your data collector set will be stored directly under User Defined as you'll see in the upcoming screenshot.

Depending on which boxes you clicked, you will be prompted to specify the parameters for Performance counter, Event trace data, and System configuration information. That is a deep dive for another tutorial.

5. As shown below, right-click on the data collector set just created and click Save Template. You will then be prompted where to save the XML file to.

That's it! That's all there is to creating a performance monitoring template. At this point, you can follow the same steps you'll be learning about in the next section to create a data collector set from this template.

Creating a Perfmon Data Collector Set Template

Sometimes it's just faster to start with someone else's vast and learned accomplishments when it comes to Windows performance monitoring. Smugness aside, let's download and use a pre-existing template. The template you'll be using is a base operating system capture. It does not include any performance counter references to applications like Microsoft Exchange or SQL, for example.

When creating a data collector set from template, be sure the computer the data collector set is being created on has the same performance counters as the source computer.

To import the example XML Template into perfmon:

Go to the GitHub repository, download the performance_capture - rolling 200.7z file and extract it's contents.
On Windows Server, open up perfmon, right-click on User Defined and click New —> Data Collector Set to open the Create New Data Collector Set window as shown below. Type the Name for the data collector set and ensure Create from a template (Recommended) is selected and click Next.

3. The template data collector set in this template example is a Basic one. Choose Basic and click Next. Then click Browse to open the browse window and pick the performance_capture - rolling 200.xml file extracted from the ZIP file earlier.

Once the XML template has been selected, perfmon will read the template and provide the template data collector set it found along with any notes in the template as shown below. Click Next.

4. Select a place to save the logs generated from this data collector set. You can see below the default path has been selected for you. This path is in the XML template. Leave the default file location as-is and click Next.

5. Ensure Save and close is selected and click Finish.

You have now created a data collector set from an XML template.

Starting the Data Collector Set

The data collector set is now built from the XML template but it's not doing much at the moment. You have to start the data collector set. To do so:

Open perfmon if it's not already open.
In the left pane, expand Data Collector Sets —> User Defined. You should now see the data collector set you just created from the template.
Right-click your custom data collector set and click Start from the pop-up menu as shown below. Performance counters will now begin collecting data.

Reviewing the Created Data Collector Set

Once the data collector set has been created via XML template, you can now inspect the settings to ensure perfmon imported all expected settings.

From permon:

Expand Data Collector Sets —> User Defined in the left pane.
Right-click the custom data collector set just created and click Properties from the pop-up menu to open the Properties dialog box as you can see below.

3. Click the Schedule tab. In this tab, verify the Start date is in the past and the checkbox for All schedules enabled is checked. This will make sure your server will resume logging data in the event of a reboot/crash.

4. Click the Stop Condition tab. Here, verify the Maximum Size of the output file is 200MB as well as the Maximum Size checkbox is checked. Anything larger than 200MB becomes unwieldy.

5. Click OK to close the Properties dialog box.

Reviewing the Data Collector

The XML template creates a data collector set but inside of that set are individual data collectors. You should also inspect the data collector created by the template. To do that:

Select the data collector in the middle pane, right-click, and click Properties from the pop-up menu as shown below.

2. In the Performance Counter Properties dialog box, ensure the Performance Counters tab is selected as shown below.

For this exercise, we are just taking a peek. Note the Performance counters being collected. In the future you can add or remove them to suit your needs. Also note the Log format is binary (BLG). Unlike tab or comma-separated value file output, BLG has a dynamic schema. This is helpful if a process starts after the log starts, it will still be included in the log file. Also notice the sample rate on this tab.

3. Click the File tab. In this box, the Log mode should be Circular. This mode captures the last several hours of the systems' activity and is written in a first-in, first-out method.

4. Click OK to close the Properties dialog box and you're done!

Wrapping up Perfmon Templates

Using performance monitoring templates to create data collector sets is a convenient way to manage performance counters at scale or via automation. You've now seen an example of using templates. Armed with that knowledge, how do you plan to use templates in your day-to-day tasks?

How to Enable and Configure Azure JIT for VMs

Adam the Automator — Fri, 15 Jan 2021 20:10:48 +0000

This article was written by Jeff Christman. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

Hackers are continually scanning and actively hunting for accessible virtual machines with open management ports. If you're VMs are in Azure though, you have a tool at your disposal called Azure Just-in-Time Access (JIT).

Azure JIT is a service that allows you to open network ports "just in time" or only when you need them open and no longer. Part of the Azure Security Center suite of products, Azure JIT is a component inside of the broader Azure Defender brand. With Azure Defender and JIT, you can control who has access to network ports on any of your Azure virtual machines.

In this article, you learn what Azure Just-In-Time access is, how to enable it, configure options and policies, and how to request access. We will also walk through different ways to allow JIT access using the Azure portal, PowerShell, and the Azure Security Center API.

Once enabled, you'll then learn how request access to VMs and also how to audit Azure JIT activity.

Prerequisites

This will be a hands-on tutorial blog post. If you would like to follow along, be sure to have the following prerequisites in place before starting this article. You'll need:

An Azure Subscription
Logged into the Azure Portal with an Azure account with the Subscription Owner role. For more detail, check out the Permissions in Azure Security Center documentation.
A Standard Azure Defender plan. You can sign up while logged into the Azure Portal via Azure Security Center.
Azure Cloud Shell or PowerShell. Be sure you log in once to create the storage account it needs at least once. Later on in the article, you'll learn how to enable Azure JIT using PowerShell. Azure Cloud Shell is the easiest way to do that unless you'd like to use the Azure PowerShell module installed on your local computer.
The Azure Defender service enabled. Part of Azure Security Center, you'll need to first enable it on your subscription.

If you'd like to manage on-prem Windows or Linux servers, be sure to install the Azure Defender for Servers software.

Azure JIT Pricing

Before you get too far, know that Azure JIT is not free. There are various Azure JIT pricing levels you need to know before diving in headfirst.

You can find all of the pricing options available on the Azure Security Center blade in the Azure portal. Since Azure JIT is part of Azure Defender (which is part of Azure Security Center), the pricing you're looking for is for Azure Defender.

Once you've enabled Azure Defender, you'll notice a Pricing and Settings option on the left-hand side of the page as shown below in the Azure portal.

Azure Defender is free for the first 30 days and anything beyond the initial 30 days will be charged as per the pricing chart below. The chart below shows the per month pricing for the various services available that can utilize Azure Defender. Generally speaking, you can expect a cost of about $15.00 per month for your virtual machines the use Azure Defender and Just-In-Time service.

All prices are valid as of 10/06/20. You can find the latest prices on the Azure Security Center pricing page.

Azure Defender Pricing

Resource	Price
Azure Defender for Servers	$14.60/Server/Month
Azure Defender for App Service	$14.60/App Service/Month
Azure Defender for SQL	$15/Server/Month
Azure Defender for MySQL	Free
Azure Defender for PostgreSQL	Free
Azure Defender for Storage	$0.02/10K Transcations
Azure Defender for IoT - By Device	$0.001/month
Azure Defender for IoT - By Messages	$0.20/25K Transactions
Azure Defender for Kubernetes	$0.00268/vCore/hour
Azure Defender for ACR	$0.29/image
Azure Defender for Key Vault	$0.01/10K Transactions

Azure Defender Pricing

Enabling Azure JIT on Azure VMs

The first task you'll need to accomplish is enabling the Azure JIT feature on each of your VMs. This can be done through the Azure Security Center in the Azure portal.

For a simple demonstration, this section will show you how to enable JIT on a single VM.

If you have hundreds of VMs, don't worry. You'll learn how to enable JIT in bulk with PowerShell a little later.

Once at the Azure Security Center page, click on Azure Defender on the left side of the page. You should then see a Just-in-time VM access title as shown below.

2. Next, click on the Just-in-time VM access tile. This will open the JIT settings blade. Once open, the blade will show three tabs: Configured, Not Configured, and Unsupported. These tabs represent the various state of Azure JIT against each VM in your subscription.

3. If this is your first time enabling Azure JIT, all of your VMs will be under the Not Configured tab as shown below. To enable JIT on the VM, click on the VM and then click on the Enable JIT on 1 VM button.

Note that the Resource Group and Subscription Name will be unique to your environment.

4. Once you click on the Enable JIT button, you'll then see a JIT VM access configuration page. This page allows you to view all of the default ports and also add any existing ports you'd like to actively manage.

To add a new port, click on Add and provide the Port, Protocol, Allowed source IPs, and IP addresses fields as required. When complete, click on OK.

When complete, you'll then have ensured the ports under management are only open for a specific amount of time (Max request time).

Once you set an access policy, when a user requests access (shown how below), a firewall rule is created with the settings set in the policy. After the Max request time has been exceeded, Azure will remove the firewall rule that opened the port, to begin with.

Know that Azure Bastion and JIT access cannot be used together. If you enable Azure Bastion with an existing JIT access policy enabled on a VM, the bastion host will not connect to the target machine and you will get a connection error!

Requesting Access to a Virtual Machine

Now that you've enabled JIT on a VM, how do you (or your users) get access to that VM through one of the managed ports?

While logged into the Azure portal, navigate to the VM you'd like to access and select Connect.
Now, select the protocol you'd like to use and change the Port number or desired Source IP, if required. Typically, when you attempt to connect to a VM, you'll immediately be able to download an RDP file or see SSH methods, for example. When a JIT access policy is applied to a VM, you'll see options like in the below screenshot.

Know that requesting access to VMs only opens the requested port. Just like logging into a virtual machine using RDP, you will need a valid Active Directory account with the appropriate permissions to log in to the virtual machine.

Automating Azure JIT using PowerShell

So let's say you've got hundreds of VMs that you need to control management ports on. Maybe you've got a request from management to get all of VM management ports locked own ASAP. You're not going to want to go through the steps you just took to enable an access policy on a single VM. Let's automate this.

Instead of logging into the Azure Security Center each time and enabling a JIT access policy for each VM, you can write a script using PowerShell. Once you've built the script, you can then incorporate it into a CI/CD pipeline too.

Below you'll find a copy/pastable code snippet for you to get started. This code creates and applies a JIT access policy to the VMName VM that limits Port 22 (SSH) and RDP (3389), all protocols, from all source IPs for a maximum of three hours.

## Build the policy with the VM's resource ID
$JitPolicy = (@{ id="/subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUP/providers/Microsoft.Compute/virtualMachines/VMNAME"
ports=(@{
     number=22; ## SSH
     protocol="*"; ## all protocols
     allowedSourceAddressPrefix=@("*"); ## any source IP
     maxRequestAccessDuration="PT3H"}, ## up to three hours
     @{
     number=3389;
     protocol="*";
     allowedSourceAddressPrefix=@("*");
     maxRequestAccessDuration="PT3H"})})
$JitPolicyArr=@($JitPolicy)

## Send the policy to Azure and commit it to the VM
Set-AzJitNetworkAccessPolicy -Kind "Basic" -Location "LOCATION" -Name VMNAME -ResourceGroupName "RESOURCEGROUP" -VirtualMachine $JitPolicyArr

Auditing JIT Access Activity

So you've set up JIT access to a bunch of VMs but is it being used? If so, how often? You need to audit the access policy activity. Auditing can be done via each VM's activity log.

When someone requests access to a management port and Azure creates an access policy, JIT logs this activity in the activity log. The activity log contains information such as when the request was made, who made the request, if it was successful, and so on.

To view the activity log, navigate to the JIT VM Access blade in the Azure Portal, click on the three ellipses on the far right of the selected virtual machine, and select Activity Log.

As you can see below, the activity log tracks when an access polity has been applied to a virtual machine, who requested access, and when access was granted or denied.

How To Make Visual Studio Code Look And Behave Like The PowerShell ISE

Adam the Automator — Thu, 14 Jan 2021 23:12:40 +0000

This article was written by Jeff Christman. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

Despite its lack of features and options, the PowerShell ISE used to be the primary PowerShell IDE tool to develop and edit PowerShell Scripts. It offered an integrated development environment (IDE) that included some basic features to build scripts and modules.

Microsoft is no longer actively developing the PowerShell Integrated Scripting Environment (ISE) and is being replaced by the more powerful and versatile open source Visual Studio Code (VS Code). With its ever-expanding options and extensions, VS Code is quickly becoming the new standard tool for developing not only PowerShell, but just about any other language you choose.

Despite all the new features available in VS Code, leaving the familiar environment of the ISE is difficult. It is like watching your child go to college. You are proud of the achievement but sad about having left a comfortable environment.

VS Code can be intimidating at first. As the default settings of VS Code can be a little hard to work with if you are used to working with the ISE. However, it's highly customizable, and with the addition of Extensions and a few configuration settings, you can make VS Code look and behave just like PowerShell ISE.

If you're more of a visual learner, be sure to check out this posts associated TechSnips how-to video.

https://www.youtube.com/watch?v=Ar6YSFC0xBE

The Look

To get VS Code to look like PowerShell ISE, the PowerShell Extension needs to be installed. To install, select the setting gear at the bottom left, then pick Extensions.

At the search box, type in Powershell and then install. This extension adds a few features to the default settings of VS Code.

To get the distinctive look of PowerShell ISE, select the settings gear and then Color Theme. Choose the PowerShell ISE theme.

Now that you have the look of PowerShell ISE, we need to set the behavior to match ISE.

The Behavior

The default install of VS Code lacks some features of the PowerShell ISE, such as Zoom, Tab-Completion, Intellisense, and Code Snippets.

For setting the environment to match that of PowerShell ISE, we need to add some environment settings to the VS Code settings.

Keyboard and Mouse Actions

Open the command palette using the ctrl+Shift+P key combination. In the command palette box, enter Preferences Open Settings (JSON). This will open up a two-pane window with the user settings on the right. Insert the following code between the brackets on the right pane.

"editor.mouseWheelZoom": true,
"editor.minimap.enabled": false,
"editor.renderControlCharacters": true,
"editor.wordWrap": "on",
"files.trimTrailingWhitespace": true,
"files.autoSave": "afterDelay",
"powershell.integratedConsole.showOnStartup": false,
"terminal.integrated.fontFamily": "Consolas",
"terminal.integrated.fontSize": 18,
"terminal.integrated.shell.windows": "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe", "powershell.powerShellExePath": "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe"

Code snippets

One of the best features of PowerShell ISE is the ability to use Code Snippets. VS Code has made code snippets more versatile.

To add code snippets, select the setting gear and then pick User Snippets. In the command palette, enter powershell.json. I've created a sample user snippets JSON file for you available here.

Summary

VS Code is now the preferred PowerShell editor. With a few customizations, we can make it behave just like the familiar PowerShell ISE.

Understanding LDIF (LDAP Data Interchange Format)

Adam the Automator — Thu, 14 Jan 2021 23:06:45 +0000

This article was written by Stuart Squibb. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

If you've worked with LDAP (Lightweight Directory Access Protocol) before, you've probably run across LDIF files. LDIF is a schema defined in text files that defines LDAP directory content as a set of records. LDIF files define one record for each object (or entry) and store actions to perform on those objects like adding, modifying, removing and renaming objects.

In this article, you'll get a deeper understanding of what the LDIF format is, what a file looks like and how it's used by various tools.

The LDIF Format

The LDIF format is always represented in plain-text files with an LDF extension. Because they are plain-text, you can easily view them in your favorite text editor. Visual Studio Code, for example, has a syntax highlighter extension for LDIF files that you can install which will make working with LDIF files easier.

An LDIF file consists of a number of records each separated from the next by a blank line. Each record refers to a single object and consists of a number of lines. You can see an example of the structure below.

Each line of a record can contains:

An LDAP attribute - This is a line that consists of an LDAP attribute name, followed by a colon, a space and then the attribute value.
A changetype - A changetype line in a record identifies the type of change to be made to the AD object (add, delete, modify, moddn/modrdn). A changetype of modify is followed by the change operations themselves.
A change operation - These lines represent the changes to be made (add, delete or replace). If object is being changed more than one way, you may also notice a dash representing separating multiple change operations within a modify changetype.
A comment line - These are lines that start with the hash (“#”) character.

Each record correlates to an AD object. Each AD object that the record refers to is identified by the first line of the record, which contains the distinguished name (DN) attribute for the LDAP object.

Example LDF File

In the next screenshot, you will see a snippet of an LDIF file generated for a user LDAP object type. This file was exported with the LDIFDE tool representing a user account for Paul Cox.

Each line of the example file below represents one of the attributes for Paul, apart from the comment line.

You'll see that this record has two multi-valued LDAP/Active Directory attributes such as objectClass and memberOf. These attributes are represented by multiple lines - one for each value. Also note that the objectGUID attribute is base64 encoded. Attributes are encoded in the LDIF file because that particular attribute is not stored in LDAP as a plain text or numeric value. Instead, it is stored as a 16-byte binary value.

Since this example file was exported with the ldifde tool, it is ready to be re-imported elsewhere so it has a changetype of add.

LDIF Support in Tools

As mentioned earlier, one tool you can work with LDIF files is called ldifde in Windows but others exist as well. LDIF files can be generated and consumed by a variety of tools such the OpenLDAP tools available on Linux and Mac OS, the python module python-ldap and the perl Net::LDAP::LDIF module.

How to Download and Install PowerShell 7 on Windows, Linux, and macOS

Adam the Automator — Thu, 14 Jan 2021 20:34:32 +0000

This article was written by Jeff Christman. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

Nowadays, sysadmins are required to know more than one operating system. That used to mean learning more than a few shell scripting languages. PowerShell Core and by downloading and installing PowerShell 7, you can change that.

It's no longer necessary to learn a new scripting language to support heterogeneous environments with PowerShell 7. PowerShell 7 is cross-platform meaning it can be installed on Windows, Linux, and other operating systems.

PowerShell 7 is supported on Windows, macOS, and Linux. It's open-source, built for heterogeneous environments and the hybrid cloud. PowerShell Core has recently become available on Windows internet of things (IoT) as well.

The cross-platform nature of PowerShell 7 means that the scripts that you write will run on any supported operating system.

PowerShell 7 vs. Windows PowerShell

The main difference between Windows PowerShell and PowerShell 7 is the platform they are built on.

Windows PowerShell is built on top of the .NET frameWork. Because of that dependency, it's only available on Windows and is launched as powershell.exe.

Note that you can run PowerShell 7 and Windows PowerShell side by side. In fact, there is no way to completely remove Windows PowerShell anyway.

PowerShell 7 is built on .NET Core and is available cross-platform and is launched as pswh.exe.

Installing PowerShell 7

This tutorial will focus on installing the latest release of PowerShell 7 at the time of this writing which is PowerShell 7.1.

There are different processes to get PowerShell 7 installed on various operating systems. Let's cover each one.

Windows

To install PowerShell 7 on Windows, navigate to the PowerShell GitHub repository and download the .msi package appropriate for your system. Then run through the wizard. Easy peasy.

Windows IoT

Windows Iot devices already have PowerShell installed which we will use for installing Powershell Core


#Enter a psession to the device
$s = New-PSSession -ComputerName <deviceIp> -Credential Administrator

#Copy the file to the device
Copy-Item .\PowerShell-7.1.0-win-x64.msi -Destination u:\users\administrator\Downloads -ToSession $s

#Connect to the device and expand the archive
Enter-PSSession $s
Set-Location u:\users\administrator\downloads
Expand-Archive .\PowerShell-7.1.0-win-x64.zip

#Setup Remoting
Set-Location .\PowerShell-7.1.0-win-x64

# Be sure to use the -PowerShellHome parameter otherwise it'll try to create a new endpoint with Windows PowerShell 5.1
.\Install-PowerShellRemoting.ps1 -PowerShellHome .

# You'll get an error message and will be disconnected from the device because it has to restart WinRM
# Connect to the device. Be sure to use the -Configuration parameter. If you omit it, you will connect to Windows PowerShell 5.1
Enter-PSSession -ComputerName <deviceIp> -Credential Administrator -Configuration powershell.7.1.0

Once in the session, you should then be running PowerShell on the IoT device!

Ubuntu, Debian

For Linux distributions, it just a matter of adding the repository and installing with the package manager.


# Download the Microsoft repository GPG keys
wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb

# Register the Microsoft repository GPG keys
sudo dpkg -i packages-microsoft-prod.deb

# Update the list of products
sudo apt-get update

# Install PowerShell
sudo apt-get install -y powershell

# Start PowerShell
pwsh

CentOS and RedHat


# Register the Microsoft RedHat repository
curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo

# Install PowerShell
sudo yum install -y powershell

# Start PowerShell
pwsh

OpenSUSE

# Register the Microsoft signature key
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

# Add the Microsoft Repository
zypper ar https://packages.microsoft.com/rhel/7/prod/

# Update the list of products
sudo zypper update

# Download and Install PowerShell 7
sudo zypper install powershell

# Start PowerShell
pwsh

Fedora

# Register the Microsoft signature key
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

# Register the Microsoft RedHat repository
curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo

# Update the list of products
sudo dnf update

# Install a system component
sudo dnf install compat-openssl10

# Download and Install PowerShell 7
sudo dnf install -y powershell

# Start PowerShell
pwsh

MacOS

For macOS, Homebrew is the preferred package manager. Installing Homebrew package manager is a single line command from a terminal, then install Powershell Core.


/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

#install PowerShell Core
brew cask install powershell

#start session
pwsh

Summary

Learn to manage different platforms and OSs. It'll only help your career. When you need a cross-platform scripting language, try out PowerShell Core to write once and deploy everywhere. It's another tool in your toolbox.

If you don't learn it, someone else will.

How to Convert Text to Speech with PowerShell

Adam the Automator — Thu, 14 Jan 2021 20:29:52 +0000

This article was written by Francisco Navarro. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

One of PowerShell’s core design principles is to allow the end-user to jump right in with little to no shell experience and hit the ground running. However, PowerShell can let you get creative too. For example, did you know you can convert text to speech with PowerShell?

In this article, you will learn how to have PowerShell speak, switch to available voices, and learn how to use PowerShell's speech capabilities to add notification mechanisms to PowerShell script.

Prerequisites

This article is built as a walkthrough. If you'd like to follow along, please be sure you're running Windows 10. It has everything you need already installed.

Preparing Text to Speech in PowerShell

PowerShell, out of the box, won't just begin talking to you. You'll first have to prepare for it. Doing so requires two steps; adding the correct .NET assembly and creating the appropriate .NET object.

Adding the `System.Speech` .NET Assembly

Since PowerShell doesn't come with native cmdlets to convert text to speech, you must first dig into .NET using a specific .NET assembly called System.Speech. The System.Speech assembly is where the .NET SpeechSynthesizer class lives. This .NET class will allow you to convert text to speech.

The SpeechSynthesizer class is native to the Windows .NET framework. It is not available in PowerShell versions 6+.

To make the SpeechSythensizer class available, you will load the System.Speeech assembly using the Add-Type cmdlet as shown below.

When you have a Windows PowerShell console open as administrator, insert the following code snippet.

PS51> Add-Type -AssemblyName System.Speech

You might have noticed there was no confirmation of any sorts when running the above code. Even by adding the Verbose parameter, you will see no output. Don't worry, everything is fine. This is the default behavior of the Add-Type cmdlet.

To ensure the assembly imported, invoke a .NET class that is part of the assembly. For example, since you'll be working with the SpeechSynthesizer class, provide the entire path to the SpeecSynthesizer class enclosed in brackets as shown below.

PS51> [System.Speech.Synthesis.SpeechSynthesizer]
 
IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     False    SpeechSynthesizer                        System.Object

If all is well, you will see the SpeechSynthesizer object returned.

You have now successfully imported the System.Speech assembly. Next, let's see how you can make the assembly work for you.

Creating a `SpeechSynthesizer` .NET Object

With the System.Speech assembly, you now have access to the .NET SpeechSynthesizer class. To invoke the class, you need to create an object first. To do that, use the New-Object cmdlet as shown below. The code below is assigning that object to the ATAVoiceEngine variable which you will use in a little bit.

PS51> $ATAVoiceEngine = New-Object System.Speech.Synthesis.SpeechSynthesizer

Once you've created the object and assigned it to a variable, confirm that the variable contains the object you expect. If the output looks like the following code snippet, you're good to go. You're one step closer to converting text to speech in PowerShell!

PS51> $ATAVoiceEngine

State Rate Volume Voice
----- ---- ------ -----
Ready    0    100 System.Speech.Synthesis.VoiceInfo

If you're curious, you can also take a look at all of the various members on the object by using Get-Member. Note the methods available on this object. You'll be using these in a bit.

PS51> $ATAVoiceEngine | Get-Member

Converting Text to Speech with PowerShell

Now that you have an object capable of converting text to speech, let's try it out. To do so, you'll use the Speak() method on the object.

Using Get-Member to inspect the members on the object, notice on method in particular called Speak() as shown below. When you pass text to this method, PowerShell will in turn use .NET to convert that text to speech.

Let's take the default text-to-speech conversion for a spin with all of the default settings. Be sure your sound and speakers are on and have PowerShell convert the phrase "Hello Adam The Automator audience. How are you doing today?" to voice. To do that, simply pass that phrase to the Speak() method as shown below.

PS51> $mytext = "Hello Adam The Automator audience. How are you doing today?"
PS51> $ATAVoiceEngine.Speak($mytext)

Feel free to change up the text as much as you want just keep it clean!

Changing up the Voice

By default, the Speak() method will use a default voice called Microsoft David. However, you can use many different voices if David doesn't meet your liking.

You might recall that Microsoft David is the default voice in the Windows Narrator feature.

Inspecting the Voice Object

Take a look at some of the common properties of the System.Speech.Synthesis.SpeechSynthesizer object. One interesting property is the Voice property. This property allows you to change up the voice used in speech. Notice that this is an embedded object of type System.Speech.Synthesis.VoiceInfo that will have its own set of properties.

PS51>  $ATAVoiceEngine | Format-Table -properties *

State Rate Volume Voice
----- ---- ------ -----
Ready    0    100 System.Speech.Synthesis.VoiceInfo

Specifically looking at the Voice property, you can see various attributes as seen below.

PS51>  $ATAVoiceEngine.Voice

Gender                : Male
Age                   : Adult
Name                  : Microsoft David Desktop
Culture               : en-US
Id                    : TTS_MS_EN-US_DAVID_11.0
Description           : Microsoft David Desktop - English (United States)
SupportedAudioFormats : {}
AdditionalInfo        : {[Age, Adult], [Gender, Male], [Language, 409], [Name, Microsoft David Desktop]...}

Let's change the voice that dictates your text.

Discovering Available Voices

Let's see what other voices are available. To get a list of voices, call the GetInstalledVoices() method on the object as shown below.

PS51> $ATAVoiceEngine.GetInstalledVoices()

You will see some VoiceInfo objects returned below. You can see that two objects are returned. These objects tell you that two different voices are currently installed. You may have more voices available.

PS51> $ATAVoiceEngine.GetInstalledVoices()

VoiceInfo                         Enabled
---------                         -------
System.Speech.Synthesis.VoiceInfo    True
System.Speech.Synthesis.VoiceInfo    True

Dig a little bit deeper to find the actual list of voices as properties on each of VoiceInfo objects by passing each of the VoiceInfo objects that the GetInstalledVoices() method returns to Get-Member. Notice the VoiceInfo property's Definition displays the System.Speech.Synthesis.VoiceInfo class and VoiceInfo class.

PS> $ATAVoiceEngine.GetInstalledVoices() | Get-Member

   TypeName: System.Speech.Synthesis.InstalledVoice

Name        MemberType Definition
----        ---------- ----------
Equals      Method     bool Equals(System.Object obj)
GetHashCode Method     int GetHashCode()
GetType     Method     type GetType()
ToString    Method     string ToString()
Enabled     Property   bool Enabled {get;set;}
VoiceInfo   Property   System.Speech.Synthesis.VoiceInfo VoiceInfo {get;}

By referencing the VoiceInfo property on each of the objects as shown below, you can get more information about each voice. Below you can see that this computer has Microsoft David Desktop and Microsoft Zira Desktop voices available.

PS51> $ATAVoiceEngine.GetInstalledVoices().VoiceInfo   

Gender                : Male
Age                   : Adult
Name                  : Microsoft David Desktop
Culture               : en-US
Id                    : TTS_MS_EN-US_DAVID_11.0
Description           : Microsoft David Desktop - English (United States)
SupportedAudioFormats : {}
AdditionalInfo        : {[Age, Adult], [Gender, Male], [Language, 409], [Name, Microsoft David Desktop]...}

Gender                : Female
Age                   : Adult
Name                  : Microsoft Zira Desktop
Culture               : en-US
Id                    : TTS_MS_EN-US_ZIRA_11.0
Description           : Microsoft Zira Desktop - English (United States)
SupportedAudioFormats : {}
AdditionalInfo        : {[Age, Adult], [Gender, Female], [Language, 409], [Name, Microsoft Zira Desktop]...}

Setting the Text-to-Speech Voice

Once you know the available voices, you can then change them by using the SelectVoice() method on the SpeechSynthesizer object. Below you can see how to change the voice to Microsoft Zira Desktop.

PS51> $ATAVoiceEngine.SelectVoice("Microsoft Zira Desktop")

Once the new voice is set, you can then use the Speak() method again passing whatever text you'd like to convert text to speech again using the new voice.

PS51> $ATAVoiceEngine.Speak("Hello, My name is Zira. PowerShell 7's older sibling?")

Freeing up the Console While Converting Text to Speech with PowerShell

You may have noticed when passing text to the speech engine that PowerShell does not allow you to do anything else while speech is happening. This may be problematic if you need to recite a lot of text and still need to perform some other tasks. Instead of using the Speak() method, you can use the SpeakAsync() method instead.

The SpeakAsync() method frees up the console as soon as the text-to-speech conversion starts. To use the SpeakAsync() method, simply replace this method with Speak().

PS51> $ATAVoiceEngine.SpeakAsync('Hello, my name is Zira. How are you doing today?')

You will see that PowerShell frees up the console as soon as you hit Enter.

Building your Own Assistant

So far you have instantiated a .NET class and turned it into a Windows PowerShell object you can leverage. You had some fun with the $ATAVoiceEngine object and learned to manipulate its settings, including changing the voice. Now let's leverage the object to be a notification mechanism in your PowerShell Scripts.

By combining a typical PowerShell script with the text-to-speech ability, your computer can vocally tell you what's going on! Below is a good example. When you run this script the engine calls out the name of the service and its status.

### In honor of PowerShell 7's avatar we select the "Zira Desktop Voice"  
$ATAVoiceEngine.SelectVoice("Microsoft Zira Desktop")

### Fetching a list of Windows Services which names start with "W" selecting the first 5
$services = Get-Service W* | Select-Object -First 5

### Create a ForEach Loop for those services
ForEach ($service in $services) {
    ### Using the speech engine object $ATAVoiceEngine with the "SpeakAsync" method
    $ATAVoiceEngine.SpeakAsync("The Service $($service.displayname) is $($service.status)") | Out-Null
}

You can run a script like this in the background, against a server or workstations and find out if your critical services are running or not.

Summary

In this article, you've discovered how to use the .NET framework and PowerShell to convert text to speech by changing up various voices and how to even integrate text-to-speech into your PowerShell scripts. Go ahead, get creative, and build your own PowerShell assistant!

Managing File Shares with PowerShell

Adam the Automator — Thu, 14 Jan 2021 20:26:03 +0000

This article was written by David Lamb. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

It can be challenging to keep track of just what file shares have been set up in your environment. This becomes even more difficult if you have to track this information across multiple servers. Adding to the tedium is remotely connecting to each server to find the list the shares. Thankfully, using PowerShell get-smbshare makes this task a snap, whether you need to enumerate shares on just one server, or many.

If you're a beginner/intermediate PowerShell scripter, be sure to check out my FREE mini-course on Building a PowerShell Tool! 9,000+ words of deep explanation and insights on how to build a PowerShell tool.

This blog post has a companion video created by TechSnips contributor, David Lamb. Feel free to have a watch or, if you prefer text, read on!

Enumerate Shares on a Single File Server

Let's start by connecting to a remote file server to gather this information from a single server. We will accomplish this by entering into a remote PowerShell session with our file server FILE01.

PS> Enter-PSSession -ComputerName FILE01

Once connected, it takes a single cmdlet to get file share information get-smbshare.

As you can see, this gives us a list of all of the share on this server. This also includes the administrative shares, whose share names are appended by $.

This does accomplish the task of getting a list of shares, but it is a little cluttered. We can clean up this list by using the Special parameter and setting it to $false to specify that we do not wish to see the administrative shares:

There, that gives us a much clearer view of the share information we are looking for.

Now that we have our share on this server identified, it might be useful to list all of the properties for this share, especially if we are looking for specific details about our share:

This allows us to view quite a bit of information about our share, including things like the type of share, folder enumeration mode, caching mode, and of course, our share name and path, to name a few.

It is also possible to view the share permissions for this share by switching to the get-smbshare access cmdlet.

This gives us a list of the users and groups, and their current level of access to the share.

We might also have a time where we need to enumerate the share permissions to find out who has full access to a share:

With this information, it is easy to tell who has full access to the share and then take steps to remove that access if it isn't appropriate for an individual or group.

Now that we are done enumerating shares on a single server, we need to make sure we close our remote PowerShell session:

PS> Exit-PSSession

Enumerate Shares on Multiple File Servers

It is also possible to retrieve this same information from multiple file servers, which is an area where PowerShell really shines.

Using Invoke-Command to run get-smbshare, we can list the shares on both the FILE01 and FILE02 servers. If we also pipe the output through Format-Table, we can also get a nice organized list:

PS> Invoke-Command -ComputerName "FILE01","FILE02" -ScriptBlock {Get-SmbShare} | Format-Table -Property Name,Path,Description,PSComputerName

While entering the file server names manually is fine if there are only two or three servers, it becomes tedious if there are many dozens of servers to check. To get around this, we can assign the output of Get-ADComputer to the variable $FileServAD and get a list of all servers in the File Servers organizational unit (OU). From there, it's easy to get the information:

$FileServAD = Get-ADComputer -SearchBase "OU=File Servers,OU=Servers,DC=corp,dc=ad" -Filter * |
Select-Object -ExpandProperty Name

Invoke-Command -ComputerName $FileServAD -ScriptBlock {
    Get-SmbShare -Special $false
} | Format-Table -Property Name,Path,Description,PSComputerName

There we have it! A nice tidy list of all of the file shares on all of our file servers.

Summary

In this blog, you have learned how to enumerate file shares using the get-smbshare cmdlet.

How to Create GPOs (Starter GPOs) for Quick Policy Baselines

Adam the Automator — Thu, 14 Jan 2021 19:40:45 +0000

This article was written by Bill Kindle. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

GPOs (Starter GPOs, actually) are a feature in Active Directory that allows you to build templates for common GPOs. In this blog, you're going to get a glimpse into how starter GPOs can help you speed up GPO-creation.

If you are lucky to build a complete Active Directory infrastructure from scratch, then you know how much planning and consideration goes into the whole process. And it doesn't just stop with delivering the environment. You have to also consider ongoing management of the environment. That's why you should consider using starter group policy objects.

What are Starter GPOs?

A starter group policy object is a blank, or clean slate group policy object. The purpose of these objects is to allow an administrator to create and have a pre-configured group of settings that represent a baseline for any future policy that is to be created.

These settings can then be copied into a more "formal" group policy object to then be applied to single or multiple organizational units. Copying these starter objects preserves your baseline strategy and allows you to dynamically add or remove settings that shouldn't be applied to future objects.

These objects are great for settings that will not be changing, such as specific security related protocol configurations, Windows Update settings, particular software settings or registry entries to name a few. The choice is yours as a sysadmin and can reflect whatever strategy you are employing.

Using Starter GPOs with PowerShell: A Story

You walk into your work area and just as you start sipping that already cold cup of coffee because you've been stopped 15 times on your way to your area, you open your email to discover you are being asked by the boss to aid in deploying group policy in an environment. You are also given a list of baselines required for this new deployment from your security team or boss.

You could begin assigning these baselines to ordinary policy objects using the Group Policy Management Console or because you are a long-term thinker, you decide to step back and see if you can maybe automate some of this task and memorialize these baselines better.

You open up your trusty PowerShell console and start looking for cmdlets. You then search for the module GroupPolicy and import it. You would have this module installed if you have already downloaded and installed RSAT.

Looking at the available cmdlets, you find two that look like they are exactly what you need, New-GPStarterGPO and Get-GPStarterGPO.

After looking at the help you see that creating this one by one or even as a loop is pretty straightforward and there are only but a couple of necessary parameters called Name and Comment.

Armed with this new info, you create a small foreach loop through an array of names & comments and pass them off to the New-GPStarterGPO cmdlet, creating 5 new baseline policies to be edited later by your intern. Time for a beverage refill.

Summary

GPOs (Starter GPOs) are GPO templates that allow you to save time as a sysadmin. Using PowerShell cmdlets like New-GPStarterGPO and Get-SPStarterGPO allow you to save even more time by quickly creating these starter GPOs directly from the command line!

If you'd like to learn more about GPOs, check out all of the other GPO posts we have available here on the blog.

Writing an Extension Vault for PowerShell SecretManagement Preview 4

Adam the Automator — Thu, 14 Jan 2021 19:37:53 +0000

This article was written by Adam Listek. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

If you've ever hardcoded a password, an API key, or a private certificate in a script, stop! You need to secure that sensitive information! One way to do that is with the PowerShell SecretManagement module. Offering a convenient way for a user to store and retrieve secrets using PowerShell, the SecretManagement module also has the ability to interface with different back-end systems such as Azure KeyStore or KeePass too using an extension vault!

An extension vault is a term used within the SecretManagement module to refer to a nested PowerShell module used within the SecretManagement module. You'll also hear vaults referred to as extension modules also.

In this article, we create an extension vault that is backed by the open-source .NET database LiteDB. An extension module can use any back-end, but using LiteDB allows us to use a .NET native simple database that demonstrates the SecretManagement module capabilities and how to interact with different systems.

Note: Don't get confused with the "secret" in the name. Even though this module is meant to be used for "secret" management, as you'll see in this tutorial, it really could be used as a frontend or just about any data source, if you wish.

Prerequisites

This article is a tutorial. If you'd like to follow along, please be sure you have the following prerequisites in order.

PowerShell 7
The Powershell SecretManagement module - You can install this module by running Install-Module -Name 'Microsoft.PowerShell.SecretManagement' -AllowPrerelease. This tutorial will be using the most current version at the time of writing which is Preview 4.
The LiteDB database - Though you can create any backing store for your secret database, this article demonstrates creating an extension module to leverage LiteDB in the background. You can install LiteDB by running Install-Package -Name 'LiteDB' -MinimumVersion '5.0.9' -Source 'nuget.org' -Scope 'CurrentUser'

Understanding the PowerShell SecretManagement Module

The PowerShell SecretManagement module is a PowerShell module that provides a standardized, Microsoft-supported way of interacting with sensitive information. Think of this module as a better way of storing and retrieving sensitive information than using Get-Credential or perhaps storing secure strings in common text files.

This module has two main object types; secrets and vaults. A vault is a data store that stores secrets. To store and retrieve secrets, you must first register a vault to then add secrets to that vault. You can then unregister that vault if you no longer need to store secrets in that data source.

When you install the module, there are no actual vaults available. If you want to install the previously default extension vault, run Install-Module -Name 'Microsoft.PowerShell.SecretStore' -AllowPrerelease. Otherwise, keep reading as you'll learn how to create a custom one with LiteDb.

You'll find a few different cmdlets in the module to interact with the various objects.

Get-Secret - Retrieve a secret from a vault.
Get-SecretInfo - Retrieve information about one or more secrets in a vault.
Get-SecretVault - Retrieve information about a specific vault.
Register-SecretVault - Register a new secret vault.
Remove-Secret - Remove a secret from a vault.
Set-Secret - Create a new secret or update an existing secret in a vault.
Test-SecretVault - Verify that a vault is correctly configured.
Unregister-SecretVault - Unregister a previously registered vault.

To actually make any of the above cmdlets functional, you need to back them with a vault. To do that, the SecretManagement module requires you to build your own functions with the same name essentially overwriting the default cmdlets.

If your extension does not offer the ability to add or update a secret, you could implement the function but only throw an error message stating that it is not supported.

Next, we will explore how to structure a PowerShell SecretManagement extension vault and start to implement the commands.

Creating a PowerShell SecretManagement Extension Vault

Now that you have seen the basic cmdlet structure and objects you'll be working with, let's now learn how to create an example extension vault!

The root directory to create the first parent module directory is in the SecretManagement module's ExtensionModules folder. You can find this directory by running (Get-Module -Name Microsoft.PowerShell.SecretManagement).Path | Split-Path -Parent.

Create the Main Vault Folder and Manifest

Open up PowerShell and create a variable holding the path to the ExtensionsModule parent directory which all underlying module folders and files will be created.

$vaultParentPath = (Get-Module -Name Microsoft.PowerShell.SecretManagement).Path | Split-Path -Parent.

2. Create the parent module directory in the ExtensionModules directory. Name this directory SecretManagement.<Vault source>. In this case, the directory is called SecretManagement.LiteDB.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb" -ItemType Directory

3. Create a module manifest for the SecretManagement.LiteDb module outlining some common manifest attributes.

New-ModuleManifest -CompatiblePSEditions Core -Author '<you>' -NestedModules './SecretManagement.LiteDB.Extension/SecretManagement.LiteDB.Extension.psd1' -RequiredModules 'Microsoft.Powershell.SecretManagement' -PowerShellVersion 7.0 -Tags 'SecretManagement' -Path "$vaultParentPath\SecretManagement.LiteDb"

4. Once New-ModuleManifest creates the template manifest, open it up and ensure it mirrors the below manifest.

@{
  ModuleVersion        = '0.0.0.1'
  # Make this only compatible with PowerShell Core/7
  CompatiblePSEditions = @('Core')
  GUID                 = '<guid here>' ## Generate a GUID with New-Guid
  Author               = 'Adam Listek'
  # Pointed to the nested module definition file
  NestedModules   = @(
    './SecretManagement.LiteDB.Extension/SecretManagement.LiteDB.Extension.psd1'
  )
  # Make this module dependant on the SecretManagement module
  RequiredModules = @(
    "Microsoft.Powershell.SecretManagement"
  )
  # Set the minimum PowerShell version of 7.0 as Core is the only one supported by the primary module and this is the recommended PowerShell version
  PowershellVersion = '7.0'
  FunctionsToExport = @()
  CmdletsToExport   = @()
  VariablesToExport = @()
  AliasesToExport   = @()
  # Not necessary, but recommended to tag your module with SecretManagement to assist PowerShell Gallery users in finding your module
  PrivateData = @{
    PSData = @{
      Tags = @('SecretManagement')
    }
  }
}

Creating the Extension Vault Directory and Manifest

Once you've created the main extension folder and manifest, next create the extension vault module with its manifest. This module is a nested module inside of the main parent extension module directory.

Create the extension vault's folder.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension" -ItemType Directory

2. Create the module manifest. This manifest only requires two attributes; RootModule and FunctionsToExport.

You'll notice the FunctionsToExport parameter shows the same function names as the SecretManagement module itself. An extension vault's commands "overwrite" the default SecretManagement modules.

New-ModuleManifest -RootModule '.\SecretManagement.LiteDB.Extension.psm1' -FunctionsToExport @('Set-Secret','Get-Secret','Remove-Secret','Get-SecretInfo','Test-SecretVault') -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension.psd1"

3. Once New-ModuleManifest creates the template manifest, open it up and ensure it mirrors the below manifest.

@{
  ModuleVersion     = '0.0.0.1'
  # The command definitions located in the same directory as this module
  RootModule        = '.\SecretManagement.LiteDB.Extension.psm1'
  # Only export the functions that the SecretManagement module expects
  FunctionsToExport = @('Set-Secret','Get-Secret','Remove-Secret','Get-SecretInfo','Test-SecretVault')
}

Now that our module is all set up, let's implement the functions themselves! As mentioned before, to allow the PowerShell SecretManagement module to interact with your extension vault, you must define functions with the exact same name as the ones shown below other than the LiteDb-specific function Open-Database.

Create the Vault Function "Scaffolding"

Since you'll be devouring a lot of code in this article, first build the PSM1 module "scaffolding". This will allow you to insert code into this framework as you go along.

Create the extension vault PSM1 module by first creating a text file.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension\SecretManagement.LiteDB.Extension.psm1" -ItemType File

2. Copy and paste the following "scaffolding" code into the PSM1 file. Code-specific comments are inline.

You must use the standard function names defined above in the Understanding section to interact with the SecretManagement module. You can also add your own functions to the module as "helper" functions if you'd like as shown in the below PSM1 file (Open-Database).

# Necessary to correctly override and implement the existing SecretManagement functions
Using Namespace Microsoft.PowerShell.SecretManagement

# An internal function, specific to this LiteDB vault, that will be used to open the database for interaction
Function Open-Database {}

# The following five functions are the standard SecretManagement functions that we will implement
Function Get-Secret {}

Function Set-Secret {}

Function Remove-Secret {} 

Function Get-SecretInfo {}

Function Test-SecretVault {}

Build the Functions

The next step is to add functionality to the extension vault. This functionality means adding functions to the extension vault (module).

Though we are creating an interface to store secrets, in this tutorial, we are not implementing the database's encryption, and in a production database that would be recommended. Once the database has been encrypted, decryption is done by passing a password upon opening the database for reading or writing.

Creating the "Helper" `Open-Database` Function

Typically, you'll only be building the standard set of functions but for LiteDB, the tutorial has a "helper" function called Open-Database. This function is strictly an internal function utilized by the extension module to simplify opening the database and making it available to the exposed functions. Code comments in-line.