PowerShell

 

1Introduction

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.1Document 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.2Intended Audience

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

1.3Prerequisites

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.

2Windows PowerShell

Windows PowerShell is Microsoft’s command-line shell and scripting language based on a .NET framework. Windows PowerShell allows administrators to automate tasks and manage all applications from a central source.

The KEMP PowerShell module allows administrators to configure the KEMP LoadMaster from the Microsoft PowerShell command line.

2.1Installing the KEMP PowerShell Module

Download the KEMP PowerShell module from the KEMP website, www.kemptechnologies.com.

The module should contain three files within the Kemp.LoadBalancer.Powershell folder:

  • Kemp.LoadBalancer.Powershell.psd1
  • Kemp.LoadBalancer.Powershell.psm1
  • Kemp.LoadBalancer.Powershell-Help.xml

Before installing the KEMP PowerShell module, please ensure that you have Microsoft PowerShell version 3.0 installed.

Copy the Kemp.LoadBalancer.Powershell folder to the relevant folder, for example:

  • <UserProfile>\Documents\WindowsPowershell\Modules or
  • C:\Windows\System32\WindowsPowerShell\v1.0\Modules

Use the Import-Module -Name Kemp.LoadBalancer.Powershell command to load the module into your PowerShell session, for example:

Import-Module -Name C:\Users\<UserProfile>\Documents\WindowsPowerShell\modules\Kemp.LoadBalancer.Powershell.psd1 –Prefix “KEMP” -Verbose

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:

Test-LmServerConnection –ComputerName 10.11.0.60 –Port 443 -Verbose

To retreive a list of available commands, run the following command:

Get-Command -Module Kemp.LoadBalancer.Powershell

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

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

2.2Importing 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.
  5. Set the execution policy to AllSigned. For example, Set-ExecutionPolicy –ExecutionPolicy AllSigned –Scope CurrentUser.

Alternatively, you could adjust your execution policy to one that is less restrictive.

2.3Using the Get-Help Command

To retrieve help text for a particular command, run the Get-Help command, followed by a command name, for example:

Get-Help Set-VirtualService

Different parameters can be specified to retrieve more detailed help text:

  • -Detailed: Provides further detailed help, including a list of parameters and their descriptions.
  • -Examples: Provides an example command and example output.
  • -Full: Provides all of the help text for the specified command.

For example:

Get-Help Set-VirtualService –Full

2.4Authenticating to the LoadMaster

To run PowerShell API commands, you need to establish authentication with the LoadMaster. There are two ways to establish authentication:

  • Using credentials; a LoadMaster username (Credential) and password
  • Using certificate-based authentication

Whichever option you use, you can either specify the parameters when running individual commands, or using the Initialize-Lm command.

You can also globally set the KEMP LoadMaster IP address that you are directing the commands to by using the Initialize-Lm command, for example:

Initialize-Lm -Address 10.11.0.60 -LBPort 443 -Credential bal -Verbose

You can either enter a username for the load balancer or provide a PSCredential object. When you enter a username, you 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 LoadMaster or Credential parameter within the command.

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

2.4.1Configure Certificate-Based Authentication

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

2.4.1.1Enable 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 System Configuration > Miscellaneous Options > WUI Settings.

Figure 2‑1: Enable Session Management

  1. 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.

  1. Configure any other settings as needed.
2.4.1.2Create a User (If Needed)
  1. 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:In the main menu of the LoadMaster WUI, expand System Configuration > System Administration and click User Management.

Figure 2‑2: Add User

  1. At the bottom of the screen, enter a username in the User text box.
  2. At this point, you can either set a Password for the new user, or select the No Local Password check box.

For further information on the No Local Password option, and on certificate authentication in general, refer to the User Management, Feature Description.

  1. Click Add User.
2.4.1.3Enable 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.

Figure 2‑3: Admin Login Method

  1. 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.4Generate 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.

Figure 2‑4: Modify user

  1. Click Modify on the relevant user.

Figure 2‑5: Generate certificate

  1. Enter a Passphrase and click Generate.

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

Figure 2‑6: New Certificate generated

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

Figure 2‑7: Download the certificate

  1. Click Download.

You can also regenerate from this screen.

2.4.1.5Create 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.
  7. Paste this text into a new file.
  8. Save the file as <KeyFileName>.key.
  9. Use the openssl command to create the .pfx file:

openssl pkcs12 -export -out <NewFileName>.pfx -inkey <KeyFilename>.key -in <CerFileName>.cer

  1. Import the certificate to the web browser.
2.4.1.6Import 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:

Figure 2‑8: Search for mmc.exe

  1. Click Start and type mmc.exe.
  2. Click mmc.exe to open the Microsoft Management Console.
  3. Click File and select Add/Remove Snap-in.

Figure 2‑9: Certificates

  1. Select Certificates on the left and click Add.

Figure 2‑10: My user account

  1. Ensure that My user account is selected and click Finish.
  2. Click OK.

Figure 2‑11: Certificates

  1. Double-click Certificates – Current User.

Figure 2‑12: Personal

  1. Double-click Personal.

Figure 2‑13: Certificates

  1. Double-click Certificates.
  2. Right-click on any white space in the middle panel, select All Tasks and click Import.

Figure 2‑14: Next

  1. Click Next.

Figure 2‑15: Browse

  1. Click Browse.
  2. Browse to the location of the .pfx file to be imported.

Figure 2‑16: All Files

  1. Select All Files in the drop-down menu in the bottom-right.
  2. Double-click the .pfx file.

Figure 2‑17: Enter Password

  1. Enter the Password (if necessary).
  2. Click Next.

Figure 2‑18: Certificate store

  1. Click Browse and select the Personal certificate store.
  2. Click Next.

Figure 2‑19: Finish

  1. Review the settings and click Finish.
2.4.1.7Specify 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

References

Unless otherwise specified, the following documents can be found at http://kemptechnologies.com/documentation.

WUI, Configuration Guide KEMP LoadMaster, Product Overview User Management, Feature Description DoD Common Access Card Authentication, Feature Description

Document History

Date

Change

Reason for Change

Version

Resp.

Sep 2015

Release updates

Updates for 7.1-30

5.0

LB

Oct 2015

Minor updates

Updated header and footer

6.0

LB

Nov 2015

Minor updates

Enhancements made

7.0

LB

Dec 2015

Release updates

Updates for 7.1-32

8.0

LB

Jan 2016

Minor updates

Enhancements made

9.0

LB

Mar 2016

Minor updates

Enhancements made

10.0

LB

July 2016

Major updates

Help text moved into module

11.0

LB

Oct 2016

Release updates

Updates for 7.2.36

12.0

LB

Jan 2017

Release updates

Updates for 7.2.37

13.0

POC

Mar 2017

Release updates

Updates for 7.2.38

14.0

LB

Was this article helpful?

1 out of 1 found this helpful

Comments

Avatar
Randy Chapman

My next job is trying to turn this http://lynciverse.blogspot.co.uk/2015/03/set-up-two-armed-kemp-vlm-as-reverse.html into something that can be done in PowerShell.