Events administration

This page contains general Redis information and installation and configuration instructions to enable events.

Overview

Perforce IPLM Events Framework requires a Redis server, PiServer to be configured to use the Redis server, and for events to be enabled by the pi-admin command.

Perforce supplies two packages for Redis support:

  • mdx-backend-redis installs the Redis binaries, Redis Server configuration file, and the mdx-backend-redis service controlling the starting, stopping, and restarting of the Redis Server as well as the showing of the Redis Server status
  • mdx-backend-sentinel, needed when using Redis in a High Availability (HA) configuration, installs the Redis Sentinel configuration file and the mdx-backend-sentinel service controlling the starting, stopping, and restarting of the Redis Sentinel Server as well as the showing of the Redis Sentinel Server status

Supported versions for Redis and Sentinel authentication

To enable Redis and Sentinel authentication, use these or later versions.

  Version
PiCache 2022.2.0
mdx-backend-redis 2022.1.0
mdx-backend-sentinel 2022.1.0
PiServer 3.4.0

Redis Server

From redis.io:

Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache and message broker.

The Perforce IPLM Events Framework uses the Redis message broker facility with Perforce IPLM components publishing events to Redis and event consumers subscribing to events from Redis.

The Perforce IPLM IP Caching component, IPLM Cache, also uses Redis for its message broker facility as well as its data structure store, so if you've installed IPLM Cache, you've already installed the Redis Backend Server.

Redis references

Redis Homepage

Redis Pub/Sub (describing Redis's message broker/messaging paradigm)

Redis Streams (describing Redis's stream data structure)

Redis Sentinel Documentation (describing Redis HA)

Redis Installation

To install Perforce' Redis Backend Server, follow the instructions in the appropriate Perforce Package Installation section to install the mdx-backend-redis package using apt-get, yum, or zypper.

If you are installing Redis in an HA configuration, after installing the mdx-backend-redis package on each node of the Redis cluster, install the mdx-backend-sentinel package on each node of the Redis cluster.

Note that if uninstalling these packages, mdx-backend-sentinel must be uninstalled before uninstalling mdx-backend-redis.

mdx-backend-redis installs the Redis binaries within /usr/share/mdx/redis. As of this writing, the latest Redis version packaged is v5.0.7 and the Redis binaries are located in /usr/share/mdx/redis/mdx-redis-bin-5.0.7/bin. Note that mdx-backend-redis installs the Redis Sentinel binary, redis-sentinel, which is just a link to the Redis Server binary, redis-server. The Redis Client, redis-cli, is also in the binaries directory, so to use this your shell's PATH environment variable needs to reference the binaries directory or you need to use the full path to redis-cli.

mdx-backend-redis and mdx-backend-sentinel install supplementary scripts in /usr/share/mdx/redis/scripts that are used by the mdx-backend-redis and mdx-backend-sentinel services.

The Redis Server configuration file is installed at /etc/mdx/mdx-backend-redis.conf, and the Redis Sentinel Server configuration file is installed at /etc/mdx/mdx-backend-sentinel.conf.

Configuration

Redis single-node configuration

For running the Redis Server on a single node and the same node as PiServer and any and all event consumers, the default Redis configuration file installed by mdx-backend-redis, /etc/mdx/mdx-backend-redis.conf, can be used as-is with the protected-mode no directive uncommented.

If the Redis Server is to be run on a single node, but a different node than PiServer and/or an event consumer, /etc/mdx/mdx-backend-redis.conf will need to be modified as follows:

  • Comment out the line for the bind 127.0.0.1 directive. This will cause the Redis Server to bind to all interfaces so the Redis Server can be accessed externally. Alternately, the bind directive can be set to one or more specific interfaces.

  • To configure Redis with a password so that clients, like PiServer and PiCache, use that password to communicate with Redis, the requirepass directive must be uncommented and set to the desired password. The protected-mode directive must be either commented or set to yes.

If the Redis Server configuration file must be changed while the mdx-backend-redis service is running, first stop the service with:

# service mdx-backend-redis stop

Then update /etc/mdx/mdx-backend-redis.conf, and finally restart the service with:

# service mdx-backend-redis start

Redis HA configuration

For a high availability configuration, three or more nodes are used to run Redis Server and Redis Sentinel Server. One node will run the Master Redis instance; the other nodes will run the Slave Redis instances. The Master Redis instance replicates its in-memory database to the other Slave Redis instances. The Redis Sentinel instances coordinate among themselves to determine which node runs the Master Redis Server instance and to coordinate failover. 

For the HA configuration, /etc/mdx/mdx-backend-redis.conf will need to be modified as follows:

  • Comment out the line for the bind 127.0.0.1 directive. This will cause the Redis Server to bind to all interfaces so the Redis Server can be accessed externally. Alternately, the bind directive can be set to one or more specific interfaces.

  • Choose a node to be the initial Master Redis instance. On that node, keep the replicaof directive commented out. On the slave nodes, uncomment the replicaof directive, changing the IP address to the IP address of the node that will run the initial Master Redis instance.

  • To configure Redis with a password so that clients, like PiServer and PiCache, use that password to communicate with Redis, the requirepass directive must be uncommented and set to the desired password and the masterauth directive also uncommented and set to the same password. The protected-mode directive must be either commented or set to yes.

If the Redis Server configuration file must be changed while the mdx-backend-redis service is running, first stop the service with:

# service mdx-backend-redis stop

Then update /etc/mdx/mdx-backend-redis.conf, and finally restart the service with:

# service mdx-backend-redis start

/etc/mdx/mdx-backend-sentinel.conf must be modified as follows:

  • Update the bind directive, giving the IP address of the node the configuration file is for.
  • Update the sentinel monitor mymaster directive, giving the IP address of the node that will run the initial Master Redis instance.

  • If Redis Server is configured with a password (in mdx-backend-redis.conf, in the requirepass directive), the sentinel auth-pass mymaster directive must be set with the password of the Redis Server.

  • To configure Redis Sentinel with a password so clients, like PiServer and PiCache, use that password to communication with Redis Sentinel, the requirepass directive must be set to the password to be used by Redis Sentinel.

  • Other directives may need to be updated as needed.

If the Redis Sentinel configuration file must be changed while the mdx-backend-sentinel service is running, first stop the service with:

# service mdx-backend-sentinel stop

Then update /etc/mdx/mdx-backend-sentinel.conf, and finally restart the service with

# service mdx-backend-sentinel start

IPLM Server configuration

IPLM Server publishes events to a Redis Server. In order for IPLM Server to do this, it uses the following Redis configuration items in piserver.yml, usually found at /etc/mdx/piserver.yml:

Redis Config in piserver.yml 
# --------------------------------------------------
# Redis (events)
# --------------------------------------------------
redis:
    # Redis hosts
    # Single host example
    #hosts: "localhost:6379"
    # Redis HA example using Redis Sentinels
    #hosts: "10.211.55.18:26379, 10.211.55.19:26379, 10.211.55.20:26379"
    # Redis client timeout waiting for server response
    timeout: 2 seconds
    # Redis Sentinel master, for an HA Redis deployment
    #sentinelMaster: "mymaster"
    # Redis Server password
    #redisPassword: "foo"
    # Redis Sentinel password
    #sentinelPassword: "bar"

At the minimum, a hosts: line must be uncommented. For a single node Redis configuration, use the format:

hosts: 10.211.55.6:6379

Using the Redis Server's host's IP address and port. For example, hosts: localhost:6379 can be used if all the components are running on the same node.

For an HA Redis configuration, use the format:

hosts: 10.211.55.6:26379,10.211.55.7:26379,10.211.55.8:26379

Using the IP addresses and Redis Sentinel port of the hosts running the Redis Sentinel servers.

Also for an HA Redis configuration, if the Redis Sentinel Master name is different than mymaster, uncomment the redis.sentinel.master line and put in the Redis Sentinel Master name the HA configuration uses.

redis.timeout is the duration in which the socket to a Redis instance will be considered stalled if waiting for packets and none are received. This may need to be tuned to your environment if you find the default setting causes unexpected Redis socket closures.

If Redis Server and Redis Sentinel are password protected, uncomment the redisPassword and sentinelPassword lines and set them to the correct passwords.

Enabling of events by pi-admin command

To see if events are enabled or not by IPLM Server, run the pi-admin command:

pi-admin Command 
 $ pi-admin settings list
┌─────────────────────────────────────────────────────┬──────────────────┐
│ KEY                                                 │ VALUE            │
╞═════════════════════════════════════════════════════╪══════════════════╡
│ SYSTEM.EVENTS.redis.pubsub.enable                   │ none (*)         │
│ SYSTEM.EVENTS.redis.stream.enable                   │ none (*)         │
│ SYSTEM.EVENTS.redis_stream_xadd_maxlen              │ -1 (*)           │
│ SYSTEM.IP.IPV.delete_operation_permission           │ admin (*)        │
│ SYSTEM.IP.IPV.project_props.auto_resolve            │ alphanumeric (*) │
│ SYSTEM.SEARCH.GLOBAL.global_search_analyzer         │ standard (*)     │
│ SYSTEM.SEARCH.GLOBAL.global_search_min_query_length │ 3 (*)            │
└─────────────────────────────────────────────────────┴──────────────────┘
Items marked (*) are defaults

If the SYSTEM.EVENTS.redis.pubsub.enable or SYSTEM.EVENTS.redis.stream.enable fields are set to none, to enable events run pi-admin settings edit:

$ pi-admin settings edit

In the resulting template set EVENTS.redis.pubsub.enable to either write_only, to only enable events for database write operations, or all, for all types of events:

[SYSTEM]

# Perforce IPLM events. Possible choices:
#  none        Disable events (default)
#  all         Enable all Perforce IPLM events
#  write_only  Enables events that result in a Write operation
#              and disables all other events
EVENTS.redis.pubsub.enable = write_only
EVENTS.redis.stream.enable= none

# PerforceIPLM redis stream maximum length. Integer value:
# -1            No limit
# >0            Maximum length
EVENTS.redis.stream.xadd.maxlen = -1

# Default resolve conflict resolution. Possible choices:
#  alphanumeric  Use alphanumeric alias resolution (default)
#  version       Use highest version resolution
# see https://help.perforce.com/methodics/ for more details
IP.IPV.project_props.auto_resolve = alphanumeric