Translations of this page:


Osmius Agent for SSH
Agent name: osm_ag_SSHDEVIC Agent code: SSHDEVIC
Content: Osmius agent for SSH devices User Manual
Date: 2010/02/05 Revision Date:

General Information

This agent can monitor SSH devices remotely. It has been tested in different environments. However, we recommend checking its functionality before implanting it in a production environment.

SSH agent has been developed using functionalities and enhancements of Osmius framework and ACE libraries, so it is necessary to install the ACE libraries for the proper deployment and operation of SSH Osmius agent. See chapter: installation.

In addition, we have used LIBSSH2 library to develop this agent, if you are planning compile this agent by yourself, you have to install it before. Take a look to prerequisites section

SSHDEVIC agent provides up to 24 basic events with configuration parameters to allow scaling of a very simple way.

All events are remote, so not intrusive. Monitoring is done through the network connection, by this reason you have to provide some connection information, see connection information. Events are based on remote command execution through ssh session. You need ssh service available on monitoring target machine and you also must know login credentials.

NOTE: This agent uses a library for the SSH connection called LIBSSH2
that causes high CPU consumption for a very short period of time.
We are waiting for the new version to see if this behavior stops.
Consider this fact.

SSH Instance

As a general rule each Osmius agent can monitor one instance type. If you are not familiar with these concepts check out the glossary. Each instance is individually defined in the configuration file (if you want further information go to agents and instances); depending on agent type is the instance type and depending on instance is the connection info.


The connection information or connection_info is data that the agent needs to know to connect to the instance. (See more about the connection_info

For SSH Osmius agent the connection_info prototype would be:


Replace the following:

  • HOST: IP address or host name of monitoring target system. Mandatory.
  • USER: SSH access granted username. Mandatory.
  • PASSWORD: password for user specified above. Mandatory.


CONECTION_INFO = -h -u username -p pass
CONECTION_INFO = -h -u useralpha -p passalpha

OBSERVATION: For security reason only 22 port is allowed.


The type defines the instance type to be monitored. Every declared instance must be associated with a type as you can see here

For SSH:


Event summary table for SSH

Here's briefly the capabilities of this agent, further down on this page each event is described in more detail.

EVENT DESCRIPTION c w a tseconds Extra parameters / Remarks
SHCUST00 Execution of command defined by user 0 X Y T s -L “command to launch”
You can build up to 24 events: SHCUST00, SHCUST01, SHCUST02, SHCUST03, SHCUST04, … SHCUST23
“Silent mode ( -s) recommmended

SSH agent events


SHCUST00 event runs a user-defined command against the instance in which it is declared. Returns the command output as text associated with the event, and if the output is numerical returns that number as the event value. On failure or empty output -1 is returned. If the command returns text, this event will return 0 on successful completion and -1 in other case.

Extra parameters:
This event need an extra parameter to work:

-L -L “command to execute” - command that the user wants to run.
Not allowed: (”) or “rm” command

Return values:

-1 Error or null output (empty) of command
X Return value in command output

Recommended parameters:

Comparison type Direct or Inverse.
Monitoring interval 15 seconds – 1 month –> depends on event goal
Warning threshold User defined
Alert threshold User defined

Parameter setting example:

SHCUST00 = -t 60 -c 0 -w 1 -a 1 -T "port 80 connections" -L "lsof -i :80 | wc -l"


This event is extremely useful and necessary for the monitoring ssh capable devices, allowing the user to enter a command line that is executed on the remote system, the output that the command produces will be recovered. \ \ This event does not allow the invocation of the command “rm” (for security). It is not allowed the use of double quotes ( ”) in the command to run (replace by single quotes [']). \ \ You may change, taking care with the changes make to these files, and keeping us informed of your improvements. Anyway Osmius is free software and you can change the code to better fit your needs. \ \ You may declare up to 24 custom events: SHCUST00, SHCUST01, SHCUST02, SHCUST03, SHCUST04 … SHCUST23, with various extra parameters.

SSH agent prerequisites

In order to compile, this agent requires a set of prerequisites, which are generic to compile any Osmius agent, you can see these prerequisites.

LIBSSH2 libraries are needed for the platform where you want to compile the agent. It is also necessary access through SSH to the target system.


For Unix-like platforms is easy to find and install this packet.

We have done it manually and the steps are the following:

./configure --with-openssl
make check
make install
  • Move “libssh_config.h” file to the directory with all libssh2 includes, by default /usr/local/include/libssh2

For Windows, there are some tricks you should know:


Also you need to access the system via SSH to monitoring. \ \ Make sure you have valid credentials to access via SSH.

SSH agent makefiles and compilation

  • Make Project Creator (MPC) is used by Osmius, so creating Makefiles is a trivial task. If you want to learn more about MPC and Osmius check out the section of Makefiles on Osmius.
  • In the particular case of Osmius SSH agent you can easily generate Makefile as follows:

Modify osm_ag_ssh.mpc file to set libraries and includes paths:

// -*- MPC -*-
// $Id$
project(*Osmius) : aceexe, ace_openssl {
  exename = osm_ag_SSHDEVIC
  install = $(OSM_ROOT)/bin
  libout  = $(OSM_ROOT)/lib
  after  += ACE_SSL_lib
  libs   += ACE_SSL

  includes +=/usr/local/include/

  libpaths += /usr/local/lib/
  libs   += ssh2

  Source_Files {
  Header_Files {

From the agent directory using console or terminal.

$ACE_ROOT/bin/ -type make osm_ag_ssh.mpc
  • Now that you have created the Makefile, agent compiling is extremely simple.
make -f Makefile.Osm_Ag_Ssh_Osmius

Binaries are automatically installed in the bin directory of OSM_ROOT base directory.

Run SSH agent

SSH agent have the same running features of the other Osmius agents. You can check it out int he section Start and Stop Agents.

To run SSH agent without Osmius web console:

osm_ag_SSHDEVIC -c osm_ag_SSHDEVIC.ini -m MASTERAG -p 1950 -d [>> osm_ag_sshdevic.log]1)

Running in standalone mode

SSH Osmius agent, like the others Osmius agents, allows the execution in standalone mode. This option may be particularly useful when developing a new agent or to perform specific agent tests.

Basically you have to add a new value, called SNDCMD, to SSH Osmius agent configuration file (osm_ag_SSHDEVIC.ini) as shown here.

Then you must run the Osmius SSH agent setting Master Agent communications port to zero, for example:

osm_ag_SSHDEVIC -c osm_ag_SSHDEVIC.ini -m 00000000 -p 0 -d

Tests list

Performed test for Osmius SSH agent.

Date: 11/12/2009
Test Results Comment
Creating an instance with all its events in silent mode OK N/A
Creating an instance with all its events with custom text OK N/A
Creating an instance with all its events but no custom text OK N/A
Declaration of 3 instances with all its events to 5 seconds and keep it
running for 48 hours
- N/A
Declare 2 instances, cause a disconnect and then reconnect OK N/A
Declare 1 instance and test each event OK N/A
Elimination of general parameter and check unbootable OK PORTCM erased
Elimination of instance CONN_INFO and check unbootable OK N/A
1) Optional, to store agent messages in a file
en/agentes/sshdevic.txt · Last modified: 2012/12/05 19:23 by osmius
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki