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/15 01:30:48 UTC
[GitHub] [geode] ezoerner opened a new pull request #7274: GEODE-9883 Update Geode for Redis docs file
ezoerner opened a new pull request #7274:
URL: https://github.com/apache/geode/pull/7274
<!-- Thank you for submitting a contribution to Apache Geode. -->
<!-- In order to streamline the review of the contribution we ask you
to ensure the following steps have been taken:
-->
### For all changes:
- [ ] Is there a JIRA ticket associated with this PR? Is it referenced in the commit message?
- [ ] Has your PR been rebased against the latest commit within the target branch (typically `develop`)?
- [ ] Is your initial contribution a single, squashed commit?
- [ ] Does `gradlew build` run cleanly?
- [ ] Have you written or updated unit tests to verify your changes?
- [ ] If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under [ASF 2.0](http://www.apache.org/legal/resolved.html#category-a)?
<!-- Note:
Please ensure that once the PR is submitted, check Concourse for build issues and
submit an update to your PR as soon as possible. If you need help, please send an
email to dev@geode.apache.org.
-->
--
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
[GitHub] [geode] DonalEvans commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790088299
##########
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:
Interesting thing about English punctuation rules (I had to look it up) is that the final `s` in the `'s` for possessives is only dropped after _plural_ nouns that end in an `s`. So `native Redis's behavior` is the correct spelling.
--
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
[GitHub] [geode] ezoerner edited a comment on pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner edited a comment on pull request #7274:
URL: https://github.com/apache/geode/pull/7274#issuecomment-1016983245
I incorporated those changes, but for some reason I'm unable to "resolve" the change request to allow this to be merged
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790035177
##########
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:
PR #7288
--
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
[GitHub] [geode] DonalEvans commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790089534
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
- - server
+Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username.
- - redis_version
+Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured.
- - redis_mode
+For information on configuring the cluster for SSL, see [Configuring SSL](../managing/security/implementing_ssl.html).
- - tcp_port
+## <a id="application-development"></a>Application Development
- - uptime_in_seconds
+### <a id="thingstoknowbeforyoubegin"></a>Things to know before you begin
+- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands
+- Applications must be using a redis client that supports Redis Cluster mode.
+- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported).
- - uptime_in_days
+```java
+@Bean
+public static ConfigureRedisAction configureRedisAction() {
+ return ConfigureRedisAction.NO_OP;
+}
+```
+This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons.
+You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124).
- - stats
+## <a id="redis-commands"></a>Redis Commands
- - total_commands_processed
+<%=vars.product_name%> for Redis supports the following Redis commands.
- - instantaneous_ops_per_sec
+| Supported Commands ||||
+|-----|-----|-----|-----|
+| APPEND | AUTH | CLIENT | CLUSTER **[1]** |
+| COMMAND **[2]** | DECR | DECRBY | DEL |
+| DUMP | ECHO | EXISTS | EXPIRE |
+| EXPIREAT | GET | GETRANGE | GETSET |
+| HDEL | HEXISTS | HGET | HGETALL |
+| HINCRBY | HINCRBYFLOAT | HKEYS | HLEN |
+| HMGET | HMSET | HSCAN **[3]** | HSET |
+| HSETNX | HSTRLEN | HVALS | INCR |
+| INCRBY | INCRBYFLOAT | INFO **[4]** | KEYS |
+| LOLWUT | MGET | MSET | MSETNX |
+| PERSIST | PEXPIRE | PEXPIREAT | PING |
+| PSETEX | PSUBSCRIBE | PTTL | PUBLISH |
+| PUBSUB | PUNSUBSCRIBE | RENAME | RENAMENX |
+| RESTORE | SADD | SCARD | SDIFF |
+| SDIFFSTORE | SET | SETEX | SETNX |
+| SETRANGE | SINTER | SINTERSTORE | SISMEMBER |
+| SMEMBERS | SMOVE | SPOP | SRANDMEMBER |
+| SREM | SSCAN **[3]** | STRLEN | SUBSCRIBE |
+| SUNION | SUNIONSTORE | TTL | TYPE |
+| UNSUBSCRIBE | QUIT | ZADD | ZCARD |
+| ZCOUNT | ZINCRBY | ZINTERSTORE | ZLEXCOUNT |
+| ZPOPMAX | ZPOPMIN | ZRANGE | ZRANGEBYLEX |
+| ZRANGEBYSCORE | ZRANK | ZREM | ZREMRANGEBYLEX |
+| ZREMRANGEBYRANK | ZREMRANGEBYSCORE | ZREVRANGE | ZREVRANGEBYLEX |
+| ZREVRANGEBYSCORE | ZREVRANK | ZSCAN **[3]** | ZSCORE |
+| ZUNIONSTORE ||||
- - total_net_input_bytes
- - instantaneous_input_kbps
+Commands not listed above are **not implemented**.
- - total_connections_received
+**NOTES:**
- - keyspace_hits
+These commands are supported for Redis 5.
+
+**[1]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT.
- - keyspace_misses
+**[2]** COMMAND is implemented only with no subcommands.
- - evicted_keys (always returns 0)
+**[3]** Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers
+(+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. <%=vars.product_name%> for Redis matches
+native Redis's behavior for COUNT, but only supports values of +/- the capacity of a signed 64-bit
+integer (+/- 9223372036854775807) for CURSOR.
- - rejected_connections (always returns 0)
+**[4]** INFO is implemented for the sections and fields listed below:
-**[3]** SLOWLOG is implemented as a NoOp.
+| INFO section | Field(s) |
+|--------------|----------|
+| clients | connected_clients<br/>blocked_clients (always returns 0) |
+| cluster | cluster_enables (always returns 1) |
Review comment:
Typo here, should be "cluster_enabled"
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
- - server
+Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username.
- - redis_version
+Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured.
- - redis_mode
+For information on configuring the cluster for SSL, see [Configuring SSL](../managing/security/implementing_ssl.html).
- - tcp_port
+## <a id="application-development"></a>Application Development
- - uptime_in_seconds
+### <a id="thingstoknowbeforyoubegin"></a>Things to know before you begin
+- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands
+- Applications must be using a redis client that supports Redis Cluster mode.
+- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported).
- - uptime_in_days
+```java
+@Bean
+public static ConfigureRedisAction configureRedisAction() {
+ return ConfigureRedisAction.NO_OP;
+}
+```
+This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons.
+You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124).
- - stats
+## <a id="redis-commands"></a>Redis Commands
- - total_commands_processed
+<%=vars.product_name%> for Redis supports the following Redis commands.
- - instantaneous_ops_per_sec
+| Supported Commands ||||
+|-----|-----|-----|-----|
+| APPEND | AUTH | CLIENT | CLUSTER **[1]** |
+| COMMAND **[2]** | DECR | DECRBY | DEL |
+| DUMP | ECHO | EXISTS | EXPIRE |
+| EXPIREAT | GET | GETRANGE | GETSET |
+| HDEL | HEXISTS | HGET | HGETALL |
+| HINCRBY | HINCRBYFLOAT | HKEYS | HLEN |
+| HMGET | HMSET | HSCAN **[3]** | HSET |
+| HSETNX | HSTRLEN | HVALS | INCR |
+| INCRBY | INCRBYFLOAT | INFO **[4]** | KEYS |
+| LOLWUT | MGET | MSET | MSETNX |
+| PERSIST | PEXPIRE | PEXPIREAT | PING |
+| PSETEX | PSUBSCRIBE | PTTL | PUBLISH |
+| PUBSUB | PUNSUBSCRIBE | RENAME | RENAMENX |
+| RESTORE | SADD | SCARD | SDIFF |
+| SDIFFSTORE | SET | SETEX | SETNX |
+| SETRANGE | SINTER | SINTERSTORE | SISMEMBER |
+| SMEMBERS | SMOVE | SPOP | SRANDMEMBER |
+| SREM | SSCAN **[3]** | STRLEN | SUBSCRIBE |
+| SUNION | SUNIONSTORE | TTL | TYPE |
+| UNSUBSCRIBE | QUIT | ZADD | ZCARD |
+| ZCOUNT | ZINCRBY | ZINTERSTORE | ZLEXCOUNT |
+| ZPOPMAX | ZPOPMIN | ZRANGE | ZRANGEBYLEX |
+| ZRANGEBYSCORE | ZRANK | ZREM | ZREMRANGEBYLEX |
+| ZREMRANGEBYRANK | ZREMRANGEBYSCORE | ZREVRANGE | ZREVRANGEBYLEX |
+| ZREVRANGEBYSCORE | ZREVRANK | ZSCAN **[3]** | ZSCORE |
+| ZUNIONSTORE ||||
- - total_net_input_bytes
- - instantaneous_input_kbps
+Commands not listed above are **not implemented**.
- - total_connections_received
+**NOTES:**
- - keyspace_hits
+These commands are supported for Redis 5.
+
+**[1]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT.
- - keyspace_misses
+**[2]** COMMAND is implemented only with no subcommands.
- - evicted_keys (always returns 0)
+**[3]** Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers
+(+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. <%=vars.product_name%> for Redis matches
+native Redis's behavior for COUNT, but only supports values of +/- the capacity of a signed 64-bit
+integer (+/- 9223372036854775807) for CURSOR.
- - rejected_connections (always returns 0)
+**[4]** INFO is implemented for the sections and fields listed below:
-**[3]** SLOWLOG is implemented as a NoOp.
+| INFO section | Field(s) |
+|--------------|----------|
+| clients | connected_clients<br/>blocked_clients (always returns 0) |
+| cluster | cluster_enables (always returns 1) |
+| keyspace | db0:keys<br/>expires (always returns 0)<br/>avg_ttl (always returns 0)<br/> |
+| memory | maxmemory<br/>used_memory<br/>mem_fragmentation_ratio |
+| persistence | loading (always returns 0)<br/>rdb_changes_since_last_save (always returns 0)<br/>rdb_last_save_time (always returns 0) |
+| replication | role (always returns "master")<br/>connected_slaves (always returns 0) |
+| server | redis_version<br/>redis_mode (always returns "cluster" because <%=vars.product_name%> for Redis always runs in cluster mode.)<br/>tcp_port<br/>uptime_in_seconds<br/>uptime_in_days |
+| stats | total_commands_processed<br/>instantaneous_ops_per_sec<br/>total_net_input_bytes<br/>instantaneous_input_kbps<br/>total_connections_received<br/>keyspace_hits<br/>keyspace_misses<br/>evicted_keys (always returns 0)<br/>rejected_connections (always returns 0)<br/>pubsub_channels<br/>pubsub_patterns|
-## <a id="advantages-over-redis" class="no-quick-link"></a>Advantages of <%=vars.product_name%> over Redis
+## <a id="advantages-over-redis"></a>Advantages of <%=vars.product_name%> over Redis
<%=vars.product_name%>’s primary advantage is its **scalability**. While the Redis server is single threaded, <%=vars.product_name%> supports high concurrency. Many Redis clients can execute commands on the <%=vars.product_name%> cluster simultaneously.
<%=vars.product_name%>'s architecture and management features help detect and resolve **network partitioning** problems without explicit management on the part of the Redis client.
-## <a id="expiration-accuracy" class="no-quick-link"></a>Expiration Accuracy
+<%=vars.product_name%> for Redis partitions data across multiple servers and keeps replicated data up to date _synchronously_, whereas Redis uses asynchronous replication.
+This provides a higher level of data consistency within the cluster.
+
+## <a id="expiration-accuracy"></a>Expiration Accuracy
Keys are expired in two ways, actively and passively:
- With active expiration, expiration is evaluated whenever a key is accessed. If the key is due to expire, it is deleted. Active expiration is accurate to the millisecond.
-- With passive expiration, keys are evaluated every second. If they are due to expire, they are deleted. Passive expiration is accurate to the second.
+- With passive expiration, keys are evaluated every three seconds. If they are due to expire, they are deleted. Passive expiration is accurate to the second.
Review comment:
This should be "every three minutes"
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,160 +25,320 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
+1. **Install Geode** \
+ Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install Geode.
+2. **Install the Redis CLI** \
+ Follow installation instructions at https://redis.io/download
+
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
+```commandLine
+gfsh> start locator
+```
+
+Use `gfsh` to start at least one server with a command of the form:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
+
+More information about the options when starting a server is given in the section [Start Server Options](#start-server-options).
+Note that `gfsh` suppots tab completion which can help with long option names.
+
+To confirm the server is listening, in a separate terminal run:
+
+```commandLine
+> redis-cli -c ping
+```
+
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
+
+If the server is functioning properly, you should see a response of `PONG`.
+
+### <a name="adding-a-server"></a> Add an additional Geode server compatible with Redis APIs
+If you’re interested in testing Geode scalability, in gfsh run the `start server` command again.
+
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
+
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
+
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
+
+### <a name="shutting-down"></a>Shutting Down
+To shut down the Geode cluster you started, in the terminal with gfsh running type the following command
+
+```commandLine
+gfsh> shutdown --include-locators=true
+```
+
+This command shuts down the entire Geode cluster. You are prompted with the following choice:
+
+```commandline
+As a lot of data in memory will be lost, including possibly events in queues, do you really want to shutdown the entire distributed system? (Y/n)
+```
+
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
+
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
+
+## <a name="start-server-options"></a>Start Server Options
+
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
+
+### `gemfire.geode-for-redis-enabled` (Default: `false`)
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
+
+### `gemfire.geode-for-redis-port` (Default: `6379`)
+Specifies the port on which the <%=vars.product_name%> server
+listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379
+(i.e. the same port that native Redis uses).
+
+### `gemfire.geode-for-redis-bind-address` (Default: `""`)
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
+
+### `gemfire.geode-for-redis-username` (Default: `"default"`)
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
+
+### `gemfire.geode-for-redis-redundant-copies` (Default: `1`)
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a Geode partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute.
+This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
+
+## <a name="security"></a>Security
+
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
+
+When using Apache Geode, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
+
+The following gfsh command will configure a `SimpleSecurityManager`:
+
+```console
+gfsh> start server \
--name=<serverName> \
--locators=<locatorPort> \
--J=-Dgemfire.geode-for-redis-enabled=true \
--J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
```
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+To confirm that the server is working, in a separate terminal run:
-Replace `<serverName>` with the name of your server.
+```console
+$> redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
+
+The `SimpleSecurityManager` is only to be used **for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
-Replace `<locatorPort>` with your locator port.
+Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. In this case, the Security Manager will need to respond to authentication requests using this username.
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured.
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+For information on configuring the cluster for SSL, see [Managing Security](../managing/security).
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+## <a name="application-development"></a>Application Development
-To confirm the server is listening, run:
+### Things to know before you begin
+- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands
+- Applications must be using a redis client that supports Redis Cluster mode.
+- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported).
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```java
+@Bean
+public static ConfigureRedisAction configureRedisAction() {
+ return ConfigureRedisAction.NO_OP;
+}
```
+This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc) that disable the CONFIG command for security reasons. You can read more about why this is done [here](https://github.com/spring-projects/spring-session/issues/124).
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+## <a name="redis-commands"></a>Redis Commands
-If the server is functioning properly, you should see a response of `PONG`.
+<%=vars.product_name%> for Redis supports the following Redis commands.
+
+- APPEND
+- AUTH
+- CLIENT
+- CLUSTER **[1]**
+- COMMAND **[2]**
+- DECR
+- DECRBY
+- DEL
+- DUMP
+- ECHO
+- EXISTS
+- EXPIRE
+- EXPIREAT
+- GET
+- GETRANGE
+- GETSET
+- HDEL
+- HEXISTS
+- HGET
+- HGETALL
+- HINCRBY
+- HINCRBYFLOAT
+- HKEYS
+- HLEN
+- HMGET
+- HMSET
+- HSCAN **[3]**
+- HSET
+- HSETNX
+- HSTRLEN
+- HVALS
+- INCR
+- INCRBY
+- INCRBYFLOAT
+- INFO **[4]**
+- KEYS
+- LOLWUT
+- MGET
+- MSET
+- MSETNX
+- PERSIST
+- PEXPIRE
+- PEXPIREAT
+- PING
+- PSETEX
+- PSUBSCRIBE
+- PTTL
+- PUBLISH
+- PUBSUB
+- PUNSUBSCRIBE
+- RENAME
+- RENAMENX
+- RESTORE
+- SADD
+- SCARD
+- SDIFF
+- SDIFFSTORE
+- SET
+- SETEX
+- SETNX
+- SETRANGE
+- SINTER
+- SINTERSTORE
+- SISMEMBER
+- SLOWLOG **[5]**
+- SMEMBERS
+- SMOVE
+- SPOP
+- SRANDMEMBER
+- SREM
+- SSCAN
+- STRLEN
+- SUBSCRIBE
+- SUNION
+- SUNIONSTORE
+- TTL
+- TYPE
+- UNSUBSCRIBE
+- QUIT
+- ZADD
+- ZCARD
+- ZCOUNT
+- ZINCRBY
+- ZINTERSTORE
+- ZLEXCOUNT
+- ZPOPMAX
+- ZPOPMIN
+- ZRANGE
+- ZRANGEBYLEX
+- ZRANGEBYSCORE
+- ZRANK
+- ZREM
+- ZREMRANGEBYLEX
+- ZREMRANGEBYRANK
+- ZREMRANGEBYSCORE
+- ZREVRANGE
+- ZREVRANGEBYLEX
+- ZREVRANGEBYSCORE
+- ZREVRANK
+- ZSCAN
+- ZSCORE
+- ZUNIONSTORE
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
Commands not listed above are **not implemented**.
-<br/>
**NOTES:**
These commands are supported for Redis 5.
+**[1]]** CLUSTER is implemented for the subcommands INFO, NODES, SLOTS, and KEYSLOT.
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+**[2]** COMMAND is implemented only with no subcommands.
-**[2]** INFO is implemented for the sections and fields listed below:
+**[3]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
+<%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
Review comment:
Well, I learned something new today!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790034749
##########
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:
[GEODE-9979](https://issues.apache.org/jira/browse/GEODE-9979)
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790035177
##########
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:
https://github.com/apache/geode/pull/7288
--
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
[GitHub] [geode] ezoerner removed a comment on pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner removed a comment on pull request #7274:
URL: https://github.com/apache/geode/pull/7274#issuecomment-1016983245
I incorporated those changes, but for some reason I'm unable to "resolve" the change request to allow this to be merged
--
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
[GitHub] [geode] ezoerner commented on pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on pull request #7274:
URL: https://github.com/apache/geode/pull/7274#issuecomment-1016955383
Preview link of built docs: https://geode-9883-review.sc2-04-pcf1-apps.oc.vmware.com/docs/guide/115/tools_modules/geode_for_redis.html
--
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
[GitHub] [geode] jdeppe-pivotal commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
jdeppe-pivotal commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790983742
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
Review comment:
When using a SecurityManager, (and cluster configuration is enabled), only the locator should be configured with the `security-manager` option. Any started servers will be handed the security manager name. This is to prevent any misconfiguration. If the server is started on it's own, it can be configured with a SecurityManager.
Examples using the `SimpleSecurityManager` should probably specify an exact username since the username will also be used to determine the authorization allowed. So a username/password of `foo/foo` will authenticate but not authorize. The username/password would have to be `data/data` to authorize both read and write operations.
I think this section needs to be expanded to explain the authorization permissions required when using a Security Manager. Doesn't need to be much and we can link to the official SecurityManager pages. Maybe something like:
> In addition to authentication, each command is authorized according to GemFire's security model (https://gemfire.docs.pivotal.io/910/geode/managing/security/implementing_authorization.html). Commands are divided into Read operations and Write operations for which the resource permissions `DATA:READ:GEODE_FOR_REDIS` and `DATA:WRITE:GEODE_FOR_REDIS` are respectively required.
--
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
[GitHub] [geode] jomartin-999 commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
jomartin-999 commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r788951462
##########
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:
The initial idea behind this image was to show that the Redis region is separated from the normal Geode regions and connects via a separate bind address and port. Open to ideas on how to improve the image to show this.
--
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
[GitHub] [geode] DonalEvans commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r788975505
##########
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:
I was thinking that an image similar in style to the one at the bottom of [this page](https://geode.apache.org/docs/guide/114/developing/partitioned_regions/how_pr_ha_works.html) would be more helpful. You could have three members shown, two regions (the geode for redis region and some non-redis region) and two clients connected, one redis client and one geode client.
--
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
[GitHub] [geode] jdeppe-pivotal commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
jdeppe-pivotal commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790983742
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
Review comment:
When using a SecurityManager, (and cluster configuration is enabled), only the locator should be configured with the `security-manager` option. Any started servers will be handed the security manager name. This is to prevent any misconfiguration. If the server is started on it's own, it can be configured with a SecurityManager.
Examples using the `SimpleSecurityManager` should probably specify an exact username since the username will also be used to determine the authorization allowed. So a username/password of `foo/foo` will authenticate but not authorize. The username/password would have to be `data/data` to authorize both read and write operations.
I think this section needs to be expanded to explain the authorization permissions required when using a Security Manager. Doesn't need to be much and we can link to the official SecurityManager pages. Maybe something like:
> In addition to authentication, each command is authorized according to GemFire's security model (https://gemfire.docs.pivotal.io/910/geode/managing/security/implementing_authorization.html). Commands are divided into Read operations and Write operations for which the resource permissions `DATA:READ:GEODE_FOR_REDIS` and `DATA:WRITE:GEODE_FOR_REDIS` are respectively required.
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r793028225
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
Review comment:
I removed the example and replaced it with a link to the Implementing Authentication page.
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r792886027
##########
File path: geode-docs/tools_modules/geode_for_redis.html.md.erb
##########
@@ -25,215 +25,243 @@ optional password authentication.
<img src="../images_svg/geode_for_redis.svg" class="image" />
-## <a id="using-the-api" class="no-quick-link"></a>Using <%=vars.product_name%> for Redis
+## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis
The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands.
-Use gfsh to start at least one server with a command of the form:
+Prerequisites for running the examples:
-```pre
-start server \
- --name=<serverName> \
- --locators=<locatorPort> \
- --J=-Dgemfire.geode-for-redis-enabled=true \
- --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
- --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress>
-```
-
-If the gemfire property `geode-for-redis-enabled`, is set to `true`, a <%=vars.product_name%>
-server with <%=vars.product_name%> for Redis will be started.
+1. **Install <%=vars.product_name%>** <br/>
+Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>.
+2. **Install the Redis CLI** <br/>
+Follow installation instructions at https://redis.io/download
-Replace `<serverName>` with the name of your server.
+Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster:
-Replace `<locatorPort>` with your locator port.
+```commandLine
+gfsh> start locator
+```
-Replace `<geodeForRedisPort>` with the port that the <%=vars.product_name%> server
- listens on for Redis commands. The typical port used with a cluster compatible with Redis is 6379.
+Use `gfsh` to start at least one server with a command of the form:
-Replace `<geodeForRedisBindAddress>` with the address of the server host.
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6379
+```
-Replace `<geodeForRedisPassword>` with the password clients use to authenticate.
+More information about the options when starting a server is given in the section [Start Server Options](#redis-start-server-options) below.
-To confirm the server is listening, run:
+To confirm the server is listening, in a separate terminal run:
-``` pre
-redis-cli -h <geodeForRedisBindAddress> -p <geodeForRedisPort> -a <geodeForRedisPassword> ping
+```commandLine
+$ redis-cli -c ping
```
-Replace `<geodeForRedisBindAddress>`,`<geodeForRedisPort>`, and `<geodeForRedisPassword>` with the same values as the server.
+The `-c` option enables cluster mode in the redis-cli, which is necessary since
+<%=vars.product_name%> for Redis runs as a Redis Cluster.
If the server is functioning properly, you should see a response of `PONG`.
-## <a id="supported-commands" class="no-quick-link"></a>Supported Redis Commands
+### <a id="adding-a-server"></a> Add an additional server
+If you’re interested in testing <%=vars.product_name%> scalability, in gfsh run the `start server` command again.
-<%=vars.product_name%> for Redis supports the following Redis commands.
-<br/>
-
- - APPEND <br/>
- - AUTH <br/>
- - DECR <br/>
- - DECRBY <br/>
- - DEL <br/>
- - EXISTS <br/>
- - EXPIRE <br/>
- - EXPIREAT <br/>
- - GET <br/>
- - GETRANGE <br/>
- - HDEL <br/>
- - HEXISTS <br/>
- - HGET <br/>
- - HGETALL <br/>
- - HINCRBY <br/>
- - HINCRBYFLOAT <br/>
- - HLEN <br/>
- - HMGET <br/>
- - HMSET <br/>
- - HSCAN **[1]** <br/>
- - HSET <br/>
- - HSETNX <br/>
- - HSTRLEN <br/>
- - HVALS <br/>
- - HKEYS <br/>
- - INCR <br/>
- - INCRBY <br/>
- - INCRBYFLOAT <br/>
- - INFO **[2]** <br/>
- - KEYS <br/>
- - MGET <br/>
- - PERSIST <br/>
- - PEXPIRE <br/>
- - PEXPIREAT <br/>
- - PING <br/>
- - PSUBSCRIBE <br/>
- - PTTL <br/>
- - PUBLISH <br/>
- - PUNSUBSCRIBE <br/>
- - QUIT <br/>
- - RENAME <br/>
- - SADD <br/>
- - SCARD <br/>
- - SDIFF <br/>
- - SDIFFSTORE <br/>
- - SINTER <br/>
- - SISMEMBER <br/>
- - SET <br/>
- - SETNX <br/>
- - SLOWLOG **[3]** <br/>
- - SMEMBERS <br/>
- - SMOVE <br/>
- - SRANDMEMBER <br/>
- - SREM <br/>
- - STRLEN <br/>
- - SUBSCRIBE <br/>
- - SUNION <br/>
- - SUNIONSTORE <br/>
- - TTL <br/>
- - TYPE <br/>
- - UNSUBSCRIBE <br/>
-
-<br/>
-Commands not listed above are **not implemented**.
+However, there are two ports that must be unique for each server in the cluster, the
+`gemfire.geode-for-redis-port`, used for receiving Redis commands, and the
+`server-port`, which is used for cluster communication.
-<br/>
-**NOTES:**
+The first server used `6379` for the redis port; we'll use `6380` for the second server.
-These commands are supported for Redis 5.
+The first server was started without
+a server port specified, so it used the default `40404`. To start up an additional server, you need to specify
+a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use
+an arbitrary available port for the server port.
+
+For example:
+
+```commandLine
+gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0
+```
-**[1]** Redis accepts 64-bit signed integers for the HSCAN cursor and COUNT parameters.
- <%=vars.product_name%> for Redis is limited to 32-bit integer values for these parameters.
+### <a id="shutting-down"></a>Shutting Down
+To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command
-**[2]** INFO is implemented for the sections and fields listed below:
+```commandLine
+gfsh> shutdown --include-locators=true
+```
- - clients
+This command shuts down the entire <%=vars.product_name%> cluster.
- - connected_clients
+To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message:
- - blocked_clients (always returns 0)
+```commandline
+Could not connect to Redis at 127.0.0.1:6379: Connection refused
+```
- - cluster
+## <a id="redis-start-server-options"></a>Start Server Options
- - cluster_enables (always returns 0)
+The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below.
+For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A).
- - keyspace
+`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/>
+If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started.
- - returns stats for db: 0
+`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/>
+Specifies the port on which the <%=vars.product_name%> server
+listens for Redis commands. Note that the default port `6379` is the same port that native Redis
+uses by default.
- - memory
+`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/>
+Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the
+empty string or if not specified, the server listens on all local addresses.
- - maxmemory
+`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/>
+Specifies the default username that the server uses when a client attempts to authenticate using
+only a password. See section on [Security](#security) for more information.
- - used_memory
+`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/>
+Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in
+the cluster. A value of 0 means no extra copies of data will be stored in the cluster.
+Note that extra servers need to be running for redundant copies to be made. For
+example if the cluster only has one server then no redundant copies will exist no matter what the
+value of this property is. Also note that <%=vars.product_name%> for Redis uses a <%=vars.product_name%> partitioned region
+to implement redundant copies and this property corresponds to the partitioned region's
+"redundant-copies" attribute. This property must be set the same on every server in the cluster that is running a
+<%=vars.product_name%> for Redis server.
- - mem_fragmentation_ratio (always reports 1.00)
+## <a id="security"></a>Security
- - persistence
+Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file.
- - loading (always returns 0)
+When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. Users can set a custom `default` username using the `geode-for-redis-username` parameter. This username will be used when `AUTH <password>` commands are sent without a `<username>`.
- - rdb_changes_since_last_save (always returns 0)
+The following gfsh command configures a `SimpleSecurityManager`:
- - rdb_last_save_time (always returns 0)
+```console
+gfsh> start server \
+ --name=<serverName> \
+ --locators=<locatorPort> \
+ --J=-Dgemfire.geode-for-redis-enabled=true \
+ --J=-Dgemfire.geode-for-redis-port=<geodeForRedisPort> \
+ --J=-Dgemfire.geode-for-redis-bind-address=<geodeForRedisBindAddress> \
+ --J=-Dgemfire.geode-for-redis-username=<geodeForRedisUsername> \
+ --J=-Dgemfire.security-manager=org.apache.geode.examples.SimpleSecurityManager
+```
- - replication
+To confirm that the server is working, in a separate terminal run:
- - role
+```console
+$ redis-cli -c -h <geodeForRedisBindAddress> -p <geodeForRedisPort> \
+ --user <geodeForRedisUsername> -a <geodeForRedisUsername> ping
+```
- - connected_slaves (always returns 0)
+The `SimpleSecurityManager` is to be used **only for demonstration purposes**. It will authenticate successfully when the `password` and `username` are the same.
Review comment:
I've added your blurb but I'm not sure how to address your concern about specifying an exact username or the `foo/foo` / `data/data` thing. Please take a look at the latest revision and see what you think.
--
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
[GitHub] [geode] ezoerner commented on pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on pull request #7274:
URL: https://github.com/apache/geode/pull/7274#issuecomment-1016983245
I incorporated those changes, but for some reason I'm unable to "resolve" the request changes to allow this to be merged
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790034196
##########
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:
Is this ok?
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r789890841
##########
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:
@nonbinaryprogrammer Hale started working on updating this image and said they were going to open a ticket for it
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r789890841
##########
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:
@nonbinaryprogrammer started working on updating this image and said they were going to open a ticket for it
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790034749
##########
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:
GEODE-9979
--
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
[GitHub] [geode] jomartin-999 commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
jomartin-999 commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r788951462
##########
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:
The initial idea behind this image was to show that the Redis region is separated from the normal Geode regions and connects via a separate bind address and port. Open to ideas on how to improve the image to show this. Also okay if we decide to remove it.
--
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
[GitHub] [geode] DonalEvans merged pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
DonalEvans merged pull request #7274:
URL: https://github.com/apache/geode/pull/7274
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790038252
##########
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:
I changed it to just "Add an additional server". Is this ok?
--
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
[GitHub] [geode] ezoerner commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
Posted by GitBox <gi...@apache.org>.
ezoerner commented on a change in pull request #7274:
URL: https://github.com/apache/geode/pull/7274#discussion_r790033691
##########
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:
I changed this to.
Specifies the port on which the Geode server listens for Redis commands. Note that the default port `6379` is the same port that native Redis uses by default.
##########
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:
I changed this to:
Specifies the port on which the Geode server listens for Redis commands. Note that the default port `6379` is the same port that native Redis uses by default.
--
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