From c823f6ade889f00fccd95a27bd30a01529e75b8d Mon Sep 17 00:00:00 2001 From: mpenning Date: Sat, 18 Nov 2023 07:31:22 -0600 Subject: [PATCH] Update documentation --- dev_tools/deploy_docs/deploy_docs.go | 2 +- sphinx-doc/factory.rst | 67 ++++++++++++++++++++++++++++ sphinx-doc/index.rst | 3 ++ sphinx-doc/legacy_syntax.rst | 2 +- sphinx-doc/syntax.rst | 33 ++++++++++++++ sphinx-doc/syntax_factory_intro.rst | 14 ++++++ 6 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 sphinx-doc/factory.rst create mode 100644 sphinx-doc/syntax.rst create mode 100644 sphinx-doc/syntax_factory_intro.rst diff --git a/dev_tools/deploy_docs/deploy_docs.go b/dev_tools/deploy_docs/deploy_docs.go index 3bb755dd..e8439993 100644 --- a/dev_tools/deploy_docs/deploy_docs.go +++ b/dev_tools/deploy_docs/deploy_docs.go @@ -28,7 +28,7 @@ func main() { // Start a new goph ssh connection with private key auth... logoru.Info(" Initialize ssh key-auth") - auth, err := goph.Key("/home/mpenning/.ssh/id_ed25519", "") + auth, err := goph.Key("/home/mpenning/.ssh/id_rsa", "") if err != nil { logoru.Critical(err.Error()) } diff --git a/sphinx-doc/factory.rst b/sphinx-doc/factory.rst new file mode 100644 index 00000000..17724247 --- /dev/null +++ b/sphinx-doc/factory.rst @@ -0,0 +1,67 @@ +======= +factory +======= + +``factory`` is an experimental feature to derive more information about configurations by using +several different configuration objects for a given ``syntax``. + +.. sourcecode:: python + + >>> from ciscoconfparse import CiscoConfParse + >>> parse = CiscoConfParse('/tftpboot/sfob09f02sw01.conf', syntax='ios', factory=True) + >>> hsrp_intf = parse.find_parent_objects("interface", " standby") + >>> + +The most developed factory is ``ios``. + +.. note:: + ``factory`` is an experimental feature; to enable it, parse with ``factory=True``. + If something doesn't work, it's a feature, not a bug. + +.. warning:: + Anything about ``factory`` parsing can change at any time (but mostly does not). + +factory=True example +-------------------- + +This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an interface that was parsed with ``factory=True``. + +.. sourcecode:: python + + >>> from ciscoconfparse import CiscoConfParse + >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=True) + >>> hsrp_intfs = parse.find_parent_objects("interface", " standby") + >>> + >>> hsrp_intfs[0] + + >>> + >>> hsrp_intfs[0].ipv4 + + >>> + +factory=False example +--------------------- + +This is the same operation with ``factory=False``. + +.. sourcecode:: python + + >>> from ciscoconfparse import CiscoConfParse + >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=False) + >>> hsrp_intfs = parse.find_parent_objects("interface", " standby") + >>> + >>> hsrp_intfs[0] + + >>> + >>> hsrp_intfs[0].ipv4 + 2023-11-18 07:00:21.216 | ERROR | ciscoconfparse.ccp_abc:__getattr__:142 - The ipv4 attribute does not exist + 2023-11-18 07:00:21.217 | ERROR | __main__::1 - An error has been caught in function '', process 'MainProcess' (111007), thread 'MainThread' (139675861627520): + Traceback (most recent call last): + + File "/home/mpenning/fixme/ciscoconfparse/ciscoconfparse/ccp_abc.py", line 138, in __getattr__ + retval = getattr(object, attr) + └ 'ipv4' + + AttributeError: type object 'object' has no attribute 'ipv4' + >>> + diff --git a/sphinx-doc/index.rst b/sphinx-doc/index.rst index 85f8f73d..a1de7594 100755 --- a/sphinx-doc/index.rst +++ b/sphinx-doc/index.rst @@ -10,6 +10,9 @@ Welcome to ciscoconfparse's documentation! installation tutorial legacy_syntax + syntax_factory_intro + syntax + factory license_copyright api diff --git a/sphinx-doc/legacy_syntax.rst b/sphinx-doc/legacy_syntax.rst index 69396e26..31ff94fc 100755 --- a/sphinx-doc/legacy_syntax.rst +++ b/sphinx-doc/legacy_syntax.rst @@ -201,7 +201,7 @@ Sometimes you find yourself wishing you could decrypt vty or console passwords t .. note:: - Cisco IOS Type 7 passwords were never meant to be secure; these passwords only protect against shoulder-surfing. When you add users and enable passwords to your router, be sure to use Cisco IOS Type 5 passwords; these are much more secure and cannot be decrypted. + Cisco IOS Type 7 passwords were never meant to be secure; these passwords only protect against shoulder-surfing. When you add users and enable passwords to your router, be sure to another Cisco IOS Type password; these are much more secure and cannot be easily decrypted. .. warning:: diff --git a/sphinx-doc/syntax.rst b/sphinx-doc/syntax.rst new file mode 100644 index 00000000..ab6485a9 --- /dev/null +++ b/sphinx-doc/syntax.rst @@ -0,0 +1,33 @@ +====== +syntax +====== + +``syntax`` is used with all configurations. By default ``ios`` syntax is used and it's +a good default for many vendor configurations (without braces). + +This configuration parse reads the configuration as ``ios`` syntax by default: + +.. sourcecode:: python + + >>> from ciscoconfparse import CiscoConfParse + >>> parse = CiscoConfParse('/tftpboot/sfob09f02sw01.conf') + >>> + +This configuration parse explicitly reads the configuration as ``asa`` syntax: + +.. sourcecode:: python + + >>> from ciscoconfparse import CiscoConfParse + >>> parse = CiscoConfParse('/tftpboot/sfob09f02fw01.conf', syntax='asa') + >>> + +``syntax`` offers a way to handle these situations: + +- Is the config delimited with braces or indentation? +- Which configuration object is used to represent configuration lines? +- These configuration objects offer the following information: + + - Is a configuration line an interface? + - Is an interface a switchport? + - Is an interface administratively shutdown? + diff --git a/sphinx-doc/syntax_factory_intro.rst b/sphinx-doc/syntax_factory_intro.rst new file mode 100644 index 00000000..6f7a5c67 --- /dev/null +++ b/sphinx-doc/syntax_factory_intro.rst @@ -0,0 +1,14 @@ +======================== +syntax and factory intro +======================== + +Overview +-------- + +When parsing configurations, vendors have some tweaks they make to the configuration. + +``CiscoConfParse`` has two parameters that are used to manage this. + +- ``syntax`` +- ``factory`` +