You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@geode.apache.org by GitBox <gi...@apache.org> on 2022/01/20 00:29:11 UTC
[GitHub] [geode] DonalEvans commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
DonalEvans commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r788233960
##########
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
Review comment:
These lines do not appear to have formatted correctly in the built docs that are linked on this PR.
##########
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.
Review comment:
Extra ] here.
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -190,34 +350,37 @@ These commands are supported for Redis 5.
- uptime_in_days
- - stats
+- stats
- - total_commands_processed
+ - total_commands_processed
- - instantaneous_ops_per_sec
+ - instantaneous_ops_per_sec
- - total_net_input_bytes
+ - total_net_input_bytes
- - instantaneous_input_kbps
+ - instantaneous_input_kbps
- - total_connections_received
+ - total_connections_received
- - keyspace_hits
+ - keyspace_hits
- - keyspace_misses
+ - keyspace_misses
- - evicted_keys (always returns 0)
+ - evicted_keys (always returns 0)
- - rejected_connections (always returns 0)
+ - rejected_connections (always returns 0)
-**[3]** SLOWLOG is implemented as a NoOp.
+**[5]** SLOWLOG is implemented as a NoOp.
## <a id="advantages-over-redis" class="no-quick-link"></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.
+<%=vars.product_name%> for Redis partitions data across multiple servers and keeps replicated up to date _synchronously_, whereas Redis uses asynchronous replication.
Review comment:
Missing word here, I think. Should be "and keeps replicated data up to date"?
##########
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
+```
Review comment:
This section doesn't seem to be rendering properly in the linked built docs. Does it need an extra newline before it maybe?
##########
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" />
Review comment:
Do we really need this image? I might be underestimating the complexity because I'm so familiar with it, but the image doesn't seem to be adding any clarification over what's written in the description above it.
##########
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`)
Review comment:
For better formatting, I think these option descriptions should not use the `###` formatting, as that leads to the "(Default:" text being much larger than the rest of the text. Also, since these options must be specified using the `--J=-Dgemfire.` format, it might be best to write them here in that format.
##########
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
+```
Review comment:
The formatting on this has got messed up somehow, possibly a newline is needed after the "For example:"
##########
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.
Review comment:
Tab completion is not available for redis-related gfsh command arguments, as they were recently removed and can only be supplied using the `--J=-Dgemfire.` format, so this line might be more confusing than helpful.
##########
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
Review comment:
This should be "Specifies the port on which the <%=vars.product_name%> server listens for Redis commands." Also, I don't think it's necessary to mention what the "typical" port used is, as we already say what our default value is.
##########
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)
+```
Review comment:
I'm not sure that it's necessary to show what the output of the shutdown command is here, particularly since the way this is formatted, the reader has to scroll across to read it all.
##########
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
Review comment:
The wording "compatible with Redis APIs" is no longer used, so this might be better as "Add an additional Geode for Redis server" or just "Add an additional Geode server"
##########
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:
This note also applies to ZSCAN and SSCAN, but is incorrect as currently stated. Native Redis supports a range of values of +/- the capacity of *un*signed 64-bit integers (+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. Geode for Redis matches native Redis' behaviour for COUNT, but only supports values of +/- the capacity of a signed 64-bit integer (+/- 9223372036854775807) for CURSOR.
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -190,34 +350,37 @@ These commands are supported for Redis 5.
- uptime_in_days
- - stats
+- stats
- - total_commands_processed
+ - total_commands_processed
- - instantaneous_ops_per_sec
+ - instantaneous_ops_per_sec
- - total_net_input_bytes
+ - total_net_input_bytes
- - instantaneous_input_kbps
+ - instantaneous_input_kbps
- - total_connections_received
+ - total_connections_received
- - keyspace_hits
+ - keyspace_hits
- - keyspace_misses
+ - keyspace_misses
- - evicted_keys (always returns 0)
+ - evicted_keys (always returns 0)
- - rejected_connections (always returns 0)
+ - rejected_connections (always returns 0)
-**[3]** SLOWLOG is implemented as a NoOp.
+**[5]** SLOWLOG is implemented as a NoOp.
## <a id="advantages-over-redis" class="no-quick-link"></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.
+<%=vars.product_name%> for Redis partitions data across multiple servers and keeps replicated up to date _synchronously_, whereas Redis uses asynchronous replication.
+This provides a higher level of data consistency within the cluster.
+
## <a id="expiration-accuracy" class="no-quick-link"></a>Expiration Accuracy
Keys are expired in two ways, actively and passively:
Review comment:
The passive expiration description below is incorrect. Passive expiration is currently evaluated every 3 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.
- - clients
+**[4]** INFO is implemented for the sections and fields listed below:
- - connected_clients
+- clients
- - blocked_clients (always returns 0)
+ - connected_clients
- - cluster
+ - blocked_clients (always returns 0)
- - cluster_enables (always returns 0)
+- cluster
- - keyspace
+ - cluster_enables (always returns 0)
Review comment:
This no longer always returns 0, but instead always returns 1, because Geode for Redis always runs in cluster mode.
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -190,34 +350,37 @@ These commands are supported for Redis 5.
- uptime_in_days
- - stats
+- stats
- - total_commands_processed
+ - total_commands_processed
- - instantaneous_ops_per_sec
+ - instantaneous_ops_per_sec
- - total_net_input_bytes
+ - total_net_input_bytes
- - instantaneous_input_kbps
+ - instantaneous_input_kbps
- - total_connections_received
+ - total_connections_received
- - keyspace_hits
+ - keyspace_hits
- - keyspace_misses
+ - keyspace_misses
- - evicted_keys (always returns 0)
+ - evicted_keys (always returns 0)
- - rejected_connections (always returns 0)
+ - rejected_connections (always returns 0)
Review comment:
The stats section also contains pubsub_channels and pubsub_patterns.
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -190,34 +350,37 @@ These commands are supported for Redis 5.
- uptime_in_days
- - stats
+- stats
- - total_commands_processed
+ - total_commands_processed
- - instantaneous_ops_per_sec
+ - instantaneous_ops_per_sec
- - total_net_input_bytes
+ - total_net_input_bytes
- - instantaneous_input_kbps
+ - instantaneous_input_kbps
- - total_connections_received
+ - total_connections_received
- - keyspace_hits
+ - keyspace_hits
- - keyspace_misses
+ - keyspace_misses
- - evicted_keys (always returns 0)
+ - evicted_keys (always returns 0)
- - rejected_connections (always returns 0)
+ - rejected_connections (always returns 0)
-**[3]** SLOWLOG is implemented as a NoOp.
+**[5]** SLOWLOG is implemented as a NoOp.
Review comment:
SLOWLOG should probably not be documented, even if it is listed internally as a supported command, because it's not actually implemented. Listing it here is just likely to cause confusion.
##########
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.
- - clients
+**[4]** INFO is implemented for the sections and fields listed below:
- - connected_clients
+- clients
- - blocked_clients (always returns 0)
+ - connected_clients
- - cluster
+ - blocked_clients (always returns 0)
- - cluster_enables (always returns 0)
+- cluster
- - keyspace
+ - cluster_enables (always returns 0)
- - returns stats for db: 0
+- keyspace
- - memory
+ - returns stats for db: 0
- - maxmemory
+- memory
- - used_memory
+ - maxmemory
- - mem_fragmentation_ratio (always reports 1.00)
+ - used_memory
- - persistence
+ - mem_fragmentation_ratio (always reports 1.00)
- - loading (always returns 0)
+- persistence
- - rdb_changes_since_last_save (always returns 0)
+ - loading (always returns 0)
- - rdb_last_save_time (always returns 0)
+ - rdb_changes_since_last_save (always returns 0)
- - replication
+ - rdb_last_save_time (always returns 0)
- - role
+- replication
- - connected_slaves (always returns 0)
+ - role
- - server
+ - connected_slaves (always returns 0)
+
+- server
- redis_version
Review comment:
Below this, redis_mode always returns "cluster" because Geode for Redis always runs in cluster mode.
##########
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.
- - clients
+**[4]** INFO is implemented for the sections and fields listed below:
- - connected_clients
+- clients
- - blocked_clients (always returns 0)
+ - connected_clients
- - cluster
+ - blocked_clients (always returns 0)
- - cluster_enables (always returns 0)
+- cluster
- - keyspace
+ - cluster_enables (always returns 0)
- - returns stats for db: 0
+- keyspace
- - memory
+ - returns stats for db: 0
- - maxmemory
+- memory
- - used_memory
+ - maxmemory
- - mem_fragmentation_ratio (always reports 1.00)
+ - used_memory
- - persistence
+ - mem_fragmentation_ratio (always reports 1.00)
- - loading (always returns 0)
+- persistence
- - rdb_changes_since_last_save (always returns 0)
+ - loading (always returns 0)
- - rdb_last_save_time (always returns 0)
+ - rdb_changes_since_last_save (always returns 0)
- - replication
+ - rdb_last_save_time (always returns 0)
- - role
+- replication
- - connected_slaves (always returns 0)
+ - role
Review comment:
This always returns "master".
##########
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.
- - clients
+**[4]** INFO is implemented for the sections and fields listed below:
- - connected_clients
+- clients
- - blocked_clients (always returns 0)
+ - connected_clients
- - cluster
+ - blocked_clients (always returns 0)
- - cluster_enables (always returns 0)
+- cluster
- - keyspace
+ - cluster_enables (always returns 0)
- - returns stats for db: 0
+- keyspace
- - memory
+ - returns stats for db: 0
Review comment:
This is incorrect. The keyspace section contains stats for `db0:keys`, `expires` and `avg_ttl`. The latter two currently always return 0, but there's a ticket open to have them return something meaningful. I'll mention in that ticket's description that this section of the docs should be updated once that work is done.
##########
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.
- - clients
+**[4]** INFO is implemented for the sections and fields listed below:
- - connected_clients
+- clients
- - blocked_clients (always returns 0)
+ - connected_clients
- - cluster
+ - blocked_clients (always returns 0)
- - cluster_enables (always returns 0)
+- cluster
- - keyspace
+ - cluster_enables (always returns 0)
- - returns stats for db: 0
+- keyspace
- - memory
+ - returns stats for db: 0
- - maxmemory
+- memory
- - used_memory
+ - maxmemory
- - mem_fragmentation_ratio (always reports 1.00)
+ - used_memory
- - persistence
+ - mem_fragmentation_ratio (always reports 1.00)
Review comment:
This no longer always reports 1.00
--
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: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org