Skip to content

Commit 6e9c1a8

Browse files
f5-rahmf5-rahm
committed
Expanded documentation for the SDK User Guide
1 parent a9ed477 commit 6e9c1a8

12 files changed

Lines changed: 233 additions & 1 deletion

‎docs/conf.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@
8383
8484
.. |Resource Section| replace:: :ref:`Resource <resource_section>`
8585
86+
.. |Unnamed Resource Section| replace:: :ref:`Unnamed Resource <unnamed_resource_section>`
87+
8688
.. |Subcollection Section| replace:: :ref:`Subcollection <subcollection_section>`
8789
8890
.. |Subcollection Resource Section| replace:: :ref:`Subcollection Resource <subcollection_resource_section>`
@@ -93,12 +95,16 @@
9395
9496
.. |Resource| replace:: :class:`~f5.bigip.resource.Resource`
9597
98+
.. |Unnamed Resource| replace:: :class:`~f5.bigip.resource.UnnamedResource`
99+
96100
.. |Subcollection| replace:: :class:`~f5.bigip.resource.Subcollection`
97101
98102
.. |Subcollection Resource| replace:: :class:`~f5.bigip.resource.SubcollectionResource`
99103
100104
.. |create| replace:: :meth:`~f5.bigip.resource.Resource.create`
101105
106+
.. |exec_cmd| replace:: :meth:`~f5.bigip.mixins.CommandExecutionMixin.exec_cmd`
107+
102108
.. |update| replace:: :meth:`~f5.bigip.resource.Resource.update`
103109
104110
.. |modify| replace:: :meth:`~f5.bigip.resource.ResourceBase.modify`

‎docs/userguide/basics.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ A set of basic REST endpoints can be derived from the object's URI and ``kind``
5353
- |Organizing Collection Section|
5454
- |Collection Section|
5555
- |Resource Section|
56+
- |Unnamed Resource Section|
5657
- |Subcollection Section|
5758
- |Subcollection Resource Section|
5859

@@ -79,6 +80,8 @@ Almost all iControl® REST API entries contain a parameter named ``kind``. This
7980
+---------------------+--------------------------+-------------------------------------------------+
8081
| ``state`` | |Resource| | |create|, |update|, |refresh|, |delete|, |
8182
| | | |load|, |exists| |
83+
+---------------------+--------------------------+-------------------------------------------------|
84+
| ``state`` | |Unnamed Resource| | |update|, |refresh|, |load|, |exists|
8285
+---------------------+--------------------------+-------------------------------------------------+
8386
| ``stats`` | |Resource| | |refresh|, |load|, |exists| |
8487
+---------------------+--------------------------+-------------------------------------------------+
@@ -94,6 +97,8 @@ Methods
9497
+===========+===============+===================================================================+
9598
| |create| | POST | | creates a new resource on the device with its own URI |
9699
+-----------+---------------+-------------------------------------------------------------------+
100+
| |exec_cmd|| POST | | executes commands on applicable unnamed resources |
101+
+-----------+---------------+-------------------------------------------------------------------+
97102
| |update| | PUT | | submits a new configuration to the device resource; sets the |
98103
| | | | Resource attributes to the state reported by the device |
99104
+-----------+---------------+-------------------------------------------------------------------+

‎docs/userguide/commands.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Commands
2+
========
3+
4+
The |exec_cmd| method is the way to run tmsh commands like run, load, and save via the SDK. It is almost always used in conjunction with an |unnamed resource|.
5+
6+
.. topic:: Example: Save the BIG-IP configuration
7+
8+
.. code-block:: python
9+
10+
>>> from f5.bigip import ManagementRoot
11+
>>> mgmt = ManagementRoot('192.168.1.1.', 'user', 'pass')
12+
>>> mgmt.tm.sys.config.exec_cmd('save')
13+
14+
.. topic:: Example: Merge a file into the BIG-IP configuration
15+
16+
.. code-block:: python
17+
18+
>>> from f5.bigip import ManagementRoot
19+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
20+
>>> options = {}
21+
>>> options['file'] = '/var/config/rest/downloads/myfile.txt'
22+
>>> options['merge'] = True
23+
>>> mgmt.tm.sys.config.exec_cmd('load', options=[options])
24+
25+
In the example above, you need to upload the file you wish to merge prior to executing this command. Also note that in version 12.1+, you will need to update the fileWhitelistPathPrefix attribute in global settings to merge files from this location.
26+
27+
.. topic:: Example: Generate a qkview file without core dumps or log files
28+
29+
.. code-block:: python
30+
31+
>>> from f5.bigip import ManagementRoot
32+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
33+
>>> mgmt.tm.util.qkview.exec_cmd('run', utilCmdArgs='-C --exclude all')
34+
35+
.. topic:: Example: Use the bash utility to print the host routing table
36+
37+
.. code-block:: python
38+
39+
>>> from f5.bigip import ManagementRoot
40+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
41+
>>> rt_table = mgmt.tm.util.bash.exec_cmd('run', utilCmdArgs='')rt = mgmt.tm.util.bash.exec_cmd('run', utilCmdArgs='-c "netstat -rn"')
42+
>>> print rt.commandResult
43+
Kernel IP routing table
44+
Destination Gateway Genmask Flags MSS Window irtt Iface
45+
0.0.0.0 10.10.10.1 0.0.0.0 UG 0 0 0 vlan10
46+
10.0.2.0 0.0.0.0 255.255.255.0 U 0 0 0 mgmt
47+
10.10.10.0 0.0.0.0 255.255.255.0 U 0 0 0 vlan10
48+
127.1.1.0 0.0.0.0 255.255.255.0 U 0 0 0 tmm
49+
127.7.0.0 127.1.1.253 255.255.0.0 UG 0 0 0 tmm
50+
127.20.0.0 0.0.0.0 255.255.0.0 U 0 0 0 tmm_bp
51+
192.168.102.0 0.0.0.0 255.255.255.0 U 0 0 0 vlan102
52+
192.168.103.0 0.0.0.0 255.255.255.0 U 0 0 0 vlan103

‎docs/userguide/connections.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
Connections
2+
===========
3+
4+
Connecting to BIG-IP with the SDK is done via :class:`f5.bigip.ManagementRoot`.
5+
6+
.. code-block:: python
7+
8+
>>> from f5.bigip import ManagementRoot
9+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
10+
11+
The required parameters are host, username, and password, respectively.
12+
13+
You can, however, supply one or more of the following kwargs (defaults listed):
14+
15+
.. table::
16+
17+
================ =====
18+
timeout 30
19+
port 443
20+
icontrol_version ''
21+
token False
22+
verify False
23+
auth_provider None
24+
================ =====
25+
26+
.. topic:: Example: Use token authentication on the nonstandard 4443 tcp port
27+
28+
.. code-block:: python
29+
30+
>>> from f5.bigip import ManagementRoot
31+
>>> mgmt = ManagementRoot('192.168.1.1.', 'user', 'pass', port=4443, token=True)
32+
33+
.. topic:: Example: Enable cert verification
34+
35+
.. code-block:: python
36+
37+
>>> from f5.bigip import ManagementRoot
38+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass', verify=True)
39+
40+

‎docs/userguide/endpoints.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ We'll start exploring the iControl® REST API's endpoints with an example detail
1919
OC |Organizing Collection Section|
2020
Coll |Collection Section|
2121
Resource |Resource Section|
22+
Unnamed Resrc |Unnamed Resource Section|
2223
SC |Subcollection Section|
2324
SubColl Resrc |Subcollection Resource Section|
2425
============= ==================================================
@@ -34,6 +35,7 @@ Endpoints
3435
endpoints/organizing_collection
3536
endpoints/collection
3637
endpoints/resource
38+
endpoints/unnamed_resource
3739
endpoints/subcollection
3840
endpoints/subcollection_resource
3941

‎docs/userguide/endpoints/unnamed_resource.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
.. _resource_section:
2+
3+
Unnamed Resource
4+
~~~~~~~~~~~~~~~~
5+
6+
An unnamed resource is a partially configurable object for which the CURDLE :ref:`methods <methods_section>` are supported with the exception of the create and delete methods.
7+
8+
* |refresh|
9+
* |update|
10+
* |load|
11+
* |exists|
12+
13+
In the F5® SDK, an unnamed resource is instantiated via its :ref:`collection <collection_section>`. Once loaded, unnamed resources contain attributes that map to the JSON fields returned by the BIG-IP®.
14+
15+
.. topic:: Example: Load a :class:`f5.bigip.tm.sys.dns` |Unnamed Resource| object.
16+
17+
.. code-block:: python
18+
19+
>>> from f5.bigip import ManagementRoot
20+
>>> mgmt = ManagementRoot('192.168.1.1', 'admin', 'admin')
21+
>>> dns = mgmt.tm.sys.dns.load()
22+
>>> pp(dns.raw)
23+
{
24+
u'description': u'configured-by-dhcp',
25+
u'kind': u'tm:sys:dns:dnsstate',
26+
u'nameServers': [u'10.10.10.1', u'8.8.8.8'],
27+
u'numberOfDots': 0,
28+
u'search': [u'localdomain', u'test.local'],
29+
u'selfLink': u'https://localhost/mgmt/tm/sys/dns?ver=13.1.0.1'
30+
}
31+
32+
The output of the :attr:`f5.bigip.tm.sys.dns` (above) shows all of the available attributes.
33+
34+
Once you have loaded the object, you can access the attributes as shown below.
35+
36+
.. code-block:: python
37+
38+
dns.nameServers = ['2.2.2.2', '3.3.3.3']
39+
dns.update()
40+
41+

‎docs/userguide/file_transfers.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
File Transfers
2+
==============
3+
4+
The file transfer worker allows a client to transfer files through a series of GET operations for downloads and POST operations for uploads. The Content-Range header is used for both as a means to chunk the content. For reference, the workers are:
5+
6+
.. table::
7+
8+
+---------------------+--------+------------------------------------------------+----------------------------+
9+
| Description | Method | URI | File Location |
10+
+---------------------+--------+------------------------------------------------+----------------------------+
11+
| Upload Image | POST | /mgmt/cm/autodeploy/sotfware-image-uploads/* | /shared/images |
12+
+---------------------+--------+------------------------------------------------+----------------------------+
13+
| Upload File | POST | /mgmt/shared/file-transfer/uploads/* | /var/config/rest/downloads |
14+
+---------------------+--------+------------------------------------------------+----------------------------+
15+
| Upload UCS | POST | /mgmt/shared/file-transfer/ucs-uploads/* | /var/local/ucs |
16+
+---------------------+--------+------------------------------------------------+----------------------------+
17+
| Download UCS | GET | /mgmt/shared/file-transfer/ucs-downloads/* | /var/local/ucs |
18+
+---------------------+--------+------------------------------------------------+----------------------------+
19+
| Download Image/File | GET | /mgmt/cm/autodeploy/sotfware-image-downloads/* | /shared/images |
20+
+---------------------+--------+------------------------------------------------+----------------------------+
21+
22+
Where the "*" in the URL is the base file name.
23+
24+
.. topic:: Example: Upload a text file
25+
26+
.. code-block:: python
27+
28+
>>> from f5.bigip import ManagementRoot
29+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
30+
>>> mgmt.shared.file_transfer.uploads.upload_file('/Users/citizenelah/Downloads/config.txt')
31+
32+
.. topic:: Example: Download a UCS file
33+
34+
.. code-block:: python
35+
36+
>>> from f5.bigip import ManagementRoot
37+
>>> mgmt = ManagementRoot('192.168.1.1', 'user', 'pass')
38+
>>> mgmt.shared.file_transfer.ucs_downloads.download_file('config.ucs', '/Users/citizenelah/Downloads/config.ucs')
39+

‎docs/userguide/index.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@ using the configuration utility (the GUI). More useful still would be if you are
99
.. toctree::
1010

1111
basics
12+
connections
1213
endpoints
1314
object_path
15+
commands
16+
file_transfers
17+
transactions
1418
ltm_pools_members_code_example
1519
odata_queries
1620
rest_proxies

‎docs/userguide/ltm_pools_members_code_example.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ Coding Example
8888
8989
# Make sure it is gone
9090
91-
if mgmt_rt.tm.ltm.pools.pool.exists(partition='Common', name='mypool'):
91+
if mgmt.tm.ltm.pools.pool.exists(partition='Common', name='mypool'):
9292
raise Exception("Object should have been deleted")
9393
9494

‎docs/userguide/object_path.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Because the REST API endpoints have a hierarchical structure, you need to load/c
2121
OC :ref:`Organizing Collection <oc_section>`
2222
Coll :ref:`Collection <coll_section>`
2323
Resource :ref:`Resource <res_section>`
24+
Unnamed Resrc :ref:`Unnamed Resource <unnamed_resource_section>`
2425
SC :ref:`Subcollection <subcoll_section>`
2526
SubColl Resrc :ref:`Subcollection Resource <subcollres_section>`
2627
============= ==================================================
@@ -156,6 +157,23 @@ In the example above, we instantiated the class :class:`f5.bigip.tm.ltm.pool.Poo
156157
}
157158
158159
160+
.. _unnamed_resource_section:
161+
162+
|Unnamed Resource Section|
163+
--------------------------
164+
165+
In the SDK, we refer to a single instance of a configuratino object with no name field as an :dfn:`unnamed resource`. Unnamed resources cannot be created or deleted, but they can be loaded, updated, etc.
166+
167+
.. topic:: Example: Load the ``httpd`` unnamed resource settings
168+
169+
.. code-block:: python
170+
171+
>>> httpd = b.tm.sys.httpd.load()
172+
>>> httpd.maxClients = 5
173+
>>> httpd.update()
174+
175+
In the example above, we instantiated the class :class:`f5.bigip.tm.sys.httpd` and used it to update the max clients to 5.
176+
159177
.. _subcoll_section:
160178

161179
|Subcollection Section|

0 commit comments

Comments
 (0)