Stop and read this first
This version uses an old PowerShell SnapIn which is not maintained anymore and has been deprecated. We don’t develop it and we don’t add new features to it. Only use this if you have versions older than 11.6 in your environment.
If you read the discrete warning above, please go ahead and continue. 🙂
This is a script which will generate a report of the BigIP LTM configuration on all your load balancers making it easy to find information and get a comprehensive overview of virtual servers and pools connected to them (including those specified in iRules).
This information is used to relay information to our NOC and developers to give them insight in where things are located and to be able to plan patching and deploys. I also use it myself as a quick way get information or gather data used as a foundation for RFC’s, ie get a list of all external virtual servers without compression profiles.
The script has been running on 13 pair of load balancers, indexing over 1200 virtual servers for over 3 years now and the report is widely used across the company.
Since the 4.1.2 release the configuration of Bigip report is done via a separate configuration file. This will make updating the script much easier when there’s minor updates and makes it easier for me to test and deploy new version.
If you find any issues with the instructions (or even spelling errors), please take the time to report them as a comment below or on Devcentral.
A live demo can be found here:
Youtube video of an older version can be found here:
Feature requests / Help
Feel free to post any feature requests on the code repository page on Devcentral. They are very much appreciated.
You can also try our Discord.
- Powershell version 5.0 (might work on earlier versions too, but not tested)
- F5 Powershell Snap-in
- A web server of your choice
Only here for the code?
All releases are linked here:
Fast track installation instructions
If you haven’t set this up before I would recommend following the more detailed path below. If you’re in a rush or simply don’t want to read that much, here’s the quick and dirty alternative.
- Setup a guest user with the same password on all load balancers
- Find yourself a Windows server with Powershell 6.0 or above
- Make sure that the server/client running the script has HTTPS access to all load balancer management interfaces
- Configure at least the minimal config in bigipreportconfig.xml (Credentials, Device groups, Report Root and Default document)
- Make sure that the aforementioned report root contains the static content (Move the content of this folder to your wwwroot or underlay depending on if you’re running 5.3.0 or earlier) and runs a web server.
- Cross your fingers for luck
- Run the script and look for any errors.
- Browse your report in a web browser (only Chrome and Firefox tested, gave up on IE)
If you’re running Windows 10 (and maybe Windows 8) you might have to install .NET version 2 in order to be able to install the iControl snapin for Powershell. It might work without too. I’ve had varied experiences.
Verify if .NET 2.0 is installed or not
- Click start and search for Turn Windows Features on or off:
- Click it to get a list of optional features:
- If .NET Framework 3.5 is enabled you’re good to go. Otherwise enable it and click OK (Windows 10 installation media might be required).
Install the iControl snapin
- Navigate to the iControl snapin download page at Devcentral and click on the download button:
- Extract the downloaded file to a new folder:
- Right click on the iControl.dll and iControlSnapin.dll, choose properties and make sure that they are not blocked. If they are click on “Unblock”:
- Click on start and type “Powershell“, right click on Powershell and choose “Run as administrator“:
- A powershell window should now start. Navigate to your downloads folder and run “.\setupSnapin“:
- Also run “Set-ExecutionPolicy RemoteSigned” to allow unsigned powershell scripts to be running on your system (otherwise you can’t run the BigIP Report script later on).
Install a web server
The Bigip report script needs a web server to host the results of the script. Since there’s no server side execution it does not matter which Web server you choose, just that you have one (I’ve been hosting Bigipreport on both IIS and Apache).
I won’t bother writing a guide on how to install a web server since there’s so many online, but here’s a few direct links:
Apache on Ubuntu
Download the BigipReport package
- Choose a version:
- Unpack the zip file to a directory of your choosing.
- The content of the folder “Move the content of this folder to your wwwroot” (the folder is called underlay in 5.3.0 and later) should perhaps not so surprisingly be moved to the root of your web server (“c:\inetpub\wwwroot” is detault for IIS, “/var/www/html/” is default for Apache):
- The script and the bigipreportconfig.xml file should be copied to where you store scripts (up to you).
Create a read-only user on the F5 Load balancers
The script will need a user on the F5 load balancers. While it’s possible to use your own user it’s highly recommended out of security reasons to create a guest user for the script.
Just make sure that the user has read access to all partitions and that the same credentials is used on all load balancers.
Configure the script
So you’ve prepared the iControl snapin, the web server, downloaded the Bigip Report package and configured user accounts for the script? Well done, almost there!
The configuration file has explanations in it so I won’t go through more than the bare minimum in this guide. If you feel something is missing, please let me know!
- Open the “bigipreportconfig.xml“
- First we need to configure the credentials the script uses:
<Credentials> <Username>icuser</Username> <Password>icontrolisfun</Password> </Credentials>
- Then we need to tell the script which load balancers to connect to (read the section about Status VIPs below for more information about that):
<DeviceGroups> <DeviceGroup> <Name>Stockholm QA</Name> <Device>192.168.10.23</Device> <Device>192.168.10.23</Device> <StatusVip>https://lb1statusvip.domain.local</StatusVip> </DeviceGroup> <DeviceGroup> <Name>London Cluster</Name> <Device>192.168.11.55</Device> <Device>192.168.11.56</Device> <StatusVip></StatusVip> </DeviceGroup> </DeviceGroups>
- And where to put the result of the script:
- And finally the default document:
That’s it for the script configuration!
Testing the script
- Open a powershell window as a non-admin
- Navigate to the script directory
- Execute the script by entering .\[script name] and enter
- Watch for any exceptions or errors
Schedule the script
If you’re happy with the result you might want to schedule the script to keep the content updated.
- Click on the start menu and then enter “task scheduler“
- In the task scheduler, click on create task (located on the right hand side:
- Under the general tab, choose a name for the task and choose to run the task whether the user is logged in or not
For security reasons you might want to change the user the script is running as as well
- Then click on the tab called “Trigger” and click “New”
Enter the settings you desire and click OK.
- Move on to the tab called “Action” and click “New”
Action: Start a program
Program/Script: Browse to the script
- Click OK and then “OK“
- Enter the credentials of the chosen account and then click “OK“
Optional – Usage of multiple configuration files
Example on how to launch the script using an alternate configuration file:
.\bigipreport.ps1 -ConfigurationFile 'C:\Scripts\bigipreportconfig2.xml'
The script defaults to
"$PSScriptRoot\bigipreportconfig.xml" so there is no need to change anything if you don’t plan to run multiple versions of BigipReport.
Additional recommended script configurations
I would highly recommend to also configure logging. It will help you troubleshoot in case the report is failing later on.
Edit the bigipreportconfig.xml file and modify the section called LogSettings. Examples are available in the file.
Configure error reporting
Error reporting will have the script send an email when the script runs into trouble. Configure the ErrorReporting section in the bigipreportconfig.xml file. Examples are available in the file.
Pool Member State Polling
However, there’s one caveat here. The iRule engine is a bit limited compared to the iControl interface, which means that the results is not as detailed as if using the reports original icons. Instead, the result would indicate whether the member is capable of passing traffic or not. Also, the virtual server statuses will not be changed. This might be added later on if I can figure out a reliable way to do so.
Essentially this means that the icons will not be as detailed in the main view of the report, however, the pool details would still contain the original state AND the current one.
Here’s a translation table with most of them:
|Original icon||Member Availability||Member State||Translated Real-time state||Translated icon|
|No monitor assigned||Enabled||Enabled|
If you encounter another, please let me know.
The iRule impact on the system has been tested by sending a constant barrage of requests to the status VIP. While doing this I was barely able to make a dent in the CPU usage of my lab instance. This said, you probably want to keep track on the statistics to be sure.
How to enable polling
Now that you understand the limitations, you can follow these steps to enable the real-time status in the report.
Setting up a member Status VIP
- Open up the bigipreport_pool_status.tcl iRule located in the iRules folder in the zip file.
- Create an iRule named bigipreport_pool_status with the content of the iRule bigipreport_pool_status.tcl found in the iRules folder of the bigipreport zip file.
- Create a virtual server with an HTTP profile and assign the iRule to the virtual server. Please note that if your BigIPReport is using SSL, so must your status VIP.
- Make sure that all of your report users has access via the firewall to the virtual server.
If your bigipreport instance use HTTPS
Since the polling uses XHR the following conditions must be true:
- Your status VIPs must use HTTPS.
- Your status VIP must have a DNS pointed to it.
- Your status VIP must have an SSL certificate that validates the DNS.
- The SSL certificate must be trusted by the clients.
Configuring the report to use it
In the device group section of the configuration, define the URL to the member status VIP. Here’s the example form the configuration file itself.
<DeviceGroups> <DeviceGroup> <Name>F5YP Devices</Name> <StatusVip>https://poolstatus.j.local</StatusVip> <Devices> <Device> <IP>192.168.10.23</IP> </Device> <Device> <IP>192.168.10.24</IP> </Device> </Devices> </DeviceGroup> </DeviceGroups>
If you have any problems with the member endpoints you can check out these sections from the FAQ below:
Protect the report content using APM
A nice guy named Shannon offered details on how to protect the report behind an APM. This provides a much cleaner interface than using integrated authentication in IIS and is recommended if your company uses APM.
For more information about that, please refer to this post:
Upgrading the script
If the new version is much higher than the old one there might be a configuration file syntax change which would require you to re-do the configuration again. There is a column called “Need Config update?” in the version history of bigipreport.ps1 that indicates when the configuration file needs to be changed between different versions. Sometimes there might also be new sections which controls new features, like the real time member status (look above).
- Replace the bigipreport.ps1 script with the new version.
- Check the version history to know if you need to also update the bigipreportconfig.xml file.
- Replace all the front-end files with the content of “Move the content of this folder to the configured report root”
- Run the script
- When the report has finished, test it by accessing it and hitting CTRL + F5 to ignore the cache.
Upgrading the iControl Snap-in
If the pre-execution checks tells you that your version of iControl is too old it’s time to upgrade. Delete the old DLL files, download the latest version of iControl from DevCentral and follow the installation instructions above.
One user reports that removal of the registry key “HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellSnapIns” might be needed. Thanks to Christoph Frischhut for that information.
I get a status code of 403 when browsing to the script directory
This is probably due to the web server not having the chosen report file name in its default document list.
- Add the chosen report file name to the web server default document list
- Change the DefaultDocument setting to one of the web servers default documents
- Specify the path when browsing to the report, ie. http://bigipreport.mydomain.local/yourdefaultdocument.html
The script finished, but no file was written
Run the script manually and check the logs.
|The script failed to connect to one or more of the configured load balancers||Remove the failing load balancer from the configuration
Check the credentials of the script user
|The user running the script does not have permissions to write to the folder||
Grant permissions to the user running the script
|Script and web server is running on separate servers and the firewall is not open between the server running the script and the web server.||Open the firewall|
The script has failed but no report has been sent
Always try to run the script manually in a powershell window to get exact details.
You can simulate an error by issuing a syntax error prior to running the script.
|The firewall is not opened for smtp traffic from the script server to the smtp server||Open the firewall|
|The mail server does not allow the script server to send emails through it||Configure the mail server to allow relay from the script server|
Could not initialize connection with supplied information
This is a tricky one. If the iControl snap-in tries to connect to the load balancers but fails for some reason this is the exception being thrown as a default error. And the reason could be other things than the credentials.
|Your credentials could actually be wrong. Don’t forget that the username is case sensitive!||Check your credentials in the configuration file|
|The script and the load balancer could not agree on a cipher.||Enable/disable TLSv2 in the configuration file|
|A firewall is dropping your requests||Open the firewall for port 443 from the server running your script|
|A proxy is dropping/denying your requests||Configure the proxy|
|The ip of the load balancer is wrong||Modify the IP in the configuration file|
I have scheduled the report but it does not write any files
There could be multiple reasons for this, and the best way to troubleshoot is to start a powershell window as the user running the report. Then execute the script manually.
|The user does not have write access to the configured log folder||Check the log folder permissions|
|The user running the script does not have Run as batchjob user permissions||Edit the group policy to allow the user access|
|Some pre-execution tests failed||Run the script as the intended user and fix the problem.|
|The script user does not have write permissions in the report directory||Add permissions to the report directory|
The report is looking strange
|The front-end files does not match the script version||Follow the upgrade guide above|
|A java script has failed to load||Copy the java script exception from the browser developer console and report it on the Bigip Report Devcentral page.|
The script reports missing JSON files
If running an older version of IIS (7.x or older) you might have to configure MIME types for JSON files.
For IIS7.x or older
Open “IIS Manager”, click on “Mime types” and then “Add”. Use the following settings:
MIME Type: application/json
If this does not solve the issue, try creating a file called web.config in the wwwroot folder with the following content:
<system.webServer> <staticContent> <mimeMap fileExtension=".json" mimeType="application/json" /> </staticContent> </system.webServer>
Other web servers
Script has had issues when creating the files due to lack of permissions or network issues. Double check your script execution logs, web folder content and try again?
The member status polling says it’s disabled
One or more status endpoints has been marked as failed
|The configured endpoint is using HTTP while your BigIPReport is using HTTPS. This would trigger security features in modern browsers and prevent any AJAX request.||Configure the endpoint to use HTTPs, or less optimal, configure the report to use HTTP.|
|The endpoint is not using a certificate trusted by your browser.||Sign a certificate trusted by your browser.|
|The DNS record is not resolvable by your clients.||Create a record that is resolvable by your clients.|
|You have create the member status endpoint on one load balancer but forgot to synchronize the configuration.||Synchronize the configuration|