# Proxy Setup
Name Tag is a backend (Paper) plugin. On a proxy network (BungeeCord, Velocity, Waterfall, Bungee-forks), point every backend server at the **same** MongoDB, MySQL, or MariaDB instance and nick state becomes network-wide — a player nicked on `lobby-1` keeps the same nickname, skin, and optional spoofed UUID when they switch to `survival-2`.
The default `LOCAL` backend writes to each server's `data.yml` only. It is not shared across servers and should be used for single-server setups only.
---
## How It Works
Each backend server runs its own copy of Name Tag. The plugins coordinate only through the shared database — there is no proxy-side plugin and no cross-server messaging channel required.
1. Player joins `lobby-1` → Name Tag loads their nick data from the shared database.
2. An admin runs `/nick <player> as <name>` on `lobby-1` → the data is written to the shared database.
3. Player transfers to `survival-2` → Name Tag on `survival-2` loads the same record and re-applies the nickname, skin, and fake rank on join.
---
## Choosing a Backend
| Backend | Shared across proxy? | Recommended for |
|---|---|---|
| `LOCAL` | No | Single-server setups |
| `MONGODB` | Yes | Existing MongoDB infrastructure |
| `MYSQL` | Yes | Existing MySQL infrastructure |
| `MARIADB` | Yes | Existing MariaDB infrastructure |
`MONGODB`, `MYSQL`, and `MARIADB` are equivalent in terms of Name Tag functionality. Pick the one your network already operates. `MYSQL` uses the MySQL Connector/J driver; `MARIADB` uses the native MariaDB JDBC driver — prefer the one that matches your database.
---
## MongoDB Setup
On **every** backend server, set `plugins/NameTag/config.yml`:
```yaml
storage:
type: "MONGODB"
mongodb:
uri: "mongodb://user:
[email protected]:27017"
database: "nametag"
collection: "players"
pool-size: 10
```
- `uri`, `database`, and `collection` must be **identical** on every backend.
- `pool-size` is per-server and can be tuned individually.
- Reload with `/nametag reload` or restart the server.
---
## MySQL Setup
On **every** backend server, set `plugins/NameTag/config.yml`:
```yaml
storage:
type: "MYSQL"
mysql:
host: "db.internal"
port: 3306
database: "nametag"
table: "nametag_players"
username: "nametag_user"
password: "change-me"
pool-size: 10
use-ssl: false
```
- `host`, `port`, `database`, and `table` must be **identical** on every backend.
- The `nametag_players` table is created automatically on first start — no manual schema work required.
- `pool-size` is per-server.
- Enable `use-ssl: true` if your MySQL instance requires TLS.
### Minimum MySQL Permissions
The configured user needs the following grants on the Name Tag database:
```sql
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE ON nametag.* TO 'nametag_user'@'%';
```
`CREATE` is only required on first start so Name Tag can provision the table. It can be revoked afterward.
---
## MariaDB Setup
On **every** backend server, set `plugins/NameTag/config.yml`:
```yaml
storage:
type: "MARIADB"
mariadb:
host: "db.internal"
port: 3306
database: "nametag"
table: "nametag_players"
username: "nametag_user"
password: "change-me"
pool-size: 10
use-ssl: false
```
- `host`, `port`, `database`, and `table` must be **identical** on every backend.
- The `nametag_players` table is created automatically on first start — no manual schema work required.
- `pool-size` is per-server.
- Enable `use-ssl: true` if your MariaDB instance requires TLS.
### Minimum MariaDB Permissions
The configured user needs the same grants as MySQL:
```sql
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE ON nametag.* TO 'nametag_user'@'%';
```
`CREATE` can be revoked after the first start.
---
## UUID Spoofing on a Proxy
The experimental `should_spoof_uuid: true` option rewrites a player's UUID to match their nick. On a proxy this can confuse plugins that track players by UUID (economy, per-player data, permissions). If you enable it:
- Enable it on **every** backend server, not just one.
- Test with a non-essential plugin first — some proxy-side plugins (chat, friends lists) may reject transferred players whose UUID does not match the proxy's cached value.
If unsure, leave `should_spoof_uuid: false`.
---
## Troubleshooting
**Nicks don't follow players between servers.**
- Confirm `storage.type` is `MONGODB`, `MYSQL`, or `MARIADB` on **every** backend, not just one.
- Confirm `database` / `collection` / `table` names match exactly.
- Check the server console for "MongoDB storage initialized successfully", "MySQL storage initialized successfully", or "MariaDB storage initialized successfully" — errors there mean the server fell back to `LOCAL`.
**"Chat disabled due to missing profile public key" when joining a new server.**
- Update all backends to v1.0.82 or later. The stale chat session is now cleared when the UUID changes.
**Different nick on different servers.**
- One backend is likely still on `LOCAL` and writing to its own `data.yml`. Switch it to the shared backend and run `/nametag reload`.
---
## Related Pages
- [[Name Tag/Server Owners/Configuration]] — Full config reference
- [[Name Tag/Server Owners/Overview]] — Plugin overview and installation
- [[Name Tag/Server Owners/Commands]] — Command and permission listing