<commit_before>Boundary Shell Plugin
=====================

Boundary Shell plugin is generic plugin that allows the use of any program or scripting language to produce metrics for the Boundary Premium product.

Additionally the Shell plugin includes:

1. Example scripts that collect metrics
2. Example dashboards that display metrics

The Shell plugin requires that you have python 2.6.6 or later installed on the target system.

## Adding the Shell Plugin to Premium Boundary

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)
3. Click on the _Plugins_ in the settings dialog: ![](src/main/resources/settings_plugins_dialog.png)

4. Locate the _shell_ and click on the _Install_ button.
![foo](src/main/resources/plugins_available.png)

5. A confirmation dialog is displayed indicating the plugin was installed sucessfully, along with the metrics and the dashboards:
![foo](src/main/resources/plugin_install.png)

6. Click on the _OK_ button to dismiss the dialog.

## Removing the Shell Plugin from Premium Boundary

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on the _Plugins_ in the settings dialog which lists the installed plugins: ![foo](src/main/resources/plugin_installed_settings.png)
4. Locate the _shell_ plugin and click on the item, which then displays the uninstall dialog:
![foo](src/main/resources/plugin_details_uninstall.png)

5. Click on the _Uninstall_ button which displays a confirmation dialog along with the details on what metrics and dashboards will be removed.![foo](src/main/resources/plugin_uninstall.png)

6. Click on the _Uninstall_ button to perfom the actual uninstall and then click on the _Close_ button to dismiss the dialog.

## Configuration

Once the Shell Plugin is installed a metric to be collected requires configuration. Any metric collection requires that a _relay_ is installed on the target system. Instructions on how to install a relay for linux/unix can found [here](http://premium-documentation.boundary.com/relays), and for Windows [here](http://premium-support.boundary.com/customer/portal/articles/1656465-installing-relay-on-windows).

General operations for plugins are describe in this [article](http://premium-support.boundary.com/customer/portal/articles/1635550-plugins---how-to)

### Overview of the Steps to Create a Shell Plugin Metric

1. Define the metric
2. Write the script that collects the metric (see _Shell Plugin Protocol_)
3. Configure the metric in the Shell plugin.

### Configuring an Example Shell Plugin Metric

#### Defining a Metric

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on _Metrics_ in the left hand side of the dialog which then displays the _Metrics_ dialog:
![](src/main/resources/metrics_dialog.png)

4. Click on the _Create Metric_ button which displays a form to define a new metric. Fill out the form as shown here:
![](src/main/resources/create_metric.png)

5. Click on the _Save_ button to create the metric.

6. Click on the _Close_ button to dismiss the dialog.

#### Write a Script that Collects the Metric

This step is going to be short cut by providing an already created script the counts the number of files in a directory. The example script is called [nfiles](scripts/nfiles.sh)


#### Configuring a Metric within the Shell Plugin
1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on the _Relay_ to display the list of installed Relays.
![](src/main/resources/installed_relays.png)

4. Click on a relay in the list which then shows a list of the plugins installed on the Relay.
![](src/main/resources/relay_plugin_list.png)

5. Click on the _Add a plugin_ drop down menu and select _shell_.
![](src/main/resources/add_metric_dialog.png)

6. Click on the _Add a Metric Command_ fill out the form as shown here and the click on _OK_:
![](src/main/resources/add_metric_command_form.png)

7. Click on the _Save_ button to save the configuration.
![](src/main/resources/save_metric_command.png)

8. The relay console is then displayed showing the plugin loading. Click on the _Close_ button to dismiss the dialog.
![](src/main/resources/relay_console.png)

#### Creating a Dashboard to Display the Metric

See [Building a Dashboard - How To](http://premium-support.boundary.com/customer/portal/articles/1635547-building-a-dashboard---how-to) to create a dashboard to display the metric configured above.

#### Enabling Debug

To aide in the development of your custom metric script you can enable debug, by checking the _Debug_ checkbox in the Metric Command definition form. This enables logging of the the command executed and the output that is produced by the command.

## Shell Plugin Protocol

Collection of your own defined metric requires a program or script to:

1. Collect, by any means the desired metric
2. Write the collected metric value, along with the metric name, and source to [standard output](http://en.wikipedia.org/wiki/Standard_output) with an accompanying new line.

Here Bash shell code snipet that illustrates:

```bash
### Collect the metric

# List the directory, count the lines, and remove white space
file_count=$(ls -1 $directory_path | wc -l | tr -d ' ')

### Write the metric standard out

echo "FILE_COUNT $file_count $(hostname)"
```

Here is yet another snipet that gets the collects and outputs the processor load in a single line of code:

```bash
echo $(uptime) $(hostname) | awk '{printf("LOAD_1_MINUTE %s %s\nLOAD_5_MINUTE %s %s\nLOAD_15_MINUTE %s %s\n",$8,$11,$9,$11,$10,$11)}'
```
## Examples
Boundary Shell Plugin bundles several examples that illustrate how to create your metrics using a program or script:

- CPU Load
- File Space Capacity
- Process Count
- Port Scan
- Random
- Windows Power Shell

### CPU Load

Collects the CPU load for the last 1,5,and 15 minute intervals.

Uses the following metrics:

- `BOUNDARY_CPU_LOAD_1_MINUTE`<commit_msg>Fix awkward sentence and missing words<commit_after>Boundary Shell Plugin
=====================

Boundary Shell plugin is generic plugin that allows the use of any program or scripting language to produce metrics for the Boundary Premium product.

Additionally the Shell plugin includes:

1. Example scripts that collect metrics
2. Example dashboards that display metrics

The Shell plugin requires that you have python 2.6.6 or later installed on the target system.

## Adding the Shell Plugin to Premium Boundary

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)
3. Click on the _Plugins_ in the settings dialog: ![](src/main/resources/settings_plugins_dialog.png)

4. Locate the _shell_ and click on the _Install_ button.
![foo](src/main/resources/plugins_available.png)

5. A confirmation dialog is displayed indicating the plugin was installed sucessfully, along with the metrics and the dashboards:
![foo](src/main/resources/plugin_install.png)

6. Click on the _OK_ button to dismiss the dialog.

## Removing the Shell Plugin from Premium Boundary

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on the _Plugins_ in the settings dialog which lists the installed plugins: ![foo](src/main/resources/plugin_installed_settings.png)
4. Locate the _shell_ plugin and click on the item, which then displays the uninstall dialog:
![foo](src/main/resources/plugin_details_uninstall.png)

5. Click on the _Uninstall_ button which displays a confirmation dialog along with the details on what metrics and dashboards will be removed.![foo](src/main/resources/plugin_uninstall.png)

6. Click on the _Uninstall_ button to perfom the actual uninstall and then click on the _Close_ button to dismiss the dialog.

## Configuration

Once the Shell Plugin is installed a metric to be collected requires configuration. Any metric collection requires that a _relay_ is installed on the target system. Instructions on how to install a relay for linux/unix can found [here](http://premium-documentation.boundary.com/relays), and for Windows [here](http://premium-support.boundary.com/customer/portal/articles/1656465-installing-relay-on-windows).

General operations for plugins are describe in this [article](http://premium-support.boundary.com/customer/portal/articles/1635550-plugins---how-to)

### Overview of the Steps to Create a Shell Plugin Metric

1. Define the metric
2. Write the script that collects the metric (see _Shell Plugin Protocol_)
3. Configure the metric in the Shell plugin.

### Configuring an Example Shell Plugin Metric

#### Defining a Metric

1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on _Metrics_ in the left hand side of the dialog which then displays the _Metrics_ dialog:
![](src/main/resources/metrics_dialog.png)

4. Click on the _Create Metric_ button which displays a form to define a new metric. Fill out the form as shown here:
![](src/main/resources/create_metric.png)

5. Click on the _Save_ button to create the metric.

6. Click on the _Close_ button to dismiss the dialog.

#### Write a Script that Collects the Metric

This step is going to be short cut by providing an already created script the counts the number of files in a directory. The example script is called [nfiles](scripts/nfiles.sh)


#### Configuring a Metric within the Shell Plugin
1. Login into Boundary Premium
2. Display the settings dialog by clicking on the _settings icon_: ![](src/main/resources/settings_icon.png)

3. Click on the _Relay_ to display the list of installed Relays.
![](src/main/resources/installed_relays.png)

4. Click on a relay in the list which then shows a list of the plugins installed on the Relay.
![](src/main/resources/relay_plugin_list.png)

5. Click on the _Add a plugin_ drop down menu and select _shell_.
![](src/main/resources/add_metric_dialog.png)

6. Click on the _Add a Metric Command_ fill out the form as shown here and the click on _OK_:
![](src/main/resources/add_metric_command_form.png)

7. Click on the _Save_ button to save the configuration.
![](src/main/resources/save_metric_command.png)

8. The relay console is then displayed showing the plugin loading. Click on the _Close_ button to dismiss the dialog.
![](src/main/resources/relay_console.png)

#### Creating a Dashboard to Display the Metric

See [Building a Dashboard - How To](http://premium-support.boundary.com/customer/portal/articles/1635547-building-a-dashboard---how-to) to create a dashboard to display the metric configured above.

#### Enabling Debug

To aide in the development of your custom metric script you can enable debug, by checking the _Debug_ checkbox in the Metric Command definition form. This enables logging of the the command executed and the output that is produced by the command.

## Shell Plugin Protocol

Collection of your own defined metric requires a program or script to:

1. Collect, by any means the desired metric
2. Write the collected metric value, along with the metric name, and source to [standard output](http://en.wikipedia.org/wiki/Standard_output) with an accompanying new line.

Here is a Bash shell code snipet that illustrates:

```bash
### Collect the metric

# List the directory, count the lines, and remove white space
file_count=$(ls -1 $directory_path | wc -l | tr -d ' ')

### Write the metric standard out

echo "FILE_COUNT $file_count $(hostname)"
```

Here is yet another snipet that collects and outputs the processor load in a single line of code:

```bash
echo $(uptime) $(hostname) | awk '{printf("LOAD_1_MINUTE %s %s\nLOAD_5_MINUTE %s %s\nLOAD_15_MINUTE %s %s\n",$8,$11,$9,$11,$10,$11)}'
```
## Examples
Boundary Shell Plugin bundles several examples that illustrate how to create your metrics using a program or script:

- CPU Load
- File Space Capacity
- Process Count
- Port Scan
- Random
- Windows Power Shell

### CPU Load

Collects the CPU load for the last 1,5,and 15 minute intervals.

Uses the following metrics:

- `BOUNDARY_CPU_LOAD_1_MINUTE`
{'fraction_non_alphanumeric': 0.07804328586370585, 'fraction_numerical': 0.012390377343310001, 'mean_word_length': 4.675799086757991, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1287915', 'n_tokens_mistral': 3550, 'n_tokens_neox': 3327, 'n_words': 1608}