Survol installation notes

SURVOL INSTALLATION NOTES

PYTHON PACKAGE INSTALLATION

Survol server-side code is a pure-Python module and as such can be installed like any module. The packages are available on the Python Package Index (Pypi), which is a repository of software for the Python programming language

Survol source distribution, complete package, can be downloaded and installed as any Python module.
Survol on Pypi (Test) , same content on test site.

The installation command is:

pip install survol

INSTALLATION FORM THE SOURCES

It is also possible to install Survol from the source code which is avalaible at two places:

Survol on Github: This is the main GIT repository; the project name is "survol".
Survol on Sourceforge: A backup source repository.

SOFTWARE REQUIREMENTS

Your machine needs a recent Python 2 or Python 3 interpreter. Great care is taken to ensure compatibility with all common Python versions.

The required Python modules are:

rdflib. Work is being done to eliminate this requirement.
psutil: Strictly speaking, is optional, but very convenient to have.

There are no other requirements. The rest is optional.

SOURCE REPOSITORIES

Survol can of course be installed from the sources, which are stored at two places:

Survol source distribution, on Pypy, complete package, can be downloaded and installed as any Python module.
Survol on Pypi (Test) , same on test site.

USING THE AD HOC CGI SERVER

Survol comes with a very simple CGI server started by the script survol/scripts/cgiserver.py . Therefore, it can run on very small platforms. Also, it is easy to run Survol on a user account with full read access rights.

$ cgiserver -h

Survol HTTP server:
cgiserver
    -p,--port=<number>      TCP/IP port number. Default is 8000
    -a,--address=<host>     IP address. Default value is local host name.
    -b,--browser=<program> Starts a browser
    -v,--verbose            Verbose mode

Example of commands:

$ cgiserver -b "C:\Program Files (x86)\Mozilla Firefox\firefox.exe"
$ cgiserver -b "C:\Program Files\Internet Explorer\iexplore.exe"
$ cgiserver -b webbrowser # Uses default browser.

APACHE SETUP

If your browser runs ActiveX, it is also possible to use Survol web pages with no agent.

Survol is based on a tree of Python scripts, all of them display information of the system the agent is running on. Some scripts do not need parameters: They will return information with no context: For example, all available databases, all detected machines on the network, all installed Python modules etc... Other scripts need parameters, as they display information about a specific object. For example; Files opened by a specific process. Columns of a SQL Server™ table. Processes connected to an Oracle™ database.

APACHE CGI SCRIPTS SETUP

Common Gateway Interface public domain logo

The HTTP Server Apache must be able to run all Python scripts residing under the directory survol/sources_types as CGI scripts. On Windows, it is necessary to specify to Apache which Python interpreter must be used to run the CGI scripts. On Windows, this is done in the registry, with various keys depending on the Windows operating system version.

On Windows 7, see the key HKEY_CLASSES_ROOT\.py\Shell\ExecCGI\Command : The key "Default" contains the program name, which can for example be:

C:\Program Files (x86)\Python32\pythonw.exe -u

With Windows XP, the command is the key itself. "C:\Python\3.2.3-0.3\pythonw.exe -u"

On Linux, all CGI scripts must be executable and the first line specifies the Pyton interpreter.
http://stackoverflow.com/questions/2036577/how-do-i-ignore-the-perl-shebang-on-windows-with-apache-2

APACHE CGI CONFIGURATION FILE

The configuration file httpd.conf must be edited. It is also possible to create a new survol.conf file, which is a preferred solution. In both cases, the content is similar to this lines, which suppose that the sources are copied in the directory C:/Projects/Survol:

AddHandler cgi-script .py

# Depending on where the sources are:
Alias /Survol "C:/Projects/Survol"
<Directory "C:/Projects/Survol" >
    Options Indexes FollowSymLinks Includes ExecCGI
    Allow from all
    AddHandler cgi-script .py
    ScriptInterpreterSource Registry-Strict
    SetEnv PYTHONPATH C:/Projects/Survol/survol
</Directory>

All HTTP results generated by scripts allow HTTP cross requests (Access-Control-Allow-Origin).
This permits to merge information from several agents, into a single browser session. It makes also possible for a static html page to load json URLs from remote agents.

TESTING INDIVIDUAL SCRIPTS

Once the core features are installed, it might be possible that some CGI scripts do not work, or not as expected. Errors are normally displayed when detected, and the Apache log file contains all the information writted to stderr. If this is not enough, a very powerful debugging technique is to run CGI scripts as command-line Python mode, by setting a couple of mandatory environment variables. This allows to test a program in isolation, possibly in a debugger, with full visibility on its context, inputs and outputs. Here is an example:

PYTHONPATH=/homez.85/primhilltc/survol/survol \
SERVER_NAME=debug.primhillcomputers.com \
SCRIPT_NAME=sources_types/CIM_ComputerSystem/mysql_databases.py \
QUERY_STRING="xid=CIM_ComputerSystem.Name%3Dprimhilltcsrvdb1.mysql.db&mode=json" \
python survol/sources_types/CIM_ComputerSystem/mysql_databases.py

With this command, the CGI script mysql_databases.py runs as if it is launched by a HTTP server.

SERVICE LOCATION PROTOCOL

openSLP logo

Service Location Protocol (SLP) defined by the Internet Engineering Task Force (IETF) allows networking applications to discover the existence, location, and configuration of networked services. It is already used by WBEM, and also by Survol, for the same reasons. The chosen implementation for Survol, is OpenSLP, which has been ported to a wide variety of systems. It is run with the slptool command from sub-processes. This prevents linking issues, 32bits/64bits compatibility problems etc... However, slptool command must be accessible from the Python scripts.

It might be helpful to pre-register some services in the file slp.reg. This is the right place to also register manually, WBEM services. An example of configuration is:

#
service:wbem:http://mymachine-hp,en,65535
description=OpenPegasus under Windows 7

# Definitions must be separated by an empty line.
service:survol:http://mymachine-hp:8000/survol/entity.py,en,65535
description=Survol Windows 7
#

SLP needs multicast, therefore some specific tuning network parameters and routers might be necessary. Because SLP is a standard, Survol is able to discover all WBEM service exposed with any implementation of SLP.

Return to Survol, its architecture, some use cases, see the FAQs, or Doxygen-generated pages here.