Access Control List

Access Control List

The ACL decides who may do what on a server: which operators may run which commands, and which privileged functions each resource's scripts may call. It lives in acl.toml in the data folder. The server writes the file itself whenever the console or the remote console changes it; edit it by hand only while the server is stopped, or run acl reload after an edit. A damaged file stops the server's start with its line and column.

Groups, objects, rights

A group has a name (1 to 32 characters of A-Z a-z 0-9 _ . -), the objects it holds, and the rights it allows and denies.

Object	Who
operator.<64 hex>	an operator's key (remote console)
player.<64 hex>	one player, by their player id
player.*	every player
ip.<address, prefix or wildcard>	players from these addresses: ip.203.0.113.7, ip.10.0.0.0/8, ip.192.168.1.*
resource.<name>	one resource's scripts
resource.*	every resource's scripts

A right starts with one of four roots and has up to 7 more parts (each up to 32 characters of A-Z a-z 0-9 _, at most 128 bytes in all):

Root	Used for
command	console commands: command.kick, command.acl, … (command alone: all of them)
function	script functions: function.kickPlayer, function.startResource, …
resource	free for resources' own checks with hasObjectPermissionTo
general	general.ModifyOtherObjects: changing elements another resource made

How a right is decided

A right is checked from its most specific level to its root: command.acl.add, then command.acl, then command. The first level anything speaks to decides:

1. the subject's groups (and, for a resource, its decided permission requests), where a deny beats an allow of the same level;
2. then the built-in defaults (for resources only, below).

If nothing speaks at any level, the right is denied. The server's own console holds every right.

The defaults for resources. Every resource may call script functions (function), except these, which an operator must allow:

function.load, function.loadstring, function.fetchRemote, function.callRemote, function.startResource, function.stopResource, function.restartResource, function.acl, general.ModifyOtherObjects, function.kickPlayer, function.banPlayer, function.mutePlayer, function.executeCommand.

A group's explicit allow, or an allowed request, beats a default. How resources ask for rights: Script Permissions.

Console commands

Command	What it does
acl list	every group with its counts, and whether the remote console is on
acl show <group>	a group's objects, allows and denies
acl check <object> <right>	the decision and what made it
acl create <group> / acl delete <group>	makes or removes a group
acl add <group> <object> / acl remove <group> <object>	puts an object into a group or takes it out
acl allow <group> <right> / acl deny <group> <right>	adds an allow or a deny
acl revoke <group> <right>	removes the right from both lists
acl reload	reads acl.toml again after a hand edit
aclrequest list [resource]	the resources' permission requests and their states
aclrequest allow <resource> <right or all>	grants a request (records who and when)
aclrequest deny <resource> <right or all>	refuses it

The file

After acl create admins, acl add admins operator.<key>, acl allow admins command and acl deny admins command.stop, the server wrote:

[[group]]
name = "admins"
objects = [
    "operator.91d0e59047b116679d90b16b4a8ded3f2946d8859db1d100fad3c8d42e6fec5e",
]
allow = [
    "command",
]
deny = [
    "command.stop",
]

A group needs all four keys (name, objects, allow, deny; empty lists are fine). Permission requests are [[request]] tables with resource, right, state (pending, allowed, denied), asked, by and at (Unix seconds); the server writes them.

Limits

256 groups; 4096 objects and 1024 rights per group; 4096 permission requests; the file at most 16 MiB. operator.* is refused: every operator is a key the ACL names.