ACI Endpoint Tracker
====================
The ACI Endpoint Tracker application tracks all of the attachment,
detachment, and movement of Endpoints on the ACI fabric. It stores
all of this activity in a database that allows administrators to
examine and query the data to gain deep visibility into what is
happening in the network. The database also provides a foundation for
visualization and querying tools.
Some sample questions that can be answered with the ACI Endpoint Tracker:
* What are all of the current Endpoints on the network ?
* Where is a specific Endpoint ?
* What was connected to the network last Thursday
between 3:30 and 4:00 ?
* What are all of the Endpoints belonging to a given Tenant ?
* What Endpoints are on this subnet ?
* What is the history of a given Endpoint (i.e. movement, etc.)?
Installation
------------
acitoolkit
~~~~~~~~~~
This application uses the acitoolkit. The installation steps for the
acitoolkit can be found at ``_.
MySQL database
~~~~~~~~~~~~~~
The ACI Endpoint Tracker uses the open source MySQL database to store
the Endpoint data. MySQL is installed separately and the installation
steps are dependent on the platform. It is recommended that MySQL be
installed in the same machine as the ACI Endpoint Tracker.
MySQL installation instructions for most platforms can be found here:
`MySQL installation instructions `_.
For Ubuntu, the installation instructions can be found here:
`Ubuntu MySQL installation instructions
`_.
Once the above package is installed, you should verify that the
MySQL database is running. In Linux and Mac OS X, this can be done by
entering the following command::
mysqladmin -u root -p status
If the database is running, the output should be similar to below::
Uptime: 358118 Threads: 3 Questions: 5767 Slow queries: 0
Opens: 109 Flush tables: 1 Open tables: 61 Queries per second
avg: 0.016
If the database is not running, the output should be similar to
below::
mysqladmin: connect to server at 'localhost' failed
MySQL Connector
~~~~~~~~~~~~~~~~
In order for the ACI Endpoint Tracker to communicate with the MySQL
database, the MySQL Connector/Python must be installed. This is
available for most platforms at
``_.
Flask
~~~~~
Flask is required for the optional GUI frontend. The installation
steps for Flask can be found at ``_.
.. _credentials:
Usage
-----
The ACI Endpoint Tracker serves as a conduit between the APIC and the
MySQL database. It requires login credentials to both, namely the
username, password, and IP address or URL.
The user can choose any **one** of 3 ways to specify the login
credentials. If multiple ways are used, they are taken in the
following priority order:
1. **Command Line Arguments**
The login credentials can be passed directly as command line
arguments. The command is shown below::
python aci-endpoint-tracker.py [[ -u | --url] ]
[[ -l | --login ] ] [[ -p | --password ]
] [[ -i | --mysqlip ] [[ -a
| --mysqladminlogin ] ]
where the parameters are as follows:
+----------------+------------------------------------------------+
+apicurl | The URL used to communicate with the APIC. |
+----------------+------------------------------------------------+
+apicusername | The username used to login to the APIC. |
+----------------+------------------------------------------------+
+apicpassword | The password used to login to the APIC. |
+----------------+------------------------------------------------+
+mysqlip | The IP address of the MySQL DB host. |
+----------------+------------------------------------------------+
+mysqladminlogin | The username used to login to the MySQL DB |
+----------------+------------------------------------------------+
+mysqlpassword | The password used to login to the MySQL DB |
+----------------+------------------------------------------------+
An example would be the following::
python aci-endpoint-tracker.py -u https://172.35.200.100 -l
admin -p apicpassword -i 127.0.0.1 -a root -s mysqlpassword
2. **Environment Variables**
The login credentials can be pulled from environment variables in
operating systems such as Mac OS X and various Linux distributions.
The environmental variables are as follows::
APIC_URL
APIC_LOGIN
APIC_PASSWORD
APIC_MYSQLIP
APIC_MYSQLLOGIN
APIC_MYSQLPASSWORD
These variables should be set to the correct value. Setting the
environment variable is OS dependent. For example, in Mac OS X,
environment variables can be set in your ``~/.bash_profile`` as
follows::
export APIC_URL=https://172.35.200.100
export APIC_LOGIN=admin
export APIC_PASSWORD=apicpassword
export APIC_MYSQLIP=127.0.0.1
export APIC_MYSQLLOGIN=root
export APIC_MYSQLPASSWORD=mysqlpassword
If environmental variables are used to specify the credentials,
then the following command will execute the ACI Endpoint Tracker.::
python aci-endpoint-tracker.py
3. **Importing a credentials.py file**
Alternatively, the login credentials can be pulled from a python
file named ``credentials.py``. In this file, it is assumed that
the following variables will be set appropriately for your
environment.::
URL = 'https://172.35.200.100'
LOGIN = 'admin'
PASSWORD = 'apicpassword'
MYSQLIP = '127.0.0.1'
MYSQLLOGIN = 'root'
MYSQLPASSWORD = 'mysqlpassword'
If a credentials.py file is used to specify the credentials,
then the following command will execute the ACI Endpoint Tracker.::
python aci-endpoint-tracker.py
What's it doing ?
-----------------
Once the ACI Endpoint Tracker is running, it will connect to the APIC
and pull all of the existing static and dynamic endpoints that are
currently connected to the fabric along with the relevant associated
information such as:
* Tenant, Application Profile, and EPG membership
* Interface to which it is connected
* Timestamp of when it connected to the fabric
This data is then inserted into a database called ``acitoolkit`` that
the ACI Endpoint Tracker will create. Within the database, it creates
a single table called ``endpoints`` where all of the endpoint
information will be inserted.
Once all of this information is collected, the ACI Endpoint Tracker
subscribes through the web socket interface to any updates to both
static and dynamic endpoints. When these updates such as endpoint
attachment, detachment, or move occurs, the database will be
immediately updated with the live data.
Note that updates to the database will only occur when the ACI
Endpoint Tracker is running.
Direct Database Query
---------------------
Once the data is in the database, the MySQL client can be used to
query the data directly. Using this method, the full power of SQL can
be used to provide deep insight into the network endpoint behavior.
To connect to the MySQL database, you can execute the following
command locally on the same host where the database is running.::
mysql -u -p
The client will then prompt for the MySQL database password. After
successfully entering the password, the MySQL prompt will come up as
shown in the screenshot below::
$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 145
Server version: 5.6.22 MySQL Community Server (GPL)
Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
At this point, the ``acitoolkit`` database should be available. The
available databases can be shown by entering the following command at
the prompt.::
mysql> show databases;
A sample output is shown below.::
+--------------------+
| Database |
+--------------------+
| information_schema |
| acitoolkit |
| mysql |
| performance_schema |
| test |
+--------------------+
5 rows in set (0.00 sec)
To switch to the ``acitoolkit`` database, enter the following
command.::
mysql> use acitoolkit;
The endpoint data is stored in a single table called ``endpoints``.
You can then display all of the endpoint data by the following
query (shown with a snippet of the output).::
mysql> select * from endpoints;
+-------------------+---------------+--------------+--------------+-------------+----------------+---------------------+---------------------+
| mac | ip | tenant | app | epg | interface | timestart | timestop |
+-------------------+---------------+--------------+--------------+-------------+----------------+---------------------+---------------------+
| 74:26:AC:76:80:5B | 192.168.1.133 | Tenant1 | Application1 | WEB | VPC1 | 2014-12-09 19:08:27 | 0000-00-00 00:00:00 |
| 00:50:56:94:D8:73 | 0.0.0.0 | Tenant1 | Application1 | WEB | eth 1/102/1/12 | 2015-01-13 23:48:15 | 0000-00-00 00:00:00 |
| 00:50:56:94:07:7E | 0.0.0.0 | Tenant1 | Application1 | WEB | eth 1/103/1/11 | 2014-12-19 00:58:16 | 0000-00-00 00:00:00 |
| 00:50:56:94:9A:1C | 192.168.0.5 | Tenant5 | Application1 | USER | eth 1/102/1/12 | 2015-01-05 15:29:13 | 0000-00-00 00:00:00 |
| 00:50:56:94:F3:CD | 0.0.0.0 | Tenant5 | Application1 | USER | eth 1/102/1/12 | 2015-01-13 23:49:33 | 0000-00-00 00:00:00 |
| 00:50:56:94:17:5E | 0.0.0.0 | Tenant5 | Application1 | WEB | eth 1/102/1/12 | 2015-01-10 01:55:40 | 0000-00-00 00:00:00 |
| 00:50:56:94:A9:B5 | 10.0.0.5 | Tenant5 | Application1 | WEB | eth 1/102/1/12 | 2015-01-05 15:29:13 | 0000-00-00 00:00:00 |
| 00:50:56:94:93:6F | 0.0.0.0 | Tenant5 | Application1 | WEB | eth 1/102/1/12 | 2015-01-10 01:55:40 | 0000-00-00 00:00:00 |
At this point, we can query the data using the SQL SELECT command. If
you haven't used SQL before, you may want to spend some time learning
some of the basic syntax related to the SQL SELECT command as it forms
the basis for all queries in the database.
Here are just a few example queries that are possible.
Various fields can be used to filter the results.
*Show all of the endpoint information for a specific tenant*::
mysql> select * from endpoints where tenant='cisco';
*Show all of the endpoints for a given EPG within a certain tenant*::
mysql> select * from endpoints where tenant='cisco' and epg='WEB';
*Show all of the endpoints that were on the network on 2014-12-25*::
mysql> select * from endpoints where timestart <= '2014-12-25'
and timestop > '2014-12-24';
*Show all of the history (attach, detach, move) for a particular
endpoint*::
mysql> select * from endpoints where ip='10.1.1.1' and
tenant='cisco';
Output can be limited to certain fields
*Show the current location of a given endpoint*::
mysql> select interface from endpoints where ip='10.1.1.1' and
tenant='cisco';
Unique fields can be shown using the ``distinct`` keyword.
*Show the EPGs with active endpoints on 2014-12-25*::
mysql> select distinct tenant,app,epg from endpoints where
timestart <= '2014-12-25' and timestop > '2014-12-24';
Counts can be provided for filtered data using the ``count`` keyword.
*Show the number of Endpoints active on 2014-12-25*::
mysql> select count(*) from endpoints where timestart <=
'2014-12-25' and timestop > '2014-12-24';
Wildcarding can be used with the ``%`` wildcard.
*Show the endpoints belonging to a given subnet*::
mysql> select * from endpoints where ip like '10.10.%';
GUI FrontEnd
------------
In addition to the very powerful MySQL interface, there is also a
GUI frontend that allows quick simple searching on the database using
a web browser. The GUI frontend leverages the `DataTables
`_ package.
Demo
~~~~
The usage of this GUI should be fairly intuitive and a
live demo with fake endpoint data can be found at the link below.
Please give it a try, specifically the Search function to get a feel
for how it works.
`ACI Endpoint Tracker GUI Demo `_
For instance, to see all of the endpoints for tenant 'cisco' simply
type cisco in the Search box. To narrow the search further to the
endpoints owned by tenant 'cisco' on leaf 102, type 'cisco 102' in the
Search box. Also, each column can be sorted by clicking on the arrows
found in each of the column headers.
Usage
~~~~~
To use the GUI front end locally on your own database, you simply need
to execute the ``aci-endpoint-tracker-gui.py`` file assuming you have
installed the Flask package as mentioned in the `Installation`_
section.
The GUI front end deals exclusively with the MySQL database and does
not communicate with the APIC, so it only requires the MySQL
credentials. These can be passed in the same manner as described for the ACI
Endpoint Tracker `credentials`_. ::
python aci-endpoint-tracker-gui.py -i 127.0.0.1 -a root -s
mysqlpassword
It should be noted that while the GUI does not communicate with the
APIC, as long as the Endpoint Tracker is running, the database will
contain the live data for the APIC.
License
-------
Copyright 2015 Cisco Systems, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.