rbeapi 0.4.0 → 0.5.0

data/guide/cookbook.rst

@@ -0,0 +1,4 @@
+Cookbook
+============
+
+.. contents:: :local:

data/guide/developing.rst

@@ -0,0 +1,4 @@
+Developing
+==========
+
+.. contents:: :local:

data/guide/faq.rst

@@ -0,0 +1,4 @@
+FAQ
+===
+
+.. contents:: :local:

data/guide/index.rst

@@ -0,0 +1,23 @@
+.. Rbeapi documentation master file, created by
+   sphinx-quickstart on Fri Jan  8 11:04:02 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Rbeapi's documentation!
+==================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   quickstart
+   installation
+   cookbook
+   troubleshooting
+   developing
+   testing
+   faq
+   release-notes
+   license

data/guide/installation.rst

@@ -0,0 +1,4 @@
+Installation
+============
+
+.. contents:: :local:

data/guide/license.rst

@@ -0,0 +1,5 @@
+License
+=======
+
+.. include:: ../LICENSE
+   :literal:

data/guide/overview.rst

@@ -0,0 +1,20 @@
+Overview
+========
+
+.. contents:: :local:
+
+Introduction
+------------
+
+The Ruby Client for eAPI provides a native Ruby implementation for programming Arista EOS network devices using Ruby.  The Ruby client provides the ability to build native applications in Ruby that can communicate with EOS either locally via Unix domain sockets (on-box) or remotely over a HTTP/S transport (off-box).  It uses a standard INI-style configuration file to specifiy one or more connection profiles.
+
+The rbeapi implemenation also provides an API layer for building native Ruby objects that allow for configuration and state extraction of EOS nodes.  The API layer provides a consistent implementation for working with EOS configuration resources.  The implementation of the API layer is highly extensible and can be used as a foundation for building custom data models.
+
+The libray is freely provided to the open source community for building robust applications using Arista EOS eAPI.  Support is provided as best effort through Github iusses.
+
+Prerequisites
+-------------
+
+* Arista EOS 4.12 or later
+* Arista eAPI enabled for at least one transport (see official EOS Config Guide at arista.com for details)
+* Ruby 1.9.3 or later

data/guide/quickstart.rst

@@ -0,0 +1,4 @@
+Quick Start
+===========
+
+.. contents:: :local:

data/guide/release-notes-0.5.0.rst

@@ -0,0 +1,60 @@
+Release 0.5.0 - January 2016
+----------------------------
+
+.. contents:: :local:
+
+Enhancements
+^^^^^^^^^^^^
+
+* Add lacp_mode option when setting port-channel members. (`89 <https://github.com/arista-eosplus/rbeapi/pull/89>`_) [`devrobo <https://github.com/devrobo>`_]
+    .. comment
+* Add support for trunk groups. (`88 <https://github.com/arista-eosplus/rbeapi/pull/88>`_) [`devrobo <https://github.com/devrobo>`_]
+    .. comment
+* Unit tests for switchports (`94 <https://github.com/arista-eosplus/rbeapi/pull/94>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+* Ensure all parse methods are private. (`93 <https://github.com/arista-eosplus/rbeapi/pull/93>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+* Add tests for timeout values (`92 <https://github.com/arista-eosplus/rbeapi/pull/92>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+* Relax check on getall entries (`91 <https://github.com/arista-eosplus/rbeapi/pull/91>`_) [`devrobo <https://github.com/devrobo>`_]
+    .. comment
+* Update framework tests (`90 <https://github.com/arista-eosplus/rbeapi/pull/90>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+* Add basic framework tests. (`85 <https://github.com/arista-eosplus/rbeapi/pull/85>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+* Address code coverage gaps (`84 <https://github.com/arista-eosplus/rbeapi/pull/84>`_) [`websitescenes <https://github.com/websitescenes>`_]
+    .. comment
+
+Fixed
+^^^^^
+
+* Copy configuration entry before modifying with connection specific info. (`101 <https://github.com/arista-eosplus/rbeapi/pull/101>`_)
+    .. comment
+* Add 'terminal' to configure command to work around AAA issue. (`99 <https://github.com/arista-eosplus/rbeapi/pull/99>`_)
+    .. comment
+* Set enable password for a connection. (`96 <https://github.com/arista-eosplus/rbeapi/pull/96>`_)
+    .. comment
+* Catch errors and syslog them when parsing eapi conf file. (`95 <https://github.com/arista-eosplus/rbeapi/pull/95>`_)
+    In the event of an unparsable ``eapi.conf`` file, which could occur due to other tools which used a YAML syntax instead of INI, rbeapi will log a warning via syslog, but continue to attempt a default connection to localhost.
+    .. comment
+* Ensure that nil is returned when getting nonexistent username. (`83 <https://github.com/arista-eosplus/rbeapi/pull/83>`_)
+    .. comment
+* Failure when eapi.conf is not formatted correctly (`82 <https://github.com/arista-eosplus/rbeapi/issues/82>`_)
+    In the event of an unparsable ``eapi.conf`` file, which could occur due to other tools which used a YAML syntax instead of INI, rbeapi will log a warning via syslog, but continue to attempt a default connection to localhost.
+* Enable password setting in the .eapi.conf file not honored (`72 <https://github.com/arista-eosplus/rbeapi/issues/72>`_)
+    ``enablepwd`` is now properly used, if defined, in the ``eapi.conf``
+* API interfaces should accept an lacp_mode to configure for port-channel members (`58 <https://github.com/arista-eosplus/rbeapi/issues/58>`_)
+    ``set_members()`` now configures LACP mode when adding members to a port-channel
+
+Known Caveats
+^^^^^^^^^^^^^
+
+* Add support for commands with input (`100 <https://github.com/arista-eosplus/rbeapi/issues/100>`_)
+    .. comment
+* Wildcard connection config gets clobbered (`86 <https://github.com/arista-eosplus/rbeapi/issues/86>`_)
+    .. comment
+* Need to validate value keyword in set methods when array (`40 <https://github.com/arista-eosplus/rbeapi/issues/40>`_)
+    .. comment
+* get_connect should raise an error instead of returning nil if no connection is found (`31 <https://github.com/arista-eosplus/rbeapi/issues/31>`_)
+    .. comment
+

data/guide/release-notes.rst

@@ -0,0 +1,6 @@
+Release Notes
+=============
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:

data/guide/testing.rst

@@ -0,0 +1,4 @@
+Testing Modules
+===============
+
+.. contents:: :local:

data/guide/troubleshooting.rst

@@ -0,0 +1 @@
+.. _troubleshooting:

data/lib/rbeapi/api/aaa.rb

@@ -35,18 +35,39 @@ require 'rbeapi/api'
 # Rbeapi toplevel namespace
 module Rbeapi
   ##
-  # Rbeapi::Api
+  # Api is module namespace for working with the EOS command API
   module Api
     ##
     # The Aaa class manages Authorization, Authentication and Accounting (AAA)
     # on an EOS node.
     class Aaa < Entity
+      ##
+      # get returns a hash of all Aaa resources
+      #
+      # @example
+      #   {
+      #     <groups>: {
+      #       <name>: {
+      #         type: <string>,
+      #         servers: <array>
+      #       },
+      #       <name>: {
+      #         type: <string>,
+      #         servers: <array>
+      #       }
+      #     }
+      #   }
+      #
+      # @return [Hash<Symbol, Object>] Returns the Aaa resources as a
+      #   Hash. If no Aaa resources are found, an empty hash is returned.
       def get
         response = {}
         response[:groups] = groups.getall
         response
       end
 
+      ##
+      # Returns an object node for working with AaaGroups class.
       def groups
         return @groups if @groups
         @groups = AaaGroups.new node
@@ -55,20 +76,20 @@ module Rbeapi
     end
 
     ##
-    # The AaaGroups class manages the server groups on a EOS node.
+    # The AaaGroups class manages the server groups on an EOS node.
     class AaaGroups < Entity
       DEFAULT_RADIUS_AUTH_PORT = 1812
       DEFAULT_RADIUS_ACCT_PORT = 1813
 
-      # Regular express that parses the radius servers from the aaa group
-      # server radius configuration block
+      # Regular expression that parses the radius servers from the aaa group
+      # server radius configuration block.
       RADIUS_GROUP_SERVER = /\s{3}server
                              [ ]([^\s]+)
                              [ ]auth-port[ ](\d+)
                              [ ]acct-port[ ](\d+)/x
 
-      # Regular expression that parse the tacacs servers from the aaa group
-      # server tacacs+ configuration block
+      # Regular expression that parses the tacacs servers from the aaa group
+      # server tacacs+ configuration block.
       TACACS_GROUP_SERVER = /\s{3}server
                              [ ]([^\s]+)
                              (?:[ ]vrf[ ](\w+))?
@@ -76,15 +97,15 @@ module Rbeapi
 
       ##
       # get returns the aaa server group resource hash that describes the
-      # current configuration for the specified server group name
+      # current configuration for the specified server group name.
       #
-      # The resource hash returned contains the following:
-      #   * type: (String) The server group type.  Valid values are either
-      #   'tacacs' or 'radius'
-      #   * servers: (Array) The set of servers associated with the group.
-      #   Servers are returned as either IP address or host name
+      # @example
+      #   {
+      #     type: <string>,
+      #     servers: <array>
+      #   }
       #
-      # @param [String] :name The server group name to return f:rom the nodes
+      # @param [String] :name The server group name to return from the nodes
       #   current running configuration.  If the name is not configured a nil
       #   object is returned.
       #
@@ -99,6 +120,23 @@ module Rbeapi
         response
       end
 
+      ##
+      # getall returns a aaa server groups hash
+      #
+      # @example
+      # {
+      #   <name>: {
+      #     type: <string>,
+      #     servers: <array>
+      #   },
+      #   <name>: {
+      #     type: <string>,
+      #     servers: <array>
+      #   }
+      # }
+      #
+      # @return [Hash<Symbol, Object>] returns the resource hashes for
+      #   configured aaa groups.  If none exist, a nil object is returned
       def getall
         cfg = config.scan(/aaa group server (?:radius|tacacs\+) (.+)$/)
         cfg.each_with_object({}) do |name, hsh|
@@ -109,7 +147,7 @@ module Rbeapi
 
       ##
       # parse_type scans the specified configuration block and returns the
-      # server group type as either 'tacacs' or 'radius'  The type value is
+      # server group type as either 'tacacs' or 'radius'.  The type value is
       # expected to always be present in the config.
       #
       # @api private
@@ -160,7 +198,6 @@ module Rbeapi
       # @param [String] :config The aaa server group block configuration for the
       #   group name to parse
       #
-      #
       # @return [Hash<Symbol, Object>] resource hash attribute
       def parse_radius_server(config)
         values = config.scan(RADIUS_GROUP_SERVER).map do |(name, auth, acct)|
@@ -175,8 +212,8 @@ module Rbeapi
       private :parse_radius_server
 
       ##
-      # parse_tacacs_server scans the provide configuration block and returns
-      # the list of servers configured.  The configuration block is expected to
+      # parse_tacacs_server scans the provided configuration block and returns
+      # the list of configured servers.  The configuration block is expected to
       # be a tacacs configuration block.  If there are no servers configured
       # for the group the servers value will return an empty array.
       #
@@ -185,7 +222,6 @@ module Rbeapi
       # @param [String] :config The aaa server group block configuration for the
       #   group name to parse
       #
-      #
       # @return [Hash<Symbol, Object>] resource hash attribute
       def parse_tacacs_server(config)
         values = config.scan(TACACS_GROUP_SERVER).map do |(name, vrf, port)|

data/lib/rbeapi/api/acl.rb

@@ -33,7 +33,7 @@ require 'netaddr'
 require 'rbeapi/api'
 
 ##
-# Eos is the toplevel namespace for working with Arista EOS nodes
+# Rbeapi toplevel namespace
 module Rbeapi
   ##
   # Api is module namespace for working with the EOS command API
@@ -56,10 +56,29 @@ module Rbeapi
       ##
       # get returns the specified ACL from the nodes current configuration.
       #
+      # @example
+      #   {
+      #     <seqno>: {
+      #       seqno: <integer>,
+      #       action: <string>,
+      #       srcaddr: <string>,
+      #       srcprefixle: <string>,
+      #       log: <string>
+      #     },
+      #     <seqno>: {
+      #       seqno: <integer>,
+      #       action: <string>,
+      #       srcaddr: <string>,
+      #       srcprefixle: <string>,
+      #       log: <string>
+      #     },
+      #     ...
+      #   }
+      #
       # @param [String] :name The ACL name.
       #
       # @return [nil, Hash<Symbol, Object>] Returns the ACL resource as a
-      #   Hash.
+      #   Hash. Returns nil if name does not exist.
       def get(name)
         config = get_block("ip access-list standard #{name}")
         return nil unless config
@@ -72,6 +91,45 @@ module Rbeapi
       # configuration as a hash. The ACL resource collection hash is
       # keyed by the ACL name.
       #
+      # @example
+      #   {
+      #     <name>: {
+      #       <seqno>: {
+      #         seqno: <integer>,
+      #         action: <string>,
+      #         srcaddr: <string>,
+      #         srcprefixle: <string>,
+      #         log: <string>
+      #       },
+      #       <seqno>: {
+      #         seqno: <integer>,
+      #         action: <string>,
+      #         srcaddr: <string>,
+      #         srcprefixle: <string>,
+      #         log: <string>
+      #       },
+      #       ...
+      #     },
+      #     <name>: {
+      #       <seqno>: {
+      #         seqno: <integer>,
+      #         action: <string>,
+      #         srcaddr: <string>,
+      #         srcprefixle: <string>,
+      #         log: <string>
+      #       },
+      #       <seqno>: {
+      #         seqno: <integer>,
+      #         action: <string>,
+      #         srcaddr: <string>,
+      #         srcprefixle: <string>,
+      #         log: <string>
+      #       },
+      #       ...
+      #     },
+      #     ...
+      #   }
+      #
       # @return [nil, Hash<Symbol, Object>] Returns a hash that represents
       #   the entire ACL collection from the nodes running configuration.
       #   If there are no ACLs configured, this method will return an

data/lib/rbeapi/api/bgp.rb

@@ -51,6 +51,50 @@ module Rbeapi
       # get returns the BGP routing configuration from the nodes current
       # configuration.
       #
+      # @example
+      #   {
+      #     bgp_as: <string>,
+      #     router_id: <string>,
+      #     shutdown: <string>,
+      #     maximum_paths: <integer>,
+      #     maximum_ecmp_paths: <integer>
+      #     networks: [
+      #       {
+      #         prefix: <string>,
+      #         masklen: <integer>,
+      #         route_map: <string>
+      #       },
+      #       {
+      #         prefix: <string>,
+      #         masklen: <integer>,
+      #         route_map: <string>
+      #       }
+      #     ],
+      #     neighbors: {
+      #       name: {
+      #         peer_group: <string>,
+      #         remote_as: <string>,
+      #         send_community: <boolean>,
+      #         shutdown: <boolean>,
+      #         description: <string>,
+      #         next_hop_selp: <boolean>,
+      #         route_map_in: <string>,
+      #         route_map_out: <string>
+      #       },
+      #       name: {
+      #         peer_group: <string>,
+      #         remote_as: <string>,
+      #         send_community: <boolean>,
+      #         shutdown: <boolean>,
+      #         description: <string>,
+      #         next_hop_selp: <boolean>,
+      #         route_map_in: <string>,
+      #         route_map_out: <string>
+      #       },
+      #       ...
+      #     }
+      #   }
+      #
       # @return [nil, Hash<Symbol, Object>] Returns the BGP resource as a
       #   Hash.
       def get
@@ -397,6 +441,18 @@ module Rbeapi
       # get returns a single BGP neighbor entry from the nodes current
       # configuration.
       #
+      # @example
+      #   {
+      #     peer_group: <string>,
+      #     remote_as: <string>,
+      #     send_community: <string>,
+      #     shutdown: <boolean>,
+      #     description: <integer>
+      #     next_hop_self: <boolean>
+      #     route_map_in: <string>
+      #     route_map_out: <string>
+      #   }
+      #
       # @param [String] :name The name of the BGP neighbor to manage.
       #   This value can be either an IPv4 address or string (in the
       #   case of managing a peer group).
@@ -422,6 +478,31 @@ module Rbeapi
       # getall returns the collection of all neighbor entries for the
       # BGP router instance.
       #
+      # @example
+      #   {
+      #     <name>: {
+      #       peer_group: <string>,
+      #       remote_as: <string>,
+      #       send_community: <string>,
+      #       shutdown: <boolean>,
+      #       description: <integer>
+      #       next_hop_self: <boolean>
+      #       route_map_in: <string>
+      #       route_map_out: <string>
+      #     },
+      #     <name>: {
+      #       peer_group: <string>,
+      #       remote_as: <string>,
+      #       send_community: <string>,
+      #       shutdown: <boolean>,
+      #       description: <integer>
+      #       next_hop_self: <boolean>
+      #       route_map_in: <string>
+      #       route_map_out: <string>
+      #     },
+      #     ...
+      #   }
+      #
       # @return [nil, Hash<Symbol, Object>] Returns a hash that
       #   represents the entire BGP neighbor collection from the nodes
       #   running configuration. If there a BGP router is not configured