ACL Builder for Redis and Valkey Users and Permissions

Paste a user’s ACL rules and pick a server version. The builder applies them the way that version does: the error ACL SETUSER would reply with, word for word, or the line ACL LIST would print, and what the user can do in plain words. Check commands against the user and get the reply ACL DRYRUN gives, or paste what MONITOR printed while an app worked and get a draft of a user that may do what the app did and nothing more. It all runs in your browser.

Nothing you paste leaves this page. The tool doesn’t send anything anywhere, and the page’s security policy stops it from fetching or loading anything from another site, so your rules and passwords stay on your machine.

On a wide screen you can open it full screen.

How to Use It

  1. Paste the rules into the first box: the arguments of ACL SETUSER, a line from ACL LIST, the user lines of redis.conf, or a whole ACL file. You can also open a file, or drop one anywhere on the page.
  2. Pick the server you run. The verdict, the ACL LIST line and the explanation change as you type, and a table shows what each of the 15 versions does with the same rules.
  3. Check commands in the second box, one per line, the way you’d type them in redis-cli. Each gets the reply ACL DRYRUN would give, the error the command itself would get, and the reason: the command, a key, a channel or a database.
  4. Draft a user. Run redis-cli MONITOR > monitor.txt while the app works, stop it after a while, and paste or open the file. The builder drafts a user that may run those commands and no others, with key and channel patterns made from the names it saw, and checks every line of the capture against it.

MONITOR shows every command the server runs, so it slows a busy server down. Keep the capture short, and take it where the traffic looks like the real thing, such as a staging server.

How ACL Rules Work

Since Redis 6 a server can have many users, each with its own passwords and rights. A client logs in with AUTH name password; one that doesn’t is the user default, which may do everything until you change it. A user’s rights are a list of rules:

ACL SETUSER app on >s3cret ~app:* %R~config:* &events:* -@all +@read +set

on lets the user log in and >s3cret adds a password, of which the server keeps only the SHA-256. ~app:* lets the user read and write keys that match app:*, and %R~config:* lets it read config:* keys and nothing more. &events:* is for Pub/Sub channels. Then the commands: -@all starts from none, +@read adds every command in the read category, and +set adds one more. Rules apply in order, so +@all -flushall and -flushall +@all don’t mean the same thing.

A command runs only if the user may run it and may use every key and channel it names. The server finds the keys from the command’s own description, so it knows that in SORT list BY weight_* STORE out the key out gets written and list gets read. Rules in parentheses make a selector, a second set of rights, and Valkey 9.1 adds databases: db=0,2 keeps a user to those two.

The rules changed between versions more than they seem to. Redis 6.2 has no selectors and no %R~, and a new user there may use every channel; from 7.0 a new user starts with none. Redis 7.0 works out the rules ACL LIST prints from what the user can do, so they can come back in another form. Some first arguments, such as +select|a b with a space, make 7.2 and later crash when they list the user. The builder does what each version does, these included, and says so.

How It Was Tested

All 15 versions were built from source: Redis 6.2.24 to 8.10.2 and Valkey 7.2.14 to 9.1.2. A script asked each one for its commands, categories and key positions, then ran the same kinds of cases on all of them and recorded the answers:

  • 71,070 ACL SETUSER calls with rules of every kind, about half of them refused, each followed by the line ACL LIST printed. 1,725 of them made the server crash while it listed the user.
  • 150,040 ACL DRYRUN checks of users against commands, with keys and channels picked to match some patterns and miss others.
  • 60,480 commands queued inside MULTI by a client logged in as the user, which is how Redis 6.2, with no ACL DRYRUN, was checked.
  • 90,000 COMMAND GETKEYSANDFLAGS calls, with the options that move keys around, such as STORE, KEYS and STREAMS.
  • 12,000 ACL files read with ACL LOAD, and 7,500 config files with user, acl-pubsub-default and aclfile lines, each a server start.

For every case, the builder gives the server’s answer: the same error text byte for byte, the same ACL LIST line, the same DRYRUN reply, the same keys with the same flags.

The Code

The builder’s logic is one JavaScript file with no dependencies, open source under the Apache License 2.0. The Config Checker uses it to check the user lines of a config file. It also runs as a command line in Node.js:

node acl/cli.js explain on ">pass word" "~app:*" +@read --server valkey-9.1
node acl/cli.js check "on nopass ~app:* +@read" -- GET app:1
node acl/cli.js check --file users.acl --user app -- SET app:1 x
node acl/cli.js build monitor.txt --name web

The full manual, the tests and the recorded answers they replay are in the acl folder on GitHub. The other tools work the same way.