Working with Dell EMC PowerFlex REST API using PowerShell - Part 1

In this article, I will explain briefly how to work with REST API exposed by PowerFlex (formerly known as ScaleIO and VxFlex OS Software) using PowerShell to manage/ monitor your PowerFlex cluster. The PowerFlex REST API is served from the PowerFlex Gateway which allows querying information and performing actions related to PowerFlex software components. PowerFlex Gateway connects and queries master MDM, reformats the results in a RESTful manner, and passes it to a REST client.

Access to the API requires a login using Gateway username and password. A successful login returns a token, and you can use this token for later authentications for other requests. The responses or results returned are in JSON format. In the following sections, I will explain how to use PowerShell to query PowerFlex REST API and obtain relevant results.  

PowerShell uses Invoke-RestMethod cmdlet which sends HTTP/ HTTPS requests to REST web services that return rich structured data. PowerShell will format the response based on the data type. For JSON PowerShell converts the response content to objects. 

Step 1: Authentication and token generation

#Note: 192.168.11.15 is the IP of PowerFlex Gateway

$User = Read-Host -Prompt "Please enter username"

$SecurePassword = Read-Host -Prompt "Enter Password for user $user" –AsSecureString

$Credentials = New-Object System.Management.Automation.PSCredential ($user,$Securepassword)

#HTTPS Get request is invoked with credentials for authentication

$Token = Invoke-RestMethod -Uri "https://192.168.11.15:443/api/login" -Method Get -Credential $Credentials

Step 2: Create header with the token

$auth = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(':'+$Token))

$global:PowerFlexAuthHeaders = @{'Authorization' = "Basic $auth"

'Content-Type' = "application/json" }

Step 3: Invoke-RestMethod

#Query all alerts in the system

$alerts = (Invoke-RestMethod -Uri "https://192.168.11.15:443/api/types/Alert/instances/" -Method Get -Headers $PowerFlexAuthHeaders)

#Query all SDSs in a PD

$all_SDS = (Invoke-RestMethod -Uri "https://192.168.11.15:443/api/instances/ProtectionDomain::3ce4af5f00000000/relationships/Sds " -Method Get -Headers $PowerFlexAuthHeaders)

#Query a specified PD

$pd01 = (Invoke-RestMethod -Uri "https://192.168.11.15:443/api/instances/ProtectionDomain::3ce4af5f00000000 " -Method Get -Headers $PowerFlexAuthHeaders)

#Query statistics of a specified PD

$pd01_stats = (Invoke-RestMethod -Uri "https://192.168.11.15:443/api/instances/ProtectionDomain::3ce4af5f00000000/relationships/Statistics " -Method Get -Headers $PowerFlexAuthHeaders)

Hope this was useful. Refer to the PowerFlex REST API Reference Guide for more details.

In the next article, I will explain how to query selected statistics/ parameters with POST method which will help you to

create custom monitoring scripts for your PowerFlex clusters.

Note:

If you are getting the below error while trying to create the token during step 1, please add the below lines of code to the

start of your script.

"Invoke-RestMethod : The underlying connection was closed: An unexpected error occurred on a send."

#Solution to above error!

add-type @"

    using System.Net;

    using System.Security.Cryptography.X509Certificates;

    public class TrustAllCertsPolicy : ICertificatePolicy {

        public bool CheckValidationResult(

            ServicePoint srvPoint, X509Certificate certificate,

            WebRequest request, int certificateProblem) {

            return true;

        }

    }

"@

[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 -bor [System.Net.SecurityProtocolType]::Tls11

PowerShell Remoting

Remoting is a feature that helps you manage Windows infrastructure in scale. It uses WS-MAN protocol implemented using WinRM. PS Remoting is enabled by default in Windows Server 2012 and later. It is recommended to turn on remoting because a lot of new graphical administrative tools are making use of PowerShell and PowerShell Remoting in the background.

Here I will be explaining remoting on systems part of same domain.

1:1 Remoting

This case is useful in managing a single system. Enter-PSSession cmdlet can be used for 1:1 remote connection.

Enter-PSSession -ComputerName AD-DNS

In the above screenshot you can see that I connected to AD-DNS from VM01 using Enter-PSSession. Once the session is established you can see the PS prompt changes to "[AD-DNS]:". This means currently you are in the command line prompt of AD-DNS. The next two cmdlets gets the IPV4 address and eventlogs of the remote machine.

1:Many Remoting

This case is useful if you want to run a specific command or task on a set of computers and get the results back to you.

invoke-command -ComputerName VM01, AD-DNS { gsv msiscsi }

What actually happens here is first a PS session is established to the remote machine. Load PowerShell and .NET and the give code is sent across the connection, execute the code on the remote machine, the resultant objects are then serialized into XML, send them across the connection, deserialize the XML to objects and place them in the pipeline of the PowerShell session.

Lets have a look at the below case where we execute gsv msiscsi on the local machine. You can see that the type name is System.ServiceProcess.ServiceController .

When you execute gsv msiscsi on remote machines by adding -ComputerName with the Invoke-Command, you can see the type name changed to Deserialized.System.ServiceProcess.ServiceController .

Another remoting use case given below where you want to check the remaining size of some specific drive on multiple machines.

PS Sessions

When you use the Enter-PSSession or Invoke-Command with -ComputerName parameter a remote session is established and it will run the task which was asked to and it will end the session when the task is complete. In case of Enter-PSSession cmdlet, the PS session will end once the user termiates the session using Exit-PSSession. So always there is an overhead of starting and ending a PS session. There is way to create persistent PS session using New-PSSession cmdlet.

$s1 = New-PSSession -ComputerName AD-DNS

Here $s1 will hold a persistent PS session to computer AD-DNS. Now you can invoke tasks remotely using the session that is already created and opened.

It is the responsibility of the user to remove the PS-Sessions after use. Otherwise it will remain opened and consume resources.

PowerShell Direct

PowerShell Direct is a new feature introduced in PowerShell version 5.1 which supports management of Windows 10 and Windows Server 2016 guest VMs running on Windows 10 or Windows Server 2016 host machines. This simply means you can establish a PowerShell session from the host machine to any of the VMs running on it by just using the VM name and it works even without network connectivity to the VM through a vSwitch. Because the connection is established not via network but over the Hyper-V VM bus. You can even use PS Direct sessions to copy files to a VM which does not have IP connectivity.

Lets have a look into the example below where I have few VMs hosted on Windows Server 2016. I will connect to one of the VM named "AD" using PS direct.

In the above screenshot you can see that a new PS session is established using the VM name. Now lets see how you can copy files to a VM over PS Direct sessions.

Hope this was useful. Happy PS remoting !

Reference ebooks:

Secrets of PowerShell Remoting
Layman's Guide to PowerShell 2.0 remoting

Reference videos:

PowerShell Pipeline and object filtering

Pipeline is a functionality in PowerShell where it allows the output of a cmdlet to be used as input to the next cmdlet in the pipeline and work with them. By default at the end of a pipeline is a special cmdlet called Out-Default. Let's have a look at the example below.

Get-Service | Where-Object {$_.Status -eq "Running"}

The above example will provide you a list of services that are currently running on your machine. Here whats actually happening is objects that are produced by the first cmdlet (Get-Service) is passed to the next cmdlet in the pipeline. The second cmdlet will filter the services that are having "Running" status and displays the final result. "$_" holds the current object in the pipeline. 

Let's go through another example to get Windows event logs for last 24 hours.

Get-eventlog -LogName System -EntryType Error -After (Get-Date).AddDays(-1) | select EventID, TimeGenerated, Message |  convertto-html | Out-File C:\errorlist.htm

As you can see this example has multiple stages where output produced by one cmdlet is passed to the next cmdlet in the pipeline. Stage 1 filters System event logs with type error in the last 24 hours. The output of stage 1 is passed to next cmdlet in the pipeline which filters EventID, TimeGenerated, and Message. Results from stage 2 are passed to the next cmdlet where it converts the result to HTML and finally passed to the last stage where the final result is written to a file.

Reference video:

PowerCLI to remove orphaned VM from inventory

Recently I came across a situation where one of the VM running on ESXi 6.0 was orphaned. This happened after I updated the ESXi with a patch. All the files associated with that VM was available in the datastore. But the VM was displayed in the inventory as orphaned. There was no option available to remove the VM from inventory from the web console. Inorder to register the original VMX file, the orphaned VM needs to be removed from inventory first.

Steps to resolve this issue:

1. Connect to vCenter server using PowerCLI: Connect-VIServer 192.168.14.15
2. Get list of VMs: Get-VM | Select Name

3. In my case "HCIBench_1.6.5.1_14G" was orphaned.

4. Remove the orphaned VM: Remove-VM HCIBench_1.6.5.1_14G

5. As you can see in the above screenshot, orphaned VM is removed from inventory. Now you can go to the datastore where the original VM files are stored, click on the VMX file and register (In my case, while I tried to register the VM it resulted in an error mentioning that the item already exists. I had to reboot the vCenter server to fix this issue. After rebooting the vCenter I was able to register the VMX file of the VM).

Hope it was helpful to you. Cheers!

Reference: blog.vmtraining.net

Active Directory Audit using PowerShell

Most of the organizations will conduct an audit of their active directory infrastructure once in three or six months as part of a regular clean up and maintenance process. Some of the common activities involved in AD audit process are given below.

• Find all disabled objects like users, computers and service accounts
• Find all accounts which are inactive for the last 90 days
• Find all accounts with a password that will never expire
• Find all users, computers and service accounts that are expired
• Find all users, computers and service accounts that will expire in next 7 days
• Find all accounts that have been locked out

Now let's see how you can use PowerShell to obtain the above information.

Find all disabled objects like users, computers and service accounts:
Search-ADAccount -AccountDisabled | Format-Table Name, ObjectClass -AutoSize

Find all accounts which are inactive for the last 90 days:

Search-ADAccount -AccountInactive -TimeSpan 90.00:00:00 | Format-Table Name, ObjectClass -AutoSize

Find all accounts with a password that will never expire:

Search-ADAccount -PasswordNeverExpires | FT Name, ObjectClass -A

Find all users, computers and service accounts that are expired:

Search-ADAccount -AccountExpired | FT Name, ObjectClass -A

Find all users, computers and service accounts that will expire in next 7 days:

Search-ADAccount -AccountExpiring -TimeSpan 7.00:00:00 | FT Name, ObjectClass -A

Find all accounts that have been locked out:

Search-ADAccount -LockedOut | FT Name, ObjectClass -A

As per company IT policies, rules and regulations they can decide what actions need to be taken against the audited items. 

Reference: docs.microsoft.com

Objects, properties and methods in PowerShell

An object is something which has a set of properties that describes it and set of methods which are the actions you can perform on it. Lets look into an example.

Get the virtual machines from a Hyper-V host: Get-VM

The result shown in the above screenshot is not just text. These are objects and associated parameters. There are 4 virtual machine objects and its associated properties like Name, State, Uptime etc. The output shows only limited properties but there are more number of properties associated with a virtual machine object.

You can find all the properties and methods available for an object using: Get-Member

Example: Get-VM | Get-Member

Here you can see all the properties and methods available. 

Property

You can select the properties as per requirement.

Get-VM | select -Property Name, IsClustered, MemoryDemand, ProcessorCount, NumaAligned, Generation, Path

To retrieve properties of a specific virtual machine object, use the below:

Get-VM -name AD | select -Property Name, IsClustered, MemoryDemand, ProcessorCount, NumaAligned, Generation, Path

You can assign this to a string variable as shown below:

$vm = Get-VM -name AD | select -Property Name, IsClustered, MemoryDemand, ProcessorCount, NumaAligned, Generation, Path

And the individual properties of that object can be retrieved too!

Method

Example: Get-Service -Name bits

To get all the properties and methods for this object: Get-Service -Name bits | gm

Note: 'gm' is alias for Get-Member

In the above screenshot you can see several methods like start, stop, refresh etc. These are actions that can be performed on the service controller object "Bits".

Below screenshot shows how to start and stop "bits" service using Start and Stop methods.

To start bits service: (Get-Service -Name bits).Start()

To stop bits service: (Get-Service -Name bits).Stop()

Hope it was useful to you. Cheers!

Avoid disasters in PowerShell

WhatIf

If you are unsure about the operation or action that is going to happen after executing a PowerShell cmdlet, use "WhatIf". This will tell you what it will do without actually doing it. So that you will have an understanding of what the cmdlet is going to perform. Consider the below PS statement. 

Get-Service | where {$PSItem.name -eq "bits"} | Start-Service

Lets assume that you are unsure of what the above statement will do. Add -WhatIf at the end and execute it.

Get-Service | where {$PSItem.name -eq "bits"} | Start-Service -WhatIf

Example: WhatIf

The above screenshot explains the operation that will perform if you execute the statement. In this case it will start the BITS service. 

Confirm

Lets consider another scenario where you want to confirm the action from the user before actually executing it straight away. You can use "Confirm" in this case. See the below example. 

Clear-EventLog -LogName System -Confirm

Example: Confirm