seafelt 2.1
Copyright © 2006 Unicity Pty Ltd
1 December 2006
Table of Contents
Congratulations on your purchase of seafelt! We hope you'll enjoy many years of happy seafelting. To help you get started, we've written this user guide that will hopefully cover most of the ways that people might want to install seafelt and use seafelt.
If you're confused by something in this guide, or it doesn't
cover something that you'd like to see, please let us know! Email us
at <devteam@seafelt.com> and we'll do what we can to help.
Commandsthat need to be entered will be displayedlike this.Variablesor other placeholders are displayedlike this.Blocks of computer input or output are displayed like this.
![[Note]](/images/note.png)
An informational note will be displayed like this.
![[Warning]](/images/warning.png)
A warning will be displayed like this.
![[Caution]](/images/caution.png)
A caution will be displayed like this.
You will need to have access to the internet in order to obtain seafelt. We do not have any plans to deliver seafelt as hardcopy CDs or DVDs. We believe this would add unnecessary overheads that are better spent on developing seafelt.
The preferred method for installing seafelt is by using Debian or Ubuntu pre-compiled packages. The Debian package management system, APT, helps to manage the interdependencies between the various seafelt components as well as the other software packages that seafelt makes use of. Letting APT handle the dependencies means you don't need to know as much about seafelt in order to install and use it.
To use the Debian packages, add the following lines to your
/etc/apt/sources.list file:
deb http://seafelt.com/software binary/ deb-src http://seafelt.com/software sources/
There are a few ways you can install seafelt via packages. These methods are described below.
| |
Debian packages are currently only provided for Debian i386, Ubuntu i386 and Ubuntu amd64. If you use another package management system, or another operating system, you will need to convert the package format yourself or install from source. |
The seafelt backend consists of the discovery engine, multiple polling engines and some support libraries. It connects to a database to store the configuration information discovered about your network by the discovery engine, and the polling information collected from devices by the polling engines.
To install these components, grab the seafelt-backend package.
The seafelt frontend consists of a Plone package designed to provide a web frontend to the seafelt database. The package contains interface modules, reporting modules and a plone skin. The package name is seafeltSite.
To install these components, grab the seafelt-frontend package.
Once the package is installed, you can add the seafeltSite package to any Plone Site to convert it to a seafelt frontend portal. Instructions on how to do this are contained in FIXME: crossref to plone instance configuration.
If you want to have the package manager create a Zope+Plone instance for you with the seafeltSite package ready to add to the instance, add the seafelt-site package.
This package will ask you a few questions about your Zope webserver instance before installing an instance and starting it for you.
One of the great benefits of seafelt is that the license you purchase entitles you to a copy of the source code. If the binary packages aren't enough, you can obtain the sourcecode to the program from http://www.seafelt.com/download.
You will need to obtain the following source packages:
libsnmpseafelt-libchartseafelt-backendseafelt-frontend
Extract the files from each source archive into a temporary area
somewhere on your system. You will need root access to install
the packages, unless you wish to override the default install
locations using the --prefix
option. Install the software using the following command:
python setup.py install
For more control over the installation process, see the
--help output.
seafelt makes use of a variety of other open source software that you will need to obtain in order to use seafelt. If you are installing seafelt from source code, you will have to manage the software dependencies yourself.
The following software packages are required for version 2.1 of the seafelt:
Python, version 2.3 or above.
PostgreSQL, version 8.1 or above.
matplotlib, version 0.82 or above.
Zope, version 2.8
Plone, version 2.1.1
The seafelt backend is the heart of seafelt's monitoring capabilities. It is the backend that handles device and element discovery, element polling and storage of poll results in the database.
This section assumes you have the PostgreSQL database engine server and client components installed. How to do this is beyond the scope of this book, but a good place to start for help would be the PostgreSQL website.
The database server can be installed on a completely different server to the seafelt backend as all communication with the database is done via TCP/IP. Alternately, you can run all seafelt components on a single server and the loopback interface will be used to connect via TCP/IP.
You will need to configure the PostgreSQL server to accept
connections from the host you plan to run the seafelt backend and
frontend on. If you're planning to run multiple backends or
frontends, you'll need to add them all. This is done by editing
the PostgreSQL pg_hba.conf file. Under linux,
this file is usually found in
/etc/postgresql/version/main.
To allow any client that can connect to the database server access to the databases via password authentication, add a line like this:
host all all all md5
For more advanced database access control, see the PostgreSQL documentation.
You will need at least one database user to manage your
database. The default is to use a single, trusted user for the
seafelt database, such as seafelt. To create
a new database user, use the following PostgreSQL command:
createuser seafelt
Make sure you give this user the ability to create databases.
seafelt uses a single database instance to contain the poller configuration and poll data. A single instance can be shared between multiple pollers to distribute load between the pollers. In most cases, a single database instance is all that you'll need, however for more advanced uses of seafelt that require multiple database instances, see the online documentation at http://www.seafelt.com/documentation.
You can create an instance manually, but the easiest way is to use the provided script seafelt-mkinstance to set up a new instance for you. You will need some information to provide the script, so find this information now if you haven't already.
- Database Hostname or IP Address
The resolveable hostname or IP address of the system running your database server.
- Database Server Port
The port your database listens on for incoming connections. The default is
5432.- Instance Name
This is optional. If you want to give your instance a symbolic name, go right ahead. You'll need to keep a note of it as the instance name is used elsewhere and you may need to let other components know if you don't use the default.
The default is
.seafelt_default- Database Username
The username you created for use with seafelt.
- Database Password
The password for the database username.
You can now create a new seafelt instance using seafelt-mkinstance as follows:
#seafelt-mkinstanceinstance_name
If you omit the instance_name, a
default instance called seafelt_default will
be created.
| |
seafelt installs its instances into
/usr/var/seafelt/instances by default.
|
The output should look something like this:
seafelt@fnord:~$ seafelt-mkinstance --instance doctest 2006-11-24 12:17:06 INFO (seafelt-mkinstance) Creating instance directory /usr/var/seafelt/instances/doctest... 2006-11-24 12:17:06 INFO (seafelt-mkinstance) Creating database doctest... Password: CREATE DATABASE 2006-11-24 12:17:16 INFO (seafelt-mkinstance) Setting db.conf parameters... 2006-11-24 12:17:16 INFO (seafelt-mkinstance) Creating database tables... 2006-11-24 12:17:18 INFO (seafelt-mkinstance) Loading base database configuration. This may take a while... 2006-11-24 12:19:09 INFO (seafelt-mkinstance) Database load complete. 2006-11-24 12:19:09 INFO (seafelt-mkinstance) seafelt instance doctest is ready for discovery.
Your seafelt instance is now configured and ready for device discovery, which is covered in Chapter 3, Discovering Devices and Elements.
If you need to create a seafelt instance manually for some reason, here's how to do it.
Create a new instance database using the PostgreSQL createdb command:
#createdbseafelt_defaultCopy the instance template directory to a new instance directory. The directory name must match your instance name.
#cd /usr/var/seafelt/template#find . -print | cpio -pdumv ../instances/seafelt_defaultEdit the database configuration file
/usr/var/seafelt/instance/in the new instance directory using your favourite text editor. There is a sample configuration file calledseafelt_default/db.confdb.conf.sampleyou can use as an example.The format of this file is a dsn string, similar to the following:
host=
localhostdbname=seafelt_defaultusername=seafeltpassword=seafeltport=5432Default values are used if you do not supply one of the fields.
Create the database structure using the seafelt-config command:
#seafelt-config --debug=warn --instance=seafelt_default--bootstrapLoad the core database configuration using the seafelt-config command:
#seafelt-config --debug=warn --instance=seafelt_default--loadThis step can take quite a while on slower servers.
The seafelt backend is now configured and ready for the next stage: discovering devices and elements. This is covered in Chapter 3, Discovering Devices and Elements
In order to start polling devices, and the elements they contain, they need to be added into the database. Unlike some other products, seafelt makes this easy through the use of its discovery engine. Rather than having to manually add devices and elements, seafelt has a highly configurable method of scanning for supported devices and elements and adding them into the database in the correct way.
You first need to decide what sort of elements you want to discover. Do you want to add just the local host, your local subnet, or the entire Internet? Do you want to discover SNMP managed elements, or specific TCP ports? seafelt can make a lot of decisions on its own, but it does need a little bit of help to begin with.
In order to monitor SNMP elements, a device will need to have an SNMP agent installed. There is a multitude of books on SNMP, and hundreds, if not millions, of pages on the web about it, so this guide will not go into detail on how to install and configure an SNMP agent on your hosts.
You may not be interested in learning about how to manipulate the discovery engine and just want to see some charts. Happily, this is really easy. You just need to point the discovery engine at whatever you want to discover. If you're discovering SNMP elements, use seafelt-snmp-discover and if you're discovering TCP elements, use seafelt-tcp-discover. The commands work like this:
usage: seafelt-snmp-discover [options] <device | IP | network> usage: seafelt-tcp-discover [options] <device | IP | network>
Just point the tool at whatever you want to discover. You can
discover a single device by name or IP address, or you can
specify an entire block of IP addresses using 'slash' notation
such as: 192.168.1.0/24. You can
specify more than one thing to discover by adding it on the end,
using spaces to separate them. You can also mix and match
devices, IP addresses and networks.
The discovery engine will attempt to guess some standard
parameters, such as the SNMP version and community string, but
if it fails to discover something, you can help it out by adding
options. For a full list of the supported options, run the
command with the --help option.
If this is a new seafelt installation, the database will not contain any elements to poll, or any poll information to report on. This is fairly boring, so it would be a good idea to add some elements into the database somehow. You can add both SNMP elements as well as arbitrary TCP ports into the database for monitoring. It is also possible to extend seafelt to monitor other kinds of elements, but for information on how this is done, please see http://www.seafelt.com/documentation
Let's assume you would like to start out by just monitoring the host that seafelt is running on. To do this, you would run the following command:
seafelt-snmp-discover localhost
This will attempt to discover elements on your local host:
2006-11-24 12:33:32 INFO (seafelt-snmp-discover) seafelt-snmp-discover 2006-11-24 12:33:33 INFO (discover) pushing ipaddr 127.0.0.1 onto device discovery queue 2006-11-24 12:33:33 INFO (discover) trying 127.0.0.1, 2c, 161, public 2006-11-24 12:33:40 INFO (discover) failed to discover 127.0.0.1 public 2c 161 2006-11-24 12:33:40 INFO (discover) trying 127.0.0.1, 1, 161, public 2006-11-24 12:33:47 INFO (discover) failed to discover 127.0.0.1 public 1 161
As you can see, seafelt attempts to use both SNMP v1 and v2 when discovering
SNMP elements, using the standard port for SNMP (161) and the default
SNMP community string of public. From this example,
we can see that either SNMP is not enabled for the local host, or it is
running on a different port, or the community string is set to something else.
If the SNMP device you are attempting to discover is listening on a different port, or has a non-default SNMP community string set, you can provide seafelt with the value to use:
seafelt-snmp-discover --snmp-community seafelt --port 162 --port 15667 localhost
As you can see, you can give seafelt a list of options and it will try each one in turn. In this way, you can discover elements on devices with different community strings, or with different ports, with a single command.
As seafelt discovers devices and elements, it provides a lot of information about what it is doing, so you can see what sorts of information it has found. It can prove quite enlightening to watch seafelt discover printers, copiers and linux servers you didn't even know you had.
If something about a device that seafelt is monitoring changes, you will want to update seafelt with the new information. You can do this by rediscovering devices. Instead of having to provide a list of all your devices, or rediscovering entire network blocks (which would take some time), seafelt assumes you want to update its information if you simply run discovery with no devices specified:
seafelt-snmp-discover
seafelt checks its database for the devices it knows about and uses its recorded settings to rediscover them. You can still provide extra options, in case you've changed the SNMP community string on some devices. seafelt will then update the database with any changes it detects, leaving unchanged information as it is.
If you only want to update the information for a subset of the devices in the database, specify just those devices for rediscovery and seafelt will leave the other devices and elements as they are.
The seafelt frontend is a web-based reporting engine that allows you to view the information collected by the seafelt backend in useful ways.
The seafelt frontend is a Zope/Plone package that is installed in a Plone portal. If you used the APT method for installing seafelt, you will already have a plone portal ready for configuration. If not, you will need to add a Plone portal to a Zope instance.
Installing Zope and setting up instances is beyond the scope of this guide, so refer to the Zope documentation for how to do this. You will need to load up a web browser, such as Firefox and browse to where you have installed your Zope instance.
Browse to the Zope Management Interface, or ZMI. You should see a list of the items that are automatically created in a Zope instance. At the top right of the main frame, there is a pulldown list that is used for adding new items to the instance. Scroll down the list until you find one called Plone Site.
You will be prompted to enter some identifying details for the new portal. The id you choose will be used in the URL for the portal. Once you have entered some details, click on .
Now that the Plone site has been added, you will need to add the seafeltSite product to the site. To do this, select on the top right of the page, and then select from the left side of the page. You should now see the Add/Remove Products screen.
Select the seafeltSite product from the list on the left by ticking the checkbox. Now click on .
The look of the screen should change as the seafeltSite package is installed into the portal. You may need to flush your browser's cached objects by clicking Reload with the Shift key held down. You should see seafeltSite appear in the list of installed products on the right. Click on the seafelt logo at the top left to be taken to the main seafelt screen.
You're now ready to link your seafelt frontend with a seafelt backend and start looking at some reports.
DataSources are objects that the seafelt frontend uses to communicate with databases, such as the seafelt backend PostgreSQL database. Query objects use DataSource objects to submit their queries to a database, and to receive the results back from the database for further processing.
| |
| The seafelt frontend currently only supports two database types: PostgreSQL and MySQL. Other databases will require a Zope Database Adapter in order to be included in the supported list of databases. |
A default DataSource, called
default-datasource, is created in the
Data Sources folder of the seafelt frontend
during the installation process. The frontend knows
to look for this DataSource as a last result when it need to
fetch some data from a database.
You will need to check the default DataSource is able to communicate with your seafelt backend database. Navigate to it, and click on the edit tab to verify the setting are correct. Save any changes you make, and the DataSource will verify that it can connect to the database you specify.
You can configure other DataSources to take precedence over
the default DataSource. If a Query isn't configured to use a
specific DataSource, it will look for a datasource
called default-datasource in its own
folder first, then the parent folder, then the parent's
parent, and so on. If a Query cannot find a DataSource this
way, it will use the default DataSource.
Using this method, you could configure one set of Queries to use a seafelt backend database, while another set of Queries could use a MySQL database that holds your MythTV configuration. Yet another DataSource could connect to a PostgreSQL database used for storing... well, anything at all. You can then use the seafelt frontend to report on all three at once.
For more information on how to report on multiple DataSources at once, see ???.
Now that you have linked the seafelt frontend with a seafelt backend, you can start reporting on the data in the database.
Once you have your seafelt backend configured and running, you will spend most of your time running reports on the information that is collected. seafelt makes it easy to summarise information about a large number of elements while still providing the ability to quickly drill into the information to find out something specific.
The reporting engine is designed to be modular. There are four important components that are used to generate reports:
- DataSource
DataSources are used to connect the seafelt frontend to a database. Multiple DataSources can be configured, each pointing to a different database.
- Query
Queries are used to extract information from DataSources. Queries contain SQL statements that are sent to the database by a DataSource. There is a special class of Query called an ElementQuery that is used to query a seafelt backend DataSource for information about seafelt elements. Generic Queries can be used with any SQL database.
- Reporter
Reporters take information obtained by Queries and present it as one or more tables or charts.
- MultiReporter
A MultiReporter collects multiple Reporters together, hence the name. A MultiReporter can even collect together other MultiReporters.
Let's take a quick tour of some example reports that are provided by the base level seafelt. There are two major types of information that people generally want to see: summary information about several things, and specific information about something.
The best example of a summary report is the Dashboard. By default, the Dashboard is configured to provide an example report made up of several other reports. Go to the main seafelt screen and click on the Dashboard icon.
This Dashboard report contains a few tables with some Top N information. The first report shows a list of interfaces, ordered by how often they have reset in the last 24 hours. Things are looking pretty good here, with no interfaces resetting in the last 24 hours. The second table lists the top 10 busiest interfaces, and as you can see, there's not a lot of traffic.
To the right of each table is an Available Reports column. Each cell in this column contains a pulldown list of reports that can be run using the information in the row of the report. Whenever a Reporter is in table mode, it will scan the frontend for any Reporters that are compatible with the rows in the table. If you add any reports of your own, they will show up in this list automatically if they are compatible with the information in the table.
This is also a Group Report pulldown list underneath each table report. This set of reports is compatible with the whole set of rows, rather than just individual rows. Some reports are more general than others; a report on CPU utilisation isn't much good for a storage element that has information about disk utilisation, but not CPU. The general element performance report can handle both element types though, so it would show up in this sort of list. Again, if you add your own reports to seafelt, they will be automatically detected as compatible and added to the Group Report pulldown when appropriate.
For an example of a report on something specific, click on one
of the elements in the first table of the Dashboard
report. This will take you to the Element Performance Report for the element.
In this example, we've chosen an ethernet interface on one of the development
servers, called fnord.
Here we have an ElementChart. The ElementChart is a seafelt specific charting type
that displays performance information as a line chart over time with the seafelt
HealthBar underneath. This chart shows the performance of the primary network
interface eth0 for
fnord over the past 36 hours, and we know that
it was available the whole time as the HealthBar is completely green.
Have a browse around with seafelt to check out some of the reports that are supplied with the package. The navigation bar on the left will show you the various report folders and reports that are available. Most reports have sensible defaults that you can use to start looking at your data straight away. If you can't find a report that shows you what you want to see, you can build your own report, which is covered in ???.
There is a feature of seafelt that is easy to overlook: you can use the seafelt frontend to report on more than just seafelt data. By using multiple DataSources, you can create reports in seafelt that use data from a variety of databases. You can create singular reports on these other databases in the same way as for a seafelt database. You can also gather these reports together in MultiReporters to present them all on one page, as in this example:
This MultiReport gathers together a report on programs recorded by MythTV recently, and performance reports from seafelt. Using this method, you can create single page reports on multiple seafelt instances, together with database from MythTV, your blogging engine backend, whatever you like.