Proxy Mode

This page applies to networks that use BungeeCord, Waterfall, or Velocity.

If you use a proxy, install SkinsRestorer on the proxy and every backend server.

How Proxy Mode works

In Proxy Mode, the proxy controls SkinsRestorer for the whole network.

When Proxy Mode is active on backend servers:

• Commands are forwarded to the proxy
• Skin data is managed centrally by the proxy
• The proxy provides the main configuration
• The proxy handles all API communication with Mojang/MineSkin

Install on a proxy

Follow the installation guide for your proxy.

Configure Proxy Mode

Set Proxy Mode in the config.yml file on each backend server:

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 has three values:

• AUTO (default): SkinsRestorer detects whether the server is behind a proxy
• ENABLED: Proxy Mode is always active
• DISABLED: Proxy Mode is always inactive

Backend API access

The api option lets backend plugins use the SkinsRestorer API. Its default value is true.

This option requires MySQL. The proxy and backend servers must use the same database.

Disable Proxy Mode

Without Proxy Mode, each backend server manages its own skins. The servers do not automatically share skin data.

To disable Proxy Mode, set detection: DISABLED in the backend config.yml file.

Troubleshooting

Make sure that Proxy Mode is active

Find this message in each backend startup log:

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

If "Proxy Mode" is absent, the mode is not active.

Using /sr status

Run /sr status on the proxy:

/sr status

The command shows the status of all required API endpoints.

Using /sr dump

To collect information for support, run:

/sr dump

The command uploads diagnostic information and returns a link. Send the link to support.

Common issues

"Proxy Mode not detected"

Symptom: Backend logs do not show "Proxy Mode".

Causes and solutions:

1. Player information forwarding is not configured

   • For BungeeCord, set bungeecord: true in spigot.yml and online-mode=false in server.properties.
   • For Velocity, follow the Velocity forwarding guide.

2. SkinsRestorer is not installed on the proxy

   • Put SkinsRestorer.jar in the proxy's plugins folder.
   • Restart the proxy.

3. SkinsRestorer is not installed on a backend server

   • Put SkinsRestorer.jar in each backend server's plugins folder.
   • Restart all backend servers.

4. A security plugin blocks plugin messages

   • Permit the SkinsRestorer channel in the security plugin.

Commands not working on backend servers

Symptom: /skin commands do not work from a backend console.

This is expected in Proxy Mode. Run administrator commands from the proxy console. Players must connect through the proxy.

Skins not applying on server switch

Symptom: Players lose their skin when they switch servers.

Solutions:

1. Install SkinsRestorer on all backend servers.
2. Find "Proxy Mode" in each backend log.
3. Make sure that player information forwarding works.

API not working on backend servers

Symptom: A backend plugin gets SkinsRestorer API errors.

Solutions:

1. Enable MySQL storage on the proxy.
2. Configure the same database on all backend servers.
3. Set server.proxyMode.api: true in each backend configuration.

See the Database Setup guide for details.

Configuration synchronization errors

If the configuration files are different:

1. Change config.yml on the proxy.
2. Copy the file to all backend servers.
3. Run /sr reload on the proxy.
4. Restart all backend servers.

Set Proxy Mode manually

If automatic detection fails, set the mode in each backend configuration.

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

SkinsRestorer supports both proxies. For a new network, Velocity provides newer security and performance features.