Documentation Hub

Welcome to the Citadel Documentation Hub. Here you will find comprehensive deployment guides, administration tutorials, mail routing instructions, security configurations, and troubleshooting references for Citadel site operators.

Getting Started & Concepts Architecture, requirements, authentication & limits Deployment & Installation Docker, Easy Install, reverse proxies & migration Mail Routing & Internet Services Domains, relaying, smart hosts & forwarding Security, TLS & Spam Protection SSL certificates, SpamAssassin, ClamAV & DKIM Client Access & Groupware Mobile sync, mailboxes, rooms & XMPP chat System Administration Backups, systemd, purging & maintenance Troubleshooting & FAQ Diagnostics, queue issues & common solutions Developer Reference & Heritage Protocol spec, coding style & project history

Getting Started & Architecture

Supported Operating Systems Linux distributions, container environments, and Unix platforms supported by Citadel.
Authentication Modes and User Accounts Choosing between internal database accounts, host PAM authentication, and corporate LDAP/Active Directory.
Initial Administrator Login and Password Performing the initial administrative login and setting up the primary administrator account.
File and Directory Layout Understanding the consolidated directory hierarchy under /usr/local/citadel for data, keys, and services.
Storage Engine and Database Architecture Why Citadel uses high-performance embedded storage (LMDB and Berkeley DB) instead of external SQL engines.
Storage Limits and Maximum Database Size 64-bit address space architecture and multi-terabyte message store capacity.
Can Citadel run on a shared web hosting account? Why Citadel requires dedicated VPS or server root access rather than shared PHP/cPanel hosting.
Citadel vs. Citadel/UX History The historical evolution from dialup BBS roots to multi-threaded Unix collaboration software.
Is running your own email server legal? Facts, regulations, and ISP terms of service regarding self-hosted email infrastructure.

Deployment & Installation

Easy Install Automated Deployment The recommended turn-key installer that downloads, builds, and configures Citadel automatically.
Docker Container Deployment Running Citadel and WebCit using official container images with persistent volume mounts.
Source Code Build & Manual Administration Guide Comprehensive reference for compiling Citadel from source and administering from the command line.
Running WebCit Behind Apache or Nginx Reverse Proxy Configuring standard web servers to proxy HTTP and HTTPS traffic to WebCit on ports 80 and 443.
Migrating Citadel to a New Host Machine Step-by-step procedure to migrate Citadel across servers, architectures, or operating systems using ctdldump and ctdlload.

Mail Routing & Internet Services

Domain Names and Internet Mail Configuration Configuring local host aliases, smart hosts, DNSBL services, and masqueradable domains in WebCit.
Configuring Outbound Relaying & Smart Hosts Routing outgoing mail through ISP relays, corporate smarthosts, or authenticated SMTP gateways.
Catch-All Email Addresses Routing undelivered or catch-all email for an entire domain to a specific room or user mailbox.
Domain-Specific Recipient Rooms for Shared Addresses Delivering common addresses (like info@domain1 and info@domain2) to separate rooms.
Automatic Email Forwarding Setting up site-wide or user-level rules to forward messages to remote email addresses.
Remote POP3/IMAP Mail Retrieval Periodically polling external mailboxes to retrieve mail directly into Citadel rooms or folders.
Message Journaling and Compliance Archival Envelope journaling technical guide for regulatory compliance and third-party archival systems.
Postmaster Email Routing Configuring which room or user receives RFC-mandated postmaster and abuse notifications.
Local Mail Injection and the citmail MDA How Citadel receives command-line mail injection via LMTP and standard sendmail interfaces.

Security, TLS & Spam Protection

Configuring SSL/TLS Certificates in Citadel Installing Let's Encrypt certificates via Certbot (HTTP-01 challenge) or custom X.509 keys and certificates.
SpamAssassin and ClamAV Integration Configuring content-based spam filtering (spamd) and real-time antivirus attachment scanning (clamd).
Realtime Blackhole Lists (DNSBL / RBL) Rejecting known spammers and open relays in real time during the SMTP handshake.
DKIM and DomainKeys Email Signing Generating cryptographic keys and signing outbound emails for trusted domain deliverability.
Configuring Standalone SpamAssassin Setup details for running the SpamAssassin daemon mode on port 783.
Configuring ClamAV Antivirus Scanner TCP socket configuration for ClamAV daemon mode on port 3310.
Single Sign-On with Active Directory Kerberos and SPNEGO single sign-on integration with Microsoft Windows domains.
LDAP Directory Authentication Authenticating Citadel against corporate LDAP directories and delegating administrator privileges.
Password Security and Complexity Policies Citadel's design philosophy on password strength enforcement and brute-force protection.

Client Access & Groupware Collaboration

Connecting Mobile Devices Synchronizing email, calendars, and address books on Android, iOS, and mobile devices (ActiveSync, CalDAV, CardDAV).
Mailing Lists and Discussion Rooms Converting any room into an email distribution list with automatic list headers.
Public Shared Mailboxes Creating collaborative mailboxes accessible by teams or groups of users.
Posting Messages into Rooms via SMTP Directing incoming email to specific bulletin boards or discussion rooms by address.
RSS and Atom Feed Aggregation into Rooms Automatically pulling headlines and articles from remote RSS feeds into Citadel rooms.
Configuring Jabber / XMPP Instant Messaging Connecting desktop and mobile chat clients to Citadel's built-in instant messaging server.
Publishing Room Content to the Web Without Login Making public announcements, blogs, and guestbooks viewable to unauthenticated visitors.
Direct Telnet Access to Citadel Configuring direct telnet port answering without requiring prior host operating system logins.
Disabling the Text-Mode Main Menu Streamlining text-mode client navigation for casual or new users.
Enabling ANSI Color in the Text Client Turning on ANSI color display for vintage terminal sessions.

System Administration & Maintenance

Backups and Standby Server Replication Recommended zero-downtime filesystem snapshot strategy (ZFS, Btrfs, LVM) and cold backup procedures.
Systemd Service Management Controlling Citadel Server, WebCit HTTP, and WebCit HTTPS services under systemd.
Message Expiration and the Auto-Purger Configuring automatic message retention policies and managing the nightly purger.
Understanding Disk Space and Database Free Lists Why deleting messages reclaims database pages for reuse rather than shrinking disk files immediately.
How Deferred Processing Works Architectural explanation of synchronous vs asynchronous operations and reference counting.
Understanding Instant Expunge Mode How IMAP client message deletion flags interact with Citadel's reference counting engine.
Batch User Creation on New Systems Importing user rosters via shell scripts and sendcommand automation.
Recovering Administrator Password Resetting the admin password or recovering aide privileges via setup tools.
Migrating Email from Legacy Mail Servers Moving mailboxes and message archives from older IMAP servers into Citadel.
Changing Server Configuration the Hard Way Editing raw low-level configuration records using text client dot-commands.
WebCit Locale and Multi-Language Configuration Configuring UTF-8 locales, GNU gettext language packs, and container environment variables.

Troubleshooting & FAQ

Outbound Mail Stuck in Queue or Port 25 Blocked Diagnosing DNS resolution, testing SMTP port 25 connectivity, and working around ISP blocks.
Diagnosing Outbound Email and DNS Issues Verifying forward/reverse DNS, SPF, and MX records to avoid spam classification.
WebCit UI Display and Browser Cache Resolving stylesheet or JavaScript rendering glitches after system upgrades by clearing browser cache.
Diagnosing "Unable to Connect to Citadel Server" Troubleshooting WebCit connection failures to citserver on the local socket or port 504.
Diagnosing "Connection refused: can't connect to 127.0.0.1.citadel" Resolving loopback networking or service startup errors.
Understanding "Connection broken during SMTP conversation" What caused remote SMTP relays to prematurely terminate inbound or outbound transmissions.
Understanding Port 504 Greeting ("200 Citadel server ready") Distinguishing Citadel native protocol port 504 from standard SMTP port 25.
Fixing TLS Key/Certificate Mismatch After Upgrades Resolving key mismatch errors when upgrading older self-signed certificate stores.
Tuning Lock Tables for Legacy Berkeley DB Systems Resolving "Lock table is out of available object entries" on legacy BDB databases using DB_CONFIG.
Resolving Duplicate Messages in Sent Items Correcting IMAP client settings when email clients save a sent copy while Citadel also records one.
Data Recovery When No Backups Exist Honest advice regarding data loss and the necessity of proactive backup schedules.

Developer Reference & Project Heritage

Application Layer Protocol Specification Comprehensive reference manual for the low-level client-server protocol primitives.
C Coding Style Standards Code formatting, indentation, threading rules, and standards for human and machine-generated contributions.
Programming Language and Technologies Overview of C, POSIX APIs, and technologies used in the Citadel codebase.
Citadel Project History: Past, Present, and Future A storied history from 1981 CP/M BBS roots to modern collaborative open source software.
Credits and GNU GPLv3 License Project contributor credits and full GNU General Public License v3 terms.
Software License Information Summary of open source licensing for Citadel.
Official Citadel Logo and Brand Assets Vector and raster logo graphics, icons, and usage guidelines.
Where is 'Home Base' for Citadel? Information on the UNCENSORED! BBS and online developer community.