| --- |
| title: Tutorial—Creating and Using a Cluster Configuration |
| --- |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| A short walk-through that uses a single computer to demonstrate how to use `gfsh` to create a cluster configuration for a <%=vars.product_name%> cluster. |
| |
| The `gfsh` command-line tool allows you to configure and start a <%=vars.product_name%> cluster. The cluster configuration service uses <%=vars.product_name_long%> locators to store the configuration at the group and cluster levels and serves these configurations to new members as they are started. The locators store the configurations in a hidden region that is available to all locators and also write the configuration data to disk as XML files. Configuration data is updated as `gfsh` commands are executed. |
| |
| This section provides a walk-through example of configuring a simple <%=vars.product_name_long%> cluster and then re-using that configuration in a new context. |
| |
| 1. Create a working directory (For example:`/home/username/my_geode`) and switch to the new directory. This directory will contain the configurations for your cluster. |
| |
| 2. Start the `gfsh` command-line tool. For example: |
| |
| ``` pre |
| $ gfsh |
| ``` |
| |
| The `gfsh` command prompt displays. |
| |
| ``` pre |
| _________________________ __ |
| / _____/ ______/ ______/ /____/ / |
| / / __/ /___ /_____ / _____ / |
| / /__/ / ____/ _____/ / / / / |
| /______/_/ /______/_/ /_/ <%=vars.product_version%> |
| |
| Monitor and Manage <%=vars.product_name_long%> |
| gfsh> |
| |
| ``` |
| |
| 3. Start a locator using the command in the following example: |
| |
| ``` pre |
| gfsh>start locator --name=locator1 |
| Starting a <%=vars.product_name%> Locator in /Users/username/my_geode/locator1... |
| ............................. |
| Locator in /Users/username/my_geode/locator1 on 192.0.2.0[10334] as locator1 |
| is currently online. |
| Process ID: 5203 |
| Uptime: 15 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/my_geode/locator1/locator1.log |
| JVM Arguments: -Dgemfire.enable-cluster-configuration=true |
| -Dgemfire.load-cluster-configuration-from-dir=false |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| |
| Successfully connected to: [host=192.0.2.0, port=1099] |
| |
| Cluster configuration service is up and running. |
| ``` |
| |
| Note that `gfsh` responds with a message indicating that the cluster configuration service is up and running. If you see a message indicating a problem, review the locator log file for possible errors. The path to the log file is displayed in the output from `gfsh`. |
| |
| 4. Start <%=vars.product_name_long%> servers using the commands in the following example: |
| |
| ``` pre |
| gfsh>start server --name=server1 --groups=group1 |
| Starting a <%=vars.product_name%> Server in /Users/username/my_geode/server1... |
| ..... |
| Server in /Users/username/my_geode/server1 on 192.0.2.0[40404] as server1 |
| is currently online. |
| Process ID: 5627 |
| Uptime: 2 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/my_geode/server1/server1.log |
| JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334] -Dgemfire.groups=group1 |
| -Dgemfire.use-cluster-configuration=true -XX:OnOutOfMemoryError=kill -KILL %p |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| |
| gfsh>start server --name=server2 --groups=group1 --server-port=40405 |
| Starting a <%=vars.product_name%> Server in /Users/username/my_geode/server2... |
| ..... |
| Server in /Users/username/my_geode/server2 on 192.0.2.0[40405] as server2 |
| is currently online. |
| Process ID: 5634 |
| Uptime: 2 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/my_geode/server2/server2.log |
| JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334] -Dgemfire.groups=group1 |
| -Dgemfire.use-cluster-configuration=true -XX:OnOutOfMemoryError=kill -KILL %p |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| |
| gfsh>start server --name=server3 --server-port=40406 |
| Starting a <%=vars.product_name%> Server in /Users/username/my_geode/server3... |
| ..... |
| Server in /Users/username/my_geode/server3 on 192.0.2.0[40406] as server3 |
| is currently online. |
| Process ID: 5637 |
| Uptime: 2 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/my_geode/server3/server3.log |
| JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334] |
| -Dgemfire.use-cluster-configuration=true -XX:OnOutOfMemoryError=kill -KILL %p |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| ``` |
| |
| Note that the `gfsh` commands you used to start `server1` and `server2` specify a group named `group1` while the command for `server3` did not specify a group name. |
| |
| 5. Create some regions using the commands in the following example: |
| |
| ``` pre |
| gfsh>create region --name=region1 --groups=group1 --type=REPLICATE |
| Member | Status |
| ------- | -------------------------------------- |
| server2 | Region "/region1" created on "server2" |
| server1 | Region "/region1" created on "server1" |
| |
| gfsh>create region --name=region2 --type=REPLICATE |
| Member | Status |
| ------- | -------------------------------------- |
| server1 | Region "/region2" created on "server1" |
| server2 | Region "/region2" created on "server2" |
| server3 | Region "/region2" created on "server3" |
| ``` |
| |
| Note that `region1` is created on all cache servers that specified the group named `group1` when starting the cache server (`server1` and `server2`, in this example). `region2` is created on all members because no group was specified. |
| |
| 6. Deploy jar files. Use the `gfsh deploy` command to deploy application jar files to all members or to a specified group of members. The following example deploys the `mx4j-3.0.1.jar` and `ra.jar` files from the distribution. (Note: This is only an example, you do not need to deploy these files to use the Cluster Configuration Service. Alternately, you can use any two jar files for this demonstration.) |
| |
| ``` pre |
| gfsh>deploy --groups=group1 --jars=/lib/mx4j-3.0.1.jar |
| Post substitution: deploy --groups=group1 --jars=/Users/username/Apache_Geode_1.0.0_Linux/lib/mx4j-3.0.1.jar |
| Member | Deployed JAR | Deployed JAR Location |
| ------- | ------------------ | ------------------------------------------------------- |
| server1 | mx4j-3.0.1.jar | /Users/username/my_geode/server1/vf.gf#mx4j-3.0.1.jar#1 |
| server2 | mx4j-3.0.1.jar | /Users/username/my_geode/server2/vf.gf#mx4j-3.0.1.jar#1 |
| |
| gfsh>deploy --jars=/lib/ra.jar |
| Post substitution: deploy --jar=/Users/username/Apache_Geode_1.0.0_Linux/lib/ra.jar |
| Member | Deployed JAR | Deployed JAR Location |
| ------- | ------------ | ----------------------------------------------- |
| server1 | ra.jar | /Users/username/my_geode/server1/vf.gf#ra.jar#1 |
| server2 | ra.jar | /Users/username/my_geode/server1/vf.gf#ra.jar#1 |
| server3 | ra.jar | /Users/username/my_geode/server1/vf.gf#ra.jar#1 |
| ``` |
| |
| Note that the `mx4j-3.0.1.jar` file was deployed only to the members of `group1` and the `ra.jar` was deployed to all members. |
| |
| 7. Export the cluster configuration. |
| You can use the `gfsh export cluster-configuration` command to create a zip file that contains the cluster's persisted configuration. The zip file contains a copy of the contents of the `cluster_config` directory. For example: |
| |
| ``` pre |
| gfsh>export cluster-configuration --zip-file-name=/Users/username/myClConfig.zip |
| ``` |
| |
| <%=vars.product_name_long%> writes the cluster configuration to the specified zip file. |
| |
| ``` pre |
| Downloading cluster configuration : /Users/username/myClConfig.zip |
| ``` |
| |
| The remaining steps demonstrate how to use the cluster configuration you just created. |
| |
| 8. Shut down the cluster using the following commands: |
| |
| ``` pre |
| gfsh>shutdown --include-locators=true |
| 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): Y |
| Shutdown is triggered |
| |
| gfsh> |
| No longer connected to 192.0.2.0[1099]. |
| gfsh> |
| ``` |
| |
| 9. Exit the `gfsh` command shell: |
| |
| ``` pre |
| gfsh>quit |
| Exiting... |
| ``` |
| |
| 10. Create a new working directory (for example: `new_geode`) and switch to the new directory. |
| 11. Start the `gfsh` command shell: |
| |
| ``` pre |
| $ gfsh |
| ``` |
| |
| 12. Start a new locator. For example: |
| |
| ``` pre |
| gfsh>start locator --name=locator2 --port=10335 |
| Starting a <%=vars.product_name%> Locator in /Users/username/new_geode/locator2... |
| ............................. |
| Locator in /Users/username/new_geode/locator2 on 192.0.2.0[10335] as locator2 |
| is currently online. |
| Process ID: 5749 |
| Uptime: 15 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/new_geode/locator2/locator2.log |
| JVM Arguments: -Dgemfire.enable-cluster-configuration=true |
| -Dgemfire.load-cluster-configuration-from-dir=false |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| |
| Successfully connected to: [host=192.0.2.0, port=1099] |
| |
| Cluster configuration service is up and running. |
| ``` |
| |
| 13. Import the cluster configuration using the `import cluster-configuration` command. For example: |
| |
| ``` pre |
| gfsh>import cluster-configuration --zip-file-name=/Users/username/myClConfig.zip |
| Cluster configuration successfully imported |
| ``` |
| |
| Note that the `locator2` directory now contains a `cluster_config` subdirectory. |
| |
| 14. Start a server that does not reference a group: |
| |
| ``` pre |
| gfsh>start server --name=server4 --server-port=40414 |
| Starting a <%=vars.product_name%> Server in /Users/username/new_geode/server4... |
| ........ |
| Server in /Users/username/new_geode/server4 on 192.0.2.0[40414] as server4 |
| is currently online. |
| Process ID: 5813 |
| Uptime: 4 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/new_geode/server4/server4.log |
| JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10335] |
| -Dgemfire.use-cluster-configuration=true -XX:OnOutOfMemoryError=kill -KILL %p |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| ``` |
| |
| 15. Start another server that references `group1`: |
| |
| ``` pre |
| gfsh>start server --name=server5 --groups=group1 --server-port=40415 |
| Starting a <%=vars.product_name%> Server in /Users/username/new_geode/server5... |
| ..... |
| Server in /Users/username/new_geode/server2 on 192.0.2.0[40415] as server5 |
| is currently online. |
| Process ID: 5954 |
| Uptime: 2 seconds |
| <%=vars.product_name%> Version: <%=vars.product_version%> |
| Java Version: 1.<%=vars.min_java_version%>.0_<%=vars.min_java_update%> |
| Log File: /Users/username/new_geode/server5/server5.log |
| JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10335] -Dgemfire.groups=group1 |
| -Dgemfire.use-cluster-configuration=true -XX:OnOutOfMemoryError=kill -KILL %p |
| -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true |
| -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 |
| Class-Path: /Users/username/Apache_Geode_1.0.0_Linux/lib/geode-dependencies.jar |
| ``` |
| |
| 16. Use the `list regions` command to display the configured regions. Note that region1 and region2, which were configured in the original cluster level are available. |
| |
| ``` pre |
| gfsh>list regions |
| List of regions |
| --------------- |
| region1 |
| region2 |
| ``` |
| |
| 17. Use the `describe region` command to see which members host each region. Note that region1 is hosted only by server5 because server5 was started using the group1 configuration. region2 is hosted on both server4 and server5 because region2 was created without a group specified. |
| |
| ``` pre |
| gfsh>describe region --name=region1 |
| .......................................................... |
| Name : region1 |
| Data Policy : replicate |
| Hosting Members : server5 |
| |
| Non-Default Attributes Shared By Hosting Members |
| |
| Type | Name | Value |
| ------ | ----------- | --------------- |
| Region | data-policy | REPLICATE |
| | size | 0 |
| | scope | distributed-ack |
| |
| gfsh>describe region --name=region2 |
| .......................................................... |
| Name : region2 |
| Data Policy : replicate |
| Hosting Members : server5 |
| server4 |
| |
| Non-Default Attributes Shared By Hosting Members |
| |
| Type | Name | Value |
| ------ | ----------- | --------------- |
| Region | data-policy | REPLICATE |
| | size | 0 |
| | scope | distributed-ack |
| ``` |
| |
| This new cluster uses the same configuration as the original system. You can start any number of servers using this cluster configuration. All servers will receive the cluster-level configuration. Servers that specify `group1` also receive the `group1` configuration. |
| |
| 18. Shut down your cluster using the following commands: |
| |
| ``` pre |
| gfsh>shutdown --include-locators=true |
| 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): Y |
| Shutdown is triggered |
| |
| gfsh> |
| No longer connected to 192.0.2.0[1099]. |
| ``` |