Redis agent

The Redis agent is a service beside the deployment. It keeps Redis's own ACL in step with the signed policies of a redis data service on every node, the replicas and every node of a cluster too, as Redis keeps an ACL on each. Redis then checks every command itself, and the agent stands in no client's way. The distribution ships it as the runnable JAR agents/redis/grantforge-agent-redis-<version>.jar; it needs Java 17 or later.

The repository's Testcontainers integration tests run the agent, and the JAR as shipped, against a primary with a replica of Redis 7.2, 7.4, 8.2 and 8.10 and Valkey 8.1 and 9.1, and a Redis 8.10 cluster. This does not certify every other release; the agent refuses Redis older than 7.2, whose ACL log numbers no entries. For the service plugin see Redis.

How it works

• The selectors are GrantForge's, the root permissions the operator's. Redis allows a command when a user's root permissions or one of its selectors allow it. The agent keeps every selector of the users it looks after and never touches their root permissions or passwords: one selector holds the keys the user may read, write or both, one the channels it may subscribe to, one those it may publish to, and on the nodes it may monitor one more.
• A change happens in one command. ACL SETUSER user clearselectors (…) replaces all of a user's selectors at once on a node, so a user never holds both the old and the new, or neither; selectors changed by hand are set right the same way at the next sync.
• Patterns, granted only where they hold. A policy's key or channel pattern is granted as Redis's own pattern where the policies decide the user alike across it; the agent cuts the pattern along every policy that overlaps it and decides each part, so another user's policy does not hold it back. A pattern policies decide differently within is withheld and logged, once.
• Nothing dangerous, no listing of others' keys. The selectors never give what Redis counts as dangerous, and give SCAN and RANDOMKEY only to a user that may read every key.
• Every node, saved where it can be. The agent finds the replicas and the cluster's nodes from the nodes given and brings each in step. A node that keeps its ACL in a file saves it with ACL SAVE; one that does not loses the selectors when it restarts and gets them again at the next sync.
• Redis is asked what it allows. Root permissions decide beside the agent's selectors. Rather than read their rules, the agent asks Redis with ACL DRYRUN whether a user may run a command on a key, channel or node a policy denies, and warns, once each, naming the user, the access and the policy. It also warns of users no selector binds, with every command on every key, and of users anyone may sign in as without a password.
• Refusals come from each node's ACL log. See Reporting refusals below.
• The policies of the present moment. Each sync plans from the policies as they apply at that moment, so validity periods start and end on time, and from the users and nodes Redis has.

Deployment

1. Add a redis data service and its policies. Open Data authorization → Agents, choose the service and issue an agent token. It is shown once, so save it in a file only the agent's account can read.

2. Create the agent's ACL user on every node. It reads users, sets their selectors, saves the ACL file, reads the ACL log, asks dry runs and finds the cluster's nodes. +acl|setuser can give itself anything, so guard this user as you guard an administrator.

   ACL SETUSER grantforge on >… -@all +@connection +acl|whoami +acl|users +acl|getuser +acl|setuser +acl|log +acl|dryrun +acl|save +config|get +info +cluster|nodes +command|info

3. Keep the root permissions of the users the agent looks after to what every user needs, such as signing in; the agent gives the rest. Root permissions that give more are found and warned of.

   ACL SETUSER alice on >… resetkeys resetchannels -@all +@connection

4. Write a settings file, changing the example addresses, paths and names:

   grantforge.server.url=https://grantforge.example.com
   grantforge.token.file=/etc/grantforge/redis-agent.token
   grantforge.instance=redis-agent-1
   grantforge.cache.dir=/var/lib/grantforge/redis-agent
   grantforge.redis.nodes=redis1.internal:6379,redis2.internal:6379
   grantforge.redis.user=grantforge
   grantforge.redis.password.file=/etc/grantforge/redis-agent.password

   These paths are on the agent's machine, and the cache directory must be writable. The password file is read as UTF-8, with surrounding white space removed.

5. Start the agent, for example as a systemd service:

   java -jar agents/redis/grantforge-agent-redis-<version>.jar /etc/grantforge/redis-agent.properties

   Replace <version> with the distribution's version. Settings given as java -Dgrantforge.…=… -jar … take precedence over the file. On SIGTERM the agent stops cleanly and sends or spools pending events; Redis keeps what it was given.

Reporting refusals

Redis keeps no record of what it allowed, so the agent reports what it refused, from the ACL log of each node: who was refused what, from where and when, and whether the policies decide as Redis did. Redis folds a refusal repeated within a minute into the entry before it; the agent reports an entry again each time it is updated.

Users, groups and roles

Policies name Redis's ACL users by name. Redis has no roles or groups of its own, so groups are those GrantForge puts users in.

Decisions and limits

• Without a snapshot the agent changes nothing. A token bound to a service not in use, or to a service whose type is not redis, grants nothing: the agent clears the selectors of the users it looks after.
• While the agent is not running Redis keeps what it last received, and policy changes wait for it. A change reaches Redis within the refresh and sync intervals.
• The agent keeps every selector of the users it looks after: a selector the operator adds by hand is removed at the next sync. Give extra permissions in root permissions, or leave the user to the operator.
• Redis's ACL names keys and channels, not databases, so a pattern covers its keys in every database of a node.
• A refused command the user may not run at all is logged by Redis without its keys, and is not reported.
• Redis filters nothing within a value and masks nothing.

Related guides

• Redis
• Data services, policies and agents