hemdal_trooper

# Hemdal Trooper

[![Elixir CI](https://github.com/altenwald/hemdal_trooper/actions/workflows/elixir.yml/badge.svg)](https://github.com/altenwald/hemdal_trooper/actions/workflows/elixir.yml)
[![Hex.pm Version](https://img.shields.io/hexpm/v/hemdal_trooper.svg)](https://hex.pm/packages/hemdal_trooper)
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/hemdal_trooper/)
[![Hex.pm Total Downloads](https://img.shields.io/hexpm/dt/hemdal_trooper.svg)](https://hex.pm/packages/hemdal_trooper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/altenwald/hemdal_trooper/main/LICENSE)
[![Paypal: Donation](https://img.shields.io/badge/paypal-donation-yellow)](https://www.paypal.com/donate/?hosted_button_id=XK6Z5XATN77L2)
[![Patreon: Donation](https://img.shields.io/badge/patreon-donation-yellow)](https://www.patreon.com/altenwald)

**Hemdal Trooper** is an SSH/SFTP host adapter plugin for the [Hemdal](https://hex.pm/packages/hemdal) monitoring and alert system. It allows Hemdal to execute remote checks, run commands in interactive shells with PTY, and upload/manage script files over SSH using [Trooper](https://hex.pm/packages/trooper).

---

## Features

- **SSH Execution:**
  - Authenticate using RSA or ECDSA private keys (with or without passphrase) or passwords.
  - Run one-time commands (`type: "line"`).
  - Run interactive commands and shells (`type: "shell"` or `interactive: true`) with PTY allocation.
- **SFTP File Management:**
  - Transparently upload scripts, execute them, and clean them up.
- **Host Concurrency & Queuing:**
  - Fully integrated with Hemdal's worker pool limiting and queueing mechanisms.

---

## Installation

Add `hemdal_trooper` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:hemdal_trooper, "~> 1.3"}
  ]
end
```

---

## Configuration Example

Configure remote SSH hosts in your Hemdal configuration:

```elixir
config :hemdal, Hemdal.Config, [
  [
    id: "6b6d247c-48c3-4a8c-9b4f-773f178ddc0f",
    name: "Remote Web Server Status",
    host: [
      id: "2a8572d4-ceb3-4200-8b29-dd1f21b50e54",
      name: "web-01.production",
      module: Hemdal.Host.Trooper,
      max_workers: 2,
      options: [
        hostname: "192.168.1.100",
        port: 22,
        username: "deploy",
        type: "rsa",
        cert_key: File.read!("priv/keys/id_rsa"),
        ptty_allow: true
      ]
    ],
    command: [
      name: "Check Nginx and Load Average",
      type: "line",
      command: ~s|"[\\"OK\\", \\"Nginx running\\"]".|
    ],
    check_in_sec: 60,
    recheck_in_sec: 5,
    broken_recheck_in_sec: 10,
    retries: 2
  ]
]
```

---

## Host Options

| Option | Type | Description |
|---|---|---|
| `:hostname` | `String.t() \| tuple()` | Remote IP or hostname (e.g. `"127.0.0.1"` or `{192, 168, 1, 1}`). |
| `:port` | `integer()` | SSH port number (default `22`). |
| `:username` | `String.t()` | SSH user account. |
| `:type` | `String.t()` | Authentication type: `"rsa"`, `"ecdsa"`, or `"password"`. |
| `:cert_key` | `String.t()` | PEM formatted private key (RSA or ECDSA). |
| `:password` | `String.t()` | User password or private key passphrase. |
| `:ptty_allow` | `boolean()` | Allocate pseudo-terminal for interactive commands (default `false`). |
| `:ptty_opts` | `list()` | PTY options list passed to SSH. |

---

## Documentation

Full documentation is available on [HexDocs](https://hexdocs.pm/hemdal_trooper).

---

## License

This project is licensed under the terms of the [MIT License](LICENSE).

---

## Support & Donations

If you find this project useful, you can support its development:

[![Donate with PayPal](https://www.paypalobjects.com/en_US/GB/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate/?hosted_button_id=XK6Z5XATN77L2)