on 04-Dec-201506:53 - edited on 05-Jun-202322:21 by JimmyPackets
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.
Add-iRuleToVirtualServer
Add-iRuleToVirtualServer
Add-PoolMember
Add-PoolMonitor
Disable-PoolMember
Disable-VirtualServer
Enable-PoolMember
Enable-VirtualServer
Get-CurrentConnectionCount (deprecated; use Get-PoolMemberStats | Select-Object -ExpandProperty 'serverside.curConns')
Get-F5Session (will be deprecated in future versions. use New-F5Session)
Get-F5Status
Get-HealthMonitor
Get-HealthMonitorType
Get-iRule
Get-iRuleCollection (deprecated; use Get-iRule)
Get-Node
Get-BIGIPPartition
Get-Pool
Get-PoolList (deprecated; use Get-Pool)
Get-PoolMember
Get-PoolMemberCollection (deprecated; use Get-PoolMember)
Get-PoolMemberCollectionStatus
Get-PoolMemberDescription (deprecated; use Get-PoolMember)
Get-PoolMemberIP (deprecated; use Get-PoolMember)
Get-PoolMembers (deprecated; use Get-PoolMember)
Get-PoolMemberStats
Get-PoolMemberStatus (deprecated; use Get-PoolMember)
Get-PoolMonitor
Get-PoolsForMember
Get-StatusShape
Get-VirtualServer
Get-VirtualServeriRuleCollection (deprecated; use Get-VirtualServer | Where rules | Select -ExpandProperty rules)
Get-VirtualServerList (deprecated; use Get-VirtualServer)
Invoke-RestMethodOverride
New-F5Session
New-HealthMonitor
New-Node
New-Pool
New-VirtualServer
Remove-HealthMonitor
Remove-iRule
Remove-iRuleFromVirtualServer
Remove-Pool
Remove-PoolMember
Remove-PoolMonitor
Remove-ProfileRamCache
Remove-Node
Remove-VirtualServer
Set-iRule
Set-PoolLoadBalancingMode (deprecated; use Set-Pool)
Set-PoolMemberDescription
Set-Pool
Set-VirtualServer
Sync-DeviceToGroup
Test-F5Session
Test-Functionality
Test-HealthMonitor
Test-Node
Test-Pool
Test-VirtualServer
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:
The name or IP address of the F5 LTM device
A credential object for a user with rights to use the REST API
An optional TokenLifespan value for extending the life of the authentication token past the default 20 minutes
You can create a credential object using Get-Credential and entering the username and password at the prompts, or programmatically like this:
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.
So I just copied and pasted all three files to both of the following locations:
%USERPROFILE%\Documents\WindowsPowerShell\Modules && C:\Windows\System32\WindowsPowerShell\v1.0\Modules\F5-LTM.
I then type:
Import-Module F5-LTM
Then I get the following error: could not be processed because it is not a valid Windows PowerShell restricted language file. Remove the elements that are not permitted by the restricted language.
I set my policy execution to unrestricted. I am running Powershell 4. I feel like some instructions are missing somewhere.
Hi, Grayson. Thanks for the feedback. I found that I have to unblock all four files ones they have been downloaded and extracted. To do this, right-click on the files, select 'Properties' and then 'Unblock.'
The files only need to be placed in one of the two locations - %USERPROFILE% is the preferred one, as C:\Windows\... is typically reserved for Microsoft modules. Can you verify that the structure looks like:
C:\Users\(Your user name)\Documents\WindowsPowerShell\Modules\F5-LTM\(downloaded files).
If this still doesn't work, please let me know.
Thanks.
Hi, Grayson. Did you put the files in C:\Users\jbob\Documents\f5? They should be in C:\Users\jbob\Documents\WindowsPowerShell\Modules\F5-LTM. Please try that and see if it fixes the issue. You may need to create the 'WindowsPowerShell' and 'Modules' folders if they don't exist.
Also, I'm not sure what the references to the ampersands are from. Is that in your error message?
I did not have that folder originally, but I did create it. C:\Users\jbob\Documents\WindowsPowershell\Modules\F5-LTM. I have all four files downloaded there and unblocked them. I change my computer environmental variables to point to the path above. I refresh PowerShell and run "Import-Module F5-LTM" and then gives a bunch of errors. Formatting here isn't great or I'd code paste it. I've tried this one different systems and get the same issues.
Hi, J.
It looks like you may not have authorized yet to the F5. You'll need to create the F5 session first
(i.e. New-F5Session -LTMName (myLTM) -LTMCredentials $mycredsobject -Default )
and then you should be able to call
Get-Pool | Select-Object -ExpandProperty fullPath ConvertFrom-Json
without issue. Let me know.
Thanks.
Can't believe I saw this just now. I started scripting my own module a couple of days ago. This one is a bit more extensive however, it will be really useful.
Do you have any plans to cover other modules as well? I was planning on making one for ASM.
No plans to cover modules other than LTM right now, as that's all I have access to. If I can assist by reviewing code or offering snippets to help with other modules, please let me know.
I get this error "'Register-ArgumentCompleter' is not recognized as the name of a cmdlet" Is this a PowerShell 5.0 comdlet or should I be able to complete this with 4.0?
Update: updating to PowerShell 5.0 resolved this issue. Thanks!
Hi. You are correct - Register-ArgumentCompleter is a PS5 cmdlet. I didn't realize this was a requirement when this function was contributed to the module. I'd prefer to have the minimum version requirement be v4, so I'm going to see about changing this. Thanks.
Joel, thanks for your response. We needed to upgrade to PS 5.0 anyway 😕
One more thing though, it seems like the module cant be imported in PowerShell (x86). It imports fine in PS x64, but when I try to import it in an x86 PS window I get an error that the module cannot be found. Have you encountered this and is it expected?
Thanks!
Hi, pbarbuto, I just tested to confirm that I could import the module into an x86 PS shell, and it worked. Assuming that the module is in one of the folders listed in the PSModulePath environment variable, you should be able to import it without issue. You could also try typing in the full path to the module. Please let me know if you're still having issues. Thanks.
I'm new to using PowerShell and the LTM-REST module and a little help would be appreciated.
I'm getting this error when trying to connect to a F5 and get a list of the existing pools.
ConvertFrom-Json : Cannot bind argument to parameter 'InputObject' because it is null.
At C:\windows\system32\windowspowershell\v1.0\Modules\F5-LTM\1.3.26\Public\Invoke-RestMethodOverride.ps1:36 char:50
+ ... $message = $_.ErrorDetails.Message | ConvertFrom-json | Selec ...
+ ~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidData: (:) [ConvertFrom-Json], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidati NullNotAllowed,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
Invoke-RestMethodOverride : "404 Not Found:
At C:\windows\system32\windowspowershell\v1.0\Modules\F5-LTM\1.3.26\Public\Get-Pool.ps1:32 char:21
+ ... $JSON = Invoke-RestMethodOverride -Method Get -Uri $URI -Credenti ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-RestMethodOverride
And I am not positive whether I am even getting authenticated. This is the script being used:
$host_address = "IPAddress_of_F5_Appliance"
$user_id = "F5_Account_ID"
$secpasswd = "Pasword_Assigned_To_F5_Account_ID"
$secpasswd = ConvertTo-SecureString "Pasword_Assigned_To_F5_Account_ID" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ($user_id, $secpasswd)
New-F5session -LTMName $host_address -LTMCredentials $mycreds -PassThrough
Get-Pool | Select-Object -ExpandProperty fullPath ConvertFrom-Json
I'm running PowerShell v.5
Thanks.
Hi, it looks like you're close. When you call:
New-F5session -LTMName $host_address -LTMCredentials $mycreds -PassThrough
you should see your session object written out to the console if you successfully connect. -PassThrough is really only needed if you're going to capture the session in a variable and then pass it to a function. You could try:
$F5Session = New-F5session -LTMName $host_address -LTMCredentials $mycreds -PassThrough;
Get-Pool -F5Session $F5Session | Select-Object -ExpandProperty fullPath;
Let me know if this helps. Thanks.
Thank you very much for the quick response Joel. I tried the method you recommended and even change the F5 being accessed but I'm still getting the same response or a similar one.
PS C:\WINDOWS\system32> $host_address = "F5_IP_Address"
$secpasswd = ConvertTo-SecureString "F5_Account_Password" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("F5_Account", $secpasswd)
$F5Session = New-F5session -LTMName $host_address -LTMCredentials $mycreds -PassThrough
PS C:\WINDOWS\system32> $F5Session
Name BaseURL Credential
---- ------- ----------
F5_IP_Address https://F5_IP_Address/mgmt/tm/ltm/ System.Management.Automation.PSCredential
Up to this point no errors displayed; but , once I run the next command, the error shown below is displayed.
PS C:\WINDOWS\system32> 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\1.3.26\Public\Invoke-RestMethodOverride.ps1:36 char:50
+ ... $message = $_.ErrorDetails.Message | ConvertFrom-json | Selec ...
+ ~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidData: (:) [ConvertFrom-Json], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidati NullNotAllowed,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
Invoke-RestMethodOverride : " :
At C:\windows\system32\windowspowershell\v1.0\Modules\F5-LTM\1.3.26\Public\Get-Pool.ps1:32 char:21
+ ... $JSON = Invoke-RestMethodOverride -Method Get -Uri $URI -Credenti ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-RestMethodOverride
Finally, the only other information that I can add is that the SSL certificate on the F5 is self-signed and that when look at the content of the variables I can see that the correct values are contained.
Once again thanks in advance for time and attention to this matter.
Hi,
Thanks for trying that. It seems like, for some reason, the message being returned from the failed login attempt can't be converted from JSON. Are you definitely using v11.6 or higher of the LTM? One way to try and get a little more info about the error message would be to:
1) Open the file F5-LTM\Public\Invoke-RestMethodOverride.ps1 file in a text editor
2) On line 36, add a to comment out the JSON conversion and expanded property selection:
$message = $_.ErrorDetails.Message | ConvertFrom-json | Select-Object -expandproperty message
3) Add a new line below line 36 to write out the content of $message:
Write-Output $message
Maybe that will give us a better idea of what's going on.
Thanks.
Would 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?
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
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:
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.
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:
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.
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.
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?
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!
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.
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.
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.
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?
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, 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, 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:
