SquadJS Admin Sync Plugin

A powerful SquadJS plugin that automatically synchronizes your Squad server's admin configuration with remote whitelists. Features intelligent beautification, backup management, flexible scheduling, and enterprise-grade reliability with async operations and concurrent URL fetching.

Features

• 🔄 Automated Sync: Fetch admin data from remote URLs on configurable schedules
• 💬 Chat Commands: Manual sync triggers via in-game admin commands
• 📊 Smart Beautification: Organized output with statistics and categorized groups
• 🔒 Enterprise Reliability: Async operations, concurrent fetching, and collision prevention
• 💾 Backup Protection: Automatic timestamped backups before each sync
• 🌐 Multi-Source: Support for multiple whitelist URLs with graceful fallbacks

Installation

1. Copy admin-sync.js to your SquadJS plugins directory:

   cp admin-sync.js /path/to/squadjs/squad-server/plugins/

2. Add the plugin configuration to your config.json:

   {
     "plugin": "AdminSync",
     "enabled": true,
     "whitelistUrl": "https://your-server.com/admins.txt",
     "adminsFilePath": "/path/to/SquadGame/ServerConfig/Admins.cfg",
     "syncInterval": 300,
     "updateOnStartup": true,
     "chatCommands": ["!syncadmins", "!updateadmins"],
     "backupBeforeSync": true,
     "beautifyOutput": true,
     "maxBackupFiles": 5
   }

3. Restart your SquadJS server

Configuration Options

Option	Type	Required	Default	Description
whitelistUrl	string/array	Yes	-	URL(s) to fetch admin data from
adminsFilePath	string	Yes	-	Path to the Admins.cfg file
syncInterval	number	No	300	Sync interval in seconds (0 = disabled)
updateOnStartup	boolean	No	true	Run sync when plugin starts
chatCommands	array	No	["!syncadmins", "!updateadmins"]	Chat commands for manual sync
backupBeforeSync	boolean	No	true	Create backup before syncing
beautifyOutput	boolean	No	false	Enable organized, beautified output
maxBackupFiles	number	No	5	Maximum backup files to retain (0 = no limit)

Usage Examples

Basic Configuration

{
  "plugin": "AdminSync",
  "enabled": true,
  "whitelistUrl": "https://example.com/admins.txt",
  "adminsFilePath": "/home/container/SquadGame/ServerConfig/Admins.cfg"
}

Multiple URLs with Beautification

{
  "plugin": "AdminSync",
  "enabled": true,
  "whitelistUrl": [
    "https://clan1.example.com/admins.txt",
    "https://clan2.example.com/admins.txt"
  ],
  "adminsFilePath": "/home/container/SquadGame/ServerConfig/Admins.cfg",
  "beautifyOutput": true,
  "syncInterval": 600,
  "maxBackupFiles": 10
}

Manual Sync Only

{
  "plugin": "AdminSync",
  "enabled": true,
  "whitelistUrl": "https://example.com/admins.txt",
  "adminsFilePath": "/home/container/SquadGame/ServerConfig/Admins.cfg",
  "syncInterval": 0,
  "updateOnStartup": false,
  "chatCommands": ["!sync"]
}

Output Examples

Standard Output

Group=Admin:ChangeMap,Pause,Cheat,Private,Balance,Chat,Kick,Ban,Config,Cameraman,Immune,Mandown,Teamchange,Reserve,Demos,ClientDemoRec,Debug

Admin=76561198123456789:Admin
Admin=a1b2c3d4e5f6789abcdef123456789ab:Admin

Beautified Output

//=============================================================================
// Squad Server Admin Configuration File
// Auto-beautified and organized by AdminSync plugin
//=============================================================================
//
// Total Statistics:
//   - Groups: 3
//   - Total Admins: 12
//   - EOS IDs: 8
//   - Steam IDs: 4
//   - Last Sync: 2024-01-15T14:30:00.000Z
//
//=============================================================================
// GROUP DEFINITIONS
//=============================================================================

// Administrative Groups
Group=Admin:ChangeMap,Pause,Cheat,Private,Balance,Chat,Kick,Ban,Config,Cameraman,Immune,Mandown,Teamchange,Reserve,Demos,ClientDemoRec,Debug // 8 members
Group=AdminJunior:Chat,Kick,Ban,Balance,Teamchange // 3 members

// Clan Groups
Group=ClanMember:Reserve,Private // 1 members

//=============================================================================
// ADMIN ASSIGNMENTS
//=============================================================================

//-----------------------------------------------------------------------------
// Admin (8 members: 5 EOS, 3 Steam)
//-----------------------------------------------------------------------------
Admin=a1b2c3d4e5f6789abcdef123456789ab:Admin // John Doe
Admin=b2c3d4e5f6789abcdef123456789abc1:Admin // Jane Smith
Admin=76561198123456789:Admin // Legacy Steam Admin
Admin=76561198234567890:Admin // Another Steam Admin

//-----------------------------------------------------------------------------
// AdminJunior (3 members: 3 EOS, 0 Steam)
//-----------------------------------------------------------------------------
Admin=c3d4e5f6789abcdef123456789abc12:AdminJunior // Junior Admin 1
Admin=d4e5f6789abcdef123456789abc123:AdminJunior // Junior Admin 2

//=============================================================================
// End of Configuration
//=============================================================================

Chat Commands

Admins can trigger manual syncs using chat commands:

• Type !syncadmins or !updateadmins in admin chat
• Plugin will acknowledge the command and provide status updates
• Only works from admin chat for security

Backup System

• Automatic backups created before each sync
• Backup filename format: Admins.cfg.backup.2024-01-15T14-30-00-000Z
• Configurable retention: keeps only the most recent backups (default: 5)
• Oldest backups are automatically deleted when maxBackupFiles limit is exceeded
• Set maxBackupFiles: 0 to disable automatic cleanup
• Disable backups entirely with "backupBeforeSync": false

Troubleshooting

Common Issues

Plugin not syncing:

• Check URL accessibility from your server
• Verify file path permissions
• Check SquadJS logs for error messages

Beautification not working:

• Ensure beautifyOutput: true in config
• Check that input data follows Squad admin format
• Verify no syntax errors in remote admin data

Chat commands not responding:

• Commands only work in admin chat
• Check command spelling and case sensitivity
• Verify admin has proper permissions

Sync operations failing:

• Check network connectivity to whitelist URLs
• Verify URLs are accessible (test with curl/wget)
• Look for timeout errors in logs (30-second limit)
• Ensure sufficient disk space for backups

Performance issues:

• Enable concurrent fetching for multiple URLs (default)
• Check for very large whitelist files (>1MB)
• Monitor server resources during sync operations

Debug Mode

Enable verbose logging in SquadJS config:

{
  "logger": {
    "verboseness": 2
  }
}

Requirements

• SquadJS v3.0+
• Node.js 16+
• Internet connectivity for URL fetching
• Write permissions to admin file location

License

This plugin is released under the MIT License. See LICENSE file for details.

Contributing

Issues and pull requests are welcome! Please ensure your code follows the existing style and includes appropriate tests.

Support

For support, please open an issue in the GitHub repository or contact via the SquadJS Discord community.