Guides

MUD Staff Handoffs with Runbooks

Volunteer-run MUDs depend on individual memory for critical operations: the specific cron job that resets daily quests, the firewall rule that blocks persistent botters, or the informal agreement with a zone builder about storyline continuity. When an implementor or head builder departs without structured handoff, these fragments vanish, causing downtime, data loss, or community fracture. This guide provides a concrete sequence for transferring operational custody in text-based multiplayer environments, treating the handoff as a technical migration rather than a social formality.

2-4 weeks per administrative role8 steps
MUD Staff Handoffs with Runbooks illustration
Placeholder illustration shown while custom artwork is being produced.
1

Audit the Digital Footprint

Catalog every access point the outgoing admin holds across the stack. In MUD environments, permissions fragment across Unix groups, in-game immortal levels, database GRANTs, and external services (Discord webhooks, PayPal for donations, domain registrars). Run `lastlog` and `getent group` to identify shell associations. Check the MUD's `wizlist` or `admin.lst` file against `/etc/group`. Document which zones or areas in the game world have build permissions tied to this specific admin's player name, as these references persist in area files long after shell access is revoked.

audit_mud_admin.sh
#!/bin/bash
# audit_mud_admin.sh
echo "=== Shell Groups ==="
groups outgoing_admin
echo "=== Sudo Access ==="
sudo -l -U outgoing_admin
echo "=== MUD Process Ownership ==="
ps aux | grep [m]ud
echo "=== Database Users (MySQL example) ==="
mysql -e "SELECT User, Host FROM mysql.user WHERE User LIKE '%admin%';"

⚠ Common Pitfalls

  • •Assuming the outgoing admin remembers all secondary accounts like DNSimple or Cloudflare
  • •Missing game-specific permission files like ~/mud/lib/config/immortals.txt
  • •Forgetting mailing list ownership or shared Dropbox credentials
2

Map the Permission Matrix

Create a four-quadrant matrix distinguishing infrastructure access (server reboots, SSL renewal), game administration (ban appeals, player file edits), content ownership (zone building privileges, quest scripts), and community management (forum moderation, Discord admin). MUDs often conflate these; an implementor might hold root shell access and own 30 zones. Separate these concerns: the new admin needs infrastructure access immediately but should not automatically inherit creative control of legacy zones unless they are also the lead builder. Document dependencies like 'Zone 45 (The Dark Forest) requires custom triggers only documented in ~/old_admin/notes/'.

permission_matrix.md
| Permission Layer | Outgoing | Incoming | Transfer Method | Verification |
|-----------------|----------|----------|----------------|--------------|
| Shell (sudo) | old_admin | new_admin | usermod -aG wheel | su - new_admin |
| DB Owner | old_admin | new_admin | ALTER USER...RENAME | \l in psql |
| MUD Imm Level | 58 (Imp) | 57 (Arch) | edit wizlist, hotboot | in-game 'who' |
| Zone Ownership | 12 zones | 0 zones | mv ~/zones/* ~/new_zones/ | load zones in test port |

⚠ Common Pitfalls

  • •Conflating in-game implementor level with server root access
  • •Missing 'soft' permissions like relationships with the hosting provider's support desk
  • •Failing to note which zones have active builder locks or uncommitted changes
3

Implement Shadow Access Protocols

Establish a 7-14 day observation period where the incoming admin receives read-only or secondary access without removing the outgoing admin. Add the new admin's SSH key to `~/.ssh/authorized_keys` alongside the old one; do not replace it. Create their immortal character at level 56 (Architect) to observe level 57+ commands via syslog or in-game 'snoop' logs. CC them on operational emails to the admin alias. This phase captures tacit knowledge like 'we restart the MUD at 4 AM because that's when the European players are offline' or 'always check /var/log/mud/runtimes.log before a copyover'.

shadow_ssh_setup.sh
# Add secondary SSH access without removing primary
# On the MUD server:
sudo useradd -m -G mudgroup new_admin
sudo mkdir /home/new_admin/.ssh
sudo echo "ssh-ed25519 AAAAC3... new_admin@laptop" | sudo tee /home/new_admin/.ssh/authorized_keys
sudo chown -R new_admin:new_admin /home/new_admin/.ssh
sudo chmod 700 /home/new_admin/.ssh
sudo chmod 600 /home/new_admin/.ssh/authorized_keys

⚠ Common Pitfalls

  • •Skipping shadow access to 'save time', resulting in untested backup procedures
  • •Granting full write access to production databases before the new admin understands the schema
  • •Forgetting to add the new admin to the 'mud' Unix group, causing permission denied errors on player files
4

Document Operational Runbooks

Write executable documentation for tasks performed less than weekly but critical to uptime: hotboot/copyover procedures, recovery from flatfile corruption (common in Diku derivatives), rotating log files to prevent disk full errors, and restoring player objects from nightly backups. Include exact file paths (/home/mud/lib/plr/, /var/lib/mysql/) and command sequences. For event-driven MUDs, document the cron jobs that trigger automated quests or seasonal resets. Test each runbook by having the new admin execute it while the outgoing admin observes silently.

runbook_daily_maintenance.sh
#!/bin/bash
# runbook_daily_maintenance.sh
set -e
MUD_HOME=/home/mud/prod
cd $MUD_HOME
# 1. Verify disk space before copyover
df -h /var/log/mud | awk '$5 > 90 {exit 1}'
# 2. Backup player files before hotboot
tar -czf /backups/mud/plr-$(date +%F).tgz lib/plr/
# 3. Trigger hotboot (signal-based copyover)
kill -USR1 $(cat var/mud.pid)
sleep 5
# 4. Verify new process spawned
pgrep -f 'mud.*port' || echo "CRITICAL: MUD did not restart" | mail -s "MUD DOWN" [email protected]

⚠ Common Pitfalls

  • •Documenting only happy-path scenarios without rollback steps
  • •Using relative paths that depend on the outgoing admin's .bashrc aliases
  • •Forgetting to document how to verify backups are restorable (test restores)
5

Execute Technical Asset Transfer

Transfer concrete ownership during a scheduled maintenance window with low player count. Change shell passwords and remove old SSH keys only after confirming the new admin can authenticate independently. Transfer database ownership via `ALTER USER` or `REASSIGN OWNED BY` in PostgreSQL. Update the MUD's internal admin lists (wizlist, admin.lst, or similar) and recompile or hotboot to load changes. Transfer domain registrar contacts and update DNS zone admin emails. Migrate 2FA devices or store recovery codes in the team's password manager (Bitwarden, Vaultwarden).

db_transfer.sql
-- PostgreSQL ownership transfer example
REASSIGN OWNED BY old_admin TO new_admin;
-- Or for specific databases:
ALTER DATABASE mud_prod OWNER TO new_admin;
-- Verify
SELECT datname, datdba::regrole FROM pg_database WHERE datname = 'mud_prod';

⚠ Common Pitfalls

  • •Changing the server root password before confirming the new admin has physical access or IPMI console
  • •Removing the old admin's database access before verifying all cron jobs run under the new user's environment
  • •Forgetting to update the 'From' address in the MUD's mailer configuration, causing password reset emails to bounce
6

Transfer Lore and Social Context

Move institutional knowledge not stored in the database: pending player ban appeals, ongoing roleplay storylines with political complexity, builder disputes about zone quality standards, and informal agreements with other MUDs (inter-game treaties, shared ban lists). Review the outgoing admin's personal notes in ~/docs/, email archives, or Discord DM history. Document 'invisible' game state like 'Player X is on final warning but the log entry is from 2019' or 'The dragon in Zone 12 is meant to respawn only when the moon is full per the storyline'.

⚠ Common Pitfalls

  • •Assuming game logs capture all disciplinary context
  • •Ignoring interpersonal dynamics between veteran players and the outgoing admin
  • •Failing to transfer ownership of ongoing events or competitions scheduled in the next quarter
7

Validate with the Bus Factor Test

Simulate the new admin's absence. The outgoing admin takes a 48-hour 'blackout' where they are unreachable while the new admin handles an unexpected issue—either naturally occurring or staged (e.g., a deliberate minor zone crash). This tests runbook accuracy and identifies hidden dependencies like 'only the old admin knows the Let's Encrypt certbot renewal hook' or 'the firewall whitelist for builder IPs is in a personal config not in /etc/'. For MUDs, this often reveals undocumented dependencies on specific client aliases or external scripts in ~/bin/.

⚠ Common Pitfalls

  • •Treating this test as optional
  • •Staging a trivial issue rather than one requiring cross-system troubleshooting
  • •Allowing the outgoing admin to 'check in' via back channels, invalidating the test
8

Archive and Sunset Access

After 30 days of stable operation, systematically remove the outgoing admin's access while preserving forensic capability. Archive their email to a shared mailbox accessible to the new admin team. Downgrade their immortal character to 'Retired' status (level 1 with immortal flag for chat access) rather than deleting it, as player files may reference their vnum or email fields. Remove shell access but retain home directory backups for 90 days. Document their emergency contact for 6-month check-ins regarding legacy systems, but revoke all privileged access permanently.

sunset_access.sh
# Safe archival process
# 1. Archive home directory
tar -czf /archives/old_admin-$(date +%F).tgz /home/old_admin/
# 2. Disable login but preserve UID references
sudo usermod -s /sbin/nologin old_admin
sudo passwd -l old_admin
# 3. Remove from groups but keep user entry for file ownership audit
sudo gpasswd -d old_admin wheel
sudo gpasswd -d old_admin mudgroup

⚠ Common Pitfalls

  • •Immediately deleting the user account, breaking file ownership chains in the MUD directory
  • •Removing access to password managers containing shared game accounts before extracting shared credentials
  • •Deleting the outgoing admin's personal zones without confirming they are backed up or transferred

What you built

Staff handoffs in volunteer MUDs are not singular events but ongoing resilience practices. The goal is to decouple operational stability from individual memory. After completing the transition, schedule quarterly permission audits using the same audit script from Step 1, and update runbooks whenever automation changes. Maintain a 'cold spare' admin—someone with current shadow access who can step in—ensuring your MUD survives not just planned departures but the sudden disappearance key to volunteer burnout. Operational continuity is the foundation that protects your community's decade-long narrative investment.