Skip to content

Commit

Permalink
Doc updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@phil-dileo
phil-dileo committed Oct 23, 2015
1 parent 0955471 commit bf05ede
Show file tree
Hide file tree
Showing 5 changed files with 190 additions and 147 deletions.
216 changes: 159 additions & 57 deletions docs/configfile.rst
View file
Original file line number Diff line number Diff line change
@@ -1,66 +1,23 @@
.. _configfile:

#########################
Pyeapi Configuration File
#########################

In order to use pyeapi, the EOS command API must be enabled using configuration
mode. This library supports eAPI calls over both HTTP/S and UNIX Domain
Sockets. Once the command API is enabled on the destination node, create a
configuration file with the node properties.

**************
Install Pyeapi
**************

Follow the instructions on the :ref:`install` guide to prepare your node for
pyeapi.
The pyeapi configuration file is a convenient place to store node connection
information. By keeping connection information central, your pyeapi scripts
can effortlessly reference nodes without any manual import of credentials
or location information. Therefore, the pyeapi configuration file becomes
a reflection of your switch inventory and the way in which the EOS Command
API is enabled on the node. The following explains how to craft your
pyeapi configuration file to address specific implementation styles.

************************
Create an eapi.conf file
************************
.. contents::
:depth: 2

This method would be used to run a pyeapi script on-box. In this mode, eAPI
can be configured to require or not require authentication. A quick summary:

=========== ========================
Type Authentication Required
=========== ========================
https Yes
http Yes
http_local No
socket No
=========== ========================

The default transport for pyeapi is ``socket`` and the default host is
``localhost``. Therefore, if running a pyeapi script on-box and have
Unix Sockets enabled, you do not need an eapi.conf, nor do you need to pass
any credentials (quite handy!).

If instead, ``https``, ``http`` or ``http_local`` is configured on your
node, then you will need an eapi.conf file in ``/mnt/flash/eapi.conf``. It
would contain something like:

.. code-block:: console
[connection:localhost]
transport: http_local
.. code-block:: console
[connection:localhost]
transport: https
username: admin
password: admin
.. code-block:: console
[connection:localhost]
transport: http
username: admin
password: admin
.. Note:: The default search path for the conf file is ``~/.eapi.conf``
followed by ``/mnt/flash/eapi.conf``. This can be overridden by setting
``EAPI_CONF=<path file conf file>`` in your environment.
********************
eapi.conf Parameters
********************

The following configuration options are available for defining node entries:

Expand Down Expand Up @@ -89,3 +46,148 @@ The following configuration options are available for defining node entries:
- transport: https, deafult port: 443
- transport: http_local, default port: 8080
- transport: socket, default port: n/a

*********************************
When is an eapi.conf file needed?
*********************************

It's important to understand the nuances of the pyeapi configuration file so
you can simplify your implementation. Here's a quick summary of when the
eapi.conf file is needed:

=========== ================== =============== ========================
Transport eapi.conf Required Script run from Authentication Required
=========== ================== =============== ========================
http Yes On/Off-switch Yes
https Yes On/Off-switch Yes
http_local Yes On-switch only No
socket No On-switch only No
=========== ================== =============== ========================


********************************
Where should the file be placed?
********************************

============ =================================================
Search Order Search Location
============ =================================================
1 Environment Variable EAPI_CONF=/path/to/eapi.conf
2 $HOME/.eapi.conf
3 /mnt/flash/eapi.conf
============ =================================================

.. Note:: There is a slight difference in #2 ``.eapi.conf`` versus
#3 ``eapi.conf``

************************************
eapi.conf for On-box Implementations
************************************

This method would be used to run a pyeapi script on-box. In this mode, eAPI
can be configured to require or not require authentication depending upon
how you enabled EOS Command API.

Notice from the table above, that if EOS Command API Unix Sockets are enabled,
or HTTP Local, you get the benefit of not needing to pass in credentials
since the connection can only be made from localhost and it assumes the user
has already authenticated to get on the switch.

Using Unix Sockets
==================

This is the preferred method. The default transport for pyeapi is ``socket``
and the default host is ``localhost``. Therefore, if running a pyeapi script
on-box and have Unix Sockets enabled, you do not need an eapi.conf, nor do you
need to pass any credentials (quite handy!).

.. Note:: Unix Sockets are supported on EOS 4.14.5+

Using HTTP Local
================

As the table above indicates, a pyeapi configuration file is required in
``/mnt/flash/eapi.conf``. It would contain something like:

.. code-block:: console
[connection:localhost]
transport: http_local
Using HTTP or HTTPS
===================

As the table above indicates, a pyeapi configuration file is required in
``/mnt/flash/eapi.conf``. It would contain something like:

.. code-block:: console
[connection:localhost]
transport: http[s]
username: admin
password: admin
*************************************
eapi.conf for Off-box Implementations
*************************************

This method would be used to run a pyeapi script from another server. In this
mode, eAPI will require authentication. The only real option is whether you
connect over HTTP or HTTPS.

.. Note:: The ``socket`` and ``http_local`` transport options are not
applicable.

Notice from the table above, that if EOS Command API Unix Sockets are enabled,
or HTTP Local, you get the benefit of not needing to pass in credentials
since the connection can only be made from localhost and it assumes the user
has already authenticated to get on the switch.

Using HTTP or HTTPS
===================

As the table above indicates, a pyeapi configuration file is required in
``$HOME/.eapi.conf``. It would contain something like:

.. code-block:: console
[connection:veos01]
transport: http
username: paul
password: nottelling
[connection:veos03]
transport: https
username: bob
password: mysecret
[connection:veos04]
host: 192.168.2.10
transport: https
username: admin
password: admin
*******************
The DEFAULT Section
*******************

The [DEFAULT] section can be used to gather globally applicable settings.
Say that all of your nodes use the same transport or username, you can do
something like:

.. code-block:: console
[connection:veos01]
[connection:veos03]
transport: https
username: bob
password: mysecret
[connection:veos04]
host: 192.168.2.10
[DEFAULT]
transport: https
username: admin
password: admin
9 changes: 4 additions & 5 deletions docs/install.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@ actual filename:
[admin@veos ~]$ sudo pip install /mnt/flash/netaddr-<VERSION>.tar.gz
[admin@veos ~]$ sudo pip install /mnt/flash/pyeapi-<VERSION>.tar.gz
These packages will be blown away on switch reboot. Therefore, add the install
commands to ``/mnt/flash/rc.eos`` to install on reboot:
These packages must be re-installed on reboot. Therefore, add the install
commands to ``/mnt/flash/rc.eos`` to trigger the install on reboot:

.. code-block:: console
Expand Down Expand Up @@ -113,6 +113,5 @@ code in the develop branch.
# Install
admin:~ admin$ sudo pip install -e ~/projects/pyeapi
.. Tip:: If you start using pyeapi and get import errors, make sure your PATH
is set to include the path to pyeapi. You can also set your PYTHONPATH
to include the pyeapi source path.
.. Tip:: If you start using pyeapi and get import errors, make sure your
PYTHONPATH is set to include the path to pyeapi.
108 changes: 25 additions & 83 deletions docs/quickstart.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,21 @@ Quickstart
In order to use pyeapi, the EOS command API must be enabled using configuration
mode. This library supports eAPI calls over both HTTP/S and UNIX Domain
Sockets. Once the command API is enabled on the destination node, create a
configuration file with the node properties.
configuration file with the node properties. There are some nuances about the
configuration file that are important to understand; take a minute and read
about the :ref:`configfile`.

**********************
Enable EOS Command API
**********************

Refer to your official Arista EOS Configuration Guide to learn how to enable
EOS Command API. Depending upon your software version, the options available
include:
- HTTP
- HTTPS
- HTTP Local
- Unix Socket

**************
Install Pyeapi
Expand All @@ -18,83 +32,9 @@ pyeapi.
Create an eapi.conf file
************************

The eAPI configuration file provides a way to keep an inventory of your
switches in one central place. You can quickly connect to a switch in your
inventory as shown below. The contents of eapi.conf will change depending upon
where you run pyeapi. Some examples are provided below.


Running pyeapi from a central server
====================================

This method would be used to connect to various Arista nodes from a central
server. The eapi.conf file would then contain all of the switches and would
likely include an HTTP or HTTPS transport method.

Here's an example

The conf file can contain more than one node. Each node section must be
prefaced by ``connection:<name>`` where <name> is the name of the connection.
When no ``host`` key is present, the connection name will be used (ie DNS).

.. code-block:: console
[connection:veos01]
username: eapi
password: password
transport: http
[connection:veos02]
host: 172.16.10.1
username: eapi
password: password
enablepwd: itsasecret
port: 1234
transport: https
Running pyeapi locally on a switch
==================================

This method would be used to run a pyeapi script on-box. In this mode, eAPI
can be configured to require or not require authentication. A quick summary:

=========== ========================
Type Authentication Required
=========== ========================
https Yes
http Yes
http_local No
socket No
=========== ========================

The default transport for pyeapi is ``socket`` and the default host is
``localhost``. Therefore, if running a pyeapi script on-box and have
Unix Sockets enabled, you do not need an eapi.conf, nor do you need to pass
any credentials (quite handy!).

If instead, ``https``, ``http`` or ``http_local`` is configured on your
node, then you will need an eapi.conf file in ``/mnt/flash/eapi.conf``. It
would contain something like:

.. code-block:: console
[connection:localhost]
transport: http_local
.. code-block:: console
[connection:localhost]
transport: https
username: admin
password: admin
.. code-block:: console
[connection:localhost]
transport: http
username: admin
password: admin
Follow the instructions on the :ref:`configfile` guide to create a pyeapi
configuration file. You can skip this step if you are running the pyeapi
script on-box and Unix Sockets are enabled for EOS Command API.

*****************
Connect to a Node
Expand All @@ -106,7 +46,9 @@ plane.

Once EOS is configured properly and the config file created, getting started
with a connection to EOS is simple. Below demonstrates a basic connection
using pyeapi. For more examples, please see the examples folder.
using pyeapi. For more examples, please see the
`examples <https://github.com/arista-eosplus/pyeapi/tree/develop/examples>`_
folder on Github.

This first example shows how to instantiate the Node object. The Node object
provides some helpful methods and attributes to work with the switch.
Expand All @@ -128,13 +70,13 @@ provides some helpful methods and attributes to work with the switch.
node.config('hostname veos01')
[{}]
# multiple commands can be sent by using a list (works for both enable or
config)
# multiple commands can be sent by using a list
# (works for both enable or config)
node.config(['interface Ethernet1', 'description foo'])
[{}, {}]
# return the running or startup configuration from the node (output omitted for
brevity)
# return the running or startup configuration from the
# node (output omitted for brevity)
node.running_config
node.startup_config
Expand Down
2 changes: 1 addition & 1 deletion docs/requirements.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@ Requirements
* Arista eAPI enabled for at least one transport (see Official EOS Config Guide
at arista.com for details)
* Python 2.7 or 3.4+ (Python 3 support is work in progress)
* Pyeapi required the netaddr Python module
* Pyeapi requires the netaddr Python module

.. Note:: netaddr gets installed automatically if you use pip to install pyeapi

0 comments on commit bf05ede

Please sign in to comment.