Installing AMXBans (MySQL Ban System) Step by Step

AMXBans replaces the flat-file amx_ban workflow with a MySQL-backed one: bans live in a database, a web panel manages them, and a fleet of servers can share one ban list. That is its whole appeal — one ban propagates everywhere and non-technical staff manage it from a browser. The trade-off is more moving parts. This walks the install in the order that avoids the usual conflicts.

1. Prerequisites

• A working AMX Mod X install (1.9 recommended) on ReHLDS or HLDS.
• The MySQL / sqlx module enabled — AMXBans is useless without it. See installing the MySQL module.
• A reachable MySQL/MariaDB server and a database you can create tables in.
• The AMXBans package for your AMXX branch. Match the AMXBans version to your AMXX version; a mismatch is the top cause of load failures.

2. Create the database and user

CREATE DATABASE amxbans CHARACTER SET utf8;
CREATE USER 'amxbans'@'%' IDENTIFIED BY 'a-long-password';
GRANT ALL PRIVILEGES ON amxbans.* TO 'amxbans'@'%';
FLUSH PRIVILEGES;

If MySQL runs on the same box as the game server, scope the host to 'localhost' instead of '%' — do not expose the database more widely than you need.

3. Import the schema

The AMXBans package ships a .sql schema file. Import it into the database you just made:

mysql -u amxbans -p amxbans < amxbans.sql

This creates the ban, admin and server tables the plugins and the web panel both read. Use the SQL file from your downloaded package — do not hand-write the schema, and do not import one from a different AMXBans version.

4. Install the plugin and module files

Copy the AMXBans plugins into addons/amxmodx/plugins/ and add them to addons/amxmodx/configs/plugins.ini. AMXBans is split into a core plugin plus a main plugin; add them in the order the package README specifies. Copy any bundled config files into addons/amxmodx/configs/ as directed.

; plugins.ini (order per the AMXBans readme)
amxbans_core.amxx
amxbans_main.amxx

Exact filenames vary by AMXBans release — use the ones in your package rather than assuming. If a plugin is missing from plugins.ini it simply never runs, with no error.

5. Configure the SQL connection

AMXBans reads its database credentials from a config file in addons/amxmodx/configs/ (the package documents the exact name). Fill in host, user, password, database and the ban-prefix/server id:

host     127.0.0.1
user     amxbans
pass     a-long-password
db       amxbans

Keep this file readable only by the server account — it holds a database password. Set the server id so the panel can tell your servers apart if you run more than one.

6. Resolve the admin-system conflict

This is the step people miss. AMXBans can manage admins from its own database tables. If you let it, you must stop the stock SQL admin plugin from fighting it: do not also run admin_sql.amxx pointed at a different table, and decide whether admins come from AMXBans' tables or from users.ini — not both. Running two admin sources produces flicker where a player is an admin one map and not the next. Pick one; for most installs, let AMXBans own bans while users.ini still owns admin flags is the simplest split, following the package's guidance for your version.

7. Load and test

amxx reload
changelevel de_dust2

A map change is the clean way to load new plugins. Watch the console at startup for AMXBans connecting to MySQL.

Common errors

• Failed to load module: mysql/sqlx — the database module is not enabled in modules.ini. Fix that first via the MySQL module guide; nothing else will work until it loads.
• AMXBans logs Can't connect to MySQL — wrong host/user/password, or the DB user is not allowed from the game server's IP. Test the same credentials with the mysql CLI from the game box.
• Plugin shows bad load — AMXBans version does not match your AMXX version. Download the build for your branch.
• Admins flicker on/off between maps — you are running two admin sources (AMXBans tables and admin_sql). Disable one, per step 6.
• Bans not appearing in the web panel — the panel points at a different database than the plugins, or the server id does not match. Confirm both use the same DB and id.

Verification

Ban a test SteamID in-game, then query the database directly:

mysql -u amxbans -p amxbans -e "SELECT player_nick, player_id, ban_length FROM amx_bans ORDER BY ban_created DESC LIMIT 5;"

(Table and column names follow your imported schema.) The ban you just issued should be the top row, and the web panel should show the same entry. Have the banned account try to reconnect and confirm it is refused. When an in-game ban, the database row, and the panel all agree, AMXBans is installed correctly.