VServer SSH Stats – Home Assistant Integration

Deutsch | Español | Français

Overview

The VServer SSH Stats integration for Home Assistant allows you to monitor remote Linux servers (vServers, Raspberry Pi, or dedicated machines) without installing any additional agents on the target machines.

It connects via SSH (using IP address, username, and password or SSH key) and collects system metrics directly from /proc, df, and other standard Linux interfaces. The metrics appear as native sensors in Home Assistant.

This makes it possible to get real-time CPU, memory, disk, uptime, network throughput, and temperature information from all your servers inside Home Assistant dashboards.

The integration also provides Home Assistant services to run ad-hoc commands on your servers.

---

Features

• No software installation required on the target server (only SSH access).
• Supports multiple servers with individual configuration.
• Configurable via Home Assistant UI (config flow).
• Existing server entries can be edited from the integration options, including host, port, username, password, SSH key, target OS, and polling timeouts.
• Supports password and SSH key authentication.
• Home Assistant services and button entities for remote commands, package updates, and reboots.
• Automatically discovers SSH-enabled hosts on your local network for quick setup, while still allowing manual configuration. Compatible servers announcing themselves via Zeroconf also appear under Home Assistant's Discovered section.
• Collects:
  • CPU usage (%)
  • Memory usage (%)
  • Swap usage (%) and total swap (GiB)
  • Total RAM (MB)
  • Disk usage (% for /)
  • Network throughput (bytes/s, in and out)
  • Uptime (seconds)
  • Temperature (°C, if available)
  • CPU cores
  • Load average (1/5/15 min)
  • CPU frequency (MHz)
  • Operating system version
  • Installed packages (count and list)
  • Docker installation, running containers, and per-container CPU/memory usage
  • Automatic creation of per-container CPU and memory sensors whenever new containers start
  • VNC support status
  • HTTP/HTTPS web server status
  • SSH enabled status
• Configurable update interval (default: 30 seconds).
• Configurable SSH connect timeout and collection command timeout.
• Services to fetch the server's local IP, uptime, list active SSH connections, run commands, update packages, and reboot the host.

Services & Events

The integration exposes Home Assistant services for remote actions:

• vserver_ssh_stats.get_local_ip – Return the server's local IP address.
• vserver_ssh_stats.get_uptime – Return uptime in seconds.
• vserver_ssh_stats.list_connections – List active SSH sessions.
• vserver_ssh_stats.run_command – Run an arbitrary shell command remotely.
• vserver_ssh_stats.update_packages – Trigger OS package updates (apt/dnf/yum).
• vserver_ssh_stats.reboot_host – Reboot the remote host.

When update_packages completes, the integration fires the vserver_ssh_stats_update_packages event on the Home Assistant event bus with the command output in the payload, so you can automate notifications or post-update actions.

Support the Project

If this integration saves you time, feel free to support development with a donation:

PayPal – Donate

Thank you for your support! Every contribution helps keep this project moving forward.

---

Installation

Via HACS (Home Assistant Community Store)

1. Ensure HACS is installed in Home Assistant.
2. In HACS, add https://github.com/404GamerNotFound/vserver-ssh-stats as a custom repository (type: integration).
3. Search for VServer SSH Stats and install the integration.
4. Restart Home Assistant to load the new integration.

Example from HACS:

Entities Created

For each server, the following entities will be available:

• sensor.<name>_cpu – CPU usage (%)
• sensor.<name>_mem – Memory usage (%)
• sensor.<name>_swap_usage – Swap usage (%)
• sensor.<name>_swap_total – Total swap (GiB)
• sensor.<name>_disk – Disk usage (%)
• sensor.<name>_disk_capacity_total – Total detected disk capacity (GiB)
• sensor.<name>_net_in – Network inbound (bytes/s)
• sensor.<name>_net_out – Network outbound (bytes/s)
• sensor.<name>_ssh_connect_time_ms – SSH connection setup time (ms)
• sensor.<name>_collection_time_ms – Full collection runtime (ms)
• sensor.<name>_uptime – Uptime (seconds)
• sensor.<name>_temp – Temperature (°C, if available)
• sensor.<name>_ram – Total RAM (MB)
• sensor.<name>_cores – CPU cores
• sensor.<name>_load_1 – 1‑minute load average
• sensor.<name>_load_5 – 5‑minute load average
• sensor.<name>_load_15 – 15‑minute load average
• sensor.<name>_cpu_freq – CPU frequency (MHz)
• sensor.<name>_os – Operating system version
• sensor.<name>_pkg_count – Pending update count
• sensor.<name>_pkg_list – Pending update packages (first 10)
• sensor.<name>_docker – 1 if Docker is installed, 0 otherwise
• sensor.<name>_containers – Running Docker containers (comma-separated list)
• sensor.<name>_vnc – "yes" if a VNC server is detected
• sensor.<name>_web – "yes" if an HTTP or HTTPS service is listening
• sensor.<name>_ssh – "yes" if the SSH service is listening
• For each detected mount point: total and free space sensors in GiB
• For each running container: sensor.<name>_container_<container>_cpu (CPU usage %) and sensor.<name>_container_<container>_mem (memory usage %)

---

Example Lovelace Dashboard

type: vertical-stack
cards:
  - type: gauge
    name: VPS1 CPU
    entity: sensor.vps1_cpu
  - type: gauge
    name: VPS1 Memory
    entity: sensor.vps1_mem
  - type: entities
    title: VPS1 Details
    entities:
      - sensor.vps1_disk
      - sensor.vps1_net_in
      - sensor.vps1_net_out
      - sensor.vps1_uptime
      - sensor.vps1_temp

Health and Alert Automations

Use the provided sensors to notify you when a server looks unhealthy. For example:

• High CPU or memory usage sustained for several minutes.
• Disks approaching full capacity.
• Sensors turning unavailable/unknown, which likely means SSH connectivity is down.

You can copy and adjust the sample automations in examples/automations/health_alerts.yaml to fit your entity names and preferred notification services.

For reusable one-click operations (uptime query, listing SSH sessions, package updates, and reboot with confirmation), see examples/scripts/maintenance_scripts.yaml.

SSH Key Storage

• When running Home Assistant OS, copy your SSH private key into the /config/ssh/ directory (for example via the File Editor add-on or Samba share). A key named id_vserver should end up at /config/ssh/id_vserver.
• In the configuration wizard enter either the absolute path /config/ssh/id_vserver or the path relative to your Home Assistant configuration directory, e.g. ssh/id_vserver. Both forms are now accepted.
• Always reference the private key file. Do not point Home Assistant to the .pub public key.
• For Home Assistant Container/Core installations you may also supply any absolute path that Home Assistant can read.

Security Notes

• It is recommended to create a dedicated, restricted user for SSH monitoring (with read-only access to /proc and df).
• Due to the syntax of the commands being executed, the user must select /bin/bash or a compatible shell; /bin/sh does not recognise certain expressions.
• SSH password authentication is supported, but SSH key authentication is strongly recommended for production use.
• Remote actions such as package upgrades and reboots rely on sudo. Ensure the remote account is permitted to execute apt-get, dnf, yum, and reboot without an interactive password prompt (for example by adding explicit rules to /etc/sudoers). Document or harden those permissions for each monitored server before enabling the buttons/services.

An example configuration for /etc/sudoers.d/<your-user-name-for-VServer-SSH-Stats>

# Monitoring-User <your user name for VServer-SSH-Stats>: A few specific cmds w/o passwort:
<your vserver-user name> ALL=(root) NOPASSWD: /usr/bin/apt update

# on real production systems there should be no upgrade.
# Use the buttons instead to get more control.
<your vserver-user name> ALL=(root) NOPASSWD: /usr/bin/apt upgrade
<your vserver-user name> ALL=(root) NOPASSWD: /sbin/reboot

# retrieving power values on newer Ubuntu / Debian Systems and may be others
<your vserver-user name> ALL=(root) NOPASSWD: /usr/bin/chmod a+r /sys/class/powercap/*/energy_uj
<your vserver-user name> ALL=(root) NOPASSWD: /usr/bin/chmod a-r /sys/class/powercap/*/energy_uj

---

Release Management

• Current stable release: v1.3.1 (matching manifest.json).
• Create a Git tag (e.g. git tag v1.3.1) and a corresponding GitHub release for every published version so HACS can track updates reliably.
• Use the existing scripts/bump_version.py helper to increment the integration version when preparing a new release.
• Document notable changes in CHANGELOG.md alongside each release.

---

Requirements

• Home Assistant.
• SSH access to the monitored servers.
• Linux-based target servers (any distro with /proc and df).

---

License

This project is licensed under the MIT License.

---

Author

Tony Brüser Original author and maintainer of this integration.