icontrol package

Submodules

icontrol.authtoken module

A requests-compatible system for BIG-IP token-based authentication.

BIG-IP only allows users with the Administrator role to authenticate to iControl using HTTP Basic auth. Non-Administrator users can use the token-based authentication scheme described at:

Use this module with requests to automatically get a new token, and attach requests.Session object, so that it is used to authenticate future requests.

Instead of using this module directly, it is easiest to enable it by passing a token=True argument when creating the iControlRESTSession:

>>> iCRS = iControlRESTSession('bob', 'secret', token=True)
class icontrol.authtoken.iControlRESTTokenAuth(username, password, login_provider_name='tmos', verify=False, auth_provider=None)

Bases: requests.auth.AuthBase

Acquire and renew BigIP iControl REST authentication tokens.

Parameters:
  • username (str) – The username on BigIP
  • password (str) – The password for username on BigIP
  • login_provider_name (str) – The name of the login provider that BigIP should consult when creating the token.
  • verify (str) – The path to a CA bundle containing the CA certificate for SSL validation

If username is configured locally on the BigIP, login_provider_name should be "tmos" (default). Otherwise (for example, username is configured on LDAP that BigIP consults), consult BigIP documentation or your system administrator for the value of login_provider_name.

get_auth_providers(netloc)

BIG-IQ specific query for auth providers

BIG-IP doesn’t really need this because BIG-IP’s multiple auth providers seem to handle fallthrough just fine. BIG-IQ on the other hand, needs to have its auth provider specified if you’re using one of the non-default ones.

Parameters:netloc –
Returns:
get_new_token(netloc)

Get a new token from BIG-IP and store it internally.

Throws relevant exception if it fails to get a new token.

This method will be called automatically if a request is attempted but there is no authentication token, or the authentication token is expired. It is usually not necessary for users to call it, but it can be called if it is known that the authentication token has been invalidated by other means.

icontrol.exceptions module

Exceptions that can be emitted by the icontrol package.

exception icontrol.exceptions.BigIPInvalidURL

Bases: exceptions.Exception

exception icontrol.exceptions.InvalidBigIP_ICRURI

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.InvalidInstanceNameOrFolder

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.InvalidPrefixCollection

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.InvalidScheme

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.InvalidSuffixCollection

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.InvalidURIComponentPart

Bases: icontrol.exceptions.BigIPInvalidURL

exception icontrol.exceptions.iControlUnexpectedHTTPError(*args, **kwargs)

Bases: requests.exceptions.HTTPError

icontrol.session module

A BigIP-RESTServer URI handler. REST-APIs use it on the requests library.

Use this module to make calls to a BigIP-REST server. It will handle:

  1. URI Sanitization uri’s produced by this module are checked to ensure compliance with the BigIP-REST server interface
  2. Session Construction – the iControlRESTSession wraps a requests.Session object.
  3. Logging – pre- and post- request state is logged.
  4. Exception generation – Errors in URL construction generate BigIPInvalidURL subclasses; unexpected HTTP status codes raise iControlUnexpectedHTTPError.

The core functionality of the module is implemented via the iControlRESTSession class. Calls to its’ HTTP-methods are checked, pre-logged, submitted, and post-logged.

There are 2 modes of operation “full_uri”, and “uri_as_parts”, toggled by the uri_as_parts boolean keyword param that can be passed to methods. It defaults to False. Use uri_as_parts when you want to leverage the full functionality of this library, and have it construct your uri for you. Example Use in uri_as_parts mode:

>>> iCRS = iControlRESTSession('jrandomhacker', 'insecure')
>>> iCRS.get('https://192.168.1.1/mgmt/tm/ltm/nat/', partition='Common', name='VALIDNAME', uri_as_parts=True)

In full_uri mode:

>>> iCRS.get('https://192.168.1.1/mgmt/tm/ltm/nat/~Common~VALIDNAME')

NOTE: If used via the f5-common-python library the typical mode is “full_uri” since that library binds uris to Python objects.

Available functions:

  • iCRS.{get, post, put, delete, patch}: requests.Session.VERB wrappers
  • decorate_HTTP_verb_method: this function preps, logs, and handles requests

against the BigIP REST Server, by pre- and post- processing the above methods.

icontrol.session.debug_prepared_request(request)
icontrol.session.decorate_HTTP_verb_method(method)

Prepare and Post-Process HTTP VERB method for BigIP-RESTServer request.

This function decorates all of the HTTP VERB methods in the iControlRESTSession class. It provides the core logic for this module. If necessary it validates and assembles a uri from parts with a call to generate_bigip_uri.

Then it:

  1. pre-logs the details of the request
  2. submits the request
  3. logs the response, included expected status codes
  4. raises exceptions for unexpected status codes. (i.e. not doc’d as BigIP RESTServer codes.)
icontrol.session.generate_bigip_uri(base_uri, partition, name, sub_path, suffix, **kwargs)

(str, str, str) –> str

This function checks the supplied elements to see if each conforms to the specification for the appropriate part of the URI. These validations are conducted by the helper function _validate_uri_parts. After validation the parts are assembled into a valid BigIP REST URI string which is then submitted with appropriate metadata.

>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/',     'CUSTOMER1', 'nat52', params={'a':1})
'https://0.0.0.0/mgmt/tm/ltm/nat/~CUSTOMER1~nat52'
>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/',     'CUSTOMER1', 'nat52', params={'a':1}, suffix='/wacky')
'https://0.0.0.0/mgmt/tm/ltm/nat/~CUSTOMER1~nat52/wacky'
>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/', '', '',     params={'a':1}, suffix='/thwocky')
'https://0.0.0.0/mgmt/tm/ltm/nat/thwocky'
::Warning: There are cases where ‘/’ and ‘~’ characters are valid in the
object name. This is indicated by passing ‘transform_name’ boolean as True, by default this is set to False.
icontrol.session.get_request_args(kwargs)
icontrol.session.get_send_args(kwargs)
class icontrol.session.iControlRESTSession(username, password, **kwargs)

Bases: object

Represents a requests.Session that communicates with a BigIP.

Instantiate one of these when you want to communicate with a BigIP-REST Server, it will handle BigIP-specific details of the uri’s. In the f5-common-python library, an iControlRESTSession is instantiated during BigIP instantiation and associated with it as an attribute of the BigIP (a compositional vs. inheritable association).

Objects instantiated from this class provide an HTTP 1.1 style session, via the requests.Session object, and HTTP-methods that are specialized to the BigIP-RESTServer interface.

Pass token=True in **kwargs to use token-based authentication. This is required for users that do not have the Administrator role on BigIP.

append_user_agent(user_agent)

Append text to the User-Agent header for the request.

Use this method to update the User-Agent header by appending the given string to the session’s User-Agent header separated by a space.

Parameters:user_agent (str) – A string to append to the User-Agent header
debug
debug_output
delete(RIC_base_uri, **kwargs)

Sends a HTTP DELETE command to the BIGIP REST Server.

Use this method to send a DELETE command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.delete()

Parameters:
  • uri (str) – A HTTP URI
  • name (str) – The object name that will be appended to the uri
  • partition (str) – The partition name that will be appened to the uri
  • **kwargs – The reqeusts.Session.delete() optional params
get(RIC_base_uri, **kwargs)

Sends a HTTP GET command to the BIGIP REST Server.

Use this method to send a GET command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.get()

Parameters:
  • uri (str) – A HTTP URI
  • name (str) – The object name that will be appended to the uri
  • partition (str) – The partition name that will be appened to the uri
  • **kwargs – The reqeusts.Session.get() optional params
patch(RIC_base_uri, **kwargs)

Sends a HTTP PATCH command to the BIGIP REST Server.

Use this method to send a PATCH command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.patch()

Parameters:
  • uri (str) – A HTTP URI
  • data (str) – The data to be sent with the PATCH command
  • name (str) – The object name that will be appended to the uri
  • partition (str) – The partition name that will be appened to the uri
  • **kwargs – The reqeusts.Session.patch() optional params
post(RIC_base_uri, **kwargs)

Sends a HTTP POST command to the BIGIP REST Server.

Use this method to send a POST command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.post()

Parameters:
  • uri (str) – A HTTP URI
  • data (str) – The data to be sent with the POST command
  • json (dict) – The JSON data to be sent with the POST command
  • name (str) – The object name that will be appended to the uri
  • partition (str) – The partition name that will be appened to the uri
  • **kwargs – The reqeusts.Session.post() optional params
put(RIC_base_uri, **kwargs)

Sends a HTTP PUT command to the BIGIP REST Server.

Use this method to send a PUT command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.put()

Parameters:
  • uri (str) – A HTTP URI
  • data (str) – The data to be sent with the PUT command
  • json (dict) – The JSON data to be sent with the PUT command
  • name (str) – The object name that will be appended to the uri
  • partition (str) – The partition name that will be appended to the uri
  • **kwargs –

    The reqeusts.Session.put() optional params
token

Convenience wrapper around returning the current token

Returns:
result (str): The current token being sent in session headers.

Module contents