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/24 17:23:48 UTC
[GitHub] [geode] jdeppe-pivotal commented on a change in pull request #7274: GEODE-9883 Update Geode for Redis docs file
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