Miner | Salzburg Research > Documentation > Operating the MINER platform

Operating the MINER platform

Requirements

MINER is currently supported on Microsoft Windows (XP, Windows 7) and Ubuntu 12.04 LTS Server edition on x86 / x64 architectures. MINER requires a Java runtime version 7. Additionally, a database system with a JDBC connector is required. At the moment MySQL is supported (but other Hibernate supported databases, e.g. PostgresSQL and HSQLDB will probably work, too).

Not all MinerTools run on all platforms. As a MinerTool often wraps a native executable, these MinerTools are often bound to a specific operating system.

Installation

A MINER release is distributed as a single archive file which has to be unpacked. This is usually done on the machine that will host the MINER Server. A new directory miner is created. We refer to this directory as ~miner in the following description.

Directory in ~miner Description
clientlib Contains the libraries necessary for developing MINER applications.
core MINER Server
doc Documentation
init.d Start/Stop scripts for running MINER on Linux
toolproxy MINER ToolProxy

Configuration

Database

First of all, an empty database and a user with all permissions on this database must be setup in the database management system (DBMS). Please check with your DBMS documentation. The SQL scripts provided in ~miner/core/database may be useful in the process. As an example, the DB could be created via:

mysql -u $DB_ADMIN < miner/core/database/miner.sql

Server

The base directory of the Server is ~miner/core.

The configuration properties of the Server are defined in a Java properties file. By default, the configuration is initialized from ~miner/core/etc/miner.properties.

A different configuration resource can be defined by setting the Java System property miner.config (MINER_CONF) in the start script. Note that the value is relative to the classpath (e.g. ~miner/core/etc and not the base directory of the Server ~miner/core).

The configuration file is well documented and should be self-explanatory. While the default values will usually work well for most configuration options, there are of course no sensible defaults for the database connection. At least the parameters db.url, db.username, and db.password must be set properly.

# excerpt from miner.properties

# REQUIRED
# The JDBC URL to the database
db.url = jdbc:mysql://localhost/db_miner

# REQUIRED
# The database user name
db.username = john

# REQUIRED
# The database password for this user
db.password = secret

For all other configuration options and their explanations, please see the comments in the file ~miner/core/etc/miner.properties as shipped with the release.

ToolProxy

The toolproxy directory contains the files that are needed to run a ToolProxy. We refer to this directory as ~toolproxy. To setup a ToolProxy on a remote host, the toolproxy and init.d directories (and their subdirectories) must be copied to the remote machine. .

The configuration properties of the ToolProxy are defined in a Java properties file. By default, the configuration is initialized from ~toolproxy/etc/toolproxy.properties.  A different configuration resource can be defined by modifying the Java system property miner.toolproxy.config (TP_CONF) in the start script. Note that (unlike miner.config) this value is relative to the base directory of the ToolProxy (~toolproxy).

The default configuration file that ships with the release contains sensible default values for most parameters. There is only parameter that has to be modified: the server setting.

# excerpt from toolproxy.properties
# REQUIRED
# The host/IP of the MINER Core.
# This must correspond with the 'host' parameter as configured
# in ~miner/core/etc/miner.properties.
server = {SERVERHOST}
MinerTools

The tools property deserves a more detailed explanation. It is used to define the set of MinerTools that are utilized at this ToolProxy.

tools = etc/tools.txt

The value of the tools property is a URL that points to a text file. To point to a local file, a simple path/file reference is sufficient (e.g. "etc/tools.txt" instead of a full-blown URL). Multiple files can be referenced by separating the URLs with a semicolon (';').

The referenced file(s) contains 1 or more tool locations which can be defined in three different ways:

  • a URL
  • a filename of a local file
  • a local directory containing the tools

As described above, a MinerTool is always provided in the form of a Java Archive (.jar file).

An sample file containing all sorts of tool locations is shown below. Empty lines and lines starting with a hash ('#') character are ignored.

# Sample tools.txt

# tools from a URL
http://tools.company.com/com.company.miner.tool.IPPMTool_1.0.0.jar
http://tools.company.com/com.company.miner.tool.NetemTool_1.0.0.jar

# local tool by its filename (absolut or relative to the toolproxy binary)
snmptool/com.company.miner.tool.SNMPTool_1.0.0.jar

# all the tools in the local subdirectory tools
tools/

When the ToolProxy starts up, it prepares all the MinerTools referenced by these locations so that they can then be used in a Scenario. First, for each tool that is referenced by a http or ftp URL pointing to a remote location, the .jar file is downloaded. Then, the ToolProxy informs the MINER Server about all its available MinerTools.

Simple tool setup

While the mechanism described above allows for complex configurations, a simple setup is often sufficient. One such typical setup is the following:

# excerpt from toolproxy.properties
tools = etc/tools.txt

The file etc/tools.txt simply points to the local directory tools which contains several MinerTools in the form of .jar files:

# a simple etc/tools.txt file
tools/

Please note that, independent of any configuration, a MinerTool must never be placed in the plugins folder!

For all other configuration options and their explanations, please see the comments in ~toolproxy/etc/toolproxy.properties as shipped in the release.

Running the MINER platform

Linux

Basic shell scripts to start the MINER Server or ToolProxy are included in the distribution.

MINER Server

To start a MINER Server use run.sh in ~miner/core.  This will start a MINER Server in foreground and the standard log will be displayed. If you enabled additional logging in ~miner/core/etc/miner.properties the according log files can be found in ~miner/core/log/.

MINER ToolProxy

To start a MINER ToolProxy use run.sh in ~toolproxy.  This will start a MINER Server in foreground and the standard log will be displayed. If you enabled additional logging in ~toolproxy/etc/toolproxy.properties the according log files can be found in ~toolproxy/log/.

As daemons

Alternatively the MINER components can be run as deamons by using the rc.d-like scripts miner.sh and toolproxy.sh that ship in the ~miner/init.d directory. These scripts need root permissions and will also run MINER as root. Furthermore these scripts require the environment variable MINER_HOME to point to ~miner.

Like other rc.d-scripts they take parameters like start, stop or restart.

If MINER is installed to /opt/miner/ you can start a MINER Server and view the log by using the following commands:

export MINER_HOME=/opt/miner/
$MINER_HOME/init.d/miner.sh start
$MINER_HOME/init.d/miner.sh log

Windows

Basic batch files are provided to start MINER on Windows.

MINER Server

To start a MINER Server use run.bat in ~miner/core.  This will start a MINER Server in foreground and the standard log will be displayed. If you enabled additional logging in ~miner/core/etc/miner.properties the according log files can be found in ~miner/core/log/.

ToolProxy

To start a MINER ToolProxy use run.bat in ~toolproxy.  This will start a MINER Server in foreground and the standard log will be displayed. If you enabled additional logging in ~toolproxy/etc/toolproxy.properties the according log files can be found in ~toolproxy/log/.