Verlihub can load Lua scripts through its Lua plugin. Use Lua when a hub needs a small behavior change without recompiling the Verlihub server.
Common uses include display bots, scheduled announcements, helper commands, validation rules, automated moderation helpers, hub statistics, and integration hooks. Lua support depends on the plugin being installed, built, and enabled.
What The Lua Plugin Does
The Lua plugin executes Lua scripts inside the hub process. That gives administrators a lighter path for hub customization than editing the Verlihub C++ source or writing a compiled plugin.
Lua scripts are usually easier to review and replace than compiled plugins when the change is small and hub-specific.
- Custom hub commands
- Automated welcome messages
- Timed announcements
- User validation checks
- Bot responses
- Operator helper commands
- Logging or notification hooks
- Simple anti-spam or anti-flood checks
- Hub-specific behavior that does not justify a C++ plugin
Requirements
Before enabling Lua support, confirm that the Lua plugin exists on the server. A common plugin path is /usr/local/lib/liblua_pi.so.
Check whether the plugin file exists:
ls -lah /usr/local/lib/liblua_pi.so
If the file does not exist, Lua was probably not built or installed. Rebuild Verlihub with Lua plugin support enabled.
Depending on the system and installation method, the plugin may also live in /usr/lib, /usr/lib64, /usr/local/lib, or /usr/local/lib64. Search for it before changing the hub configuration:
find /usr /usr/local -name 'liblua_pi.so' 2>/dev/null
Building Verlihub With Lua Support
If Lua support was not included during installation, install the Lua development package first. On Debian or Ubuntu:
sudo apt update
sudo apt install lua5.4 liblua5.4-dev
Some Verlihub builds use Lua 5.3 instead of Lua 5.4. Install the matching package when your branch or distribution requires it:
sudo apt install lua5.3 liblua5.3-dev
Then rebuild Verlihub with the Lua plugin enabled through CMake:
cmake .. -DWITH_LUA=ON
make
sudo make install
The exact CMake option name can vary by Verlihub version. Check the available build options before rebuilding a production hub:
cmake -LAH ..
After installation, confirm that the plugin library was installed:
find /usr /usr/local -name 'liblua_pi.so' 2>/dev/null
Plugin Commands
The Lua plugin is managed through Verlihub plugin commands from an operator account.
- List installed or known plugins with
!lstplug. - Register the Lua plugin with
!addplug lua -p /usr/local/lib/liblua_pi.so -a 1 -d Support for Lua scripts.. - Mark the Lua plugin active with
!modplug lua -a 1. - Load the plugin with
!onplug lua. - Confirm loaded plugins with
!pluglist.
!lstplug
!addplug lua -p /usr/local/lib/liblua_pi.so -a 1 -d Support for Lua scripts.
!modplug lua -a 1
!onplug lua
!pluglist
Command Explanation
!lstplug
Lists plugins known to Verlihub. Use it first to see whether the Lua plugin is already registered.
!lstplug
!addplug
Registers the Lua plugin with Verlihub.
!addplug lua -p /usr/local/lib/liblua_pi.so -a 1 -d Support for Lua scripts.
Option meaning:
lua: Internal plugin name.-p /usr/local/lib/liblua_pi.so: Path to the Lua plugin shared library.-a 1: Marks the plugin as active.-d Support for Lua scripts.: Human-readable plugin description.
!modplug
Modifies the plugin record and makes sure the Lua plugin is marked active.
!modplug lua -a 1
!onplug
Loads or starts the Lua plugin after it has been added and enabled.
!onplug lua
!pluglist
Shows currently loaded plugins. Use it to confirm that Lua is active.
!pluglist
Recommended Lua Script Location
Keep Lua scripts in a dedicated directory owned by the Verlihub service user.
sudo mkdir -p /usr/local/etc/verlihub/lua
sudo chown -R verlihub:verlihub /usr/local/etc/verlihub/lua
sudo chmod 750 /usr/local/etc/verlihub/lua
If your Verlihub service runs as another user, replace verlihub:verlihub with the correct user and group.
sudo chown -R vh:vh /usr/local/etc/verlihub/lua
sudo chown -R www-data:www-data /usr/local/etc/verlihub/lua
Do not make Lua script directories world-writable. Avoid chmod 777 /usr/local/etc/verlihub/lua.
Example Lua Script
Create a small test script:
sudo nano /usr/local/etc/verlihub/lua/test.lua
Example content:
-- Simple Verlihub Lua test script.
-- This file confirms that the Lua plugin can load and execute scripts.
function Main()
VH:SendToAll("Lua test script loaded successfully.")
end
The available Lua functions depend on the Verlihub Lua plugin API. Some installations expose helper objects or functions differently, so compare examples with the Lua script library used by your Verlihub version.
Loading Lua Scripts
After the Lua plugin is active, scripts can usually be loaded through plugin-specific Lua commands or configured script directories.
Start by checking available Lua plugin commands from inside the hub:
!help lua
!plughelp lua
If the plugin supports script listing, loading, unloading, or reloading, you may see commands similar to these:
!lua
!lslua
!loadlua
!unloadlua
!reloadlua
Command names can differ between Verlihub builds and plugin versions.
Verifying Lua Is Working
Verify the setup in stages. First confirm that the plugin is registered, then confirm that it is loaded:
!lstplug
!pluglist
Then check server logs for Lua plugin messages:
journalctl -u verlihub -n 100 --no-pager
If Verlihub is not managed by systemd, check the configured Verlihub log directory instead. Common locations include /var/log/verlihub and /usr/local/var/log/verlihub.
Search for Lua-related log entries when the service log is large:
grep -i lua /var/log/verlihub/* 2>/dev/null
Production Recommendations
Use Lua for small custom behavior, not for heavy processing. Lua code runs inside the hub process, so a bad script can affect chat, login, or user-list updates.
Good Lua use cases:
- Simple commands
- Hub messages
- User checks
- Lightweight automation
- Small integration hooks
Avoid using Lua for:
- Long-running background jobs
- Heavy database queries
- Large file processing
- Blocking network calls
- CPU-heavy loops
- Anything that can freeze the hub process
Test scripts on a staging hub before loading them on a public hub with users connected.
Security Notes
Only trusted administrators should be able to upload or modify Lua scripts.
Recommended permissions:
sudo chown -R verlihub:verlihub /usr/local/etc/verlihub/lua
sudo chmod -R u=rwX,g=rX,o= /usr/local/etc/verlihub/lua
Do not allow untrusted users to write Lua files. Do not store secrets directly in Lua scripts unless file permissions are locked down.
Keep plugin management commands operator-only or admin-only. Normal users should not be able to load, unload, or replace scripts.
Troubleshooting
Plugin file not found
Symptoms include Cannot load plugin, No such file, or liblua_pi.so not found. Search for the library, then update the stored plugin path:
find /usr /usr/local -name 'liblua_pi.so' 2>/dev/null
!modplug lua -p /correct/path/to/liblua_pi.so
Lua plugin does not appear in the plugin list
Check whether it was added. If it is missing, add it, mark it active, and load it:
!lstplug
!addplug lua -p /usr/local/lib/liblua_pi.so -a 1 -d Support for Lua scripts.
!modplug lua -a 1
!onplug lua
Plugin exists but fails to load
Check shared library dependencies and look for missing Lua libraries:
ldd /usr/local/lib/liblua_pi.so
not found
If Lua libraries are missing, install the matching Lua runtime package.
sudo apt install lua5.4 liblua5.4-0
sudo apt install lua5.3 liblua5.3-0
Script does not run
Check the script path, file permissions, and Verlihub logs. Also verify that the Lua plugin supports the script API used by the script.
ls -lah /usr/local/etc/verlihub/lua
journalctl -u verlihub -n 100 --no-pager
Hub becomes unstable after loading a script
Unload the script or disable the Lua plugin. If the hub is not responsive, stop Verlihub from the shell and move the script out of the Lua directory:
sudo systemctl stop verlihub
sudo mkdir -p /usr/local/etc/verlihub/lua-disabled
sudo mv /usr/local/etc/verlihub/lua/problem-script.lua /usr/local/etc/verlihub/lua-disabled/
sudo systemctl start verlihub
Suggested Admin Workflow
- Confirm the Lua plugin exists.
- Add the plugin with
!addplug. - Enable it with
!modplug. - Start it with
!onplug. - Confirm it with
!pluglist. - Create a dedicated Lua script directory.
- Add one small test script.
- Check Verlihub logs.
- Add production scripts one at a time.
- Keep backups of working scripts before making changes.
Verlihub Lua Script Library
The Verlihub Lua script library contains example scripts and reusable Lua code for hub customization. Use it as a reference for supported functions, event hooks, and command patterns.
When using scripts from the library:
- Review the script before installing it.
- Confirm it matches your Verlihub version.
- Test it on a non-production hub first.
- Check for hardcoded paths, hub names, operator nicknames, or database settings.
- Keep a backup of the original script before editing.