<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
# Sensor Stubs

A service has been created to simulate the behavior of a sensor by sending canned telemetry data to a Kafka topic.  These "Sensor Stubs" consume fewer resources than the actual sensor that they replace.

### (Q) How do the sensor stubs work?

The stubs are installed with a set of canned data for each sensor type; Bro, Snort and YAF.  A subset of this canned data is randomly selected and sent to the Kafka topic in batches.  The timestamp of each message is updated to match current system time.  

### (Q) How do I configure the message rate?

The number of telemetry messages sent in each batch, along with the time delay between batches is configurable.  Before installation, these values can be configured by redefining `sensor_stubs_delay` and `sensor_stubs_count`.  The values can also be configured by altering the deployed system service script at `/etc/init.d/sensor-stubs`.

### (Q) How do I install the sensor stubs?

Using the default playbooks, this role can be installed by using the Ansible tag `sensor-stubs`.  This service is installed on the same hosts where the sensors would be; defined by the `sensors` host group.

The defaults for the "Full Dev" environment have been changed so that the Sensor Stubs are installed by default, rather than the sensors themselves.

### (Q) How do I use the sensor stubs?

Start all sensor stubs.  The output includes the PID for each running sensor stub.
```
$ service sensor-stubs start
Starting sensor-stubs...
       bro: Ok [26505]
       yaf: Ok [26507]
     snort: Ok [26509]
```

Check the status of each sensor stub.
```
$ service sensor-stubs status
Checking sensor-stubs...
       bro: Running [26505]
       yaf: Running [26507]
     snort: Running [26509]
```

Stop all sensor stubs.
```
$ service sensor-stubs stop
Stopping sensor-stubs...
..       bro: Ok [26505]
..       yaf: Ok [26507]
..     snort: Ok [26509]
```

Check the status.  All sensor stubs should be stopped.
```
$ service sensor-stubs status
Checking sensor-stubs...
       bro: Not running
       yaf: Not running
     snort: Not running
```

Start only the Bro sensor stub.
```
$ service sensor-stubs start bro
Starting sensor-stubs...
       bro: OK [11616]
```

Stop the Bro sensor stub.
```
$ service sensor-stubs stop bro
Stopping sensor-stubs...
..       bro: Ok [11616]
```

### (Q) How do I install the original sensors?

The default behavior can be changed by skipping the `sensor-stubs` flag and including the `sensors` flag. For example, to deploy "Full Dev" with the original sensors run the following command.

```
cd metron-deployment/development/centos6
vagrant --ansible-skip-tags="sensor-stubs,solr" up
```

### (Q) Where does the mock data come from?

The data produced by the sensor stubs was generated by running the sensors against the example pcap file that is distributed with Metron.  This ensures that the data produced by the sensor stubs is similar to the data produced when using the actual sensors.
