BBS provides a suite of command-line tools for installation, updates, backups, and administrative tasks.

Performs a complete installation of BBS on a fresh Ubuntu 22.04+ server.

Location: Installer script (not installed with BBS)

Usage:

sudo bash bbs-install [--hostname HOST] [--no-ssl]

Options:

What It Does:

1. Installs system packages (Apache, PHP 8.1+, MySQL, Composer, etc.)
2. Configures Apache with virtual host
3. Clones BBS repository to /var/www/bbs/
4. Runs Composer to install PHP dependencies
5. Configures MySQL database
6. Generates .env configuration (including APP_KEY)
7. Sets up file permissions
8. Installs SSL certificate via Certbot (unless --no-ssl)
9. Configures cron job for scheduler
10. Runs database schema migration

Requirements:

• Fresh Ubuntu 22.04+ installation
• Root or sudo access
• Internet connectivity
• Valid domain name (for SSL)

Examples:

# Interactive installation with prompts
sudo bash bbs-install

# Automated installation with hostname
sudo bash bbs-install --hostname bbs.example.com

# LAN installation without SSL
sudo bash bbs-install --hostname bbs.local --no-ssl

Updates the BBS server to a new version or branch.

Location: /var/www/bbs/bin/bbs-update

Usage:

sudo /var/www/bbs/bin/bbs-update [path] [branch/tag]

Arguments:

What It Does:

1. Fetches latest code from GitHub
2. Checks out specified tag or branch
3. Runs composer install --no-dev --optimize-autoloader
4. Fixes file permissions on /var/www/bbs/
5. Updates SSH helper script in /usr/local/bin/
6. Updates sudoers configuration for www-data
7. Checks and installs/updates rclone if needed
8. Runs pending database migrations from migrations/
9. Fixes permissions on /var/bbs/ storage directory
10. Restarts PHP-FPM service

Update Modes:

Production (Latest Release):

sudo /var/www/bbs/bin/bbs-update

Development (Main Branch):

sudo /var/www/bbs/bin/bbs-update /var/www/bbs main

Specific Version:

sudo /var/www/bbs/bin/bbs-update /var/www/bbs v0.9.4-beta

Examples:

# Update to latest stable release
sudo /var/www/bbs/bin/bbs-update

# Update to development branch (beta server)
sudo /var/www/bbs/bin/bbs-update /var/www/bbs main

# Rollback to previous version
sudo /var/www/bbs/bin/bbs-update /var/www/bbs v0.9.3-beta

Creates a backup of the BBS server (database, config, version).

Location: /var/www/bbs/bin/bbs-backup

Usage:

sudo /var/www/bbs/bin/bbs-backup [backup_dir]

Arguments:

What It Does:

1. Creates MySQL dump of entire BBS database
2. Copies /var/www/bbs/config/.env to archive
3. Copies /var/www/bbs/VERSION to archive
4. Creates compressed archive: bbs-backup-YYYY-MM-DD_HHMMSS.tar.gz
5. Deletes backups older than 7 most recent

Backup Contents:

• database.sql - Complete MySQL dump
• config.env - Configuration file with APP_KEY
• VERSION - Server version identifier

Examples:

# Default location (/var/bbs/backups/)
sudo /var/www/bbs/bin/bbs-backup

# Custom location
sudo /var/www/bbs/bin/bbs-backup /root/bbs-backups/

# One-time backup before update
sudo /var/www/bbs/bin/bbs-backup /tmp/pre-update/

Automation:

• Runs automatically daily via scheduler.php
• No manual intervention needed for routine backups

Restores BBS server from a backup archive.

Location: /var/www/bbs/bin/bbs-restore

Usage:

sudo /var/www/bbs/bin/bbs-restore <backup.tar.gz>

Arguments:

Prerequisites:

• BBS must be installed first (run bbs-install)
• Valid backup archive from bbs-backup
• Root or sudo access

What It Does:

1. Extracts VERSION from backup
2. Checks out matching code version from git
3. Prompts: Restore config/.env? (y/n)
   • If yes, overwrites /var/www/bbs/config/.env
4. Prompts: Restore database? (y/n)
   • If yes, drops existing tables and imports database.sql
5. Recreates Unix SSH users for all agents (e.g., bbs-1, bbs-2)
6. Restores SSH authorized keys from database
7. Runs bbs-update if backup version is older than current release
8. Fixes storage permissions on /var/bbs/

Examples:

# Restore from local backup
sudo /var/www/bbs/bin/bbs-restore /var/bbs/backups/bbs-backup-2026-02-01_120000.tar.gz

# Restore from downloaded backup
sudo /var/www/bbs/bin/bbs-restore /tmp/bbs-backup-2026-02-01_120000.tar.gz

Interactive Prompts:

Restore config/.env? (y/n): y
Restore database? (y/n): y

Use Cases:

• Disaster recovery after hardware failure
• Server migration to new hardware
• Rollback after catastrophic misconfiguration

Emergency tool to disable two-factor authentication for a locked-out user.

Location: /var/www/bbs/bin/bbs-2fa-reset

Usage:

sudo /var/www/bbs/bin/bbs-2fa-reset <username>

Arguments:

What It Does:

1. Connects to MySQL database
2. Sets totp_enabled = 0 for the specified user
3. Clears totp_secret for the user
4. User can now log in without 2FA code

Examples:

# Reset 2FA for admin user
sudo /var/www/bbs/bin/bbs-2fa-reset admin

# Reset 2FA for locked-out user
sudo /var/www/bbs/bin/bbs-2fa-reset jdoe

When to Use:

• User lost access to authenticator app
• User cannot generate valid TOTP codes
• Emergency admin access needed

Security Note:

• Only use when absolutely necessary
• Re-enable 2FA immediately after regaining access
• Log administrative actions

Internal utility for Unix user management, SSH keys, Borg operations, and rclone sync.

Location: /usr/local/bin/bbs-ssh-helper

Usage: Not typically called manually (used by web application)

Subcommands:

How It Works:

• Installed by bbs-update to /usr/local/bin/
• www-data user has passwordless sudo access via /etc/sudoers.d/bbs
• Web application invokes via sudo bbs-ssh-helper <subcommand>

Examples (Internal Use):

# Create agent user (called by web app)
sudo bbs-ssh-helper create-user 1 "ssh-rsa AAAAB3..."

# Extract file from Borg (called during restore)
sudo bbs-ssh-helper borg-extract 1 myarchive path/to/file /tmp/restore/

# Sync to S3 (called by scheduler)
sudo bbs-ssh-helper rclone-sync

Manual Use (Troubleshooting):

# Fix repository permissions manually
sudo bbs-ssh-helper fix-repo-perms 5

# Manually sync to S3
sudo bbs-ssh-helper rclone-sync

Cron-driven task runner that executes periodic server operations.

Location: /var/www/bbs/scheduler.php

Usage: Runs automatically via cron (every minute)

Cron Configuration:

* * * * * /usr/bin/php /var/www/bbs/scheduler.php >> /var/log/bbs-scheduler.log 2>&1

What It Does:

Logs:

• Output: /var/log/bbs-scheduler.log
• Rotated by logrotate

Manual Execution:

# Run scheduler manually (for testing)
sudo -u www-data /usr/bin/php /var/www/bbs/scheduler.php

Troubleshooting:

# Check cron status
sudo systemctl status cron

# View scheduler log
tail -f /var/log/bbs-scheduler.log

# Verify cron job exists
sudo crontab -u www-data -l | grep scheduler

# Restart Apache
sudo systemctl restart apache2

# Check status
sudo systemctl status apache2

# View error log
sudo tail -f /var/log/apache2/error.log

# Restart PHP-FPM
sudo systemctl restart php8.1-fpm

# Check status
sudo systemctl status php8.1-fpm

# View PHP-FPM log
sudo journalctl -u php8.1-fpm -f

# Access MySQL
sudo mysql

# Restart MySQL
sudo systemctl restart mysql

# Check status
sudo systemctl status mysql

# View agent status
systemctl status bbs-agent

# View agent logs
journalctl -u bbs-agent -f

# Restart agent
sudo systemctl restart bbs-agent

# Backup first
sudo /var/www/bbs/bin/bbs-backup /root/pre-update/

# Update to latest release
sudo /var/www/bbs/bin/bbs-update

# Verify version
cat /var/www/bbs/VERSION

# 1. Install on new server
sudo bash bbs-install --hostname bbs.example.com

# 2. Transfer backup
scp backup.tar.gz root@newserver:/tmp/

# 3. Restore
sudo /var/www/bbs/bin/bbs-restore /tmp/backup.tar.gz

# Reset user's 2FA
sudo /var/www/bbs/bin/bbs-2fa-reset admin

# User can now log in without 2FA
# Instruct user to re-enable in Settings → Security

• Updating BBS - Update procedures
• Server Backup and Restore - Backup and restore details
• Installation - Initial server setup
• Troubleshooting - Common issues