Frequently asked questions

The questions we answer most often in #help-support, grouped by topic. If yours isn’t here, drop into our Discord and ask.

General

What is SourceBans++?

A source-available admin and ban-management system for Source-engine game servers, free for community use. It has a web panel your admins log into and a set of SourceMod plugins running on each of your game servers. They share a database and coordinate through it.

The Overview has the longer answer.

Is it free?

Yes, for everyone except game-server hosting companies who want to offer the panel to their customers as a hosted, managed service.

The web panel is distributed under the Elastic License 2.0; the SourceMod plugins are under GPLv3. Hobby use, community use, running it for your own clan / network, bundling it into a Docker image, publishing a Pterodactyl egg, and packaging it for a distro all stay free under ELv2’s terms. What ELv2 reserves is the right to provide the panel as a hosted or managed service to third parties; if that’s your business model, the project offers a separate commercial license. For commercial licensing inquiries, reach out on the Discord. See the sponsor page for the longer breakdown.

We don’t sell hosting, support, or plugins ourselves.

Where can I get help?

• First: the docs you’re reading. The Quickstart and Troubleshooting sections cover the things we answer most often.
• Then: our Discord #help-support channel.
• Bug reports: open a GitHub issue with reproduction steps.

I want to contribute, where do I start?

Take a stab at the issues labelled good first issue or help wanted on the issue tracker. The AGENTS.md file in the repo root is the contributor cheatsheet: conventions, the local Docker dev stack, and the “where to find what” index.

Translation PRs are always welcome too. See Translating.

Installing

Can I use SourceBans++ without the web panel?

Not really. You need the web panel at minimum to install, configure, and add servers. In theory you could stop using the panel after that and the in-game half would keep enforcing bans, but you’d lose access to most of what makes SourceBans++ useful: adding admins, managing bans, processing appeals, viewing the audit log.

We recommend running the entire package, panel included.

Does it work with [game]?

Anything built on Source / Source 2 with a SourceMod release: TF2, Counter-Strike (Source / GO / 2), Garry’s Mod, DoD:S, L4D / L4D2, Insurgency, NMRiH, Synergy, and friends.

If SourceMod runs on it, SourceBans++ usually runs on it.

Can I run the panel and game servers on different hosts?

Yes. The panel and plugin halves only need to share a database; they can be on different hosts, different networks, even different continents. The DB user’s grant has to allow connections from both hosts, which is the most common stumbling block. See Database setup → Granting permission.

Will it work on shared hosting?

Yes, with two caveats:

• The host must run PHP >= 8.5 with pdo_mysql, openssl, xml, and mbstring. Most modern shared hosts do. (Older 1.x installs also required gmp. Not needed since 2.x; native 64-bit int math handles Steam ID conversion.)
• The host must allow remote database connections if your game servers aren’t on the same host. Many shared hosts disable this by default; check the control panel for a “Remote MySQL” or “Allowed hosts” setting.

The web panel

Why am I seeing a blank white page?

PHP hit a fatal error before any output was sent. The actual error goes to your webserver’s PHP error log. See Panel won’t load for the typical log paths and how to read them.

Why isn’t the panel emailing me as the owner?

The owner account isn’t assigned to any permission group by default, so email-on-event triggers don’t fire for it.

Edit the owner account under Admin Panel → Admins and assign yourself to an admin group with the relevant notification flags (typically the group that gets emails for new ban submissions, protests, etc.).

How do I verify SMTP without waiting for a real event?

Go to Admin Panel → Settings → Main and scroll to the SMTP card. Below the regular SMTP fields you’ll see Send a test email — it’s pre-populated with your admin account’s email but you can swap in any recipient. Click Send test email and the panel dispatches a one-shot verification message through the saved SMTP credentials.

A few things to keep in mind:

• The button is greyed out until Host, Username, and the From address are saved. Save the form first if you just changed any of them — the test reads the persisted values, not the unsaved contents of the inputs.
• The action is rate-limited to one send every 10 seconds per install (prevents accidental misconfiguration from spamming your SMTP relay).
• Both success and failure show up in Admin Panel → System log, so you can correlate a “Test email failed” toast with the underlying SMTP error (Mail error) entry from the same request.

I locked myself out by enabling Steam-only login

If you flipped the Steam-only login switch and you no longer have Steam access, the panel won’t accept your password.

The fix is a one-row database update. Sign into your DB with any client (PHPMyAdmin, Adminer, the mysql CLI):

1. Open the _settings table.
2. Find the row where setting = 'config.enablesteamlogin'.
3. Set its value back to 1.

That re-enables password login alongside Steam OpenID. Sign in, then fix the configuration the way you intended.

Caution

Editing _settings directly is a foot-gun: bad values can break the panel’s bootstrap. Touch only the row you intend to fix, and back up the table first if you’re not sure.

How do I customize the dashboard?

See Customizing the dashboard. Short version: Admin Panel → Settings → Settings → Dashboard, edit the intro text (Markdown supported), save.

The plugin

Why is “Ban player” missing from SourceMod’s admin menu?

SourceMod’s built-in basebans.smx was still loaded when you installed SourceBans++. The plugin automatically disables basebans.smx, but the menu doesn’t refresh until the server is restarted.

After the restart, check that basebans.smx moved to plugins/disabled/. Some hosters don’t allow plugins to move files; if basebans.smx is still in plugins/, move it manually.

Why does the panel say “Database failure: Could not find database conf ‘sourcebans’”?

The "sourcebans" block is missing from SourceMod’s databases.cfg. The Quickstart shows the canonical block. Add it, save, reload the map, and the plugin will pick it up.

Why does the panel only show “Max Players” instead of the actual player list?

The game server is hiding the player list from external A2S queries. Add this to server.cfg (or any startup config):

host_players_show 2

Reload the map and the panel will see the real player list on its next poll.

Can I forward bans to Discord?

Yes, via the separate sbpp/discord-forward plugin. Setup is in Discord notifications.

Note: the forwarder currently only fires for actions taken in-game. Bans applied from the web panel won’t be forwarded (this is a tracked feature request).

Updating

How do I upgrade SourceBans++?

The full upgrade path is in Updating. Short version: back up your database, upload the new files, visit /updater/, delete the install/ and updater/ directories when done.

Is upgrading to 2.0.x different?

Yes. Read Upgrading from 1.8.x to 2.0.x first. v2.0 raises the PHP version floor, resets the active theme, and ships default-on anonymous telemetry. The upgrade itself is otherwise normal.

Will my custom theme survive an upgrade?

For minor / patch upgrades, yes. For major version jumps (like 1.8.x → 2.0.x), custom themes are usually broken because the template signatures change. The v2.0 updater specifically resets the active theme to default to keep the panel loadable; you can re-select your fork after porting it.

See Upgrading from 1.8.x → 2.0.x for the v2.0 details.