From 7ed93e4a8b4e62c6140b1286445d614ba18b5c1d Mon Sep 17 00:00:00 2001 From: m1ngsama Date: Tue, 2 Dec 2025 12:52:09 +0800 Subject: [PATCH] Rewrite README in classic Unix style - README: Man page format (BSD style) - README.md: Minimal markdown (GitHub) Follows Unix documentation philosophy: - Concise and dense - No marketing fluff - Information over presentation - Reference manual style Inspired by original Unix manuals and BSD docs. --- README | 98 ++++++++++++++++++++++++++++ README.md | 187 ++++++++++++++++-------------------------------------- 2 files changed, 154 insertions(+), 131 deletions(-) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..514afdd --- /dev/null +++ b/README @@ -0,0 +1,98 @@ +TNT(1) User Commands TNT(1) + +NAME + tnt - terminal chat server with vim-style interface + +SYNOPSIS + tnt [-p port] [-h] + +DESCRIPTION + TNT (TNT's Not Tunnel) is a lightweight SSH chat server. + Supports vim-style navigation and message history browsing. + +INSTALLATION + curl -sSL https://raw.githubusercontent.com/m1ngsama/TNT/main/install.sh | sh + + Or download binary from: + https://github.com/m1ngsama/TNT/releases + +USAGE + Start server: + tnt # Listen on port 2222 + tnt -p 3333 # Listen on port 3333 + PORT=3333 tnt # Same as above + + Connect as client: + ssh -p 2222 localhost + +OPTIONS + -p port Listen on specified port (default: 2222) + -h Display help message + +MODES + INSERT Type and send messages (default mode) + ESC Switch to NORMAL mode + Enter Send message + Backspace Delete character + + NORMAL Browse message history + i Return to INSERT mode + : Enter COMMAND mode + j/k Scroll down/up + g/G Jump to top/bottom + ? Show help + + COMMAND Execute commands + :list List online users + :help Show available commands + ESC Return to NORMAL mode + +ENVIRONMENT + PORT Server port (default: 2222) + +FILES + messages.log Message history (append-only) + host_key SSH host key (auto-generated) + +EXAMPLES + Start server on port 3000: + PORT=3000 tnt + + Connect and set username: + ssh -p 2222 localhost + # Enter username when prompted + + Production deployment with systemd: + sudo cp tnt.service /etc/systemd/system/ + sudo systemctl enable --now tnt + +DIAGNOSTICS + Build with debug symbols: + make debug + + Check for memory leaks: + make asan + ASAN_OPTIONS=detect_leaks=1 ./tnt + + Run tests: + ./test_basic.sh + ./test_stress.sh 50 120 + +BUGS + Report bugs at: https://github.com/m1ngsama/TNT/issues + +SEE ALSO + ssh(1), sshd(8) + + Project documentation: + HACKING Developer guide + DEPLOYMENT.md Production setup + CICD.md CI/CD workflow + +AUTHOR + Written by m1ng. + +LICENSE + MIT License. See LICENSE file for details. + +TNT 1.0 December 2025 TNT(1) diff --git a/README.md b/README.md index 1b40835..deb98f5 100644 --- a/README.md +++ b/README.md @@ -1,157 +1,82 @@ # TNT -**TNT's Not Tunnel** - A lightweight terminal chat server written in C +Terminal chat server. Vim-style interface. SSH-based. -![License](https://img.shields.io/badge/license-MIT-blue.svg) -![Language](https://img.shields.io/badge/language-C-blue.svg) +## Install -## Features - -- ✨ **Vim-style operations** - INSERT/NORMAL/COMMAND modes -- 📜 **Message history** - Browse with j/k keys -- 🕐 **Full timestamps** - Year-month-day hour:minute with timezone -- 📖 **Bilingual help** - Press ? for Chinese/English help -- 🌏 **UTF-8 support** - Full support for Chinese, Japanese, Korean -- 📦 **Single binary** - Lightweight executable -- 🔒 **SSH access** - Secure encrypted connections -- 🖥️ **Auto terminal detection** - Adapts to your terminal size -- 💾 **Message persistence** - All messages saved to log file -- ⚡ **Low resource usage** - Minimal memory and CPU - -## Building - -**Dependencies:** -- libssh (required for SSH support) - -**Install dependencies:** -```bash -# On macOS -brew install libssh - -# On Ubuntu/Debian -sudo apt-get install libssh-dev - -# On Fedora/RHEL -sudo dnf install libssh-devel -``` - -**Build:** -```bash -make -``` - -For debug build: -```bash -make debug -``` - -## Installation - -**Quick install (recommended):** -```bash +```sh curl -sSL https://raw.githubusercontent.com/m1ngsama/TNT/main/install.sh | sh ``` -**Or download from [releases](https://github.com/m1ngsama/TNT/releases)** +Or download from [releases](https://github.com/m1ngsama/TNT/releases). -See [DEPLOYMENT.md](DEPLOYMENT.md) for production setup. +## Run -## Running - -```bash -./tnt +```sh +tnt # port 2222 +tnt -p 3333 # custom port +PORT=3333 tnt # env var ``` -Connect from another terminal: -```bash -ssh -p 2222 localhost +Connect: `ssh -p 2222 localhost` + +## Keys + +**INSERT** (default) +- `ESC` → NORMAL +- `Enter` → send +- `Backspace` → delete + +**NORMAL** +- `i` → INSERT +- `:` → COMMAND +- `j/k` → scroll +- `g/G` → top/bottom +- `?` → help + +**COMMAND** +- `:list` → users +- `:help` → commands +- `ESC` → back + +## Build + +```sh +make # normal +make debug # with symbols +make asan # sanitizer +make check # static analysis ``` -The server will prompt for a password (any password is accepted) and then ask for your username. +Requires: `libssh` -## Usage +## Deploy -### Operating Modes +See [DEPLOYMENT.md](DEPLOYMENT.md) for systemd setup. -- **INSERT** - Type and send messages (default) -- **NORMAL** - Browse message history -- **COMMAND** - Execute commands +## Files -### Keyboard Shortcuts - -#### INSERT Mode -- `ESC` - Enter NORMAL mode -- `Enter` - Send message -- `Backspace` - Delete character -- `Ctrl+C` - Exit - -#### NORMAL Mode -- `i` - Return to INSERT mode -- `:` - Enter COMMAND mode -- `j` - Scroll down (older messages) -- `k` - Scroll up (newer messages) -- `g` - Jump to top -- `G` - Jump to bottom -- `?` - Show help -- `Ctrl+C` - Exit - -#### COMMAND Mode -- `Enter` - Execute command -- `ESC` - Cancel, return to NORMAL -- `Backspace` - Delete character - -### Available Commands - -- `list`, `users`, `who` - Show online users -- `help`, `commands` - Show available commands -- `clear`, `cls` - Clear command output - -## Architecture - -- **Network**: Multi-threaded SSH server using libssh -- **TUI**: ANSI escape sequences with automatic terminal size detection -- **Storage**: Append-only log file -- **Concurrency**: pthread + rwlock -- **Security**: Encrypted SSH connections with host key authentication - -## Configuration - -Set port via environment variable: - -```bash -PORT=3333 ./tnt +``` +messages.log chat history +host_key SSH key (auto-gen) +tnt.service systemd unit ``` -## Technical Details +## Test -- Written in C11 -- POSIX-compliant -- Thread-safe operations -- Proper UTF-8 handling for CJK characters -- Box-drawing characters for UI -- SSH protocol with PTY support for terminal size detection -- Dynamic window resize handling - -## Development - -```bash -make debug # Build with debug symbols -make asan # Build with AddressSanitizer -make check # Run static analysis -./test_basic.sh # Run basic tests -./test_stress.sh # Run stress test +```sh +./test_basic.sh # functional +./test_stress.sh 50 # 50 clients ``` -See [HACKING](HACKING) for development details. +## Docs -## Security - -- **Encrypted connections**: All traffic is encrypted via SSH -- **Host key authentication**: RSA host key generated on first run -- **Password authentication**: Currently accepts any password (customize for production) -- **Host key persistence**: Stored in `host_key` file -- **No plaintext**: Unlike telnet, all data is encrypted in transit +- `README` - man page style +- `HACKING` - dev guide +- `DEPLOYMENT.md` - production +- `CICD.md` - automation +- `QUICKREF` - cheat sheet ## License -MIT License - see LICENSE file +MIT