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
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:
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:
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
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
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.