ACL SETUSER · Valkey

ACL SETUSER

Creates and modifies an ACL user and its rules.

Usage

ACL SETUSER username rule [rule…]

Description

Create an ACL user with the specified rules or modify the rules of an existing user.

Manipulate Valkey ACL users interactively. If the username does not exist, the command creates the username without any privilege. It then reads from left to right all the rules provided as successive arguments, setting the user ACL rules as specified. If the user already exists, the provided ACL rules are simply applied in addition to the rules already set. For example:

ACL SETUSER virginia on allkeys +set

The above command creates a user called virginia who is active(the on rule), can access any key (allkeys rule), and can call the set command (+set rule). Then, you can use another ACL SETUSER call to modify the user rules:

ACL SETUSER virginia +get

The above rule applies the new rule to the user virginia, so other than SET, the user virginia can now also use the GET command.

ACL rules can also be grouped into multiple distinct sets of rules, called selectors. Selectors are added by wrapping the rules in parentheses and providing them just like any other rule. In order to execute a command, either the root permissions (rules defined outside of parenthesis) or any of the selectors (rules defined inside parenthesis) must match the given command. For example:

ACL SETUSER virginia on +GET allkeys (+SET ~app1*)

This sets a user with two sets of permissions, one defined on the user and one defined with a selector. The root user permissions only allow executing the get command, but can be executed on any keys. The selector then grants a secondary set of permissions: access to the SET command to be executed on any key that starts with app1. Using multiple selectors allows you to grant permissions that are different depending on what keys are being accessed.

When we want to be sure to define a user from scratch, without caring if it had previously defined rules associated, we can use the special rule reset as first rule, in order to flush all the other existing rules:

ACL SETUSER antirez reset [... other rules ...]

After resetting a user, its ACL rules revert to the default: inactive, passwordless, can’t execute any command nor access any key or channel:

127.0.0.1:6379> ACL SETUSER antirez reset
OK
127.0.0.1:6379> ACL LIST
1) "user antirez off -@all"

ACL rules are either words like “on”, “off”, “reset”, “allkeys”, or are special rules that start with a special character, and are followed by another string (without any space in between), like “+SET”.

The following documentation is a reference manual about the capabilities of this command, however our ACL tutorial may be a more gentle introduction to how the ACL system works in general.

ACL rules

Valkey ACL rules are split into two categories: rules that define command permissions or command rules, and rules that define the user state or user management rules. This is a list of all the supported Valkey ACL rules:

Command rules

User management rules

Reply

Simple string reply: OK.

If the rules contain errors, the error is returned.

Complexity

O(N). Where N is the number of rules provided.

ACL Categories

@admin @dangerous @slow

Examples

127.0.0.1:6379> ACL SETUSER alan allkeys +@string +@set -SADD >alanpassword
OK
127.0.0.1:6379> ACL SETUSER antirez heeyyyy
(error) ERR Error in ACL SETUSER modifier 'heeyyyy': Syntax error

History

See also

ACL, ACL CAT, ACL DELUSER, ACL DRYRUN, ACL GENPASS, ACL GETUSER, ACL HELP, ACL LIST, ACL LOAD, ACL LOG, ACL SAVE, ACL USERS, ACL WHOAMI, BGREWRITEAOF, BGSAVE, COMMAND, COMMAND COUNT, COMMAND DOCS, COMMAND GETKEYS, COMMAND GETKEYSANDFLAGS, COMMAND HELP, COMMAND INFO, COMMAND LIST, CONFIG, CONFIG GET, CONFIG HELP, CONFIG RESETSTAT, CONFIG REWRITE, CONFIG SET, DBSIZE, DEBUG, FAILOVER, FLUSHALL, FLUSHDB, INFO, LASTSAVE, LATENCY, LATENCY DOCTOR, LATENCY GRAPH, LATENCY HELP, LATENCY HISTOGRAM, LATENCY HISTORY, LATENCY LATEST, LATENCY RESET, LOLWUT, MEMORY, MEMORY DOCTOR, MEMORY HELP, MEMORY MALLOC-STATS, MEMORY PURGE, MEMORY STATS, MEMORY USAGE, MODULE, MODULE HELP, MODULE LIST, MODULE LOAD, MODULE LOADEX, MODULE UNLOAD, MONITOR, PSYNC, REPLCONF, REPLICAOF, RESTORE-ASKING, ROLE, SAVE, SHUTDOWN, SLOWLOG, SLOWLOG GET, SLOWLOG HELP, SLOWLOG LEN, SLOWLOG RESET, SWAPDB, SYNC, TIME.