Nexardo

Terraria Field guide

TShock permissions and group management in Terraria: security and roles

Role-based access control and group management in Terraria TShock: auth token bootstrapping, superadmin roles, permission inheritance, and SQLite backups.

EugenePublishedUpdatedReading time4 min
TShock permissions and group management in Terraria: security and roles

TShock is the premier server modification for Terraria, providing a robust role-based access control (RBAC) engine, anti-griefing tools, and granular administrative commands. Without properly structured permission groups, players either lack essential interaction commands or inherit dangerous privileges that compromise world stability and the in-game economy.

This operational guide details the TShock permission architecture, superadmin account bootstrapping, configuring group inheritance, anti-griefing constraints, and backing up the underlying authorization database.

Authorization architecture and the tshock.sqlite database#

Unlike vanilla Terraria servers where authorization relies solely on a shared server password, TShock stores player accounts, hashed credentials, groups, and explicit permissions inside a relational SQLite database (tshock/tshock.sqlite).

The core RBAC entities consist of:

  • Users: Individual player credentials bound to unique usernames and passwords.
  • Groups: Roles containing a defined set of permissions (e.g. guest, default, vip, admin, superadmin).
  • Permissions: String identifiers controlling actions, such as tshock.world.modify, tshock.tp.self, or tshock.buff.heal.

Group hierarchies rely on parent-child inheritance: child groups automatically inherit all permissions granted to their parent while adding specialized privileges.

Initial authorization via auth token and superadmin creation#

During its first startup, TShock outputs a one-time authentication token. Locate this token in the server console or extract it from the log file:

bash
grep -i "auth code" /opt/terraria/tshock/logs/tshock.log | tail -n 1

The output will display a token sequence: Generated auth token: 7492812

Connect your Terraria client to the server and execute the command in the chat box: /auth 7492812

Your character is now granted membership in the superadmin group.

If managing the server exclusively via SSH terminal sessions without entering the game client, create a superadmin user directly through the server CLI:

bash
screen -S terraria -X stuff "user add admin MasterSecretPass superadmin\n"

Creating groups and configuring permission inheritance#

A standard production permission hierarchy follows:

  1. guest: Unregistered players (building and breaking restricted if protection is active).
  2. default: Registered players with core survival and chat permissions.
  3. vip: Trusted players with quality-of-life perks (self-teleportation, chat formatting).
  4. admin: Moderators possessing kick, ban, and rollback rights.
  5. superadmin: Unrestricted operational control.

To create a vip group inheriting from the default baseline:

bash
screen -S terraria -X stuff "group add vip default\n"

Grant safe, functional permissions to the new group:

bash
screen -S terraria -X stuff "group addperm vip tshock.tp.self\n"
screen -S terraria -X stuff "group addperm vip tshock.world.info\n"
screen -S terraria -X stuff "group addperm vip tshock.npc.spawninfo\n"

Inspect the active permission list assigned to vip:

bash
screen -S terraria -X stuff "group listperm vip\n"

With an enterprise server management platform, permission modeling, user registration, and group inheritance are handled through a clean visual interface with pre-built security presets.

Anti-griefing protection and restricting destructive commands#

Never grant wildcard permissions like tshock.world.* or tshock.admin.* to public player tiers. Critical permissions that must remain restricted to administrators include:

  • tshock.world.edit: Raw world block modifications via external tools.
  • tshock.ignore.ssc: Bypassing Server-Side Characters (prevents importing cheated items from single-player worlds).
  • tshock.item.spawn: Generating arbitrary items via /item.

Ensure Server-Side Characters and explosion limits are enabled in tshock/config.json:

json
{
  "ServerSideCharacters": true,
  "StartingInventory": [],
  "DisableInvisPVPHacks": true,
  "AllowExplosions": false,
  "PreventHardmode": false
}

Reload the runtime configuration without bouncing the server process:

bash
screen -S terraria -X stuff "reload\n"

Backing up permissions and direct SQLite management#

Because tshock.sqlite updates on every player registration and login, take regular hot backups before making structural group changes:

bash
BACKUP_DIR="/opt/terraria/backups"
mkdir -p "$BACKUP_DIR"
sqlite3 /opt/terraria/tshock/tshock.sqlite ".backup '$BACKUP_DIR/tshock_rbac_$(date +%Y%m%d_%H%M%S).sqlite'"

Perform an immediate terminal audit of elevated accounts via SQLite queries:

bash
sqlite3 /opt/terraria/tshock/tshock.sqlite "SELECT ID, Username, Usergroup FROM Users WHERE Usergroup IN ('admin', 'superadmin');"

If an administrative password is lost or an account is accidentally demoted, reassign permissions directly in the database:

bash
sqlite3 /opt/terraria/tshock/tshock.sqlite "UPDATE Users SET Usergroup='superadmin' WHERE Username='admin';"

Sources#