F5 BIG-IP iControl REST API client

1.3.13 · abandoned · verified Thu Apr 16

The `f5-icontrol-rest` Python library simplifies interaction with the F5 BIG-IP iControl REST API. It manages HTTP sessions (leveraging `requests.Session`), handles URI validation, and provides integrated logging. This generic library is used by other F5 SDKs and projects for programmatic communication with BIG-IP and BIG-IQ devices via the REST API. [1, 4, 5, 7] As of version 1.3.13, the project's GitHub repository is archived and no longer maintained.

Common errors

```
HTTP 500 - Internal Server Error or AsyncContext timeout
```
cause Attempting to fetch a very large number of objects from the F5 BIG-IP iControl REST API without pagination. This can exhaust resources on the BIG-IP device. [11]

fix Refactor your API calls to use OData `$skip` and `$top` query parameters for pagination, retrieving objects in smaller chunks. Example: `url/path?$skip=0&$top=100`. [5]
```
HTTP 400 Bad Request or HTTP 401 Unauthorized
```
cause API authentication failures or issues with an existing session token on the BIG-IP device, possibly due to token exhaustion, insufficient memory for REST services, or corrupted storage. [8, 12]

fix Verify credentials. If the issue persists, consider deleting all authentication tokens on the BIG-IP (`restcurl -X DELETE /shared/authz/tokens`), increasing allocated memory for management/REST daemons, or restarting the `restjavad` service (requires maintenance window). [8, 12]
```
REST system unavailable due to disk corruption!
```
cause This error originates from the BIG-IP device itself, indicating corruption in the local filesystem storage used by the `restjavad` process, which handles iControl REST requests. [10]

fix This requires troubleshooting on the BIG-IP appliance. Check `/var/log/restjavad.*.log` for details. A common fix involves checking for `/var/config/rest/storage/LOST-STORAGE.txt` and potentially restarting services, though sometimes a device-level recovery is needed. [10]
```
TypeError: __init__() got an unexpected keyword argument 'proxies'
```
cause Attempting to pass the `proxies` keyword argument during `iControlRESTSession` instantiation with an `f5-icontrol-rest` version older than 1.3.13, where global proxy configuration was not supported. [v1.3.13 release notes from prompt]

fix Upgrade `f5-icontrol-rest` to version 1.3.13 or newer (`pip install --upgrade f5-icontrol-rest`). Alternatively, for older versions, pass the `proxies` argument directly to each HTTP method call (e.g., `icr_session.get(..., proxies=my_proxies)`).

Warnings

breaking The `f5-icontrol-rest-python` GitHub repository is archived and explicitly marked as no longer maintained. This means there will be no further feature development, bug fixes, or security updates. Users are advised to consider migrating to actively maintained alternatives like `f5-sdk` or `BIGREST` for ongoing support and new features.
Fix: Evaluate migration to actively developed F5 SDKs (e.g., `f5-sdk` or `bigrest`) for long-term project stability and security. [5, 7, 19]
gotcha Fetching a large number of objects via iControl REST can result in 'HTTP 500 - Internal Server Error' or 'AsyncContext timeout' on the BIG-IP. This is due to resource limitations on the device. [1, 5, 11]
Fix: Implement pagination for requests returning large datasets using OData `$skip` and `$top` query parameters in your API calls (e.g., `?%24skip=0&%24top=100`). [5]
gotcha Intermittent 'HTTP 400 Bad Request' or '401 Unauthorized' errors can occur during API authentication or subsequent calls. Common causes include insufficient memory on the BIG-IP for management daemons, exhaustion of login tokens, or corrupted REST storage. [8, 12]
Fix: On the BIG-IP device, consider deleting all current tokens (`restcurl -X DELETE /shared/authz/tokens`), increasing management and REST daemon memory, or restarting the `restjavad` service during a maintenance window. [8, 12]
gotcha Prior to version 1.3.13, the `proxies` keyword argument was only functional when passed directly to individual HTTP method calls (e.g., `icr_session.get(..., proxies=...)`) and was ignored if provided during the `iControlRESTSession` instantiation. [v1.3.13 release notes from prompt]
Fix: For versions older than 1.3.13, explicitly pass the `proxies` dictionary to each method call. For 1.3.13 and newer, it can be passed during `iControlRESTSession` instantiation for global proxy configuration.
gotcha Version 1.3.9 removed a hard dependency on `urllib3`, instead relying on the version installed by the `requests` library. This change could cause conflicts or unexpected behavior if your environment had a specific `urllib3` version pinned independently of `requests`. [v1.3.9 release notes from prompt]
Fix: Ensure `urllib3` is compatible with the `requests` version installed. If encountering issues, try reinstalling `requests` to pull a compatible `urllib3` version, or explicitly align `urllib3` version with `requests`' requirements.

Install

pip install f5-icontrol-rest Install latest version

Imports

iControlRESTSession
wrong:
```
from f5_icontrol_rest import iControlRESTSession
```
correct:
```
from icontrol.session import iControlRESTSession
```
The primary interaction class is nested within the 'icontrol.session' submodule, not directly under the top-level package.

Quickstart

This quickstart demonstrates how to establish a session with an F5 BIG-IP device using `iControlRESTSession` and perform a basic GET request to retrieve LTM NAT objects. Ensure to replace placeholder credentials and host with actual values, preferably using environment variables for security. It disables SSL verification for simplicity, which should be avoided in production environments. [1, 5]

import os
from icontrol.session import iControlRESTSession

BIGIP_HOST = os.environ.get('F5_BIGIP_HOST', 'your_bigip_ip_or_hostname')
BIGIP_USER = os.environ.get('F5_BIGIP_USER', 'admin')
BIGIP_PASS = os.environ.get('F5_BIGIP_PASSWORD', 'password')


try:
    # Initialize the session
    icr_session = iControlRESTSession(BIGIP_USER, BIGIP_PASS, address=BIGIP_HOST)

    # Example: Get a list of all LTM NAT objects in Common partition
    # Note: For versions < 1.3.13, 'proxies' kwarg only works on method calls, not instantiation.
    response = icr_session.get(
        f'https://{BIGIP_HOST}/mgmt/tm/ltm/nat',
        name='*', 
        partition='Common',
        uri_as_parts=True,
        verify=False # Use with caution in production without proper certs
    )

    print(f"Successfully connected to {BIGIP_HOST}.")
    print("LTM NAT objects:")
    for item in response.json().get('items', []):
        print(f"  - Name: {item.get('name')}, Partition: {item.get('partition')}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →