201
README.md
Normal file
201
README.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# avni — a single-binary control center for your VPS
|
||||
|
||||
`avni` is a fast, dependency-light **terminal dashboard (TUI) + CLI** for operating a
|
||||
self-hosted Linux server: see your Docker apps, domains, bandwidth, SSH sessions and
|
||||
brute-force attackers at a glance — and act on them (start/stop services, ban/blacklist
|
||||
IPs, manage users) without leaving the terminal.
|
||||
|
||||
It shells out to the tools already on the box (`docker`, `fail2ban-client`, `ipset`,
|
||||
`vnstat`, `who`/`last`, `getent`, …) — **no daemon, no database, no agent**. One Rust
|
||||
binary, ~2% CPU, microsecond redraws.
|
||||
|
||||
> Built for a small multi-app VPS behind [Traefik](https://traefik.io/). It auto-discovers
|
||||
> the apps Traefik routes, so the dashboard never goes stale as you add or remove services.
|
||||
|
||||
```
|
||||
┌ AVNI CLOUD · control center ─────────────────────────────────────────────────────────┐
|
||||
│ 1.Overview · 2.Services · 3.Domains · 4.Traffic · 5.Security · 6.SSH · 7.Users · 8.Set…│
|
||||
└────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
┌ Applications (9/9 enabled) — s enable · x disable · R restart · l logs · ↵ details ─────┐
|
||||
│ APP STATE SUBDOMAIN PORT HOST PORTS │
|
||||
│ » ● gitea enabled git.example.com 3000 127.0.0.1:3000->3000 │
|
||||
│ ● n8n enabled n8n.example.com 5678 127.0.0.1:5678->5678 │
|
||||
│ ● uptime-kuma enabled uptime.example.com 3001 127.0.0.1:3001->3001 │
|
||||
│ ○ analytics disabled stats.example.com 3000 - │
|
||||
└──────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
s enable x disable R restart l logs ↵ details 1-9/⇄ tabs ↑↓ move r refresh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Table of contents
|
||||
- [Features](#features)
|
||||
- [Requirements](#requirements)
|
||||
- [Install](#install)
|
||||
- [Using the TUI](#using-the-tui)
|
||||
- [CLI](#cli-scriptable)
|
||||
- [Access control — who can run `avni`](#access-control--who-can-run-avni)
|
||||
- [How it works](#how-it-works)
|
||||
- [Data & file locations](#data--file-locations)
|
||||
- [Security notes](#security-notes)
|
||||
- [Build from source](#build-from-source)
|
||||
- [Python fallback](#python-fallback)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
A tabbed dashboard (switch with `1`–`9`, `Tab`, or `←/→`):
|
||||
|
||||
| Tab | What it shows / does |
|
||||
|-----|----------------------|
|
||||
| **Overview** | host, IP, uptime, load/memory/disk gauges, service & attacker summary, dual clock (server + your local time) |
|
||||
| **Services** | every Docker container with status + the domain Traefik routes to it; `s`/`x`/`R` start/stop/restart, `l` logs |
|
||||
| **Domains** | every `Host()` route → backend; `Enter` checks live HTTP status + TLS cert expiry |
|
||||
| **Traffic** | `vnstat` bandwidth bar chart, 24h / 7d / 30d windows (pins the real uplink interface) |
|
||||
| **Security** | a persistent **IP registry** of everyone who has touched the box (country, attempts, logins, status). Temp-ban (fail2ban), permanent firewall **blacklist** (ipset+iptables), and a **whitelist** that can never be banned |
|
||||
| **SSH** | live sessions (kick / kick+blacklist) + the effective `sshd` policy |
|
||||
| **Users** | list/create/delete Linux users, grant/revoke sudo, lock/unlock, **set login password**, and a full per-user **activity** view (system metadata only) |
|
||||
| **Settings** | delegate the tool to other admins (see [access control](#access-control--who-can-run-avni)) |
|
||||
| **Apps** | the user-facing apps Traefik routes — **enable/disable**, ports, subdomain, live HTTPS + cert details |
|
||||
|
||||
Highlights:
|
||||
- **Auto-discovery** — apps and domains come straight from container labels; nothing to configure.
|
||||
- **Persistent attacker registry** with **incremental log parsing** (reads only newly-appended bytes of `auth.log`, survives rotation).
|
||||
- **Optimistic UI** — actions reflect instantly, then reconcile with the real system state.
|
||||
- **Dual time** — every timestamp shows a second timezone beside it (configured for IST in the source; see [Build](#build-from-source) to change).
|
||||
- **Scriptable** — every view is also a one-shot CLI subcommand.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Linux, run as **root** (or as a delegated `avni`-group member — it self-elevates via sudo).
|
||||
- A recent **Rust** toolchain (rustup stable; ratatui 0.26 needs a newer rustc than some distros ship).
|
||||
- Expected on the box (features degrade gracefully if missing):
|
||||
`docker`, `fail2ban-client`, `ipset` + `iptables`, `vnstat`, `geoiplookup` (geoip-bin),
|
||||
`whois`, plus coreutils (`who`, `last`, `lastb`, `getent`, `passwd`, `chpasswd`).
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
git clone https://git.example.com/you/vps-tool-avni.git
|
||||
cd vps-tool-avni
|
||||
sudo bash install.sh
|
||||
```
|
||||
|
||||
`install.sh` builds the release binary and installs it to `/usr/local/bin/avni`, installs the
|
||||
firewall helper to `/usr/local/bin/avni-firewall.sh`, creates the `avni` group, and writes a
|
||||
sudoers drop-in so delegated admins can launch it. Re-run it after pulling changes.
|
||||
|
||||
Then just:
|
||||
|
||||
```bash
|
||||
avni # full-screen dashboard
|
||||
avni status # one-shot CLI
|
||||
```
|
||||
|
||||
## Using the TUI
|
||||
|
||||
Global keys: `1`–`9` / `Tab` / `←→` switch tabs · `↑↓` (or `j`/`k`) move · `r` refresh · `q` quit.
|
||||
|
||||
Per-tab actions are always shown in the footer. The most useful:
|
||||
|
||||
- **Services / Apps** — `s` start/enable · `x` stop/disable · `R` restart · `l` logs · `Enter` details
|
||||
- **Security** — `[` `]` switch sub-tab · `a` add blacklist · `A` add whitelist · `b` ban · `B` blacklist selected · `W` whitelist selected · `u` undo · `w` whois · `Enter` IP intel
|
||||
- **SSH** — `k` kick a session · `K` kick + blacklist its IP
|
||||
- **Users** — `N` new user · `P` set login/SSH password (masked) · `G`/`g` grant/revoke sudo · `L`/`U` lock/unlock · `D` delete (keeps `/home`) · `Enter` activity
|
||||
- **Settings** — `g` grant the tool · `x` revoke
|
||||
|
||||
Full reference: **[docs/guide.md](docs/guide.md)**.
|
||||
|
||||
## CLI (scriptable)
|
||||
|
||||
Every subcommand prints the same data the TUI shows:
|
||||
|
||||
```bash
|
||||
avni status # host + counts
|
||||
avni services # all containers
|
||||
avni apps # user-facing apps: state · subdomain · port
|
||||
avni ips [attackers|banned|new|all] # the IP registry
|
||||
avni attackers [N] # top N attackers with country
|
||||
avni ban <ip> | unban <ip>
|
||||
avni blacklist [add <ip|cidr|domain>]
|
||||
avni whitelist [add|del <ip>]
|
||||
avni geo <ip> | ssh | users
|
||||
avni adduser <user> [password] # create account (-m home, bash)
|
||||
avni passwd <user> <password> # set a user's Linux login / SSH password
|
||||
avni sudo <user> | unsudo <user> # grant / revoke sudo
|
||||
avni deluser <user> # delete account, KEEP /home
|
||||
avni activity <user> # logins, failed logins, sudo cmds, processes
|
||||
avni access | grant <user> | revoke <user> # tool delegation
|
||||
```
|
||||
|
||||
## Access control — who can run `avni`
|
||||
|
||||
The tool is **root-only** by default. To let a teammate use it:
|
||||
|
||||
1. They must already be an **admin (sudo)** — `avni sudo <user>` (Users tab `G`).
|
||||
2. Grant the tool — `avni grant <user>` (Settings tab `g`). This adds them to the `avni`
|
||||
group; the sudoers drop-in lets the binary **auto-elevate via sudo** when they run it.
|
||||
|
||||
Anyone not granted gets a polite "not authorised" message. Root can never be revoked.
|
||||
The single binary at `/usr/local/bin/avni` is a real root-owned file (mode 0755), so a
|
||||
delegated user can exec it but cannot modify it.
|
||||
|
||||
## How it works
|
||||
|
||||
- **Background gather** — a worker thread fans out the independent fetches (docker, auth-log
|
||||
registry, sessions, users, vnstat) across threads, so a full refresh ≈ the slowest single
|
||||
part (~2 s) instead of the sum. The UI never blocks; a loading splash shows on first start.
|
||||
- **Incremental log parsing** — stores a byte offset per log inode and reads only the new tail
|
||||
of `auth.log` on each refresh (not the whole multi-MB file).
|
||||
- **Auto-discovery** — services, domains and apps are parsed from `docker ps` + Traefik
|
||||
`Host()` labels in a single call. Nothing is hard-coded; add a container and it appears.
|
||||
- **Traffic** pins the **default-route interface** (a busy box can have dozens of docker
|
||||
veth/bridge interfaces; `vnstat`'s `interfaces[0]` is often a zero-traffic bridge).
|
||||
|
||||
## Data & file locations
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `/usr/local/bin/avni` | the binary |
|
||||
| `/usr/local/bin/avni-firewall.sh` | blacklist/whitelist engine (ipset + iptables) |
|
||||
| `/var/lib/avni/ips.json` | persistent IP registry (+ per-log byte offsets) |
|
||||
| `/etc/avni/whitelist.txt`, `/etc/avni/blacklist.save` | firewall state |
|
||||
| `/etc/fail2ban/jail.d/avni-whitelist.conf` | auto-generated fail2ban `ignoreip` |
|
||||
| `/etc/sudoers.d/avni` | NOPASSWD drop-in for the `avni` group |
|
||||
|
||||
## Security notes
|
||||
|
||||
- **No secrets are stored in this repo or the binary.** `avni` reads live system state at
|
||||
runtime; it never embeds passwords, IPs or hostnames. (The examples in the code are
|
||||
[RFC 5737](https://datatracker.ietf.org/doc/html/rfc5737) documentation addresses.)
|
||||
- **Whitelist your own IPs first.** A firewall guard and fail2ban `ignoreip` then make it
|
||||
impossible to accidentally lock yourself out under a brute-force burst; an anti-lockout
|
||||
check also refuses to blacklist your current SSH client IP.
|
||||
- **Docker-published ports bypass host UFW** — the firewall engine adds rules to the
|
||||
`DOCKER-USER` chain too, so a blacklist actually blocks container-exposed ports.
|
||||
- The per-user **activity** view uses only system metadata (logins, sudo audit, `ps`) and
|
||||
**never reads anyone's home directory or shell history** — safe on a multi-tenant box.
|
||||
|
||||
## Build from source
|
||||
|
||||
```bash
|
||||
cargo build --release # at the repo root → target/release/avni
|
||||
```
|
||||
|
||||
Toolchain: rustup **stable**. Dependencies are just `ratatui`, `crossterm`, `serde`,
|
||||
`serde_json` (see `Cargo.toml`).
|
||||
|
||||
**Changing the second timezone:** the dual-clock offset is computed in `ist_delta_min()` in
|
||||
`src/main.rs` (currently targets IST, +05:30). Adjust the `330` (minutes) and the
|
||||
`TZ=Asia/Kolkata` strings to your zone.
|
||||
|
||||
## Python fallback
|
||||
|
||||
`avni.py` is an earlier pure-Python (curses) implementation kept as a zero-build fallback.
|
||||
`install.sh` installs it as `/usr/local/bin/avni-py`. The Rust binary is the maintained one.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE) © 2026 Jagadeesh (AVNI Cloud).
|
||||
Reference in New Issue
Block a user