Proxy Mode

This page is for servers that are using a proxy (BungeeCord, Waterfall or Velocity) in their network to connect multiple servers together. If you're not using a proxy, you can skip this page.

Using a proxy? --> You MUST use proxy installation!

What is "Proxy Mode"?

The proxy will handle SkinsRestorer's commands, API, permission, database and config in a "centralized" manner.

When proxy mode is active on backend servers:

• Commands are forwarded to the proxy
• Skin data is managed centrally by the proxy
• Configuration changes only need to be made on the proxy
• The proxy handles all API communication with Mojang/MineSkin

How to install on proxy?

Please read: https://skinsrestorer.net/docs/installation#platform-installation

Proxy Mode Configuration

Proxy mode can be configured in the config.yml file on your backend servers:

server:
  proxyMode:
    # Options: ENABLED, DISABLED, or AUTO (default)
    detection: AUTO
    # Enable API access on backend servers (requires database)
    api: true

Proxy Mode Detection

The detection option controls how proxy mode is determined:

• AUTO (default): Automatically detects if the server is behind a proxy
• ENABLED: Forces proxy mode on
• DISABLED: Forces proxy mode off

Backend API Access

The api option (default: true) enables plugins on backend servers to use the SkinsRestorer API. This is useful when using plugins like BedWars, Dynmap, etc. that need to get skin data through the API from the backend server.

Keep in mind that connecting MySQL to the same database as the proxy is required for this to work!

Disabling Proxy Mode

Disabling proxy mode will force the backend to handle everything including applying skins on join. This is not recommended as the proxy has better control over the player connection.

To disable proxy mode, set detection: DISABLED in your backend server's config.yml.

Troubleshooting

Verifying proxy mode is active

Check your backend server logs during startup. You should see:

[SkinsRestorer] +==================+
[SkinsRestorer] |   SkinsRestorer  |
[SkinsRestorer] |------------------|
[SkinsRestorer] |    Proxy Mode    |
[SkinsRestorer] +==================+

If you don't see "Proxy Mode" in the startup message, proxy mode is not active.

Using /sr status

Run /sr status on the proxy to check API connectivity:

/sr status

This will show the status of all required API endpoints and help identify connection issues.

Using /sr dump

If you need help from the SkinsRestorer team, run:

/sr dump

This uploads diagnostic information to a paste service and gives you a link to share with support.

Common issues

"Proxy Mode not detected"

Symptoms: Backend servers don't show "Proxy Mode" in logs.

Causes and fixes:

1. Player information forwarding not configured

   • BungeeCord: Set bungeecord: true in spigot.yml and online-mode=false in server.properties
   • Velocity: Follow the Velocity forwarding guide

2. SkinsRestorer not installed on proxy

   • Ensure SkinsRestorer.jar is in the proxy's plugins folder
   • Restart the proxy after adding the plugin

3. SkinsRestorer not installed on backend

   • Ensure SkinsRestorer.jar is in each backend server's plugins folder
   • Restart the backend servers

4. Plugin messaging channel blocked

   • Some security plugins block plugin messaging
   • Whitelist SkinsRestorer's channel in your security plugin

Commands not working on backend servers

Symptoms: /skin commands don't work on backend servers.

This is expected behavior! In proxy mode, commands are handled by the proxy. Run commands on the proxy console or ensure players are connected through the proxy.

Skins not applying on server switch

Symptoms: Players lose their skin when switching servers.

Fixes:

1. Ensure SkinsRestorer is installed on ALL backend servers
2. Verify all servers show "Proxy Mode" in their logs
3. Check that player information forwarding is working

API not working on backend servers

Symptoms: Plugins using SkinsRestorer API get errors on backend servers.

Fixes:

1. Enable database storage on the proxy
2. Configure the same database on backend servers
3. Ensure server.proxyMode.api: true (default) in backend config

See the Database Setup guide for details.

Config sync issues

If configs are out of sync:

1. Make changes on the proxy first
2. Copy the config.yml to all backend servers
3. Run /sr reload on the proxy
4. Restart all backend servers (they can't use /sr reload)

Force enabling/disabling proxy mode

If auto-detection isn't working correctly, you can force the mode:

Force proxy mode ON (on backend servers):

server:
  proxyMode:
    detection: ENABLED

Force proxy mode OFF (use standalone mode):

server:
  proxyMode:
    detection: DISABLED

BungeeCord vs Velocity

Both proxies work well with SkinsRestorer. Velocity is generally recommended for new installations due to better performance and security.