# SSH Monitor

## Introduction

{{SSH_Monitor}} enables you to supervise any {{target}} computer
through {{SSH}} commands
(i.e. {{shell_instruction}} executed through a {{SSH}} connection).

In particular, it allows to monitor any hardware/software data from one or multiple
{{target}}s (e.g. data like network activity, disks filling
level, RAM space left, CPU overload, RAID status, temperatures values, expressions in log files,
etc).

In fact, {{SSH_Monitor}} is made in such a way that it allows you to monitor absolutely any data, as
long as you can come up with a {{shell_instruction}} that can retrieve that data.

For example, you might want to retrieve the available RAM from a Linux {{target}}.
In this case, you might end up using the following
{{shell_instruction}}: `free -m | grep 'Mem:' | awk '{print $7}'`.
Once you found the right {{shell_instruction}} retrieving the data you want,
then you'll have to specify it in a dedicated configuration file (here, a
{{substitutions}} file).

A lot of common {{shell_instruction}}s are already included in this project as references/examples.
You can use them as is, or tweak them, or come up with new ones...
The choice is yours about what to retrieve and how to retrieve it.

```{important}
{{SSH_Monitor}} is not meant to replace dedicated monitoring tools
(e.g. like [Grafana](https://grafana.com/docs/grafana/latest/introduction/)).
It is intended to be used in additions to this kind of tools. For example:

* A dedicated monitoring tool might be more interesting for metrics like RAM usage, but maybe not
  suited if you want an {{EPICS}} alarm on the RAM consumption of
  a specific {{target}}.
* A dedicated monitoring tool might also be more interesting for common metrics, but maybe not
  appropriate if you are looking for very specific informations like particular expressions
  (specific for you project), e.g. in some weird log files...
* A dedicated monitoring tool might need a data-exporter to be installed on the
  {{target}} machine, which might be considered "intrusive" and a
  "NO-GO" for a lot of {{target}}s. {{SSH_Monitor}} allows very
  little to no intervention on the {{target}} machine.
* Data-exporters might not support the {{target}} machine CPU
  architecture. In that case, if the {{target}} machine has an
  available {{SSH}} connection (like most Linux
  {{target}}s), then you won't have to care much about its CPU
  architecture with SSH Monitor.
```

```{warning}
{{SSH_Monitor}} is based on {{SSH}} connections.
This has very serious security implications
that are detailed in the [security explanations](./explanations/security_explanations.md)
and addressed in the [security how-to](./how-to-guides/basics/security_how_to.md).
```

```{note}
{{SSH_Monitor}} allows you to configure every {{SSH}} connection the way you want,
i.e. with any arguments and options described by `man ssh` on the machine hosting SSH Monitor.
See [SSH how-to](./how-to-guides/basics/ssh_how_to.md) for more details.
```

```{note}
Currently, {{SSH_Monitor}} is very Linux-oriented
but [Windows support is also planned](sshmonitor-gitlab-url:issues/38).
```

## Glossary

See the [glossary](./glossary.md)
for definitions of {{EPICS}} specific terms,
and {{SSH_Monitor}} related terms.

## Documentation

The following documentation is structured according to the [diátaxis](https://diataxis.fr/)
documentation framework. I.e. you will find the following four main sections:

* [The tutorials section](./tutorials/index.md) ([learning oriented](https://diataxis.fr/tutorials/)).
* [The how-to guides section](./how-to-guides/index.md) ([task oriented](https://diataxis.fr/how-to-guides/)).
* [The explanations section](./explanations/index.md) ([understanding oriented](https://diataxis.fr/explanation/)).
* [The references section](./references/index.md) ([information oriented](https://diataxis.fr/reference/)).

In addition, you will find the following sections, that are quite common for this kind of project:

* [Glossary](./glossary.md)
* [Troubleshooting guide](./troubleshooting_guide.md)
* [Contribution guide](./contribution_guide.md)
* [Project layout](./project_layout.md)
* [Change log](./CHANGELOG.md)
* [Similar work and alternatives](./similar_work_and_alternatives.md)
* License (🚧 TODO 🚧)

## Where to start

You can simply jump in {{SSH}} monitoring by following the
[step-by-step tutorial (with a Rocky Linux virtual machine)](./tutorials/step_by_step_tutorial_on_a_rocky_linux_vm.md).

If you are familiar with [Nix](https://nixos.org/explore/),\
then you might prefer starting with the
[quick step-by-step tutorial (with a NixOS Linux virtual machine)](./tutorials/quick_step_by_step_tutorial_on_a_nixos_linux_vm.md),\
(which is faster to complete).

```{toctree}
:glob:
:hidden:

glossary
tutorials/index
how-to-guides/index
explanations/index
references/index
troubleshooting_guide
contribution_guide
project_layout
CHANGELOG
similar_work_and_alternatives
```