{"id":8983,"library":"f5-icontrol-rest","title":"F5 BIG-IP iControl REST API client","description":"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.","status":"abandoned","version":"1.3.13","language":"en","source_language":"en","source_url":"https://github.com/F5Networks/f5-icontrol-rest-python","tags":["f5","big-ip","icontrol","rest","api","network","automation","big-iq"],"install":[{"cmd":"pip install f5-icontrol-rest","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP session management and underlying REST communication.","package":"requests","optional":false}],"imports":[{"note":"The primary interaction class is nested within the 'icontrol.session' submodule, not directly under the top-level package.","wrong":"from f5_icontrol_rest import iControlRESTSession","symbol":"iControlRESTSession","correct":"from icontrol.session import iControlRESTSession"}],"quickstart":{"code":"import os\nfrom icontrol.session import iControlRESTSession\n\nBIGIP_HOST = os.environ.get('F5_BIGIP_HOST', 'your_bigip_ip_or_hostname')\nBIGIP_USER = os.environ.get('F5_BIGIP_USER', 'admin')\nBIGIP_PASS = os.environ.get('F5_BIGIP_PASSWORD', 'password')\n\n\ntry:\n    # Initialize the session\n    icr_session = iControlRESTSession(BIGIP_USER, BIGIP_PASS, address=BIGIP_HOST)\n\n    # Example: Get a list of all LTM NAT objects in Common partition\n    # Note: For versions < 1.3.13, 'proxies' kwarg only works on method calls, not instantiation.\n    response = icr_session.get(\n        f'https://{BIGIP_HOST}/mgmt/tm/ltm/nat',\n        name='*', \n        partition='Common',\n        uri_as_parts=True,\n        verify=False # Use with caution in production without proper certs\n    )\n\n    print(f\"Successfully connected to {BIGIP_HOST}.\")\n    print(\"LTM NAT objects:\")\n    for item in response.json().get('items', []):\n        print(f\"  - Name: {item.get('name')}, Partition: {item.get('partition')}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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]"},"warnings":[{"fix":"Evaluate migration to actively developed F5 SDKs (e.g., `f5-sdk` or `bigrest`) for long-term project stability and security. [5, 7, 19]","message":"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.","severity":"breaking","affected_versions":"<=1.3.13"},{"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]","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"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]","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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]","severity":"gotcha","affected_versions":"<1.3.13"},{"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.","message":"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]","severity":"gotcha","affected_versions":">=1.3.9"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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]","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]","error":"HTTP 500 - Internal Server Error or AsyncContext timeout"},{"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]","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]","error":"HTTP 400 Bad Request or HTTP 401 Unauthorized"},{"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]","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]","error":"REST system unavailable due to disk corruption!"},{"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)`).","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]","error":"TypeError: __init__() got an unexpected keyword argument 'proxies'"}]}