docker: comprehensive config template pass

.env.example

@@ -0,0 +1,332 @@
+# ============================================================================
+# X3 IRC Services — Docker environment defaults (.env.example)
+# ============================================================================
+#
+# HOW TO USE
+#   1. Copy this file to .env.local:   cp .env.example .env.local
+#   2. Edit .env.local and change ONLY the values you care about — every value
+#      shown here is already the built-in default the container entrypoint
+#      (docker/dockerentrypoint.sh) would use anyway. You never need to set a
+#      var just to keep its default; only OVERRIDE what you want to change.
+#   3. At minimum, review the lines marked "CHANGE THIS — secret" below.
+#
+# HOW IT WORKS (regeneration policy)
+#   On container start, dockerentrypoint.sh reads docker/x3.conf-dist, replaces
+#   each %X3_*% placeholder with the matching environment variable (falling
+#   back to the defaults documented here), and writes /x3/data/x3.conf.
+#   It only (re)generates that file when the file is absent OR its first line
+#   carries the generator marker ("// GENERATED BY dockerentrypoint.sh ...").
+#   A user-supplied x3.conf that LACKS that marker (e.g. a volume-mounted,
+#   hand-managed config) is left untouched and these variables are ignored.
+#
+# FORWARD-COMPATIBILITY
+#   This file is intended to eventually become X3's single canonical, documented
+#   source of default values — a future change may have X3 read .env* directly
+#   instead of templating through the entrypoint. It is therefore written to be
+#   complete (all 70 X3_* vars), accurate (exact entrypoint defaults), and
+#   self-contained (each var is understandable without reading source).
+#
+# Value syntax: shell-style KEY=value, one per line. Do not add quotes unless
+# the value itself must contain them (see X3_SUPPORT_CHANNEL).
+# ============================================================================
+
+
+# ----------------------------------------------------------------------------
+# Server identity  (conf: "server" { } — how this X3 presents on the network)
+# ----------------------------------------------------------------------------
+
+# Server name X3 announces on link. This MUST be the name used in the ircd's
+# Connect/C:line for X3. Shows in /links and /whois.
+X3_GENERAL_NAME=x3.network
+
+# Free-text server description, shown in /links.
+X3_GENERAL_DESCRIPTION=Network Services
+
+# Network domain. Used as the "network" name and woven into the hidden-host
+# suffix (Users.<domain>), admin block, and all mail from/body templates.
+X3_GENERAL_DOMAIN=example.com
+
+# Server numeric. Each server on a P10 network needs a unique numeric —
+# if you get collisions on link, CHANGE THIS.
+X3_GENERAL_NUMERIC=199
+
+# Protocol/compat type — MUST match your ircd version:
+#   8 = Nefarious 1.3.x and higher (legacy)
+#   9 = Nefarious 2.0.x / nefarious2 (current)
+# (Lower values 4-7 exist for old/obsolete ircds.) Default is 8; set 9 for
+# a modern nefarious2 uplink.
+X3_SERVER_TYPE=8
+
+# LOCAL source IP X3 binds when connecting out to the uplink (uplink
+# "bind_address"). Also becomes the default connect-from address.
+X3_GENERAL_BIND_ADDRESS=127.0.0.1
+
+
+# ----------------------------------------------------------------------------
+# Uplink  (conf: "uplinks"."Hub" — the IRC server X3 links to)
+# ----------------------------------------------------------------------------
+
+# IP/address of the ircd X3 connects to.
+X3_UPLINK_ADDRESS=127.0.0.1
+
+# TCP port of the uplink's server (C:line) listener.
+X3_UPLINK_PORT=8888
+
+# CHANGE THIS — secret. Link password; fills BOTH "password" and
+# "uplink_password" and must match the pass in the ircd's Connect/C:line for X3.
+X3_UPLINK_PASSWORD=changeme
+
+
+# ----------------------------------------------------------------------------
+# Service bot nicks  (conf: "services".<bot>."nick")
+# ----------------------------------------------------------------------------
+
+# Authentication service (NickServ/AuthServ) — register and auth here.
+X3_NICKSERV_NICK=AuthServ
+
+# Operator service (OpServ) nick. Afternet uses "O3" (easier to type).
+X3_OPSERV_NICK=O3
+
+# OpServ /whois hostname (only used because OpServ also sets a description).
+X3_OPSERV_HOSTNAME=X3.Services
+
+# Channel service (ChanServ) nick.
+X3_CHANSERV_NICK=X3
+
+# Global announcement bot nick.
+X3_GLOBAL_NICK=Global
+
+# MemoServ bot nick (user-to-user memos module).
+X3_MEMOSERV_BOT=MemoServ
+
+
+# ----------------------------------------------------------------------------
+# Channels  (service/report/autojoin channels)
+# ----------------------------------------------------------------------------
+
+# OpServ debug channel — bot joins it; also the target for override/error/fatal
+# log events.
+X3_DEBUG_CHANNEL=#TheOps
+
+# OpServ general-alert channel (e.g. flood alerts). Bot joins it.
+X3_ALERT_CHANNEL=#TheOps
+
+# Channel where staff-auth notices are announced. Bot joins it.
+X3_STAFF_AUTH_CHANNEL=#OperServ
+
+# Snoop module channel (connect/quit/join/part feed). Keep it secure — it
+# exposes user activity. Also used as the log target for "staff" severity.
+X3_SNOOP_CHANNEL=#MrSnoopy
+
+# Track module channel (per-user event tracking). NOTE: the track module is
+# known-unstable and normally not compiled in; this only matters if it is.
+X3_TRACK_CHANNEL=#MrPeanuts
+
+# ChanServ support_channel list — helpers must be in one of these to be "on
+# duty". This is a conf LIST body: keep each channel individually quoted.
+X3_SUPPORT_CHANNEL="#Operations", "#Help"
+
+
+# ----------------------------------------------------------------------------
+# Hidden-host / cloaking  (conf: "server" — must mirror the ircd's F:lines)
+# ----------------------------------------------------------------------------
+
+# Host-hiding style: 1 = simple (Users.<domain>), 2 = Nefarious style-2 keyed
+# cloaking. If you use +x style-2 on the ircd, set 2 and the keys/prefix below.
+X3_HIDDEN_HOST_TYPE=1
+
+# CHANGE THIS — secret (style-2 only). These three keys MUST exactly match the
+# ircd's HOST_HIDING_KEY1/2/3 F:lines. The shipped stock values make style-2
+# cloaks predictable — change them in production.
+X3_HIDDEN_HOST_KEY1=45432
+X3_HIDDEN_HOST_KEY2=76934
+X3_HIDDEN_HOST_KEY3=98336
+
+# Style-2 host prefix — the name prefixed onto cloaked hosts.
+X3_HIDDEN_HOST_PREFIX=NETWORK
+
+
+# ----------------------------------------------------------------------------
+# OpServ / G-line durations  (clone control + module G-lines)
+# ----------------------------------------------------------------------------
+
+# OpServ clone threshold (untrusted_max): auto-G-line a host that exceeds this
+# many connections. Default 6 (stock). 0 DISABLES it — testbeds set 0 in
+# .env.local so a harness opening many connections from one host isn't
+# auto-G-lined (which would make the network look dead).
+X3_UNTRUSTED_MAX=6
+
+# How long the clone/untrusted-max G-line lasts (duration units: s m h d m y).
+X3_CLONE_GLINE_DURATION=2h
+
+# SockCheck (open-proxy scanner) max concurrent sockets. 0 = effectively off.
+# Only enable proxy scanning with ISP permission — probes look like attacks.
+X3_SOCKCHECK_MAX_SOCKETS=0
+
+# G-line duration SockCheck issues when it flags an open proxy.
+X3_SOCKCHECK_GLINE_DURATION=1d
+
+# G-line duration for blacklist (DNSBL/file) hits in the blacklist module.
+X3_BLACKLIST_GLINE_DURATION=1h
+
+
+# ----------------------------------------------------------------------------
+# ChanServ limits  (conf: "services"."chanserv")
+# ----------------------------------------------------------------------------
+
+# off_channel mode: no/0 = ChanServ idles in registered channels; 1 = use the
+# registered-channel mode and self-op; 2 = as 1 but ChanServ does NOT idle in
+# the channel. Needs ircd +z support; do not run another +z service alongside.
+X3_OFF_CHANNEL=no
+
+# Max channels one account may own (FORCE can override).
+X3_MAX_OWNED=2
+
+# Max users tracked in a channel userlist.
+X3_MAX_CHAN_USERS=512
+
+
+# ----------------------------------------------------------------------------
+# MemoServ  (conf: "modules"."memoserv")
+# ----------------------------------------------------------------------------
+
+# Age at which memos are auto-deleted; 0 disables memo expiry.
+X3_MEMO_EXPIRY=30d
+
+# Max number of memos one account may hold.
+X3_MEMO_LIMIT=30
+
+
+# ----------------------------------------------------------------------------
+# Mail / email  (conf: "mail" + AuthServ email-cookie settings)
+# ----------------------------------------------------------------------------
+
+# Master mail switch. Disabled by default: the image ships NO MTA at
+# /usr/sbin/sendmail, so "enabled" without a working mailer/SMTP just makes
+# every cookie mail fail at exec time. Set 1 AND provide a mailer/SMTP to use it.
+X3_MAIL_ENABLE=0
+
+# Path to the sendmail-compatible binary (used when mail is enabled and you are
+# not using the SMTP back-end).
+X3_MAIL_MAILER=/usr/sbin/sendmail
+
+# SMTP server host (SMTP mail back-end).
+X3_MAIL_SMTP_SERVER=localhost
+
+# SMTP service/port name (from /etc/services, e.g. "smtp" = 25).
+X3_MAIL_SMTP_SERVICE=smtp
+
+# AuthServ: allow account verification and password reset by email.
+# Requires mail (above) to be enabled and configured.
+X3_EMAIL_ENABLED=0
+
+# AuthServ: if email is enabled, require verification before an account may
+# authenticate.
+X3_EMAIL_REQUIRED=0
+
+# How long an email verification/reset cookie stays valid.
+X3_COOKIE_TIMEOUT=2d
+
+# How many accounts may share one email address.
+X3_ACCOUNTS_PER_EMAIL=1
+
+
+# ----------------------------------------------------------------------------
+# Password / login policy  (conf: "services"."nickserv")
+# ----------------------------------------------------------------------------
+
+# Minimum characters AuthServ enforces in a password.
+X3_PASSWD_MIN_LENGTH=4
+
+# Minimum digit characters required in a password (0 = no requirement).
+X3_PASSWD_MIN_DIGITS=0
+
+# Minimum uppercase characters required in a password (0 = no requirement).
+X3_PASSWD_MIN_UPPER=0
+
+# Minimum lowercase characters required in a password (0 = no requirement).
+X3_PASSWD_MIN_LOWER=0
+
+# Default max simultaneous logins on a NEW account (users can change their own).
+X3_DEFAULT_MAXLOGINS=3
+
+# Hard ceiling on simultaneous logins that a user cannot raise past.
+X3_HARD_MAXLOGINS=10
+
+# User modes auto-set when an oper auths. If it contains 'o' they are
+# auto-remote-opered on auth.
+X3_AUTO_OPER=+oxwgs
+
+# Oper privileges granted alongside X3_AUTO_OPER when an oper auths
+# (space-separated privilege tokens).
+X3_AUTO_OPER_PRIVS=CHAN_LIMIT SHOW_INVIS SHOW_ALL_INVIS KILL LOCAL_KILL REHASH RESTART DIE JUPE LOCAL_JUPE OPMODE WHOX SEE_CHAN PROPAGATE DISPLAY SEE_OPERS WIDE_GLINE FORCE_OPMODE REMOTEREHASH CHECK SEE_SECRET_CHAN WIDE_SHUN WIDE_ZLINE LIST_CHAN
+
+
+# ----------------------------------------------------------------------------
+# LDAP  (conf: "services"."nickserv" ldap_* — disabled by default)
+# ----------------------------------------------------------------------------
+
+# Master LDAP switch. 0 = off (accounts live only in saxdb). Set 1 to
+# authenticate/store accounts against an LDAP directory.
+X3_LDAP_ENABLE=0
+
+# Write new registrations (including credentials) back to LDAP. REQUIRED for
+# SASL when LDAP is authoritative — without it nickserv gates out ldap_do_add
+# and new accounts land credential-less in saxdb only.
+X3_LDAP_WRITEBACK=0
+
+# LDAP server URI.
+X3_LDAP_URI=ldap://localhost:389
+
+# Base DN under which user entries live.
+X3_LDAP_BASE=ou=users,dc=example,dc=net
+
+# DN format used to bind as a user; %s is replaced with the account name.
+X3_LDAP_DN_FMT=uid=%s,ou=users,dc=example,dc=net
+
+# Admin/manager bind DN used for writes and searches.
+X3_LDAP_ADMIN_DN=cn=admin,dc=example,dc=net
+
+# CHANGE THIS — secret. Password for the admin bind DN above.
+X3_LDAP_ADMIN_PASS=changeme
+
+# Attribute holding the account name.
+X3_LDAP_FIELD_ACCOUNT=uid
+
+# Attribute holding the (hashed) password.
+X3_LDAP_FIELD_PASSWORD=userPassword
+
+# Attribute holding the email address.
+X3_LDAP_FIELD_EMAIL=mail
+
+# Attribute holding the X3 OpServ level.
+X3_LDAP_FIELD_OSLEVEL=X3AccountLevel
+
+# Search filter used to locate user entries.
+X3_LDAP_FILTER=(objectClass=inetOrgPerson)
+
+# Auto-create an LDAP entry on first registration (1 = yes).
+X3_LDAP_AUTOCREATE=1
+
+# LDAP operation timeout, in seconds.
+X3_LDAP_TIMEOUT=10
+
+
+# ----------------------------------------------------------------------------
+# Misc
+# ----------------------------------------------------------------------------
+
+# How often the mondo database (/x3/data/x3.db) is flushed to disk.
+# Set 0 to disable automatic saves.
+X3_DB_SAVE_FREQUENCY=30m
+
+# CHANGE THIS — secret. qserver (remote query interface) password.
+# The entrypoint default is NOT a literal: if this var is left UNSET the
+# entrypoint auto-generates a random 16-char password per boot. Set an explicit
+# value here only if you need a stable, known qserver password.
+X3_QSERVER_PASSWORD=changeme
+
+# AuthServ 'USET title' fakehost suffix (name.title.<suffix>). The entrypoint
+# default is DERIVED from X3_GENERAL_DOMAIN (i.e. equals your domain) unless you
+# set an explicit value here.
+X3_TITLEHOST_SUFFIX=example.com