From 0244d17a5e315c4f80844cb0c62c3f867edc49f2 Mon Sep 17 00:00:00 2001 From: chrissmith-mcafee Date: Wed, 15 Feb 2017 14:19:52 -0800 Subject: [PATCH] Documentation updates --- README | 6 ++ dist.py | 5 + doc/sdk/basiccorehelpexample.rst | 99 ++++++++++++++++++ doc/sdk/basicsystemfindexample.rst | 120 ++++++++++++++++++++++ doc/sdk/index.rst | 3 + doc/sdk/installation.rst | 35 +++++++ doc/sdk/overview.rst | 13 +++ doc/sdk/sampleconfig.rst | 20 ++++ dxlepoclient/__init__.py | 2 +- sample/basic/basic_core_help_example.py | 11 +- sample/basic/basic_system_find_example.py | 12 ++- 11 files changed, 318 insertions(+), 8 deletions(-) create mode 100644 doc/sdk/basiccorehelpexample.rst create mode 100644 doc/sdk/basicsystemfindexample.rst diff --git a/README b/README index b4c7ca0..ef6f0a2 100644 --- a/README +++ b/README @@ -11,6 +11,12 @@ client library provides a high level wrapper for invoking ePO remote commands vi The purpose of this library is to allow users to invoke ePO remote commands without having to focus on lower-level details such as ePO-specific DXL topics and message formats. +This client requires an ePO DXL service to be running and available on the DXL fabric. + +A Python-based implementation of an ePO DXL service is available here: + +* `McAfee ePolicy Orchestrator (ePO) DXL Python Service `_ + Documentation ------------- diff --git a/dist.py b/dist.py index 11bdc3a..136cdc7 100755 --- a/dist.py +++ b/dist.py @@ -49,6 +49,11 @@ print("\nCalling sphinx-build\n") subprocess.check_call(["sphinx-build", "-b", "html", DIST_DOCTMP_DIR, os.path.join(DIST_DIRECTORY, "doc")]) +# Delete .doctrees +remove_tree(os.path.join(os.path.join(DIST_DIRECTORY, "doc"), ".doctrees"), verbose=1) +# Delete .buildinfo +os.remove(os.path.join(os.path.join(DIST_DIRECTORY, "doc"), ".buildinfo")) + # Move README.html to root of dist directory print("\nMoving README.html\n") move_file(os.path.join(DIST_DOCTMP_DIR, "README.html"), DIST_DIRECTORY) diff --git a/doc/sdk/basiccorehelpexample.rst b/doc/sdk/basiccorehelpexample.rst new file mode 100644 index 0000000..dac9568 --- /dev/null +++ b/doc/sdk/basiccorehelpexample.rst @@ -0,0 +1,99 @@ +Basic Core Help Example +======================== + +This sample invokes and displays the results of the "core help" remote command via the ePO DXL service. +The "core help" command lists the remote commands that are exposed by a particular ePO server. + + +Prerequisites +************* +* The samples configuration step has been completed (see :doc:`sampleconfig`) +* The ePO DXL service is running and available on the fabric (see `ePO DXL Python Service `_) +* The client is authorized to invoke the ePO DXL Service (see `ePO DXL Service Client Authorization `_) + +Setup +***** + +Modify the example to include the `unique identifier` associated with the ePO to invoke the remote command on. + +For more information on the ePO unique identifier, refer to the following: + +* `Configuration File for ePO DXL Python Service (uniqueId property) `_ +* The :func:`dxlepoclient.client.EpoClient.lookup_epo_unique_identifiers` method which will return a ``set`` + containing the identifiers for all ePO servers that are currently connected to the fabric. + +For example: + + .. code-block:: python + + EPO_UNIQUE_ID = "epo1" + +If only one ePO server is connected to the DXL fabric this constant can be set to ``None`` (the client will +automatically determine the ePO's unique identifier). + +Running +******* + +To run this sample execute the ``sample/basic/basic_core_help_example.py`` script as follows: + + .. parsed-literal:: + + python sample/basic/basic_core_help_example.py + +The output should appear similar to the following: + + .. code-block:: python + + ComputerMgmt.createAgentDeploymentUrlCmd deployPath groupId [edit] [ahId] + [fallBackAhId] [urlName] [agentVersionNumber] [agentHotFix] - Create Agent + Deployment URL Command + ComputerMgmt.createCustomInstallPackageCmd deployPath [ahId] [fallBackAhId] - + Create Custom Install Package Command + ComputerMgmt.createDefaultAgentDeploymentUrlCmd tenantId - Create Default + Non-Editable Agent Deployment URL Command + ComputerMgmt.createTagGroup parentTagGroupId newTagGroupName - Create a new + subgroup under an existing tag group. + ComputerMgmt.deleteTag tagIds [forceDelete] - Delete one or more tags. + ComputerMgmt.deleteTagGroup tagGroupIds [deleteTags] - Delete one or more Tag + Groups. + ComputerMgmt.listAllTagGroups - List All Tag Groups in Tag Group Tree + ComputerMgmt.moveTagsToTagGroup tagIds tagGroupId - Move tags to an existing tag + group. + + ... + +Each remote command exposed by the particular ePO server is listed along with its associated parameters. + +Details +******* + +The majority of the sample code is shown below: + + .. code-block:: python + + # The ePO unique identifier + EPO_UNIQUE_ID = None + + # Create the client + with DxlClient(config) as client: + + # Connect to the fabric + client.connect() + + # Create the ePO client + epo_client = EpoClient(client, EPO_UNIQUE_ID) + + # Display the help + print epo_client.help() + + +Once a connection is established to the DXL fabric, a :class:`dxlepoclient.client.EpoClient` instance is created +which will be used to invoke remote commands on the ePO server. The `unique identifier` of the ePO server +to invoke remote commands on is specified as an argument to the client constructor. In this particular case, a +value of ``None`` is specified which triggers the client to automatically determine the ePO server's unique identifier. +This will not work if multiple ePO servers are connected to the fabric (an exception will be raised). + +Next, the results of invoking the :func:`dxlepoclient.client.EpoClient.help` method are displayed to the screen. + + + diff --git a/doc/sdk/basicsystemfindexample.rst b/doc/sdk/basicsystemfindexample.rst new file mode 100644 index 0000000..8c8e452 --- /dev/null +++ b/doc/sdk/basicsystemfindexample.rst @@ -0,0 +1,120 @@ +Basic System Find Example +========================= + +This sample invokes and displays the results of a "system find" remote command via the ePO DXL service. +The results of the find command are displayed in JSON format. + +Prerequisites +************* +* The samples configuration step has been completed (see :doc:`sampleconfig`) +* The ePO DXL service is running and available on the fabric (see `ePO DXL Python Service `_) +* The client is authorized to invoke the ePO DXL Service (see `ePO DXL Service Client Authorization `_) +* The user that is connecting to the ePO server (within the ePO DXL service) has permission to execute the + "system find" remote command + +Setup +***** + +Modify the example to include the `unique identifier` associated with the ePO to invoke the remote command on. + +For more information on the ePO unique identifier, refer to the following: + +* `Configuration File for ePO DXL Python Service (uniqueId property) `_ +* The :func:`dxlepoclient.client.EpoClient.lookup_epo_unique_identifiers` method which will return a ``set`` + containing the identifiers for all ePO servers that are currently connected to the fabric. + +For example: + + .. code-block:: python + + EPO_UNIQUE_ID = "epo1" + +If only one ePO server is connected to the DXL fabric this constant can be set to ``None`` (the client will +automatically determine the ePO's unique identifier). + +Modify the example to include the search text for the system find command. + +For example: + + .. code-block:: python + + SEARCH_TEXT = "broker" + + +Running +******* + +To run this sample execute the ``sample/basic/basic_system_find_example.py`` script as follows: + + .. parsed-literal:: + + python sample/basic/basic_system_find_example.py + +The output should appear similar to the following: + + .. code-block:: python + + [ + { + "EPOBranchNode.AutoID": 7, + "EPOComputerProperties.CPUSerialNum": "N/A", + "EPOComputerProperties.CPUSpeed": 2794, + "EPOComputerProperties.CPUType": "Intel(R) Core(TM) i7-4980HQ CPU @ 2.80GHz", + "EPOComputerProperties.ComputerName": "broker1", + "EPOComputerProperties.DefaultLangID": "0409", + "EPOComputerProperties.Description": null, + + ... + } + ] + +The properties for each system found will be displayed. + +Details +******* + +The majority of the sample code is shown below: + + .. code-block:: python + + # The ePO unique identifier + EPO_UNIQUE_ID = None + + # The search text + SEARCH_TEXT = "broker" + + # Create the client + with DxlClient(config) as client: + + # Connect to the fabric + client.connect() + + # Create the ePO client + epo_client = EpoClient(client, EPO_UNIQUE_ID) + + # Run the system find command + res = epo_client.run_command("system.find", + {"searchText": SEARCH_TEXT}, + output_format=OutputFormat.JSON) + + # Load find result into dictionary + res_dict = json.loads(res, encoding='utf-8') + + # Display the results + print json.dumps(res_dict, sort_keys=True, indent=4, separators=(',', ': ')) + + +Once a connection is established to the DXL fabric, a :class:`dxlepoclient.client.EpoClient` instance is created +which will be used to invoke remote commands on the ePO server. The `unique identifier` of the ePO server +to invoke remote commands on is specified as an argument to the client constructor. In this particular case, a +value of ``None`` is specified which triggers the client to automatically determine the ePO server's unique identifier. +This will not work if multiple ePO servers are connected to the fabric (an exception will be raised). + +Next, the :func:`dxlepoclient.client.EpoClient.run_command` method is invoked with an output +format of ``json`` and a ``searchText`` parameter that is specified with the value of ``broker``. + +Finally, the JSON response text is loaded into a Python dictionary (``dict``), formatted, +and displayed to the screen. + + + diff --git a/doc/sdk/index.rst b/doc/sdk/index.rst index fc69a42..605edbf 100755 --- a/doc/sdk/index.rst +++ b/doc/sdk/index.rst @@ -41,4 +41,7 @@ Basic .. toctree:: :maxdepth: 1 + basiccorehelpexample + basicsystemfindexample + diff --git a/doc/sdk/installation.rst b/doc/sdk/installation.rst index 52e15a6..4da7ccf 100755 --- a/doc/sdk/installation.rst +++ b/doc/sdk/installation.rst @@ -1,3 +1,38 @@ Library Installation ==================== +Prerequisites +************* + +* OpenDXL Python Client library installed + * ``_ +* The OpenDXL Python Client prerequisites must be satisfied + * ``_ +* McAfee ePolicy Orchestrator (ePO) service is running and available on DXL fabric + * ``_ (Python-based service implementation) +* OpenDXL Python Client has permission to invoke ePO remote commands + * ``_ + +Installation +************ + +Use ``pip`` to automatically install the module: + + .. parsed-literal:: + + pip install dxlepoclient-\ |version|\-py2.7-none-any.whl + +Or with: + + .. parsed-literal:: + + pip install dxlepoclient-\ |version|\.zip + +As an alternative (without PIP), unpack the dxlepoclient-\ |version|\.zip (located in the lib folder) and run the setup +script: + + .. parsed-literal:: + + python setup.py install + + diff --git a/doc/sdk/overview.rst b/doc/sdk/overview.rst index 802d341..f863d8f 100755 --- a/doc/sdk/overview.rst +++ b/doc/sdk/overview.rst @@ -1,2 +1,15 @@ Overview ======== + +The `McAfee ePolicy Orchestrator `_ (ePO) DXL Python +client library provides a high level wrapper for invoking ePO remote commands via the +`Data Exchange Layer `_ (DXL) fabric. + +The purpose of this library is to allow users to invoke ePO remote commands without having to focus +on lower-level details such as ePO-specific DXL topics and message formats. + +This client requires an ePO DXL service to be running and available on the DXL fabric. + +A Python-based implementation of an ePO DXL service is available here: + +* `McAfee ePolicy Orchestrator (ePO) DXL Python Service `_ \ No newline at end of file diff --git a/doc/sdk/sampleconfig.rst b/doc/sdk/sampleconfig.rst index 8d6080c..b3fcada 100755 --- a/doc/sdk/sampleconfig.rst +++ b/doc/sdk/sampleconfig.rst @@ -1,3 +1,23 @@ Samples Configuration ===================== +The ePO DXL Python client distribution contains a configuration file (``dxlclient.config``) located +in the ``sample`` sub-directory that must be populated in order for the samples to connect to the DXL fabric. + +The steps to populate this configuration file are the same as those documented in the `OpenDXL Python +SDK`, see the +`OpenDXL Python SDK Samples Configuration `_ +page for more information. + +The following is an example of a populated configuration file: + + .. code-block:: python + + [Certs] + BrokerCertChain=c:\\certificates\\brokercerts.crt + CertFile=c:\\certificates\\client.crt + PrivateKey=c:\\certificates\\client.key + + [Brokers] + {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};8883;mybroker.mcafee.com;192.168.1.12 + {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};8883;mybroker2.mcafee.com;192.168.1.13 diff --git a/dxlepoclient/__init__.py b/dxlepoclient/__init__.py index 9adf7c8..7ea14c1 100644 --- a/dxlepoclient/__init__.py +++ b/dxlepoclient/__init__.py @@ -6,7 +6,7 @@ from .client import EpoClient, OutputFormat -__version__ = "0.0.1" +__version__ = "0.1.0" def get_version(): diff --git a/sample/basic/basic_core_help_example.py b/sample/basic/basic_core_help_example.py index 2f30001..2d19dea 100644 --- a/sample/basic/basic_core_help_example.py +++ b/sample/basic/basic_core_help_example.py @@ -1,14 +1,17 @@ -# This sample invokes and displays the results of the "core help" command via -# the ePO DXL service. This displays the remote commands that are exposed by -# the ePO server. +# This sample invokes and displays the results of the "core help" remote +# command via the ePO DXL service. The "core help" command lists the +# remote commands that are exposed by the particular ePO server. # # NOTE: Prior to running this sample you must provide values for the following # constants in this file: # # EPO_UNIQUE_ID : The unique identifier used to identify the ePO server # on the DXL fabric. +# +# If only one ePO server is connected to the DXL fabric +# this constant can be set to None (the client will +# automatically determine the ePO's unique identifier). -import json import os import sys diff --git a/sample/basic/basic_system_find_example.py b/sample/basic/basic_system_find_example.py index 5667f61..1dada93 100755 --- a/sample/basic/basic_system_find_example.py +++ b/sample/basic/basic_system_find_example.py @@ -8,6 +8,10 @@ # EPO_UNIQUE_ID : The unique identifier used to identify the ePO server # on the DXL fabric. # +# If only one ePO server is connected to the DXL fabric +# this constant can be set to None (the client will +# automatically determine the ePO's unique identifier). +# # SEARCH_TEXT : The search text to use (system name, etc.) import json @@ -33,8 +37,7 @@ EPO_UNIQUE_ID = None # The search text -#SEARCH_TEXT = "" -SEARCH_TEXT = "broker" +SEARCH_TEXT = "" # Create the client with DxlClient(config) as client: @@ -50,5 +53,8 @@ {"searchText": SEARCH_TEXT}, output_format=OutputFormat.JSON) + # Load find result into dictionary + res_dict = json.loads(res, encoding='utf-8') + # Display the results - print json.dumps(json.loads(res, encoding='utf-8'), sort_keys=True, indent=4, separators=(',', ': ')) + print json.dumps(res_dict, sort_keys=True, indent=4, separators=(',', ': '))