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')¶ 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.
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 oflogin_provider_name
.-
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
¶
-
exception
icontrol.exceptions.
InvalidInstanceNameOrFolder
¶
-
exception
icontrol.exceptions.
InvalidPrefixCollection
¶
-
exception
icontrol.exceptions.
InvalidScheme
¶
-
exception
icontrol.exceptions.
InvalidSuffixCollection
¶
-
exception
icontrol.exceptions.
InvalidURIComponentPart
¶
-
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:
- URI Sanitization uri’s produced by this module are checked to ensure compliance with the BigIP-REST server interface
- Session Construction – the
iControlRESTSession
wraps arequests.Session
object. - Logging – pre- and post- request state is logged.
- Exception generation – Errors in URL construction generate
BigIPInvalidURL
subclasses; unexpected HTTP status codes raiseiControlUnexpectedHTTPError
.
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.
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:
- pre-logs the details of the request
- submits the request
- logs the response, included expected status codes
- 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 specifiction 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'
-
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.-
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
andpartition
as part of**kwargs
they will be added to theuri
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 therequests.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
andpartition
as part of**kwargs
they will be added to theuri
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 therequests.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
andpartition
as part of**kwargs
they will be added to theuri
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 therequests.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
andpartition
as part of**kwargs
they will be added to theuri
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 therequests.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
andpartition
as part of**kwargs
they will be added to theuri
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 therequests.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 appened to the uri
- **kwargs –
The
reqeusts.Session.put()
optional params
-