============================================ LBBS - The Lightweight Bulletin Board System

.. contents:: Contents .. section-numbering::

Welcome! Whether you're new to BBSing or a veteran sysop, LBBS was written to be a highly configurable, modular BBS for developers, sysops, and users alike.

LBBS is a BBS (bulletin board system) package and personal server written from the ground up to be extensible, modular, and, of course, lightweight. The codebase is relatively small (~80K SLOC), with relatively few dependencies. It is designed to be easy for sysops to administer, easy for users to use and navigate, and easy for developers to read, understand, maintain, and contribute to the source code.

While LBBS is first and foremost a BBS server, its different components can also be used individually: for example, you could use the mail modules as a private mail server, and not load the BBS-related functionality.

Features

Key features and capabilities include:

• Fast and lightweight, written entirely in C

• Terminal access via Telnet, RLogin, SSH, and UNIX domain socket support (note that Telnet and RLogin are plain text protocols and thus insecure)

• ANSI art support

• File transfers via FTP, SFTP, Gopher, HTTP/HTTPS, and ZMODEM

• HTTP 1.1 web server, with WebSocket and forward-proxy support

• User home directories

• Container environment for executing programs

• Password and public key authentication

• Config-file driven configuration

• Submenu "skip menu navigation" - select options in multiple nested menus at once

• Automatic menu screen generation and resizing

• Electronic mail (SMTP, POP3, IMAP4)

  • Aliases and subaddressing

  • Mailing lists

  • Mailbox quotas

  • Shared mailboxes and ACL controls

  • Multi-domain support

  • Relay support

  • Advanced queuing support

  • IMAP NOTIFY support

  • RFC 4468 BURL IMAP and server-side proxied append support, for more efficient (bandwidth saving) email submission

  • Remote mailboxes (IMAP proxy)

    • Built-in OAuth2 proxy, allowing the BBS to log in to remote IMAP servers using OAuth2, while your IMAP client uses your normal BBS credentials

  • SPF, DKIM, ARC, DMARC, and SpamAssassin support

  • Filtering

    • Sieve filtering scripts and ManageSieve service
    • MailScript filtering engine <configs/.rules>_ for flexible, custom, dynamic mail filtering rules (Sieve alternative)
    • Intelligent sender/recipient analysis - prevent yourself from ever sending an email to the wrong people by mistake!

  • Webmail client backend

• Newsgroups (NNTP)

• Native realtime chat

• Internet Relay Chat client and server (including ChanServ), with native IRC, Slack, and Discord relays, along with IRC bouncer functionality

• Queue agent position system for Asterisk

• Terminal autodetection (ANSI support, link speed)

• Emulated slow baud rate support

• TDD/TTY (telecommunications device for the deaf) support

• Sysop capabilities

  • Node spying
  • Interrupt nodes
  • Kick nodes

Usage

Installation

To install LBBS, you will need to compile it from source. Fortunately, we've made this as easy as possible::

     cd /usr/local/src
     git clone https://github.com/InterLinked1/lbbs.git
     cd lbbs
     ./scripts/install_prereq.sh
     make modcheck
     make modconfig
     make
     make install
     make samples
     make service

(Running :code:`make modcheck` is optional. It will tell you all the modules that are available and which will be disabled for the current build.
Running :code:`make modconfig` is what actually makes changes to the build environment, disabling any modules with unmet dependencies.)

If you are setting up a Linux server from scratch, you may also want to refer to :code:`scripts/server_setup.sh` for a more complete script to set up your BBS server.

Afterwards, you may optionally choose to use :code:`scripts/setup_wizard.sh`, a simple utility to do some basic configuration initialization for you. However, this tool is not comprehensive.

To start the BBS with the sysop console in the foreground, you can then run :code:`lbbs -c`. To daemonize it, just run :code:`lbbs`.

At the console, press :code:`?` or :code:`h` for a list of available commands. You can also run :code:`lbbs -?` or :code:`lbbs -h` for a list of startup options.

Some configuration of the BBS will be needed before you can use it. Consult the sample configs in :code:`/etc/lbbs` for an overview of settings you may need to configure. At a minimum, you will need to add a menu to the BBS (:code:`menus.conf`).

LBBS is best run on a modern version of Debian Linux (Debian 12 or 13). It should also compile on most other commonly used Linux distros. A recent version of gcc is required (e.g. >= 11).
The BBS core should compile and install on FreeBSD, but not all module dependencies may be available and some functionality may be degraded.

**WARNING: Do not run the BBS as root!** Create a non-root user and configure the BBS to run as that instead. See :code:`lbbs -?` or :code:`/etc/lbbs/bbs.conf` to configure the run user and run group.

Sysoping
~~~~~~~~

Sysops can monitor and control the BBS using the sysop console provided by the :code:`mod_sysop` module. For example, you can list information about configured BBS menus, spy on nodes, or restart the entire BBS. Most commands are available by typing :code:`/` followed by a string, although some common commands are available by single-press hotkeys. Press :code:`?` in the console for a list of available options and commands.

If the BBS is started in the foreground, a sysop console is available on STDIN/STDOUT.

Additionally, regardless of how the BBS is started, the sysop console can be accessed remotely (so called since the access originates from outside the BBS process) by running the :code:`rsysop` program. This program is part of the external utilities and is installed to :code:`/var/lib/lbbs/external/rsysop`.

**WARNING:** Note that anyone that can access the :code:`rsysop` program is able to perform sysop tasks on the BBS. Even if the BBS is not running as root, it should be running under an account that is secured to the sysop.

System Configuration

Configuration of LBBS and modules are done entirely through INI config files. Different parts of LBBS have their own config files, as does each module that uses one. Config files go in :code:/etc/lbbs and sample configuration files exist in the :code:configs subdirectory of the source tree. Each sample config file documents all available options. Refer to the sample configs for all relevant configuration.

A few especially important configuration files:

• :code:bbs.conf - key startup settings

• :code:mail.conf - Email configuration

• :code:menus.conf - BBS menus, menu items and options.

• :code:mod_auth_mysql.conf - MySQL/MariaDB auth provider module config

• :code:mod_mail.conf - General email server configuration

• :code:mod_smtp_filter_dkim.conf - DKIM signing

• :code:modules.conf - module loading settings (to disable a module, you do it here)

• :code:net_smtp.conf - SMTP server configuration

• :code:net_ssh.conf - SSH and SFTP server configuration

• :code:nodes.conf - Node-related configuration

• :code:tls.conf - SSL/TLS configuration

• :code:transfers.conf - File transfer configuration

Additionally, the MailScript rules engine uses a script file called :code:.rules in the user's root maildir or user's :code:~/.config (and :code:before.rules and :code:after.rules in the root maildir for global filtering) for manipulating messages. A sample MailScript rules file is in :code:configs/.rules (though this is not a config file, but a sample rule script file).

User Configuration

User configuration goes in :code:`~/.config`, which is a subdirectory of each user's BBS home directory (unrelated to any system home directories).

Users can edit these files either via the BBS shell (if configured by the sysop) or via any enabled file transfer protocols (e.g. FTP, FTPS, SFTP).

* :code:`.imapremote` - IMAP client proxy configuration

* :code:`.oauth.conf` - OAuth authentication configuration (used for IMAP client proxy and SMTP submission)

* :code:`.plan` - UNIX .plan file, used by the Finger protocol

* :code:`.project` - UNIX .project file, used by the Finger protocol. Limited to 1 line.

Network Login Services

Network login or comm drivers are modules in the :code:nets source directory, responsible for implementing a network login service. These are what allow users to actually connect to the BBS itself.

Generally speaking, the comm drivers implement some kind of standardized TCP-based protocol. There are builtin drivers for Telnet, RLogin, and SSH. Note that Telnet and RLogin are plain text protocols and thus insecure! Using SSH is recommended for any public connections.

LBBS also includes a UNIX domain socket module (:code:net_unix). One use case for this is if you want to "proxy" connections to the BBS through the main, public-facing network login service. For example, say you run OpenSSH on port 22 (and you don't want to change the port), but you still want people to be able to connect to your BBS on port 22. You can create a public user account on your server that executes the BBS as a program, rather than providing a login shell. If you do this, you don't need any of the network drivers loaded or running besides :code:net_unix (UNIX domain sockets provide the least overhead for these kinds of loopback connections). That said, the UNIX domain socket driver is quite primitive. Using one of the other drivers, particularly the SSH driver, will provide a far superior experience.

Do note, should you choose to proxy connections in the manner described above, there are several important security implications of doing this that you must understand, or you open your system