1 Introduction

PowerShell is a scripting language developed by Microsoft to enable automation of administrative tasks. The LoadMaster PowerShell wrapper enables direct access to the LoadMaster Application Program Interface (API) from PowerShell to simplify automation of configuration, deployment and lifecycle management of LoadMaster instances.

KEMP Technologies products optimize web and application infrastructure as defined by high-availability, high-performance, flexible scalability, security and ease of management. They minimize the total cost-of-ownership for web infrastructure, while enabling flexible and comprehensive deployment options.

1.1 Document Purpose

This document provides some information on how to import the KEMP PowerShell module, how to enable the API interface on the LoadMaster and how to use the Get-Help command to retrieve help text relating to the various commands and parameters that can be used.

1.2 Intended Audience

This document is intended to help anyone who wishes to configure or interface to the KEMP LoadMaster using Windows PowerShell commands.

1.3 Prerequisites

For the PowerShell API to work with the LoadMaster, the following prerequisites must be met:

Either TLS1.1 or TLS1.2 must be enabled in the LoadMaster WUI Settings. These are enabled by default. SSLv3 and TLS1.0 are unsupported with the PowerShell API. To set the Supported TLS Protocols, go to Certificates & Security > Admin WUI Access and select the check boxes provided.

The API interface must be enabled on the LoadMaster. To enable it â€“ go to Certificates & Security > Remote Access and tick the Enable API Interface check box or enable the API programmatically using the Enable-SecAPIAccess command. If you license the LoadMaster using the API, the API interface gets automatically enabled.

PowerShell version 5 or above is recommended.

2 Windows PowerShell

Companies are focusing on the internal changes necessary to enable their organization to scale efficiently in line with growth. Working more quickly and efficiently means managing and protecting a greater number of devices, applications, systems and identities. IT departments are using automation frameworks to meet that challenge.

PowerShell is an automation platform and scripting language for Windows and Windows Server. KEMP have had a PowerShell module since 2013. It simplifies the management of systems and is key to enabling IT departments to adopt automation in dynamic environments. In PowerShell, administrative tasks are generally performed by cmdlets, which are specialized .NET classes implementing particular operations. KEMPâ€™s PowerShell cmdlet improvements in our 7.2.39 release, are an enhancement for companies on an automation path, especially for automating your KEMP LoadMaster family of products.

2.1 Installing the KEMP PowerShell Module

The module contains the following files within the Kemp.LoadBalancer.Powershell folder:

Kemp.LoadBalancer.Powershell.psd1

Kemp.LoadBalancer.Powershell.psm1

deprecated.psm1

Kemp.LoadBalancer.Powershell-Help.xml

Copy the Kemp.LoadBalancer.Powershell folder to the relevant folder.

Install the module in a folder that is available in PSModulePath ($Env:PSModulePath).

If PSModulePath does not contain the module folder value, add the module path to the in PSModulePath environment variable. The module path can be for the current user only or for all users. Recommended values are:

$home\Documents\WindowsPowerShell\Modules for the current User

$Env:ProgramFiles\WindowsPowerShell\Modules for All Users

For example, install the KEMP PowerShell module for the current user only:

For the PowerShell commands to work, the API interface must be enabled on the LoadMaster. To enable it using the Web User Interface (WUI), go to Certificates & Security > Remote Access and select Enable API Interface.

You can test the connection to the load balancer by using the Test-LmServerConnection command, for example:

To retrieve the build number of the PowerShell module, run the following command:

(Get-Module Kemp.LoadBalancer.Powershell).ReleaseNotes

2.2 Importing the Certificate

As of LoadMaster version 7.2.36 the PowerShell module is signed. Depending on your execution policy, you may need to import the KEMP PowerShell certificate to allow execution. When you download the module from the KEMP website to obtain the following files:

Kemp.LoadBalancer.Powershell-Help.xml

Kemp.LoadBalancer.Powershell.psd1

Kemp.LoadBalancer.Powershell.psm1

kemp-cert.cer

symantec-ca-cer

symantec-int.cer

Perform the following steps:

1. Double-click the symantec-ca.cer file and install it in Trusted Root Certification Authorities.

2. Double the symantec-int.cer file and install it in Trusted Root Certification Authorities.

3. Confirm the installation by clicking OK when requested.

4. Double click the kemp-cert.cer and install it in Trusted Publishers.

You can either enter a username for the load balancer or provide a PSCredential object. When you enter a username, a prompt appears asking for the password. You can override the globally-provided LoadBalancer address and User Name on each individual command by using the LoadBalancer or Credential parameter within the command.

Similarly, you can specify the details to use certificate-based authentication using the Initialize-LmConnectionParameters command. For further information on the various steps involved to configure certificate-based authentication, refer to the below section.

2.4.1 Configure Certificate-Based Authentication

Follow the steps in the sections below to configure certificate-based authentication.

2.4.1.1 Enable Session Management

You must enable Session Management before you can enable client certificate authentication. To enable Session Management, follow the steps below:

1. In the main menu of the LoadMaster WUI, navigate to Certificates & Security > Admin WUI Access.

2. Select the Enable Session Management check box.

Once this check box is selected, the user is required to log in to continue using the LoadMaster.

3. Configure any other settings as needed.

The default state for the Require Basic Authentication check box is disabled. When this option is disabled, both certificate and credential-based remote access are available. If the check box is enabled, only credentials are valid for remote access.

2.4.1.2 Create a User (If Needed)

It is not possible to use certificate-based authentication with the bal user. However, you can create a non-bal user and grant it All Permissions, or whatever permissions you want. If you do not already have another user created, you can add one by following these steps:

1. In the main menu of the LoadMaster WUI, expand System Configuration > System Administration and click User Management.

2. At the bottom of the screen, enter a username in the User text box.

3. At this point, you can either set a Password for the new user, or select the No Local Password check box.

2.4.1.3 Enable Client Certificate Authentication on the LoadMaster

A number of different login methods are available to enable. For steps on how to set the Admin Login Method, along with a description of each of the available methods, refer to the steps below:

1. In the main menu of the LoadMaster WUI, expand Certificates & Security and click Remote Access.

2. Select the relevant Admin Login Method.

Using local certificates will only work with API authentication. Because of this, it might be best to select the Password or Client certificate option. This will allow API access using the client certificate and WUI access using the username/password.

The following login methods are available:

Password Only Access (default): This option provides access using the username and password only â€“ there is no access using client certificates.

Password or Client certificate: The user can log in either using the username/password or using a valid client certificate. If a valid client certificate is in place, the username and password is not required.The LoadMaster asks the client for a certificate. If a client certificate is available, the LoadMaster checks for a match. The LoadMaster checks if the certificate is a match with one of the local certificates, or checks if the Subject Alternative Name (SAN) or Common Name (CN) of the certificate is a match. The SAN is used in preference to the CN when performing a match. If there is a match, the user is granted access to the LoadMaster. This works both using the API and user interface.An invalid certificate will not allow access.If no client certificate is supplied, the LoadMaster will expect that a username and password is supplied (for the API) or will ask the user to enter a password using the standard WUI login page.

Client certificate required: Access is only allowed using the use of a client certificate. It is not possible to log in using the username and password. SSH access is not affected by this (only the bal user can log in using SSH).

Client certificate required (Verify via OCSP): This is the same as the Client certificate required option, but the client certificate is verified using an OCSP service. You must configure the OCSP Server Settings for this to work. For further information on the OCSP Server Settings, refer to the DoD Common Access Card Authentication, Feature Description.

Some points to note regarding the client certificate methods are below:

The bal user does not have a client certificate. Therefore, it is not possible to log into the LoadMaster as bal using the Client certificate required methods. However, a non-bal user can be created and granted All Permissions. This will allow the same functionality as the bal user.

There is no log out option for users that are logged in to the WUI using client certificates, as it is not possible to log out (if the user did log out the next access would automatically log them back in again). The session terminates when the page is closed, or when the browser is restarted.

2.4.1.4 Generate and Download the Client Certificate

To generate a local certificate, follow the steps below:

Users with User Administration permissions are able to manage local certificates for themselves and other users.

1. In the main menu of the LoadMaster WUI, navigate to System Configuration > System Administration > User Management.

2. Click Modify on the relevant user.

3. Enter a Passphrase and click Generate.

Entering a passphrase is optional. If a passphrase is entered it gets used to encrypt the private key.

4. Click OK to the pop-up message that appears.

5. Click Download.

You can also regenerate from this screen.

2.4.1.5 Create the PFX File

When you generate a certificate, as described in the section above, the LoadMaster creates a .pem file. For certificate-based authentication to work with PowerShell, a .pfx file is required.

You can convert the .pem file to .pfx any way you like. For the purposes of this document, we have provided steps on how to do it using OpenSSL. If you are using Windows, you may need to install OpenSSL to run these steps.

To create a .pfx file using, follow the steps below:

1. Open the .pem certificate.

2. Copy from the start of the -----BEGIN CERTIFICATE----- section to the end of the -----END CERTIFICATE----- section.

3. Paste this text into a new file.

4. Save the file as <CerFileName>.cer.

5. Go to the .pem certificate file again.

6. Copy from the start of the -----BEGIN RSA PRIVATE KEY----- section to the end of the -----END RSA PRIVATE KEY----- section.

2.4.1.6 Import the PFX File into the Microsoft Management Console (if using Windows)

If you are using Windows, follow the steps below to import the .pfx file into the Microsoft Management Console:

11. Click Start and type mmc.exe.

12. Click mmc.exe to open the Microsoft Management Console.

13. Click File and select Add/Remove Snap-in.

14. Select Certificates on the left and click Add.

15. Ensure that My user account is selected and click Finish.

16. Click OK.

17. Double-click Certificates â€“ Current User.

18. Double-click Personal.

19. Double-click Certificates.

20. Right-click on any white space in the middle panel, select All Tasks and click Import.

21. Click Next.

22. Click Browse.

23. Browse to the location of the .pfx file to be imported.

24. Select All Files in the drop-down menu in the bottom-right.

25. Double-click the .pfx file.

26. Enter the Password (if necessary).

27. Click Next.

28. Click Browse and select the Personal certificate store.

29. Click Next.

30. Review the settings and click Finish.

2.4.1.7 Specify the Certificate Details in the API

After configuring all of the options as outlined in the above sections, you need to specify the details of the certificate to run the API commands successfully. You can either do this using the Initialize-Lm command or in individual commands when they are run. The two parameters related to certificate-based authentication are:

SubjectCN: This parameter is mandatory if you want to use certificate-based authentication. This is the certificate Common Name (CN). This is the username of the LoadMaster user that the certificate was generated for. If you do not specify the CertificateStoreLocation, the certificate is searched for in the <CurrentUser>/My location.

CertificateStoreLocation: This parameter is optional. If you do not use it, the cmdlet searches for the certificate in the <CurrentUser>/My location (default). If the CertificateStoreLocation parameter is set, the API searches for the certificate in the specified location, for example Cert:\<CurrentUser>\TrustedPeople

2.5 Object Structure

Before version 7.2.39.0.334 of the KEMP PowerShell wrapper, the output format did not have a defined standard - each commandlet had variable structure and output.

In the 7.2.39.0.344 version of the wrapper, improvements were made to the output structure. All commands (except Test-LmServerConnection) return a PowerShell object with the following structure:

The Test-LmServerConnection command returns True if the LoadMaster is reachable by the API, False if not (or if the API interface is disabled on the LoadMaster).

ReturnCode (integer)

Response (string)

Data (PowerShell object, if any)

As a result of the new object structure, the current KEMP PowerShell wrapper is not compatible with scripts written based on an older version of the KEMP PowerShell wrapper (before version 7.2.39.0.344).

The possible values for the ReturnCode field are:

200: The command completed successfully

4xx/500: The command ended with an error. The error code depends on the error type.

The possible values for the Response field are:

Command successfully executed

Description of the error when the command fails, for example Unknown parameter value lmversion.

The Data field contains the response, if any. The structure of this field depends on the command. The elements of this field can be accessed using the â€œdotâ€ notation. If the command fails, this field is empty.

In the above example, the $licDet.Data.License is an array and each single element of the array can be accessed using the â€œ[]â€ notation. For example, to access the field name of the second element of the previous array we have to use the following notation: $licDet.Data.License[1].name. The index of the array starts from 0. The NULL object is returned if we try to access a non-existing element.

The benefits of the structure of the command answers are:

It is easy to check for success/error (ReturnCode)

There is a short description (Response)

The Data field returns a PowerShell object when successful and null when there is an error

2.5.1 Errors

If the error is a functional one (for example using the wrong credentials, parameter value or LoadMaster IP address) the cmdlet returns a PowerShell object, as described, with a ReturnCode containing the code of the error and with Response containing the description of the error that has occurred.

For example: Try to get the firmware version installed on the LoadMaster using an invalid certificate (installed in the Windows machine but not belonging to any user inside the LoadMaster):

If the error is due to a wrong/missing mandatory input, the cmdlet throws an exception. These types of errors do not return a ReturnCode because an exception has been thrown. The execution of the command is halted.

For example: Get the firmware version installed on the LoadMaster using a certificate not installed in the Windows machine:

$lma = Get-LmParameter -Param version -LoadBalancer 172.21.59.189 `

-SubjectCN invalidcertificate

ERROR: Can't find a certificate with "invalidcertificate" as CN in the default Cert:\CurrentUser\My store.

At C:\Users\ExampleUser\Work\Kemp.LoadBalancer.Powershell\Kemp.LoadBalancer.Powershell.psm1:273 char:5

2.6 Initially Configure a LoadMaster Using PowerShell API Commands

Several steps are involved in initially deploying a LoadMaster, such as accepting the End User License Agreement (EULA) and licensing the unit. Before the LoadMaster can be fully deployed, the EULAs must be displayed and accepted. These initial configuration steps can either be performed using the WUI or the API. The PowerShell API commands relating to initial configuration are in the sections below.

These commands should be run in sequential order.

2.6.1 Licensing Cloud LoadMasters

The two main licensing models for cloud LoadMasters are pay-per-use and Bring Your Own License (BYOL).

The Bring Your Own License (BYOL) model offers an alternative to the pay-per-use model. BYOL licenses are perpetual licenses which can include feature subscriptions. To use BYOL licensing, contact a KEMP representative to purchase a license. Then apply the license to the LoadMaster.

The pay-per-use licensing model enables you to pay for individual LoadMasters you need, for as long as you need to use them. You only pay for the usage consumed, and once you stop using them there are no additional costs or fees. Like BYOL subscription licenses, pay-per-use LoadMaster instances offer many different options for bandwidth throughput and add-on services.

Pay-per-use cloud LoadMasters are â€œpre-licensedâ€. Therefore, the following commands are not valid for pay-per-use LoadMasters: Read-LicenseEULA, Confirm-LicenseEULA, Confirm-LicenseEULA2 and Request-LicenseOnline. These commands are valid for BYOL cloud LoadMasters.

When deploying a pay-per-use LoadMaster, you can use the Set-LicenseInitialPassword command to configure the administrator password. The LoadMaster is ready to use after that point.

2.6.2 Initial Configuration Commands List

The initial configuration commands are listed below:

EULA:

- Read-LicenseEULA (mandatory)

- Confirm-LicenseEULA (mandatory)

- Confirm-LicenseEULA2 (mandatory)

These EULA commands must be run in the above order.

License type:

- Get-LicenseType (optional)

- Get-AslLicenseType (optional)

These commands are optional when completing the licensing process. The Get-LicenseType command contacts the KEMP Licensing Server. The Get-AslLicenseType must be used with a KEMP 360 Central Activation Server instance that is acting as a â€œlocal licensing serverâ€.

Licensing:

- Request-LicenseOnline

- Request-LicenseOffline

- Request-LicenseOnPremise

To install the license on the LoadMaster, one of the above commands must be used:

- The online command is used when the LoadMaster can reach the KEMP licensing server.

- Otherwise, the offline command must be used. If using offline licensing, you must have the â€œBLOBâ€ licensing text that KEMP sent in an email.

- The Request-LicenseOnPremise command is used to license a LoadMaster using a KEMP 360 Central acting as a â€œlocal licensing serverâ€.

Set password:

- Set-LicenseInitialPassword (mandatory)

This command must be used to set the LoadMaster administrator (bal) password.

Get license details:

- Get-LicenseInfo (optional)

Upgrade license:

- Update-LicenseOnline (optional)

- Update-LicenseOffline (optional)

Legacy:

- Get-LicenseAccessKey

2.6.3 Accept the EULAs

To license a LoadMaster, you must acknowledge the EULA licenses. This step involves three commands and they must be run in the following order:

1. Read-LicenseEULA

2. Confirm-LicenseEULA

3. Confirm-LicenseEULA2

For example:

$reula = Read-LicenseEULA -LoadBalancer 172.21.59.85 -Credential bal

$reula

ReturnCode Response Data

---------- -------- ----

200 Command successfully executed @{Eula=}

$reula.Data.Eula

MagicString Eula

----------- ----

d15981f0-ec48-4558-8a3e-796e2036300d ...

The MagicString parameter must be used as input for the Confirm-LicenseEULA command. The Type parameter is optional. The default value for the Type parameter is Trial. The Free value must only be used for the Free LoadMaster.

$ceula = Confirm-LicenseEULA -Magic $reula.Data.Eula.MagicString `

-LoadBalancer 172.21.59.85 -Credential bal

$ceula

ReturnCode Response Data

---------- -------- ----

200 Command successfully executed @{Eula2=}

$ceula.Data.Eula2

MagicString Eula2

----------- -----

46181257-2f09-4094-a9cd-6af02f352180 ...

The last step is to run the Confirm-LicenseEULA2 command. The MagicString parameter is from the Confirm-LicenseEULA output.

Setting the Accept parameter to yes when running the Confirm-LicenseEULA2 command means that your LoadMaster sends data to KEMP anonymously to improve our product usage knowledge. If this parameter is set to no, your LoadMaster does not send this data.

Setting the Accept parameter to no, disables notifications regarding new releases in the LoadMaster WUI.

2.6.4 Retreive the Available Licenses (optional)

Before running the command to license the LoadMaster (Request-LicenseOnline/Request-LicenseOffline) it is possible to retrieve the available license(s) for a specific KEMP ID from the KEMP Licensing Server using the Get-LicenseType command.

The parameters for this command are:

KempId (mandatory)

Password (mandatory)

OrderId (optional)

The output of the command (when successful) has the following structure:

ReturnCode : 200

Response : Command successfully executed.

Data : @{License=}

The field Data.License contains details about the the license(s) and it always includes the temporary license option. For example:

2.6.5 License the LoadMaster

The commands to license the LoadMaster (initially license the LoadMaster for the first time, not updating an existing LoadMaster license) are Request-LicenseOnline and Request-LicenseOffline.

To use the Request-LicenseOnline command, the LoadMaster must be able to connect to the KEMP Licensing Server. If this is not possible, the Request-LicenseOffline command can be used.

The Request-LicenseOnPremise command is used to license a LoadMaster using a KEMP 360 Central as a â€œLocal Licensing Serverâ€.

The Request-LicenseOnline command interface contains the OrderId and LicenseTypeId parameters. When you purchase a product from KEMP, KEMP provide you with the OrderId. The OrderId is a unique string that is a pointer to the record that details what was purchased. The OrderId is a container â€“ there may be multiple license types for one OrderId. The LicenseTypeId is the â€œlicense IDâ€ that can be retrieved using the Get-LicenseType command, as shown in the above examples.

If you specify the OrderId but not the LicenseTypeId, the first license in the list matching the specified Order ID is used. This is the first license defined (the oldest) for that order ID.

If you specify both the OrderId and LicenseTypeId, the specific license matching both the Order ID and License Type ID is used.

If you do not specify either an OrderId or LicenseTypeId, a temporary license is applied.

If you specify a LicenseTypeId but not an OrderId, an error message is returned. This is an invalid combination â€“ the Order ID must also be specified if using the License Type ID.

The following table summarizes the above text:

OrderId (not mandatory)

LicenseTypeId (not mandatory)

License Given to the LoadMaster

Used

Not used

First license in the list matching the specified Order ID

Used

Used (value from Get-LicenseType)

The specific license matching the Order ID and License Type ID

Not used

Not used

Temporary license

Not used

Used (value from Get-LicenseType)

Invalid combination (error is returned). The Order ID must also be specified.

2.6.5.1 Online Licensing Example

The below example uses online licensing and requests a specific license (both the OrderId and LicenseTypeId must be used):

You can check the updated license by running the Get-LicenseInfo command.

2.7 Code Snippet Examples

Refer to the sections below for some code snippet examples.

2.7.1 Initialize the LoadMaster Connection Parameters

In the above examples, the required parameters, LoadBalancer and Credential, can be initialized before running the commands with the Initialize-LmConnectionParameters command. If you do this, it is not necessary to specify these parameters in each command.