---
description: Running BBS-MD as a public SSH service
---

# SysOp Handbook

So you want to run a BBS. Welcome to the club.

## Setting Up SSH Access

The classic BBS experience: users connect via SSH and land directly in BBS-MD.

### 1. Create a BBS User

```bash
# Create user with bbs-md as their login shell
sudo useradd -m -s /usr/local/bin/bbs-md bbsguest

# Set up their vault
sudo mkdir -p /home/bbsguest/vault
sudo cp -r /path/to/your/vault/* /home/bbsguest/vault/

# Set a password (or use SSH keys)
sudo passwd bbsguest
```

### 2. Configure bbs.toml

Place `bbs.toml` next to the binary or in the user's home directory:

```toml
vault_path = "/home/bbsguest/vault"
theme = "default"
```

### 3. Test the Connection

```bash
ssh bbsguest@your-server.com
```

The user lands directly on the index page. No shell prompt, no confusion. Just content.

## Security Considerations

- BBS-MD runs as a **login shell** — there is no escape to bash
- The `q` key is **disabled** in login shell mode
- Only double `Ctrl+C` can exit (returns to SSH disconnect)
- Path traversal is guarded — `../../etc/passwd` won't resolve
- Only `.md` files inside the vault are accessible

## Content Management

Your vault is just a directory of markdown files. You can:

- Edit files over SFTP or SCP
- Use `rsync` to sync from a local copy
- Mount a Git repository and pull updates
- Write a cron job to generate content

BBS-MD watches for changes. Your updates appear live.

> The best BBS is the one that's always fresh.

## Monitoring

Watch the process with standard Unix tools:

```bash
# Check if bbs-md is running for connected users
ps aux | grep bbs-md

# Watch vault changes in real time
inotifywait -m /home/bbsguest/vault/
```

---

Back to [[index|home]] or see the [[Features]].