System::Session

Introduced : BIG-IP_v11.0.0
The Session interface allows you to manage iControl sessions. An iControl session is a set of attributes which can persist across iControl requests for a specific user. These values currently include the active folder and the transaction. By default, a user session is identified by the user&aposs name. However, finer grained control over user session can be gained via an explicit session identifier, which can be requested by a user and included in any subsequent requests which are intended to be included in that session. This interface does not support transactions.

Methods

Method Description Introduced
get_active_folder Gets the active folder. BIG-IP_v11.0.0
get_dtd_processing_state Gets the state for all future iControl SOAP requests whether or not to process SOAP requests received with Document Type Definitions (DTDs). BIG-IP_v12.0.0
get_force_sessions_state Gets the state for all future iControl SOAP requests that indicates whether or not to force non-default iControl SOAP sessions to be established before SOAP requests are processed. BIG-IP_v12.0.0
get_maximum_sessions Gets the maximum number of user sessions. BIG-IP_v11.0.0
get_recursive_query_state Gets the state to recursively query the contents of the active folder. BIG-IP_v11.0.0
get_returned_path Gets the type of path information returned with object names. BIG-IP_v11.0.0
get_session_identifier Gets a new session identifier. This identifier is a value which uniquely identifies a user session. Once retrieved by a client, it may be included in any subsequent requests to notify the iControl portal that a specific request should be executed in the context of the session associated with that identifier. Use of this identifier is completely optional. If it is not included in an iControl request, the session key defaults to the user name. Note that this is even true if you have retrieved a unique session identifier. It is also possible to have more than one such unique session identifier active at the same time. However, it is important to understand that each session key, whether the unique identifier or the default user name represent distinct sessions. Changing a session variable in one session does not effect the variable in any other session. On the other hand, if different clients have the same session key and one changes a session variable, the others will see it. The important distinction is not the client being run and not the user running it, but the session key for each request. When used, this session identifier must be passed to the iControl portal via either an HTTP header or a SOAP header element. There is no preference for which transport is used, as the portal will pick up either. The client is free to use whichever is easier to work with in the client&aposs SOAP package. If for some reason, conflicting values are set in the HTTP header and SOAP header element, the SOAP header element value will take precedence. The HTTP header holding the session identifier is named “X-IControl-Session”. If used, its value must be set to the text representation of the session identifier. Thus in the HTTP request, the header would look like, e.g., X-iControl-Session: 14. Most SOAP packages include a straightforward way to add an HTTP header to the HTTP request, so reference your documentation. The SOAP header element is named “session”. If used, its value must be a SOAP integer element holding the session identifier. If this client is intended to work with older versions of iControl, be aware that the mustUnderstand SOAP header element attribute must be set to 0. Reference your SOAP package documentation for details for adding a SOAP header to a request. BIG-IP_v11.0.0
get_session_timeout Gets the session timeout. BIG-IP_v11.0.0
get_transaction_timeout Gets the transaction timeout. BIG-IP_v11.0.0
get_version Gets the version information for this interface. BIG-IP_v11.0.0
rollback_transaction Roll back the transaction. When called, all of the requests submitted since start_transaction was called are un-done. The configuration will remain unchanged. If no transaction is open, an error is signaled. If no requests have been queued in the transaction, nothing is done and no error is signaled. BIG-IP_v11.0.0
set_active_folder Sets the active folder. Most configuration objects reside in folders (see the Management::Folder interface), but continually specifying the full path to name an object can be wearing. For ease, an “active folder” can be specified. When creating or accessing objects and a full object path is not specified (i.e., the object path does not begin with a slash (/)), the active folder is prepended to the object name. Thus if the name for an object to be created is specified as “repository-a” and the active folder is /george/server, the full path for the created object is /george/server/repository-a. Note that relative paths are also allowed in the object identifier, so that if the active folder is /george/server and the given object identifier is virtual/repository-a, then the full object path is /george/server/virtual/repository-a. The active folder may be the root folder (/), but that is only usable when querying. If for some reason, neither the currently active folder nor the newly requested active folder exist, the currently active folder will be set to the user&aposs default folder. BIG-IP_v11.0.0
set_dtd_processing_state Sets the state for all future iControl SOAP requests whether or not to process SOAP requests received with Document Type Definitions (DTDs). This is set to STATE_DISABLED by default. Only administrators can set this value. This was introduced in BIG-IP_v12.0.0 to conform to SOAP specifications that disallow DTDs. SOAP requests that use DTDs will return a “parsing aborted” error and not parse the request. This will also set the “iControl.DTDParsing” DB variable to “enable” or “disable” respectively. If modifying the DB variable directly, restart httpd to make the changes go into effect. BIG-IP_v12.0.0
set_force_sessions_state Sets the state for all future iControl SOAP requests whether or not to force non-default iControl SOAP sessions to be established before SOAP requests are processed. This will disable the use of the default session identifier (the username) and force the use of a system provided identifier received from a call to get_session_identifier. This is set to STATE_DISABLED by default. Only administrators can set this value. This was introduced in BIG-IP_v12.0.0 to enable enhanced protections against CSRF attacks. Any attempts to run a command without a session will return a “Could not find the iControl session for <user> error”. Use caution before turning this feature on as it may break existing SOAP clients, many of which may not establish sessions before making requests. This will also set the “iControl.ForceSessions” DB variable to “enable” or “disable” respectively. If modifying the DB variable directly, restart httpd to make the changes go into effect. In order tune iControl SOAP sessions to your needs, see: get_session_identifier: which will return the session ID for a given session. set_session_timeout: which will set the amount of time a session will be in effect. set_maximum_sessions: which will set the maximum number of concurrent user sessions at any given time. BIG-IP_v12.0.0
set_maximum_sessions Sets the maximum number of concurrent user sessions. A system could be attacked by creating an inordinate number of iControl user sessions, eventually bringing the iControl portal (or the system itself) to a crawl. If iControl is already supporting this number of user sessions, subsequent attempts to create a new user sessions are rejected with an error. If this limit is set to zero, the number of user sessions is unlimited. Only administrators can set this value. BIG-IP_v11.0.0
set_recursive_query_state Sets the state to recursively query the contents of the active folder. As of 11.4.0, this setting applies also to delete_all_x operations. If not set, any query will return objects in the active folder only. If set, any query will return objects in the active folder, plus objects in any sub-folders under that active folder no matter how deeply nested. Note, regarding other recursive operations: when folders were introduced, the behavior of delete_all_x methods, such as LocalLB::Pool::delete_all_pools, was unspecified with respect to folders. (It was unspecified in which folders to apply the operation). As of 11.4.0, the behavior of delete_all_x methods is clarified: delete_all_pools and similar methods operate on objects in the active folder, and only there. If you would like to delete all pools in the active folder and folders below it, enable recursive query using this method. If you would like to delete all pools in a top-level folder (partition) and below, set the active folder to the desired folder and turn on recursive query. BIG-IP_v11.0.0
set_returned_path Sets the type of path information returned with object names. BIG-IP_v11.0.0
set_session_timeout Sets the session timeout. The session timeout is the amount of time for which a user session has not processed a request before it is marked as eligible for deletion. For a user session without a session identifier, re-using an expired session will trigger the creation of a new user session with the default session values. For a user session with a session identifier, re-using an expired session will result in an error. The session timeout is a global value, so it applies equally to all user sessions. A zero timeout means that only one request can be handled per user session, effectively turning off sessions. Only administrators can set this value. BIG-IP_v11.0.0
set_transaction_timeout Sets the transaction timeout, the amount of time that an open transaction can be inactive before it is marked for deletion. This is effectively a lower limit, an inactive open transaction may be open longer than that, though is effectively unusable after that point. Expiring transactions are logged. The transaction timeout is unique for each session. BIG-IP_v11.0.0
start_transaction Start an iControl transaction, which combines the effects of a number of iControl methods into a single atomic transaction. Once an iControl client calls start_transaction, the handling of subsequent iControl requests changes until the client submits or rolls back the transaction, i.e. while the transaction is open. It is important to understand the characteristics of iControl requests made in this mode. iControl requests which modify the configuration are submitted for subsequent execution. The requests do not affect the configuration at the time they are made. iControl requests which query the configuration are executed immediately and do not see the effects of a pending transaction. iControl modify requests made outside a session with an open transaction affect the configuration immediately and do not see effects of any pending transactions. A transaction remains open until submit_transaction or rollback_transaction is called or until it is idle for too long. Reporting errors also differ while a transaction is open. Some classes of errors (such as invalid arguments) are returned by the method itself. The context for these errors should thus be as clear as without a transaction. However, most errors will be returned by the submit_transaction call. Note that this can make it difficult to determine which iControl method caused the error. If an error occurs at any time during a transaction, the transaction remains open, but is marked as errant. When submit_transaction is subsequently called, the transaction will actually be deleted, as if rollback_transaction has been called. Note that even if an error occurs, submit_transaction or rollback_transaction still must be called to properly close it. Not all interfaces and methods support transactions. These methods are processed per normal, i.e., executed immediately and not as part of the transaction. The documentation includes a note for those interfaces and methods which do not. The contents of pending transaction cannot be queried or modified. Only one transaction can be open at the same time in a single user session. BIG-IP_v11.0.0
submit_transaction Submit the transaction for execution. When called, all of the requests submitted since start_transaction was called are committed to the configuration as a single atomic transaction. If all of the requests succeed, the configuration is updated. If any of the requests fail, the transaction as a whole fails and the configuration remains unchanged. If an error is signaled, it may be from any of the submitted requests. Nothing outside the returned error message can indicate which request triggered the error. If no requests have been queued in the transaction, nothing is done and no error is signaled. If no transaction is open, an error is signaled. BIG-IP_v11.0.0

Structures

Structure Description

Enumerations

Enumeration Description
ReturnedPath Specification for the path information included with object names. There are no methods to retrieve the folder that hold a specific object. To determine that, when querying object names, the full folder path can be prepended to the name, e.g., /george/server/virtual/repository-a. However, that is not always wanted. The returned object path could include the full path, a path relative to the active folder, or even just the bare path-less object name. This enumeration controls that option.

Exceptions

Exception Description

Constants

Constant Type Value Description

Aliases

Alias Type Description

See Also

Warning

The links to the sample code below are remnants of the old DevCentral wiki and will result in a 404 error. For best results, please copy the link text and search the codeshare directly on DevCentral.

Sample Code


The BIG-IP API Reference documentation contains community-contributed content. F5 does not monitor or control community code contributions. We make no guarantees or warranties regarding the available code, and it may contain errors, defects, bugs, inaccuracies, or security vulnerabilities. Your access to and use of any code available in the BIG-IP API reference guides is solely at your own risk.