beszel/readme.md

# Beszel

A lightweight server resource monitoring hub with historical data, docker stats, and alerts.

<!-- <table width="100%">
  <tbody>
    <tr>
      <td width="50%"><img src="https://henrygd-assets.b-cdn.net/social-image-server/before-capture.png" alt="example of turso.tech/pricing link which is missing an og:image as of may 11 2024"/></td>
      <td width="50%"><img src="https://henrygd-assets.b-cdn.net/social-image-server/after-capture.webp" alt="example of turso.tech/pricing link using an image generated by the server as it's og:image"/></td>
    </tr>
  </tbody>
</table> -->

## Features

- **Lightweight**: Much smaller and less demanding than leading solutions.
- **Historical data**: Stats are available for up to 30 days.
- **Docker stats**: CPU and memory usage history for each container.
- **Alerts**: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- **Simple**: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- **Multi-user**: Each user has their own systems. Admins can share systems across users.
- **Secure**: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- **Oauth / OIDC**: Supports many OAuth2 providers and password auth can be disabled.
- **Automated backups**: Automatically back up your data to S3-compatible storage.
- **Open source**: MIT license and no paywalled features.

## Introduction

Beszel has two components: the hub and the agent.

The hub is a web application, built on top of [PocketBase](https://pocketbase.io/), that provides a dashboard to view and manage your connected systems.

The agent runs on each system you want to monitor. It provides a minimal SSH server through which it communicates system information to the hub.

## Installation

The hub and agent are distributed as single binary files, as well as docker images.

### Docker

> **Note**: The docker version cannot automatically detect the filesystem to use for disk I/O stats, so use the binary version if that's important to you.

### Binary

## Environment Variables

### Hub

| Name                    | Default | Description                      |
| ----------------------- | ------- | -------------------------------- |
| `DISABLE_PASSWORD_AUTH` | false   | Disables password authentication |

### Agent

| Name         | Default | Description                                      |
| ------------ | ------- | ------------------------------------------------ |
| `FILESYSTEM` | unset   | Filesystem / partition to use for disk I/O stats |
| `PORT`       | 45876   | Port to listen on                                |

## OAuth / OIDC setup

Beszel supports OpenID Connect and many OAuth2 authentication providers (see list below). To enable this, you will need to:

1. Create an OAuth2 application using your provider of choice. The redirect / callback URL should be `<your-beszel-url>/api/oauth2-redirect`.
2. When you have the client ID and secret, go to the "Auth providers" page and enable your provider.

<details>
  <summary>Supported provider list</summary>

- Apple
- Bitbucket
- Discord
- Facebook
- Gitea
- Gitee
- GitHub
- GitLab
- Google
- Instagram
- Kakao
- LiveChat
- mailcow
- Microsoft
- OpenID Connect
- Patreon (v2)
- Spotify
- Strava
- Twitch
- Twitter
- VK
- Yandex
</details>

## REST API

Because Beszel is built on PocketBase, you can use the PocketBase [Web APIs](https://pocketbase.io/docs/api-records/) and [Client-side SDKs](https://pocketbase.io/docs/client-side-sdks/) to read or update data from outside Beszel itself.

## Security

The hub and agent communicate over SSH, so they don't need to be exposed to the internet. And the connection won't break if you put your own auth gateway, such as Authelia, in front of the hub.

When the hub is started for the first time, it generates an ED25519 key pair.

The agent's SSH server is configured to accept connections only using this key. It does not provide a pty or accept any input, so it is not possible to execute commands on the agent even if your private key is compromised.

## FAQ / Troubleshooting

### Agent is not connecting

Assuming the agent is running, the connection is probably being blocked by a firewall. You should add an inbound rule to allow TCP connections to the port. Check any active firewalls on the agent system, like iptables or ufw, and in your cloud provider account if applicable.

Connectivity can be tested by running `telnet <agent-ip> <port>` or `nc -zv <agent-ip> <port>` from a remote machine.

### Finding the correct filesystem

The filesystem / partition to use for disk I/O stats is specified in the `FILESYSTEM` environment variable.

If it's not set, the agent will try to find the filesystem mounted on `/` and use that. This doesn't seem to work in a container, so it's recommended to set this value. One of the following methods should work (you usually want the option mounted on `/`):

- Run `df -h` and choose an option under "Filesystem"
- Run `lsblk` and choose an option under "NAME"
- Run `sudo fdisk -l` and choose an option under "Device"

### Month / week records are not populating reliably

Records for longer time periods are made by averaging stats from the shorter time periods. They require the agent to be running uninterrupted for long enough to get a full set of data.

If you pause / unpause the agent for longer than one minute, the data will be incomplete and the timing for the current interval will reset.