LinkBox Web Monitor + Admin Tool - Setup Instructions ===================================================== *** READ THIS ENTIRE FILE BEFORE INSTALLING OR UPDATING *** See also: README-FIRST.txt (short checklist and disclaimer) DISCLAIMER AND INTENDED AUDIENCE ------------------------------ This package is for operators running TheLinkBox (TLB) as: 1. An IRLP experimental reflector (exp####), and/or 2. An EchoLink conference (*CONF* / *OHIO* / similar), and/or 3. An EchoLink -L (Link) or -R (Repeater) station running TLB, and/or 4. A mixed bridge that carries IRLP and/or EchoLink (including -L / -R) The installer/updater asks: - What THIS box is (exp / conference / -L / -R) - Which networks it uses (both, IRLP only, or EchoLink only / no IRLP) It provides: - A public, read-only web status monitor (exp.php — Paul KN2R official name) - A separate tlb-admin/index.php tool (Apache login) for Connect, Mute, Bump, Ban, logs - Optional EventScripts for cleaner IRLP bumps and auto-linking (tlbevent-conference.sh WITH policy, or tlbevent.sh WITHOUT) This is NOT a general-purpose IRLP node web panel. Do not install on a standard IRLP node unless you also run TLB as a reflector/conference bridge. Use at your own risk. Test on a non-production system first when possible. The authors provide no warranty; you are responsible for Apache security, passwords, and TLB conference policy on your system. PREREQUISITES (verify before install) ------------------------------------- [ ] TheLinkBox is installed and running; tlbcmd responds on this server [ ] Know which site type you are (installer asks; NAME decides the title): 1) IRLP experimental reflector — name like exp0092 only Page shows: "IRLP exp0092 Reflector" Requires: export ALLOW_EXPERIMENTAL_NODES=YES 2) EchoLink conference — name like *OHIO* / *CONF* / *HAM* Page shows: "EchoLink *OHIO* Conference" A name starting with * is NEVER titled as an IRLP Reflector. 3) EchoLink -L Link — callsign like K8LRC-L Page shows: "EchoLink K8LRC-L Link" 4) EchoLink -R Repeater — callsign like K8LRC-R Page shows: "EchoLink K8LRC-R Repeater" [ ] Know which networks this box uses (installer asks): both IRLP+EchoLink, IRLP only, or EchoLink only (no IRLP) [ ] IRLP / conferences: installer asks which ONE EventScript to activate: 1) tlbevent-conference.sh = WITH conference policy (normal production) 2) tlbevent-nopolicy.sh = WITHOUT policy (preferred NO-policy name) 3) tlbevent.sh = WITHOUT policy (legacy name) All three install if missing; EventScript= set only if unset All support linkit and clean IRLP .bump (TCP 15425) [ ] EchoLink -L / -R / conference traffic as applicable (tlbevent-conference.sh also has *CALLSIGN* / *-L* / *-R* / CONF handling) [ ] Apache2 with PHP; document root /var/www/html (or set WEB_ROOT) [ ] Plan to password-protect tlb-admin/ (included .htaccess template) [ ] Optional: /home/tlb.log and /home/tlb/log/messages readable by www-data OVERVIEW -------- This package splits the LinkBox web interface into: 1. Public status monitor (exp.php) - read only, no login. (Paul KN2R official name) 2. Admin tool (tlb-admin/index.php) - Connect, Mute, Bump, Disconnect, Ban, Restart TLB, logs, etc. Protected ENTIRELY by Apache Basic Auth (.htaccess + .htpasswd). Restart TLB runs Paul's restart-tlb bash script (NOT systemd). See Step 5b. 3. EventScripts (Step 6) - strongly recommended for IRLP experimental reflectors; optional for others. Needed so .bump disconnects problem IRLP nodes cleanly. Two names (pick one in tlb.conf): /home/thelinkbox/scripts/tlbevent-conference.sh (WITH policy) /home/thelinkbox/scripts/tlbevent.sh (WITHOUT policy) WEB DEPLOYMENT (/var/www/html) ------------------------------ The public monitor and admin tool MUST live under your Apache web root. Default on Debian/Ubuntu: /var/www/html (index.html is NOT installed — package no longer ships a web-root test page) /var/www/html/exp.php - public status monitor (read only) /var/www/html/tlb-common.inc - shared PHP functions /var/www/html/tlb-admin/index.php - administration tool /var/www/html/tlb-admin/.htaccess - Apache login for tlb-admin/ install-tlbweb.sh copies templates there automatically (WEB_ROOT=/var/www/html). If your web root is different, set WEB_ROOT before running the installer: sudo WEB_ROOT=/var/www/html ./install-tlbweb.sh Package download uses the server IP first (some networks block crabdance.com DDNS): http://45.32.193.131/Beta/tlb-2+/ Alternate: http://linkbox.k8lrc.crabdance.com/Beta/tlb-2+/ Do NOT leave the live site in /root or the download folder - install copies everything into /var/www/html for Apache to serve. FILES IN THIS PACKAGE (in order) -------------------------------- README-FIRST.txt - short disclaimer + checklist (read first) SETUP-INSTRUCTIONS.txt - this file (full guide) CHANGELOG.txt - project history (started 2026-06-02 / major updates) install-tlbweb.sh - automated installer (v15-BETA - see Step 0) update-tlbweb.sh - update existing install (v17-BETA - see Step 0b) index.template - DO NOT EDIT; installer -> /var/www/html/exp.php (public monitor) tlb-common.inc - shared functions -> /var/www/html/tlb-common.inc tlbevent-conference.template - WITH policy -> tlbevent-conference.sh (Step 6 A) tlbevent-conference.sh - same WITH-policy script (reference) tlbevent.template - WITHOUT policy -> tlbevent.sh (Step 6 B) tlbevent.sh - same NO-policy script (reference) admin-index.template - DO NOT EDIT; installer -> /var/www/html/tlb-admin/index.php admin-htaccess - template -> copy to /var/www/html/tlb-admin/.htaccess tlbevent-nopolicy.template - WITHOUT policy -> tlbevent-nopolicy.sh (preferred) tlbevent-nopolicy.sh - same NO-policy script (preferred name) restart-tlb.sample - Restart TLB NO policy (Step 5b) restart-tlb-conference.sample - Restart TLB WITH policy (kills tlbevent-conference.sh) Also at the Beta parent URL (Paul-style one-package tgz): ../install-tlbweb-fresh - wget tgz, tar xvzf, run install (like supermonASL_fresh_install) ../update-tlbweb-latest - wget tgz, tar xvzf, run update (like supermonASL3_latest_update) ../tlb-2+-web.tgz - one archive (built by ../make-tlbweb-tgz.sh with tar cvzf) Publish ALL of the above files at the package URL (flat directory, no auth). STEP 0 - Automated install (recommended if you want a script) ------------------------------------------------------------ Preferred — one-package tgz (same idea as Paul's supermonASL_fresh_install): wget 'http://45.32.193.131/Beta/install-tlbweb-fresh' chmod +x install-tlbweb-fresh sudo ./install-tlbweb-fresh Package URL (files / alternate to tgz wrappers): http://45.32.193.131/Beta/tlb-2+/ Alternate: http://linkbox.k8lrc.crabdance.com/Beta/tlb-2+/ Or download installer only - package files fetch automatically: wget 'http://45.32.193.131/Beta/tlb-2+/install-tlbweb.sh' chmod +x install-tlbweb.sh sudo ./install-tlbweb.sh You should see: LinkBox web installer v15-BETA ... before any prompts. The Server public IP prompt auto-detects your IP as the default. If package files are missing, the script downloads them first. If you already have the full package directory on your server: chmod +x install-tlbweb.sh sudo ./install-tlbweb.sh The script will install into /var/www/html (Apache web root): - index.template -> /var/www/html/exp.php (official public monitor) - tlb-common.inc -> /var/www/html/tlb-common.inc - admin-index.template -> /var/www/html/tlb-admin/index.php - admin-htaccess -> /var/www/html/tlb-admin/.htaccess - Prompt for Apache auth (new .htpasswd or reuse Supermon's) - Optionally install EventScripts (conference + plain) and fix log permissions - Back up any existing files before overwriting Non-interactive examples: # IRLP experimental reflector (often also carries EchoLink): sudo SITE_TYPE=irlp SERVER_IP=203.0.113.10 REFLECTOR_NAME=exp0092 \ USES_IRLP=1 USES_ECHOLINK=1 DOMAIN_OR_IP=linkbox.example.com \ ALLSTAR_NODE=41001 INSTALL_TLBEVENT=1 TLBEVENT_POLICY=conference \ ./install-tlbweb.sh --yes # EchoLink conference only (no IRLP): sudo SITE_TYPE=echolink SERVER_IP=203.0.113.10 REFLECTOR_NAME='*CONF*' \ USES_IRLP=0 USES_ECHOLINK=1 ./install-tlbweb.sh --yes # EchoLink -L Link station (no IRLP): sudo SITE_TYPE=link SERVER_IP=203.0.113.10 REFLECTOR_NAME=K8LRC-L \ USES_IRLP=0 USES_ECHOLINK=1 ./install-tlbweb.sh --yes # EchoLink -R Repeater station (no IRLP): sudo SITE_TYPE=repeater SERVER_IP=203.0.113.10 REFLECTOR_NAME=K8LRC-R \ USES_IRLP=0 USES_ECHOLINK=1 ./install-tlbweb.sh --yes Then continue with Steps 4-7 below if Apache auth modules or AllowOverride still need attention. Skip Steps 1-2 if the script completed successfully. STEP 0b - Update an existing install ------------------------------------ Preferred — one-package tgz (same idea as Paul's supermonASL3_latest_update): wget 'http://45.32.193.131/Beta/update-tlbweb-latest' chmod +x update-tlbweb-latest sudo ./update-tlbweb-latest Or use update-tlbweb.sh to refresh templates while keeping your IP, reflector name, AllStar node, log paths, public monitor filename, and tlb-admin passwords. wget 'http://45.32.193.131/Beta/tlb-2+/update-tlbweb.sh' chmod +x update-tlbweb.sh sudo ./update-tlbweb.sh Run from /root or any directory - NOT from /var/www/html. The script updates files inside /var/www/html automatically. install-tlbweb.sh is downloaded to the same folder if needed. Also updates: tlb-common.inc, public monitor (exp.php), tlb-admin/index.php. New installs standardize on exp.php public + tlb-admin/index.php admin. Sets tlb-admin "Back to public monitor" link automatically. Public monitor links to tlb-admin/ (Administration Tools; Apache login required). Logs are viewed inside tlb-admin (not as separate public links). Does NOT overwrite / touch on update: tlb-admin/.htaccess (if present), .htpasswd /home/thelinkbox/scripts/* (EventScripts, restart-tlb*) tlb.conf EventScript= WEB_ROOT/index.html (no longer shipped) Copy EventScripts / restart scripts from the package by hand if you want newer versions. Edit tlb.conf EventScript= yourself, then restart TLB. Optional: sudo ./update-tlbweb.sh --yes # no confirm prompt (Public monitor is permanently exp.php; web-root index.php is not updated.) STEP 1 - Copy web files to /var/www/html (manual) -------------------------------------------------- Install these under your Apache document root (default /var/www/html): /var/www/html/exp.php (from index.template) — official public monitor /var/www/html/tlb-common.inc (from tlb-common.inc) /var/www/html/tlb-admin/index.php (from admin-index.template) /var/www/html/tlb-admin/.htaccess (from admin-htaccess) install-tlbweb.sh always uses exp.php for public monitoring. (Web-root index.php is never the public monitor; admin is tlb-admin/index.php.) Public URL: http://YOUR-SERVER/exp.php Admin URL: http://YOUR-SERVER/tlb-admin/ STEP 2 - Edit placeholders (manual only) ----------------------------------------- Open exp.php and tlb-admin/index.php and replace: YOUR_SERVER_IP -> your server's public IP address YOUR_SUPERMON_URL -> typed Supermon site (http or https; blank = omit link) YOUR_LINK_TYPE -> IRLP or EchoLink YOUR_REFLECTOR_NAME -> exp0092 (IRLP) or *CONF* / *HAM* (EchoLink) YOUR_SITE_KIND -> Reflector (IRLP) or Conference (EchoLink) YOUR_ALLSTAR_NODE -> your AllStar hub node (public monitor only; remove the AllStar link line entirely if you don't use AllStar) Headline becomes: The LinkBox Monitor 2+ IRLP exp0092 Reflector The LinkBox Monitor 2+ EchoLink *CONF* Conference YOUR_PUBLIC_MONITOR_SCRIPT -> exp.php (tlb-admin back link; set by installer) YOUR_DOMAIN_OR_IP -> fallback hostname (tlb-admin/index.php only) Public monitor links to tlb-admin/ (Administration Tools; Apache auth). tlb.log and messages are shown inside tlb-admin only. The install script sets exp.php (default) and updates tlb-admin to match. Also check at the top of both files: $tlbcmdport -> e.g. "-p6198" if tlbcmd uses a non-default port $tlblogpath -> default /home/tlb.log (tlb-admin only, if different) $tlbmessagespath -> default /home/tlb/log/messages (tlb-admin only) $tlbrestartscript -> full path to Paul's restart-tlb (tlb-admin only; Step 5b) STEP 3 - Apache auth for tlb-admin/ (manual if not using install script) ------------------------------------------------------------------------- IMPORTANT — always use htpasswd capital -B (bcrypt). Always. If -B is omitted, htpasswd uses old MD5 encryption, which by today's standards is NOT secure. With -B, htpasswd uses bcrypt (best available) — considered Secure. Pick ONE: A) Reuse Supermon's password file: Edit tlb-admin/.htaccess -> AuthUserFile /var/www/html/supermon/.htpasswd (If you create or update Supermon users later, use -B there too.) B) Create a dedicated admin password file (deletes any current users if the file already exists): htpasswd -cB /var/www/html/tlb-admin/.htpasswd yourusername To ADD more usernames later (do not use -c — that recreates/wipes the file): htpasswd -B /var/www/html/tlb-admin/.htpasswd anotheruser The install script uses the same bcrypt -B option automatically. STEP 4 - Allow Apache to read .htaccess ---------------------------------------- In /etc/apache2/apache2.conf, for /var/www/: AllowOverride All (NOT None) Then: apache2ctl configtest systemctl restart apache2 Enable auth modules if needed: a2enmod auth_basic authn_file authz_user authz_core systemctl restart apache2 STEP 5 - Log file permissions (admin log panels) ------------------------------------------------- The admin tool tails these logs (adjust paths in tlb-admin/index.php if needed): /home/tlb.log /home/tlb/log/messages Apache (www-data) must be able to read them: chmod 644 /home/tlb.log /home/tlb/log/messages chmod 755 /home/tlb/log chmod o+x /home/tlb (if the home directory is locked down) STEP 5b - Restart TLB button (three scripts — pick one) ------------------------------------------------------- There are THREE restart scripts (fresh install asks 1, 2, or 3): 1) restart-tlb-conference — WITH policy (pair with tlbevent-conference.sh) 2) restart-tlb-nopolicy — NO policy (pair with tlbevent-nopolicy.sh) 3) restart-tlb — NO policy legacy (pair with tlbevent.sh) All three install if missing (never overwritten); tlb-admin uses the one you choose. The "Restart TLB" button runs that bash script. It does a clean restart: kill tlb + the matching EventScript, then start tlb again. Automated (fresh install recommended): sudo ./install-tlbweb.sh (update-tlbweb.sh does NOT overwrite restart scripts — copy by hand if needed) Fresh install: - Installs all three if missing (never overwrites existing) - Asks 1 / 2 / 3 (defaults to match EventScript choice) - Creates /etc/sudoers.d/tlb-restart-web if missing - Sets $tlbrestartscript in tlb-admin/index.php to the active choice Override path if needed: sudo RESTART_TLB_NOPOLICY_DEST=/usr/local/bin/restart-tlb-nopolicy ./install-tlbweb.sh Manual setup (if not using the installer): 1. Install the script (use your copy, or restart-tlb.sample from this package): cp restart-tlb.sample /home/thelinkbox/scripts/restart-tlb chmod 755 /home/thelinkbox/scripts/restart-tlb Edit the script if your TLB binary or tlb.conf path differs from: /usr/local/libexec/tlb -d -f /home/thelinkbox/tlb.conf The script may live anywhere; common paths: /home/thelinkbox/scripts/restart-tlb /usr/local/bin/restart-tlb 2. Point tlb-admin at it (top of tlb-admin/index.php): $tlbrestartscript = "/home/thelinkbox/scripts/restart-tlb"; Empty string = auto-detect the common paths above. 3. Allow Apache (www-data) to run restart-tlb with NO password. File to create: /etc/sudoers.d/tlb-restart-web Line that MUST be in that file: www-data ALL=(root) NOPASSWD: /home/thelinkbox/scripts/restart-tlb Create it as root: cat > /etc/sudoers.d/tlb-restart-web <<'EOF' # Allow Apache (www-data) to run Paul's restart-tlb from tlb-admin # without a password. Used by tlb_restart_service() in tlb-common.inc. www-data ALL=(root) NOPASSWD: /home/thelinkbox/scripts/restart-tlb EOF Then set permissions and validate: chmod 440 /etc/sudoers.d/tlb-restart-web visudo -cf /etc/sudoers.d/tlb-restart-web chmod 440 is correct and required (r--r-----). sudo will refuse the file if it is group- or world-writable. Path in this file MUST match $tlbrestartscript exactly. Check it: sudo -l -U www-data | grep restart-tlb 4. Test from the shell as the web user: sudo -u www-data sudo -n /home/thelinkbox/scripts/restart-tlb You should see Paul's Stand-by / Done! / Status output (no password prompt). 5. In tlb-admin, click Restart TLB. Expect a green banner: TheLinkBox restarted OK (restart-tlb finished) STEP 6 - EventScript: three choices (installer asks 1, 2, or 3) --------------------------------------------------------------- All three scripts install if missing (never overwritten). Fresh install asks which ONE to set in tlb.conf (only if EventScript= is unset): 1) WITH conference policy — tlbevent-conference.sh 2) NO policy — tlbevent-nopolicy.sh (preferred name) 3) NO policy (legacy name) — tlbevent.sh Point EventScript in tlb.conf at exactly ONE of them, then restart TLB. Typical install directory (use /home/tlb/scripts/ on older boxes if that is where your TLB scripts live): /home/thelinkbox/scripts/ A) tlbevent-conference.sh — WITH conference POLICY (normal / production) ----------------------------------------------------------------------- Use this for day-to-day conference / reflector operation. Includes: - Auto-link (linkit) new VoIP users to others on the reflector - Rapid-reconnect and multi-conference POLICY (bans when enabled) - Clean IRLP .bump / kick / ban via Speak Freely TCP 15425 (stn####) - Extra handling for *CALLSIGN*, *-L, *-R, and CONF links Install (from the package directory, or after wget from tlb-2.0+/): mkdir -p /home/thelinkbox/scripts cp tlbevent-conference.template \ /home/thelinkbox/scripts/tlbevent-conference.sh # or: cp tlbevent-conference.sh /home/thelinkbox/scripts/ chmod +x /home/thelinkbox/scripts/tlbevent-conference.sh In tlb.conf: EventScript = /home/thelinkbox/scripts/tlbevent-conference.sh B) tlbevent-nopolicy.sh — WITHOUT policy (preferred NO-policy name) ------------------------------------------------------------------ Use this when operators are testing Restart TLB, rapid reconnects, or multi-conf experiments and you do NOT want policy bans. Includes: - Auto-link (linkit) — same as WD5M-style behavior - Clean IRLP .bump / kick / ban via TCP 15425 (stn####) - Stops any leftover tlbevent-conference.sh --monitor so policy cannot keep running in the background Does NOT include: - Rapid-reconnect bans - Multi-conference bans Install: mkdir -p /home/thelinkbox/scripts cp tlbevent-nopolicy.template /home/thelinkbox/scripts/tlbevent-nopolicy.sh # or: cp tlbevent-nopolicy.sh /home/thelinkbox/scripts/ chmod +x /home/thelinkbox/scripts/tlbevent-nopolicy.sh In tlb.conf: EventScript = /home/thelinkbox/scripts/tlbevent-nopolicy.sh C) tlbevent.sh — WITHOUT policy (legacy name; same as B) ------------------------------------------------------- Same behavior as tlbevent-nopolicy.sh. Keep using this name if your tlb.conf already points here. Install: mkdir -p /home/thelinkbox/scripts cp tlbevent.template /home/thelinkbox/scripts/tlbevent.sh # or: cp tlbevent.sh /home/thelinkbox/scripts/tlbevent.sh chmod +x /home/thelinkbox/scripts/tlbevent.sh In tlb.conf: EventScript = /home/thelinkbox/scripts/tlbevent.sh Installer (installs all three if missing; you pick one for tlb.conf): sudo INSTALL_TLBEVENT=1 ./install-tlbweb.sh (or answer Y when fresh install asks) sudo ./update-tlbweb.sh (updater does NOT refresh EventScripts or /home/thelinkbox/scripts — copy from the package manually if you want newer scripts) Defaults: /home/thelinkbox/scripts/tlbevent-conference.sh (WITH policy) /home/thelinkbox/scripts/tlbevent-nopolicy.sh (WITHOUT policy — preferred) /home/thelinkbox/scripts/tlbevent.sh (WITHOUT policy — legacy) After your choice: - Edit TLBCMD / TLB_LOGFILE at the top of the script if your paths differ - Restart TheLinkBox - Without any EventScript, the web Bump button still runs, but IRLP experimental reflectors should use A, B, or C so problem stn#### nodes actually disconnect (TCP 15425) Legacy note: older packages used tlbevent.sh or tlbevent.conference.sh for WITH policy, and tlbevent-testing.sh for WITHOUT. Prefer: EventScript = /home/thelinkbox/scripts/tlbevent-conference.sh EventScript = /home/thelinkbox/scripts/tlbevent-nopolicy.sh STEP 7 - Test ------------- 1. http://YOUR-SERVER/exp.php -> public monitor, NO login prompt 2. http://YOUR-SERVER/tlb-admin/ -> MUST prompt for username/password (use a private/incognito window) 3. After login: live table refreshes, Bump/Mute/Connect work, logs display 4. Bump an IRLP test node - should disappear cleanly from the table 5. EchoLink -L / -R / conference: confirm Connect and Bump behave as expected 6. Restart TLB button: green "restarted OK" banner; tlb process comes back (Step 5b - requires Paul's restart-tlb + sudoers) CREDITS ------- Paul Aidukas KN2R - LinkBox / original exp.php architecture Logan Crook K8LRC - packaging, installers, public/admin split AI - co-generation assistance TROUBLESHOOTING --------------- - wget/download fails (401, 404, or missing file): Upload ALL package files from tlb-web to the package URL (flat directory). Required: install-tlbweb.sh SETUP-INSTRUCTIONS.txt index.template admin-index.template admin-htaccess tlb-common.inc tlbevent-conference.template tlbevent-conference.sh tlbevent.template tlbevent.sh restart-tlb.sample URL: http://45.32.193.131/Beta/tlb-2+/ - Installer prompts before downloading (old v1/v2 script): Re-fetch install-tlbweb.sh; v3 downloads package files before prompts - No login prompt on /tlb-admin/: .htaccess empty or missing, AllowOverride None, or auth modules disabled - Log panels show "not readable": Fix permissions (Step 5) or set $tlblogpath / $tlbmessagespath - Restart TLB says "password is required" or does nothing: Step 5b: install restart-tlb, set $tlbrestartscript, then put this exact line in /etc/sudoers.d/tlb-restart-web and chmod 440 that file: www-data ALL=(root) NOPASSWD: /home/thelinkbox/scripts/restart-tlb Then test: sudo -u www-data sudo -n /home/thelinkbox/scripts/restart-tlb - PHP notices in error log: Use the current tlb-common.inc from this package - IRLP bump leaves node lingering with Kicked/Inactive flags: Install an EventScript (Step 6) and confirm EventScript in tlb.conf