DonalEvans commented on a change in pull request #7274: URL: https://github.com/apache/geode/pull/7274#discussion_r790089534
########## File path: geode-docs/tools_modules/geode_for_redis.html.md.erb ########## @@ -25,215 +25,243 @@ optional password authentication. <img src="../images_svg/geode_for_redis.svg" class="image" /> -## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis +## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands. -Use gfsh to start at least one server with a command of the form: +Prerequisites for running the examples: -```pre -start server \ - --name=<serverName> \ - --locators=<locatorPort> \ - --J=-Dgemfire.geode-for-redis-enabled=true \ - --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \ - --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> -``` - -If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%> -server with <%=vars.product_name%> for Redis will be started. +1. **Install <%=vars.product_name%>** <br/> +Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>. +2. **Install the Redis CLI** <br/> +Follow installation instructions at https://redis.io/download -Replace `<serverName>` with the name of your server. +Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster: -Replace `<locatorPort>` with your locator port. +```commandLine +gfsh> start locator +``` -Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server - listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379. +Use `gfsh` to start at least one server with a command of the form: -Replace `<geodeForRedisBindAddress>` with the address of the server host. +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379 +``` -Replace `<geodeForRedisPassword>` with the password clients use to authenticate. +More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below. -To confirm the server is listening, run: +To confirm the server is listening, in a separate terminal run: -``` pre -redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping +```commandLine +$ redis-cli -c ping ``` -Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server. +The `-c` option enables cluster mode in the redis-cli, which is necessary since +<%=vars.product_name%> for Redis runs as a Redis Cluster. If the server is functioning properly, you should see a response of `PONG`. -## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands +### <a id="adding-a-server"></a> Add an additional server +If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again. -<%=vars.product_name%> for Redis supports the following Redis commands. -<br/> - - - APPEND <br/> - - AUTH <br/> - - DECR <br/> - - DECRBY <br/> - - DEL <br/> - - EXISTS <br/> - - EXPIRE <br/> - - EXPIREAT <br/> - - GET <br/> - - GETRANGE <br/> - - HDEL <br/> - - HEXISTS <br/> - - HGET <br/> - - HGETALL <br/> - - HINCRBY <br/> - - HINCRBYFLOAT <br/> - - HLEN <br/> - - HMGET <br/> - - HMSET <br/> - - HSCAN **[1]** <br/> - - HSET <br/> - - HSETNX <br/> - - HSTRLEN <br/> - - HVALS <br/> - - HKEYS <br/> - - INCR <br/> - - INCRBY <br/> - - INCRBYFLOAT <br/> - - INFO **[2]** <br/> - - KEYS <br/> - - MGET <br/> - - PERSIST <br/> - - PEXPIRE <br/> - - PEXPIREAT <br/> - - PING <br/> - - PSUBSCRIBE <br/> - - PTTL <br/> - - PUBLISH <br/> - - PUNSUBSCRIBE <br/> - - QUIT <br/> - - RENAME <br/> - - SADD <br/> - - SCARD <br/> - - SDIFF <br/> - - SDIFFSTORE <br/> - - SINTER <br/> - - SISMEMBER <br/> - - SET <br/> - - SETNX <br/> - - SLOWLOG **[3]** <br/> - - SMEMBERS <br/> - - SMOVE <br/> - - SRANDMEMBER <br/> - - SREM <br/> - - STRLEN <br/> - - SUBSCRIBE <br/> - - SUNION <br/> - - SUNIONSTORE <br/> - - TTL <br/> - - TYPE <br/> - - UNSUBSCRIBE <br/> - -<br/> -Commands not listed above are **not implemented**. +However, there are two ports that must be unique for each server in the cluster, the +`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the +`server-port`, which is used for cluster communication. -<br/> -**NOTES:** +The first server used `6379` for the redis port; we'll use `6380` for the second server. -These commands are supported for Redis 5. +The first server was started without +a server port specified, so it used the default `40404`. To start up an additional server, you need to specify +a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use +an arbitrary available port for the server port. + +For example: + +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0 +``` -**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters. - <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters. +### <a id="shutting-down"></a>Shutting Down +To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command -**[2]** INFO is implemented for the sections and fields listed below: +```commandLine +gfsh> shutdown --include-locators=true +``` - - clients +This command shuts down the entire <%=vars.product_name%> cluster. - - connected_clients +To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message: - - blocked_clients (always returns 0) +```commandline +Could not connect to Redis at 127.0.0.1:6379: Connection refused +``` - - cluster +## <a id="redis-start-server-options"></a>Start Server Options - - cluster_enables (always returns 0) +The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below. +For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A). - - keyspace +`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/> +If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started. - - returns stats for db: 0 +`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/> +Specifies the port on which the <%=vars.product_name%> server +listens for Redis commands. Note that the default port `6379` is the same port that native Redis +uses by default. - - memory +`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/> +Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the +empty string or if not specified, the server listens on all local addresses. - - maxmemory +`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/> +Specifies the default username that the server uses when a client attempts to authenticate using +only a password. See section on [Security](#security) for more information. - - used_memory +`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/> +Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in +the cluster. A value of 0 means no extra copies of data will be stored in the cluster. +Note that extra servers need to be running for redundant copies to be made. For +example if the cluster only has one server then no redundant copies will exist no matter what the +value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region +to implement redundant copies and this property corresponds to the partitioned region's +"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a +<%=vars.product_name%> for Redis server. - - mem_fragmentation_ratio (always reports 1.00) +## <a id="security"></a>Security - - persistence +Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file. - - loading (always returns 0) +When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`. - - rdb_changes_since_last_save (always returns 0) +The following gfsh command configures a `SimpleSecurityManager`: - - rdb_last_save_time (always returns 0) +```console +gfsh> start server \ + --name=<serverName> \ + --locators=<locatorPort> \ + --J=-Dgemfire.geode-for-redis-enabled=true \ + --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \ + --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \ + --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \ + --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager +``` - - replication +To confirm that the server is working, in a separate terminal run: - - role +```console +$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \ + --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping +``` - - connected_slaves (always returns 0) +The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same. - - server +Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username. - - redis_version +Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured. - - redis_mode +For information on configuring the cluster for SSL, see [Configuring SSL](../managing/security/implementing_ssl.html). - - tcp_port +## <a id="application-development"></a>Application Development - - uptime_in_seconds +### <a id="thingstoknowbeforyoubegin"></a>Things to know before you begin +- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands +- Applications must be using a redis client that supports Redis Cluster mode. +- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported). - - uptime_in_days +```java +@Bean +public static ConfigureRedisAction configureRedisAction() { + return ConfigureRedisAction.NO_OP; +} +``` +This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons. +You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124). - - stats +## <a id="redis-commands"></a>Redis Commands - - total_commands_processed +<%=vars.product_name%> for Redis supports the following Redis commands. - - instantaneous_ops_per_sec +| Supported Commands |||| +|-----|-----|-----|-----| +| APPEND | AUTH | CLIENT | CLUSTER **[1]** | +| COMMAND **[2]** | DECR | DECRBY | DEL | +| DUMP | ECHO | EXISTS | EXPIRE | +| EXPIREAT | GET | GETRANGE | GETSET | +| HDEL | HEXISTS | HGET | HGETALL | +| HINCRBY | HINCRBYFLOAT | HKEYS | HLEN | +| HMGET | HMSET | HSCAN **[3]** | HSET | +| HSETNX | HSTRLEN | HVALS | INCR | +| INCRBY | INCRBYFLOAT | INFO **[4]** | KEYS | +| LOLWUT | MGET | MSET | MSETNX | +| PERSIST | PEXPIRE | PEXPIREAT | PING | +| PSETEX | PSUBSCRIBE | PTTL | PUBLISH | +| PUBSUB | PUNSUBSCRIBE | RENAME | RENAMENX | +| RESTORE | SADD | SCARD | SDIFF | +| SDIFFSTORE | SET | SETEX | SETNX | +| SETRANGE | SINTER | SINTERSTORE | SISMEMBER | +| SMEMBERS | SMOVE | SPOP | SRANDMEMBER | +| SREM | SSCAN **[3]** | STRLEN | SUBSCRIBE | +| SUNION | SUNIONSTORE | TTL | TYPE | +| UNSUBSCRIBE | QUIT | ZADD | ZCARD | +| ZCOUNT | ZINCRBY | ZINTERSTORE | ZLEXCOUNT | +| ZPOPMAX | ZPOPMIN | ZRANGE | ZRANGEBYLEX | +| ZRANGEBYSCORE | ZRANK | ZREM | ZREMRANGEBYLEX | +| ZREMRANGEBYRANK | ZREMRANGEBYSCORE | ZREVRANGE | ZREVRANGEBYLEX | +| ZREVRANGEBYSCORE | ZREVRANK | ZSCAN **[3]** | ZSCORE | +| ZUNIONSTORE |||| - - total_net_input_bytes - - instantaneous_input_kbps +Commands not listed above are **not implemented**. - - total_connections_received +**NOTES:** - - keyspace_hits +These commands are supported for Redis 5. + +**[1]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT. - - keyspace_misses +**[2]** COMMAND is implemented only with no subcommands. - - evicted_keys (always returns 0) +**[3]** Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers +(+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. <%=vars.product_name%> for Redis matches +native Redis's behavior for COUNT, but only supports values of +/- the capacity of a signed 64-bit +integer (+/- 9223372036854775807) for CURSOR. - - rejected_connections (always returns 0) +**[4]** INFO is implemented for the sections and fields listed below: -**[3]** SLOWLOG is implemented as a NoOp. +| INFO section | Field(s) | +|--------------|----------| +| clients | connected_clients<br/>blocked_clients (always returns 0) | +| cluster | cluster_enables (always returns 1) | Review comment: Typo here, should be "cluster_enabled" ########## File path: geode-docs/tools_modules/geode_for_redis.html.md.erb ########## @@ -25,215 +25,243 @@ optional password authentication. <img src="../images_svg/geode_for_redis.svg" class="image" /> -## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis +## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands. -Use gfsh to start at least one server with a command of the form: +Prerequisites for running the examples: -```pre -start server \ - --name=<serverName> \ - --locators=<locatorPort> \ - --J=-Dgemfire.geode-for-redis-enabled=true \ - --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \ - --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> -``` - -If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%> -server with <%=vars.product_name%> for Redis will be started. +1. **Install <%=vars.product_name%>** <br/> +Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>. +2. **Install the Redis CLI** <br/> +Follow installation instructions at https://redis.io/download -Replace `<serverName>` with the name of your server. +Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster: -Replace `<locatorPort>` with your locator port. +```commandLine +gfsh> start locator +``` -Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server - listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379. +Use `gfsh` to start at least one server with a command of the form: -Replace `<geodeForRedisBindAddress>` with the address of the server host. +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379 +``` -Replace `<geodeForRedisPassword>` with the password clients use to authenticate. +More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below. -To confirm the server is listening, run: +To confirm the server is listening, in a separate terminal run: -``` pre -redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping +```commandLine +$ redis-cli -c ping ``` -Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server. +The `-c` option enables cluster mode in the redis-cli, which is necessary since +<%=vars.product_name%> for Redis runs as a Redis Cluster. If the server is functioning properly, you should see a response of `PONG`. -## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands +### <a id="adding-a-server"></a> Add an additional server +If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again. -<%=vars.product_name%> for Redis supports the following Redis commands. -<br/> - - - APPEND <br/> - - AUTH <br/> - - DECR <br/> - - DECRBY <br/> - - DEL <br/> - - EXISTS <br/> - - EXPIRE <br/> - - EXPIREAT <br/> - - GET <br/> - - GETRANGE <br/> - - HDEL <br/> - - HEXISTS <br/> - - HGET <br/> - - HGETALL <br/> - - HINCRBY <br/> - - HINCRBYFLOAT <br/> - - HLEN <br/> - - HMGET <br/> - - HMSET <br/> - - HSCAN **[1]** <br/> - - HSET <br/> - - HSETNX <br/> - - HSTRLEN <br/> - - HVALS <br/> - - HKEYS <br/> - - INCR <br/> - - INCRBY <br/> - - INCRBYFLOAT <br/> - - INFO **[2]** <br/> - - KEYS <br/> - - MGET <br/> - - PERSIST <br/> - - PEXPIRE <br/> - - PEXPIREAT <br/> - - PING <br/> - - PSUBSCRIBE <br/> - - PTTL <br/> - - PUBLISH <br/> - - PUNSUBSCRIBE <br/> - - QUIT <br/> - - RENAME <br/> - - SADD <br/> - - SCARD <br/> - - SDIFF <br/> - - SDIFFSTORE <br/> - - SINTER <br/> - - SISMEMBER <br/> - - SET <br/> - - SETNX <br/> - - SLOWLOG **[3]** <br/> - - SMEMBERS <br/> - - SMOVE <br/> - - SRANDMEMBER <br/> - - SREM <br/> - - STRLEN <br/> - - SUBSCRIBE <br/> - - SUNION <br/> - - SUNIONSTORE <br/> - - TTL <br/> - - TYPE <br/> - - UNSUBSCRIBE <br/> - -<br/> -Commands not listed above are **not implemented**. +However, there are two ports that must be unique for each server in the cluster, the +`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the +`server-port`, which is used for cluster communication. -<br/> -**NOTES:** +The first server used `6379` for the redis port; we'll use `6380` for the second server. -These commands are supported for Redis 5. +The first server was started without +a server port specified, so it used the default `40404`. To start up an additional server, you need to specify +a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use +an arbitrary available port for the server port. + +For example: + +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0 +``` -**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters. - <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters. +### <a id="shutting-down"></a>Shutting Down +To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command -**[2]** INFO is implemented for the sections and fields listed below: +```commandLine +gfsh> shutdown --include-locators=true +``` - - clients +This command shuts down the entire <%=vars.product_name%> cluster. - - connected_clients +To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message: - - blocked_clients (always returns 0) +```commandline +Could not connect to Redis at 127.0.0.1:6379: Connection refused +``` - - cluster +## <a id="redis-start-server-options"></a>Start Server Options - - cluster_enables (always returns 0) +The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below. +For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A). - - keyspace +`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/> +If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started. - - returns stats for db: 0 +`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/> +Specifies the port on which the <%=vars.product_name%> server +listens for Redis commands. Note that the default port `6379` is the same port that native Redis +uses by default. - - memory +`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/> +Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the +empty string or if not specified, the server listens on all local addresses. - - maxmemory +`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/> +Specifies the default username that the server uses when a client attempts to authenticate using +only a password. See section on [Security](#security) for more information. - - used_memory +`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/> +Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in +the cluster. A value of 0 means no extra copies of data will be stored in the cluster. +Note that extra servers need to be running for redundant copies to be made. For +example if the cluster only has one server then no redundant copies will exist no matter what the +value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region +to implement redundant copies and this property corresponds to the partitioned region's +"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a +<%=vars.product_name%> for Redis server. - - mem_fragmentation_ratio (always reports 1.00) +## <a id="security"></a>Security - - persistence +Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file. - - loading (always returns 0) +When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`. - - rdb_changes_since_last_save (always returns 0) +The following gfsh command configures a `SimpleSecurityManager`: - - rdb_last_save_time (always returns 0) +```console +gfsh> start server \ + --name=<serverName> \ + --locators=<locatorPort> \ + --J=-Dgemfire.geode-for-redis-enabled=true \ + --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \ + --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \ + --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \ + --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager +``` - - replication +To confirm that the server is working, in a separate terminal run: - - role +```console +$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \ + --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping +``` - - connected_slaves (always returns 0) +The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same. - - server +Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username. - - redis_version +Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured. - - redis_mode +For information on configuring the cluster for SSL, see [Configuring SSL](../managing/security/implementing_ssl.html). - - tcp_port +## <a id="application-development"></a>Application Development - - uptime_in_seconds +### <a id="thingstoknowbeforyoubegin"></a>Things to know before you begin +- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands +- Applications must be using a redis client that supports Redis Cluster mode. +- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported). - - uptime_in_days +```java +@Bean +public static ConfigureRedisAction configureRedisAction() { + return ConfigureRedisAction.NO_OP; +} +``` +This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons. +You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124). - - stats +## <a id="redis-commands"></a>Redis Commands - - total_commands_processed +<%=vars.product_name%> for Redis supports the following Redis commands. - - instantaneous_ops_per_sec +| Supported Commands |||| +|-----|-----|-----|-----| +| APPEND | AUTH | CLIENT | CLUSTER **[1]** | +| COMMAND **[2]** | DECR | DECRBY | DEL | +| DUMP | ECHO | EXISTS | EXPIRE | +| EXPIREAT | GET | GETRANGE | GETSET | +| HDEL | HEXISTS | HGET | HGETALL | +| HINCRBY | HINCRBYFLOAT | HKEYS | HLEN | +| HMGET | HMSET | HSCAN **[3]** | HSET | +| HSETNX | HSTRLEN | HVALS | INCR | +| INCRBY | INCRBYFLOAT | INFO **[4]** | KEYS | +| LOLWUT | MGET | MSET | MSETNX | +| PERSIST | PEXPIRE | PEXPIREAT | PING | +| PSETEX | PSUBSCRIBE | PTTL | PUBLISH | +| PUBSUB | PUNSUBSCRIBE | RENAME | RENAMENX | +| RESTORE | SADD | SCARD | SDIFF | +| SDIFFSTORE | SET | SETEX | SETNX | +| SETRANGE | SINTER | SINTERSTORE | SISMEMBER | +| SMEMBERS | SMOVE | SPOP | SRANDMEMBER | +| SREM | SSCAN **[3]** | STRLEN | SUBSCRIBE | +| SUNION | SUNIONSTORE | TTL | TYPE | +| UNSUBSCRIBE | QUIT | ZADD | ZCARD | +| ZCOUNT | ZINCRBY | ZINTERSTORE | ZLEXCOUNT | +| ZPOPMAX | ZPOPMIN | ZRANGE | ZRANGEBYLEX | +| ZRANGEBYSCORE | ZRANK | ZREM | ZREMRANGEBYLEX | +| ZREMRANGEBYRANK | ZREMRANGEBYSCORE | ZREVRANGE | ZREVRANGEBYLEX | +| ZREVRANGEBYSCORE | ZREVRANK | ZSCAN **[3]** | ZSCORE | +| ZUNIONSTORE |||| - - total_net_input_bytes - - instantaneous_input_kbps +Commands not listed above are **not implemented**. - - total_connections_received +**NOTES:** - - keyspace_hits +These commands are supported for Redis 5. + +**[1]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT. - - keyspace_misses +**[2]** COMMAND is implemented only with no subcommands. - - evicted_keys (always returns 0) +**[3]** Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers +(+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. <%=vars.product_name%> for Redis matches +native Redis's behavior for COUNT, but only supports values of +/- the capacity of a signed 64-bit +integer (+/- 9223372036854775807) for CURSOR. - - rejected_connections (always returns 0) +**[4]** INFO is implemented for the sections and fields listed below: -**[3]** SLOWLOG is implemented as a NoOp. +| INFO section | Field(s) | +|--------------|----------| +| clients | connected_clients<br/>blocked_clients (always returns 0) | +| cluster | cluster_enables (always returns 1) | +| keyspace | db0:keys<br/>expires (always returns 0)<br/>avg_ttl (always returns 0)<br/> | +| memory | maxmemory<br/>used_memory<br/>mem_fragmentation_ratio | +| persistence | loading (always returns 0)<br/>rdb_changes_since_last_save (always returns 0)<br/>rdb_last_save_time (always returns 0) | +| replication | role (always returns "master")<br/>connected_slaves (always returns 0) | +| server | redis_version<br/>redis_mode (always returns "cluster" because <%=vars.product_name%> for Redis always runs in cluster mode.)<br/>tcp_port<br/>uptime_in_seconds<br/>uptime_in_days | +| stats | total_commands_processed<br/>instantaneous_ops_per_sec<br/>total_net_input_bytes<br/>instantaneous_input_kbps<br/>total_connections_received<br/>keyspace_hits<br/>keyspace_misses<br/>evicted_keys (always returns 0)<br/>rejected_connections (always returns 0)<br/>pubsub_channels<br/>pubsub_patterns| -## <a id="advantages-over-redis" class="no-quick-link"></a>Advantages of <%=vars.product_name%> over Redis +## <a id="advantages-over-redis"></a>Advantages of <%=vars.product_name%> over Redis <%=vars.product_name%>’s primary advantage is its **scalability**. While the Redis server is single threaded, <%=vars.product_name%> supports high concurrency. Many Redis clients can execute commands on the <%=vars.product_name%> cluster simultaneously. <%=vars.product_name%>'s architecture and management features help detect and resolve **network partitioning** problems without explicit management on the part of the Redis client. -## <a id="expiration-accuracy" class="no-quick-link"></a>Expiration Accuracy +<%=vars.product_name%> for Redis partitions data across multiple servers and keeps replicated data up to date _synchronously_, whereas Redis uses asynchronous replication. +This provides a higher level of data consistency within the cluster. + +## <a id="expiration-accuracy"></a>Expiration Accuracy Keys are expired in two ways, actively and passively: - With active expiration, expiration is evaluated whenever a key is accessed. If the key is due to expire, it is deleted. Active expiration is accurate to the millisecond. -- With passive expiration, keys are evaluated every second. If they are due to expire, they are deleted. Passive expiration is accurate to the second. +- With passive expiration, keys are evaluated every three seconds. If they are due to expire, they are deleted. Passive expiration is accurate to the second. Review comment: This should be "every three minutes" ########## File path: geode-docs/tools_modules/geode_for_redis.html.md.erb ########## @@ -25,160 +25,320 @@ optional password authentication. <img src="../images_svg/geode_for_redis.svg" class="image" /> -## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis +## <a id="using-geode-for-redis" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands. -Use gfsh to start at least one server with a command of the form: +Prerequisites for running the examples: -```pre -start server \ +1. **Install Geode** \ + Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install Geode. +2. **Install the Redis CLI** \ + Follow installation instructions at https://redis.io/download + +Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster: +```commandLine +gfsh> start locator +``` + +Use `gfsh` to start at least one server with a command of the form: + +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379 +``` + +More information about the options when starting a server is given in the section [Start Server Options](#start-server-options). +Note that `gfsh` suppots tab completion which can help with long option names. + +To confirm the server is listening, in a separate terminal run: + +```commandLine +> redis-cli -c ping +``` + +The `-c` option enables cluster mode in the redis-cli, which is necessary since +<%=vars.product_name%> for Redis runs as a Redis Cluster. + +If the server is functioning properly, you should see a response of `PONG`. + +### <a name="adding-a-server"></a> Add an additional Geode server compatible with Redis APIs +If you’re interested in testing Geode scalability, in gfsh run the `start server` command again. + +However, there are two ports that must be unique for each server in the cluster, the +`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the +`server-port`, which is used for cluster communication. + +The first server used `6379` for the redis port; we'll use `6380` for the second server. + +The first server was started without +a server port specified, so it used the default `40404`. To start up an additional server, you need to specify +a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use +an arbitrary available port for the server port. + +For example: +```commandLine +gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0 +``` + +### <a name="shutting-down"></a>Shutting Down +To shut down the Geode cluster you started, in the terminal with gfsh running type the following command + +```commandLine +gfsh> shutdown --include-locators=true +``` + +This command shuts down the entire Geode cluster. You are prompted with the following choice: + +```commandline +As a lot of data in memory will be lost, including possibly events in queues, do you really want to shutdown the entire distributed system? (Y/n) +``` + +To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message: + +```commandline +Could not connect to Redis at 127.0.0.1:6379: Connection refused +``` + +## <a name="start-server-options"></a>Start Server Options + +The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below. +For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A). + +### `gemfire.geode-for-redis-enabled` (Default: `false`) +If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started. + +### `gemfire.geode-for-redis-port` (Default: `6379`) +Specifies the port on which the <%=vars.product_name%> server +listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379 +(i.e. the same port that native Redis uses). + +### `gemfire.geode-for-redis-bind-address` (Default: `""`) +Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the +empty string or if not specified, the server listens on all local addresses. + +### `gemfire.geode-for-redis-username` (Default: `"default"`) +Specifies the default username that the server uses when a client attempts to authenticate using +only a password. See section on [Security](#security) for more information. + +### `gemfire.geode-for-redis-redundant-copies` (Default: `1`) +Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in +the cluster. A value of 0 means no extra copies of data will be stored in the cluster. +Note that extra servers need to be running for redundant copies to be made. For +example if the cluster only has one server then no redundant copies will exist no matter what the +value of this property is. Also note that <%=vars.product_name%> for Redis uses a Geode partitioned region +to implement redundant copies and this property corresponds to the partitioned region's +"redundant-copies" attribute. +This property must be set the same on every server in the cluster that is running a +<%=vars.product_name%> for Redis server. + +## <a name="security"></a>Security + +Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file. + +When using Apache Geode, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`. + +The following gfsh command will configure a `SimpleSecurityManager`: + +```console +gfsh> start server \ --name=<serverName> \ --locators=<locatorPort> \ --J=-Dgemfire.geode-for-redis-enabled=true \ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \ - --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> + --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \ + --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \ + --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager ``` -If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%> -server with <%=vars.product_name%> for Redis will be started. +To confirm that the server is working, in a separate terminal run: -Replace `<serverName>` with the name of your server. +```console +$> redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \ + --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping +``` + +The `SimpleSecurityManager` is only to be used **for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same. -Replace `<locatorPort>` with your locator port. +Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username. -Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server - listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379. +Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured. -Replace `<geodeForRedisBindAddress>` with the address of the server host. +For information on configuring the cluster for SSL, see [Managing Security](../managing/security). -Replace `<geodeForRedisPassword>` with the password clients use to authenticate. +## <a name="application-development"></a>Application Development -To confirm the server is listening, run: +### Things to know before you begin +- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands +- Applications must be using a redis client that supports Redis Cluster mode. +- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported). -``` pre -redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping +```java +@Bean +public static ConfigureRedisAction configureRedisAction() { + return ConfigureRedisAction.NO_OP; +} ``` +This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc) that disable the CONFIG command for security reasons. You can read more about why this is done [here](https://github.com/spring-projects/spring-session/issues/124). -Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server. +## <a name="redis-commands"></a>Redis Commands -If the server is functioning properly, you should see a response of `PONG`. +<%=vars.product_name%> for Redis supports the following Redis commands. + +- APPEND +- AUTH +- CLIENT +- CLUSTER **[1]** +- COMMAND **[2]** +- DECR +- DECRBY +- DEL +- DUMP +- ECHO +- EXISTS +- EXPIRE +- EXPIREAT +- GET +- GETRANGE +- GETSET +- HDEL +- HEXISTS +- HGET +- HGETALL +- HINCRBY +- HINCRBYFLOAT +- HKEYS +- HLEN +- HMGET +- HMSET +- HSCAN **[3]** +- HSET +- HSETNX +- HSTRLEN +- HVALS +- INCR +- INCRBY +- INCRBYFLOAT +- INFO **[4]** +- KEYS +- LOLWUT +- MGET +- MSET +- MSETNX +- PERSIST +- PEXPIRE +- PEXPIREAT +- PING +- PSETEX +- PSUBSCRIBE +- PTTL +- PUBLISH +- PUBSUB +- PUNSUBSCRIBE +- RENAME +- RENAMENX +- RESTORE +- SADD +- SCARD +- SDIFF +- SDIFFSTORE +- SET +- SETEX +- SETNX +- SETRANGE +- SINTER +- SINTERSTORE +- SISMEMBER +- SLOWLOG **[5]** +- SMEMBERS +- SMOVE +- SPOP +- SRANDMEMBER +- SREM +- SSCAN +- STRLEN +- SUBSCRIBE +- SUNION +- SUNIONSTORE +- TTL +- TYPE +- UNSUBSCRIBE +- QUIT +- ZADD +- ZCARD +- ZCOUNT +- ZINCRBY +- ZINTERSTORE +- ZLEXCOUNT +- ZPOPMAX +- ZPOPMIN +- ZRANGE +- ZRANGEBYLEX +- ZRANGEBYSCORE +- ZRANK +- ZREM +- ZREMRANGEBYLEX +- ZREMRANGEBYRANK +- ZREMRANGEBYSCORE +- ZREVRANGE +- ZREVRANGEBYLEX +- ZREVRANGEBYSCORE +- ZREVRANK +- ZSCAN +- ZSCORE +- ZUNIONSTORE -## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands -<%=vars.product_name%> for Redis supports the following Redis commands. -<br/> - - - APPEND <br/> - - AUTH <br/> - - DECR <br/> - - DECRBY <br/> - - DEL <br/> - - EXISTS <br/> - - EXPIRE <br/> - - EXPIREAT <br/> - - GET <br/> - - GETRANGE <br/> - - HDEL <br/> - - HEXISTS <br/> - - HGET <br/> - - HGETALL <br/> - - HINCRBY <br/> - - HINCRBYFLOAT <br/> - - HLEN <br/> - - HMGET <br/> - - HMSET <br/> - - HSCAN **[1]** <br/> - - HSET <br/> - - HSETNX <br/> - - HSTRLEN <br/> - - HVALS <br/> - - HKEYS <br/> - - INCR <br/> - - INCRBY <br/> - - INCRBYFLOAT <br/> - - INFO **[2]** <br/> - - KEYS <br/> - - MGET <br/> - - PERSIST <br/> - - PEXPIRE <br/> - - PEXPIREAT <br/> - - PING <br/> - - PSUBSCRIBE <br/> - - PTTL <br/> - - PUBLISH <br/> - - PUNSUBSCRIBE <br/> - - QUIT <br/> - - RENAME <br/> - - SADD <br/> - - SCARD <br/> - - SDIFF <br/> - - SDIFFSTORE <br/> - - SINTER <br/> - - SISMEMBER <br/> - - SET <br/> - - SETNX <br/> - - SLOWLOG **[3]** <br/> - - SMEMBERS <br/> - - SMOVE <br/> - - SREM <br/> - - STRLEN <br/> - - SUBSCRIBE <br/> - - SUNION <br/> - - TTL <br/> - - TYPE <br/> - - UNSUBSCRIBE <br/> - -<br/> Commands not listed above are **not implemented**. -<br/> **NOTES:** These commands are supported for Redis 5. +**[1]]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT. -**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters. - <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters. +**[2]** COMMAND is implemented only with no subcommands. -**[2]** INFO is implemented for the sections and fields listed below: +**[3]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters. +<%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters. Review comment: Well, I learned something new today! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
