nodetool invalidaterolescache

Cassandra 4.1+

This command is available in Cassandra 4.1 and later.

Invalidates the roles cache on the node.

---

Synopsis

nodetool [connection_options] invalidaterolescache

See connection options for connection options.

---

Description

nodetool invalidaterolescache clears all cached role information on the node. The roles cache stores role definitions and role hierarchy relationships from the system_auth.roles and system_auth.role_members tables, allowing Cassandra to resolve role memberships without querying the auth tables for every operation.

Role caching is essential for performance in environments with complex role hierarchies, where a single user might inherit permissions from multiple nested roles. After invalidation, subsequent operations trigger fresh role lookups from the system_auth tables.

Authentication Required

The roles cache is only relevant when authentication and authorization are enabled. If running with AllowAllAuthenticator and AllowAllAuthorizer, this cache is not used.

---

Examples

Basic Usage

nodetool invalidaterolescache

After Role Hierarchy Changes

# After modifying role memberships
cqlsh -e "GRANT admin_role TO power_user;"

# Invalidate to ensure changes take effect immediately
nodetool invalidaterolescache

---

Roles Cache Overview

What the Cache Stores

Cached Data	Description
Role name	The role identifier
Role properties	SUPERUSER, LOGIN capabilities
Role membership	Parent roles (inherited roles)
Membership graph	Complete hierarchy for permission resolution

How It Improves Performance

Without Roles Cache:
  Authorization Check → Resolve role membership → Query role_members recursively → Aggregate permissions

With Roles Cache:
  Authorization Check → Lookup cached membership → Aggregate permissions
  (Avoids recursive auth table queries)

Role Hierarchy Example

                    superadmin
                    /        \
              admin_role    dba_role
               /     \          \
         developer  analyst    operator

When checking permissions for developer, Cassandra must resolve that it inherits from admin_role, which inherits from superadmin. The roles cache stores this complete hierarchy.

---

When to Use

After Role Creation or Deletion

# Create new role
cqlsh -e "CREATE ROLE analytics_team WITH LOGIN = false;"

# Invalidate cache
nodetool invalidaterolescache

After Role Hierarchy Changes

When role memberships are modified:

# Grant role membership
cqlsh -e "GRANT analytics_team TO data_scientist;"

# Revoke role membership
cqlsh -e "REVOKE admin_role FROM former_admin;"

# Ensure changes take effect immediately
nodetool invalidaterolescache

After Role Property Changes

When role properties are modified:

# Change superuser status
cqlsh -e "ALTER ROLE operator WITH SUPERUSER = true;"

# Change login capability
cqlsh -e "ALTER ROLE service_account WITH LOGIN = true;"

# Invalidate to reflect changes
nodetool invalidaterolescache

Security Incident Response

When immediate role changes are critical:

emergency_role_revoke.sh

#!/bin/bash
USER="$1"
ROLE_TO_REVOKE="$2"

# Revoke the role
cqlsh -e "REVOKE $ROLE_TO_REVOKE FROM $USER;"

# Invalidate cache on all nodes immediately
for node in $(nodetool status | grep "^UN" | awk '{print $2}'); do
    ssh "$node" "nodetool invalidaterolescache"
    ssh "$node" "nodetool invalidatepermissionscache"
done

echo "Role $ROLE_TO_REVOKE revoked from $USER on all nodes."

Troubleshooting Permission Issues

When users have unexpected permissions:

# Clear all auth caches to ensure fresh resolution
nodetool invalidaterolescache
nodetool invalidatepermissionscache
nodetool invalidatecredentialscache

# Verify permissions
cqlsh -e "LIST ALL PERMISSIONS OF problem_user;"

---

Impact Assessment

Immediate Effects

Aspect	Impact
Cached role data	All cleared
Next operations	Require auth table lookups
Role resolution	Temporarily slower
Permission checks	May have slight latency increase

Recovery Timeline

Phase	Duration	Cache State
Immediately after	0	Empty
Initial operations	Seconds	Roles being cached
Normal operations	Minutes	Cache populated for active roles

Low Impact Operation

Role cache invalidation typically has minimal performance impact since role lookups are relatively fast and the cache repopulates quickly with normal operations.

---

Configuration

Cache Settings

The cassandra.yaml parameter names vary by version:

Cassandra Version	Validity Parameter	Update Interval Parameter
Pre-4.1	roles_validity_in_ms	roles_update_interval_in_ms
4.1+	roles_validity	roles_update_interval

# cassandra.yaml (4.1+)
roles_validity: 2s
roles_update_interval: 1s
roles_cache_max_entries: 1000

# cassandra.yaml (Pre-4.1)
# roles_validity_in_ms: 2000
# roles_update_interval_in_ms: 1000
# roles_cache_max_entries: 1000

Tuning Considerations

Setting	Low Value	High Value
roles_validity	Faster permission propagation, more auth queries	Better performance, delayed propagation
roles_cache_max_entries	Lower memory, more cache misses	Higher memory, better hit rate

---

Cluster-Wide Operations

Invalidate on All Nodes

For role changes to take effect cluster-wide immediately:

invalidate_roles_cluster.sh

#!/bin/bash
echo "Invalidating roles cache cluster-wide..."

# Get list of node IPs from local nodetool status
nodes=$(nodetool status | grep "^UN" | awk '{print $2}')

for node in $nodes; do
    echo -n "$node: "
    ssh "$node" 'nodetool invalidaterolescache 2>/dev/null && echo "invalidated" || echo "FAILED"'
done

echo "Roles cache cleared on all nodes."

Complete Auth Cache Refresh

For comprehensive auth changes:

refresh_all_auth_caches.sh

#!/bin/bash
echo "Refreshing all authentication caches cluster-wide..."

# Get list of node IPs from local nodetool status
nodes=$(nodetool status | grep "^UN" | awk '{print $2}')

for node in $nodes; do
    echo "Processing $node..."
    ssh "$node" "nodetool invalidaterolescache 2>/dev/null"
    ssh "$node" "nodetool invalidatepermissionscache 2>/dev/null"
    ssh "$node" "nodetool invalidatecredentialscache 2>/dev/null"
    echo "  Done"
done

echo "All auth caches cleared."

---

Workflow: Role Modification with Validation

role_modification_workflow.sh

#!/bin/bash
ROLE="$1"
ACTION="$2"  # create, delete, grant, revoke
TARGET="$3"  # target role for grant/revoke

echo "=== Role Modification Workflow ==="

# 1. Show current state
echo "1. Current roles:"
cqlsh -e "SELECT role, is_superuser, can_login, member_of FROM system_auth.roles WHERE role = '$ROLE';"

# 2. Perform action
echo ""
echo "2. Performing: $ACTION"
case $ACTION in
    create)
        cqlsh -e "CREATE ROLE $ROLE;"
        ;;
    delete)
        cqlsh -e "DROP ROLE $ROLE;"
        ;;
    grant)
        cqlsh -e "GRANT $TARGET TO $ROLE;"
        ;;
    revoke)
        cqlsh -e "REVOKE $TARGET FROM $ROLE;"
        ;;
esac

# 3. Invalidate cache
echo ""
echo "3. Invalidating roles cache..."
nodetool invalidaterolescache

# 4. Verify change
echo ""
echo "4. Role state after change:"
cqlsh -e "SELECT role, is_superuser, can_login, member_of FROM system_auth.roles WHERE role = '$ROLE';"

echo ""
echo "=== Complete ==="

---

Troubleshooting

Role Changes Not Taking Effect

# Invalidate on all nodes
for node in $(nodetool status | grep "^UN" | awk '{print $2}'); do
    ssh "$node" "nodetool invalidaterolescache"
done

# Also clear permissions cache as they depend on roles
for node in $(nodetool status | grep "^UN" | awk '{print $2}'); do
    ssh "$node" "nodetool invalidatepermissionscache"
done

Inherited Permissions Not Working

# Check role hierarchy is correct
cqlsh -e "SELECT role, member_of FROM system_auth.roles;"

# Verify the grant was recorded
cqlsh -e "SELECT * FROM system_auth.role_members WHERE role = 'parent_role';"

# Clear cache and retry
nodetool invalidaterolescache

Superuser Status Not Recognized

# Verify superuser flag in auth tables
cqlsh -e "SELECT role, is_superuser FROM system_auth.roles WHERE role = 'the_role';"

# Clear all auth caches
nodetool invalidaterolescache
nodetool invalidatepermissionscache
nodetool invalidatecredentialscache

Cannot List Roles After Invalidation

# Check system_auth keyspace is healthy
nodetool status system_auth

# Check for auth-related errors
grep -i "auth\|role" /var/log/cassandra/system.log | tail -20

# Ensure superuser role exists
cqlsh -u cassandra -p cassandra -e "SELECT * FROM system_auth.roles;"

---

Best Practices

Roles Cache Guidelines

1. Invalidate after hierarchy changes - Always invalidate when modifying role membership
2. Cluster-wide for security - Invalidate all nodes when revoking role memberships
3. Combine with permissions cache - Role changes often require both caches cleared
4. Test role changes - Verify expected permissions after modifications
5. Document role hierarchy - Maintain documentation of role relationships

Security Considerations

• Role hierarchy changes can have cascading effects on permissions
• Always invalidate cluster-wide when revoking roles
• Consider the full inheritance chain when troubleshooting
• Audit role changes for compliance requirements

Relationship to Other Caches

The roles cache works together with other auth caches:

• Credentials cache: Validates login credentials
• Roles cache: Resolves role memberships and hierarchy
• Permissions cache: Determines allowed operations

For complete auth refresh, invalidate all three caches.

---

Related Commands

Command	Relationship
invalidatecredentialscache	Clear credentials cache
invalidatepermissionscache	Clear permissions cache
getauthcacheconfig	View auth cache settings
setauthcacheconfig	Modify auth cache settings