on 04-Dec-2015 06:53
Problem this snippet solves:
To report an issue with the F5-LTM or F5-BIGIP modules, please use the Issues sections of the GitHub repos (here and here) instead of commenting here. Thanks!
This PowerShell module uses the iControlREST API to manipulate and query pools, pool members, virtual servers, and iRules. It aims to support version 11.5.1 and higher, and to conform to the schedule for technical support of versions, though this may eventually prove to become difficult.
The module currently includes some functionality that, strictly speaking, is outside the scope of the LTM module. Hence, there is an active effort to wrap this LTM module into a larger BIG-IP module, and relocate that functionality elsewhere within that parent module, as well as expand the scope of functionality to include BIG-IP DNS (formerly GTM) and possibly other areas. Both the LTM module and the parent BIG-IP module are projects on github. Please use these projects to report any issues you discover. Thanks!
The module contains the following functions.
How to use this snippet:
To use the module, click 'Download Zip', extract the files, and place them in a folder named F5-LTM beneath your PowerShell modules folder. By default, this is %USERPROFILE%\Documents\WindowsPowerShell\Modules. The WindowsPowerShell and Modules folders may need to be created.
You will most likely need to unblock the files after extracting them. Use the Unblock-File PS cmdlet to accomplish this.
The Validation.cs class file (based on code posted by Brian Scholer) allows for using the REST API with LTM devices with self-signed SSL certificates.
Nearly all of the functions require an F5 session object as a parameter, which contains the base URL for the F5 LTM and a credential object for a user with privileges to manipulate the F5 LTM via the REST API. Use the New-F5session function to create this object. This function expects the following parameters:
You can create a credential object using Get-Credential and entering the username and password at the prompts, or programmatically like this:
$secpasswd = ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential "username", $secpasswd
Thanks to Kotesh Bandhamravuri and his blog entry for this snippet.
There is a function called Test-Functionality that takes an F5Session object, a new pool name, a new virtual server, an IP address for the virtual server, and a computer name as a pool member, and validates nearly all the functions in the module.
I've also contributed this code sample for how to gather some basic info about your LTM with this PS module.
The module has been tested on:
Code :
https://github.com/joel74/POSH-LTM-Rest
Tested this on version:
11.5Would you please update the document to include the correct process for establishing the connection? Powershell doesn't use parentheses when passing parameters. While the comments section is helpful, a newbie (like myself) would have thought the document as displayed was correct.
`Function F5-Connect {
if ( (Get-Module | Where-Object { $_.Name -eq "F5-LTM"}) -eq $null ) {
Write-error "'F5-LTM' is not installed on this computer."
Exit
} else {
Connect to the F5 Load Balancer using the predefined credentials for node management
$myhost = 'myf5.mycompany.com'
$myuser = 'f5adminusername'
$mysecpass = ConvertTo-SecureString "f5adminpassword" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential $myuser, $mysecpass
$SessionToken = New-F5Session -LTMName $myhost -LTMCredentials $mycreds -Passthrough
}
Return $SessionToken
} `
Hi, I'd be happy to correct whatever is currently incorrect, but I'm not clear on the function call with parentheses that you're referring to. Could you please include the line with the params? Are you referring to something on devcentral.com or the github repo?
Thanks, Joel
The code snippet at the top of this page:
$mycreds = New-Object System.Management.Automation.PSCredential ("username", $secpasswd)
Should be:
$mycreds = New-Object System.Management.Automation.PSCredential "username", $secpasswd
Another gotcha I found with the commands was capturing the Pool membership statistics. In a comment on this page, someone posted this solution:
Get-Pool -F5Session $F5Session | Select-Object -ExpandProperty fullPath;
The problem I had was determining what "fullPath" was. I wanted to see the number of server connections for a given node. I stumbled onto a solution using -ExpandProperty *
. A sample:
$PoolConnections = Get-PoolMemberStats -F5Session $F5Session -PoolName $Poolname -Partition $PoolPartition -Address $IPAddress | Select -ExpandProperty * | % { $_.nestedStats.entries.'serverside.curConns'.value }
Thanks for clarifying re: the parentheses in the New-Object call. The code works as is, but it is more in line with PowerShell standards to not include the parentheses, so I'll remove them.
Re: the call to get pool member connections, if you call the deprecated function Get-CurrentConnectionCount, you'll get a message that it's recommended to use:
Get-PoolMemberStats | Select-Object -ExpandProperty 'serverside.curConns'
which is similar to your method. However, this may no longer work as of v12.1, so I have an open issue in the GitHub project to look into this.
Cheers, Joel
what is the usage for new-virtualserver? I've tried using it like this: New-VirtualServer -name "test" -DestinationIP 192.168.15.98 -DestinationPort 30784 -DefaultPool "testpool"
I get this error:
New-VirtualServer : Parameter set cannot be resolved using the specified named parameters.
Hi, Alvin. Thanks for catching this. The issue was that, when neither VlanEnabled or VlanDisabled were specified, the cmdlet didn't know how to process. I've fixed that and committed it to the github repo (https://github.com/joel74/POSH-LTM-Rest/commit/cdb7f03ca90f87af739b61d8ba29294abc3f18e6), but I'm not seeing the commit show up yet.
One thing to note, you'll need to include the ipProtocol parameter and a value for that, as that's a mandatory param. In my testing with the committed change, this worked for me:
new-virtualserver -name "test" -DestinationIP "192.168.15.98" -DestinationPort "30784" -DefaultPool "TEST_POOL" -ipProtocol tcp
PS C:\Windows\system32> $F5Session = New-F5session -LTMName "ServerNameHere" -LTMCredentials $mycreds -PassThrough; Get-Pool -F5Session $F5Session | Select-Object -ExpandProperty fullPath; ConvertFrom-Json : Cannot bind argument to parameter 'InputObject' because it is null. At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\F5-LTM\Public\Invoke-RestMethodOverride.ps1:64 char:50 + $message = $_.ErrorDetails.Message | ConvertFrom-json | Select-Objec ... + ~~~~~~~~~~~~~~~~ + CategoryInfo : InvalidData: (:) [ConvertFrom-Json], ParameterBindingValidationException + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
Invoke-RestMethodOverride : " : At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\F5-LTM\Public\New-F5Session.ps1:27 char:15 + $Result = Invoke-RestMethodOverride -Method POST -Uri $AuthURL -Body $JSONBo ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-RestMethodOverride
ConvertFrom-Json : Cannot bind argument to parameter 'InputObject' because it is null. At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\F5-LTM\Public\Invoke-RestMethodOverride.ps1:64 char:50 + $message = $_.ErrorDetails.Message | ConvertFrom-json | Select-Objec ... + ~~~~~~~~~~~~~~~~ + CategoryInfo : InvalidData: (:) [ConvertFrom-Json], ParameterBindingValidationException + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
Invoke-RestMethodOverride : " : At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\F5-LTM\Public\Get-Pool.ps1:32 char:21 + $JSON = Invoke-RestMethodOverride -Method Get -Uri $URI -WebSession ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-RestMethodOverride
This happens when the LTM device can't be found. I could add a check to test that the name / IP entered for the LTM is a reachable device (i.e. responds to a ping) but it's still up to the user to use the correct LTM name.
Do I need special permissions in F5 to be able to run PS commands?
I am able to get a session
PS C:\Windows\system32> $F5session = New-F5Session -LTMName 192.168.XXX.XXX -LTMCredentials $mycredentials -Passthrough
PS C:\Windows\system32> $F5session
Name
BaseURL
WebSession
----
-------
----------
192.168.XXX.XXX
https://192.168.XXX.XXX/mgmt/tm/ltm/
Microsoft.PowerShell.Commands.WebReq...
but when I try get-pool, i get this
PS C:\Windows\system32> Get-Pool $F5session
Invoke-RestMethodOverride : "401 F5 Authorization Required: Authorization failed:
user=https://localhost/mgmt/shared/authz/users/Mayur.Kirtani resource=/mgmt/tm/ltm/pool verb=GET
uri:http://localhost:8100/mgmt/tm/ltm/pool/ referrer:10.XXX.XXX.XXX sender:10.XXX.XXX.XXX
At C:\windows\system32\windowspowershell\v1.0\Modules\F5-LTM\Public\Get-Pool.ps1:32 char:21
+ $JSON = Invoke-RestMethodOverride -Method Get -Uri $URI -WebSession ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-RestMethodOverride
am i missing something?
thanks M
Hi, Mayur,
You'll need tmsh terminal access to be able to successfully make calls against the iControlREST API. I'd recommend checking your user permissions in the F5 and seeing if this is enabled.
Cheers, Joel
I would first like to say this is awesome, great work! I was able to easily deploy a node in about 5 minutes of scripting development. I don't know if this is on the roadmap or not but would be very useful for me is a way to deploy an entire iApp using something like this. I have went through the documentation Here: which was pretty good at explaining some of the REST options but didn't seem to have a good way of showing how to add members to a pool since those parts are truncated. I have a custom iApp that I have created that I use for most of my HTTP deployments. I am looking for an easier way to deploy VIPs in our HQ and DR environments at the same time if possible in a more automated fashion. It looks like REST will do it, is there a really good article on the API, possibly with complete examples someone could point me to?
Thanks! Buddy
Hi, Buddy. Thanks for the kind words! I haven't used iApps for anything, so I've been relying on others' experience and contributions to get iApp support into the module. The best way to get something on the roadmap for the module is to open an issue in the github repo, so if this is something you'd like to see added, please consider doing that. Thanks!
Cheers, Joel
This worked when I initially installed the module. And now it is not working.
PS C:> import-module -name f5-ltm PS C:> $secpasswd = ConvertTo-SecureString "MYPASSWORD" -AsPlainText -Force PS C:> $mycreds = New-Object System.Management.Automation.PSCredential "admin", $secpasswd PS C:> PS C:> $MyLTM_IP=”MYIP” PS C:> $F5Sess= New-F5Session -LTMName $MyLTM_IP -LTMCredentials $MyCreds –PassThru PS C:> $F5Sess
Name BaseURL Credential WebSession
MYIP System.Management.Automation.PSCredential Microsoft.PowerShell.Commands.WebRequestSessi
PS C:> get-virtualserver -F5Session $F5Sess ConvertFrom-json : Invalid JSON primitive: Document. At C:\Program Files\WindowsPowerShell\Modules\f5-ltm\1.4.110\Private\Invoke-F5RestMethod.ps1:39 char:50 + ... $message = $_.ErrorDetails.Message | ConvertFrom-json | Selec ... + ~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [ConvertFrom-Json], ArgumentException + FullyQualifiedErrorId : System.ArgumentException,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
I get a convertfrom-json issue with pretty much any get command I try.
Hi, bujnovskyd, what version of the LTM do you have, and are you using local authentication or external (i.e. AD or something)?
Well it is working today again. Hurray. FYI updated to f5-ltm 1.4.111 today. F5 is Version 12.1.1 Build 2.0.204 Hotfix HF2 and I am using local Authentication on the F5.
Not sure what was happening yesterday, and maybe a local computer reboot helped?
Thank you for the quick response and all of your hard work on this module.
Ok, when I run
New-F5Session -LTMName 0.0.0.0 -LTMCredentials $cred
I get nothing back to let me know the session.
If you want your session returned, you need to use -PassThru. Otherwise it gets assigned to the Script scope.
Hi Joel!
Excellent work on your module. I thought you could help eliminate people having trouble installing this module.
here is an example I found: https://gist.github.com/darkoperator/3f9da4b780b5a0206bca
In here you even do an unblock-file in small loop. All you need to do then is add you gist.github.com url. This can also help with deploying in break fix for bugs that you may find.
Thank you for developing this excellent module!!!
Thanks - I like the simplicity and helpfulness of that script.
I created a gist and included notes on installing via PSGet. Hopefully that helps.
Hi Joel
I am at a loss here. I can successfully run functions which don't in turn call other functions, however when I run functions like Get-PoolMember which in turn calls Get-Pool, my session object is not being carried through. I am using the -passthru parameter.
This Works* $MyLTM_IP = '10.0.0.1' $PoolName = 'myPoolName' $Partition = 'myPartition'
$F5Session = New-F5Session -LTMName $MyLTM_IP -LTMCredentials $MyLTMCreds -PassThru
Get-Pool -F5Session $F5Session -Name $PoolName -Partition $Partition
This DOESNT work* $MyLTM_IP = '10.0.0.1' $PoolName = 'myPoolName' $Partition = 'myPartition'
$F5Session = New-F5Session -LTMName $MyLTM_IP -LTMCredentials $MyLTMCreds -PassThru
Get-PoolMember -F5Session $F5Session -PoolName $PoolName -Partition $Partition
I get this error : Invoke-F5RestMethod : "401 F5 Authorization Required: An authorization header is missing.
Thanks Mike
Hi, Mike. Thanks for reporting this issue. I haven't been able to repro it on 11.6 or 12.1. What version of the LTM are you running? Does the issue happen if you use the -Default switch for New-F5Session and then don't pass a session to Get-PoolMember?
Thanks, Joel
Hi,
I'm running 11.6.1 Build 1.0.326 HF1 and i have a very weird issue where I get a 401 access denied (using a get-pool) unless i have previously given the user administrator access to all partitions.
I can return the user back to guest after i have granted the admin and it still works.
If i create a guest account straight up (with tmsh access granted) it gives a 401 error. Yet if i change that account to administrator, then back to guest it will work.
Hi Joel
Running this gives me the same error :
$MyLTM_IP = '192.168.0.1' $PoolName = 'mypoolname' $Partition = 'common'
New-F5Session -LTMName $MyLTM_IP -LTMCredentials $MyLTMCreds -Default Get-Poolmember -PoolName $PoolName -Partition $Partition
I am running BIG-IP 11.5.4 Build 0.0.256 Final
Thanks Mike
Hi, matvan, per the v11.6 docs, "administrative level access to the iControl® REST namespace [is needed] to make iControl REST requests." That you're able to remove admin access and still use iControlREST is strange, and seemingly not intended. On 11.6.0 HF4, if I remove admin access, I can no longer access iControlREST.
Thanks, Mike. Thanks for testing that. I'm assuming but want to clarify that you're using a local account, and that that account has the admin role for the common partition. Is that correct? Cheers.
Hi Joel
Yep that's correct. I am using a local admin account. I tried 2 admin accounts actually, one with tmsh and without with the same results.
Thanks Mike
Hi, Mike, I only have 11.6 and 12.1 available to me at the moment. I'll see if I can spin up 11.5.4 in AWS and repro this issue. In the meantime, what happens if you execute that line explicitly, i.e. create an F5 session and call:
Get-Pool -F5Session $F5Session -Name 'MyPool' -Partition 'Common' | Get-PoolMember -F5session $F5Session -Address * -Name *
Cheers, Joel