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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
