IAM.ROLE.CREATE

IAM.ROLE.CREATE defines a role. IAM.USER.ASSIGN gives it to users and groups, and a login that has it can run the commands the role allows, on the keys it reaches, and nothing else. See Roles and single sign-on for how roles are used.

The role is the same on every node of a cluster: a change made on one node reaches the others, and it is saved with the data and replicated. A role cannot be changed once it is made: delete it with IAM.ROLE.DELETE and create it again.

Arguments

Argument	Meaning
name	1 to 64 characters, with no spaces or control characters
permissions	What the role allows, a list separated by commas (see below)

permissions is a list of entries, and the role needs at least one that allows something:

Entry	Meaning
get, config|get	Allow a command, or one subcommand of it
@read, @write, @connection, @all	Allow a category of commands (* is @all). ACL CAT lists them
-flushall, -@dangerous, -@admin	Never allow a command or a category, whatever else the role allows

Names are not case sensitive. A command or category that does not exist is an error, so a typo cannot leave a command allowed.

Options

Option	Meaning	Default
KEY_PREFIXES prefixes	The keys the role reaches, separated by commas. An entry with no *, ? or [ is a prefix (app: is app:*), one with them is a pattern. Channels follow the keys	All keys
RATE_LIMIT n	Commands per second, for all the connections of a login together	0 (unlimited)
IP_ALLOWLIST networks	Addresses or networks (CIDR) a login must come from to have the role, separated by commas, such as 10.0.0.0/8,fd00::/8	From anywhere

Option names are not case sensitive.

@write also holds HotKV’s administrative commands that change the server, such as IAM.USER.ASSIGN and TENANT.CREATE, so a role of @write alone would let its users give themselves any role. A role like that is refused unless it removes those commands (-@admin or -@dangerous), or names @admin, @dangerous or @all to say that is meant.

Return value

Simple string OK in RESP2 and RESP3, or one of these errors (the role is not created):

Case	Error
The name is taken	ERR role already exists
A bad name	ERR a role name is 1 to 64 characters, with no spaces or control characters
Nothing is allowed	ERR a role needs at least one command or @category it allows
An entry with a space or a control character	ERR a permission has a space or a control character: 'get set'
A command or category that does not exist	ERR unknown command or category 'nosuchcommand'
A rate limit that is not a number	ERR invalid RATE_LIMIT value
MEMORY_QUOTA	ERR MEMORY_QUOTA is not supported. Use maxmemory for the server, or tenants (TENANT.*) for separate budgets
An option the command does not know	ERR unknown option 'name'
An option without a value	ERR syntax error
A key prefix that is empty or has a space	ERR a key prefix is empty, or has a space or a control character
A network that is not one	ERR 'nonsense' is not an address or a network (10.0.0.0/8)
A prefix length longer than the address	ERR '10.0.0.0/99' has a prefix length that is longer than the address
A role that would allow administration	ERR this role would let its users run administrative commands that change the server (iam.role.create, iam.role.delete, iam.user.assign, iam.user.unassign, ...): remove them with -@admin or -@dangerous, or name @admin or @all if that is meant
Fewer than two arguments	ERR wrong number of arguments for 'iam.role.create' command
No license that includes enterprise-iam	NOLICENSE enterprise-iam requires a HotKV license. Contact sales@hotkv.com

Examples

127.0.0.1:6379> IAM.ROLE.CREATE app "@read,@write,@connection,-@dangerous" KEY_PREFIXES app:
OK
127.0.0.1:6379> IAM.ROLE.CREATE reporting "get,mget,scan" KEY_PREFIXES "report:,shared:*" RATE_LIMIT 500
OK
127.0.0.1:6379> IAM.ROLE.CREATE office "@all" IP_ALLOWLIST "10.0.0.0/8,fd00::/8"
OK
127.0.0.1:6379> IAM.ROLE.CREATE app get
(error) ERR role already exists
127.0.0.1:6379> IAM.ROLE.CREATE writer "@write"
(error) ERR this role would let its users run administrative commands that change the server (iam.role.create, iam.role.delete, iam.user.assign, iam.user.unassign, ...): remove them with -@admin or -@dangerous, or name @admin or @all if that is meant

Compatibility

HotKV-only command.

See also

IAM.USER.ASSIGN, IAM.ROLE.INFO, IAM.ROLE.DELETE, IAM.AUTH