---
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: 70919
    Uptime: 12 seconds
    <%=vars.product_name%> Version: <%=vars.product_version%>
    Java Version: <%=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/geode<%=vars.product_version_nodot%>/lib/geode-dependencies.jar

    Successfully connected to: JMX Manager [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: <%=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.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
    -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
    Class-Path: /Users/username/geode<%=vars.product_version_nodot%>/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: <%=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.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
    -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
    -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
    Class-Path: /Users/username/geode<%=vars.product_version_nodot%>/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: <%=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.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
    -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
    -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
    Class-Path: /Users/username/geode<%=vars.product_version_nodot%>/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 | Message
    ------- | ------ | --------------------------------------
    server1 | OK     | Region "/region1" created on "server1"
    server2 | OK     | Region "/region1" created on "server2"

    Cluster configuration for group 'group1' is updated.


    gfsh>create region --name=region2 --type=REPLICATE
    Member  | Status | Message
    ------- | ------ | --------------------------------------
    server1 | OK     | Region "/region2" created on "server1"
    server2 | OK     | Region "/region2" created on "server2"
    server3 | OK     | Region "/region2" created on "server3"

    Cluster configuration for group 'cluster' is updated.

    ```

    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.2.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.2.jar

    Deploying files: mx4j-3.0.2.jar
    Total file size is: 0.39MB

    Continue?  (Y/n): y
    Member  |  Deployed JAR  | Deployed JAR Location
    ------- | -------------- | ----------------------------------------------------------
    server1 | mx4j-3.0.2.jar | /Users/username/my_geode/server1/mx4j-3.0.2.v1.jar
    server2 | mx4j-3.0.2.jar | /Users/username/my_geode/server2/mx4j-3.0.2.v1.jar

    gfsh>deploy --jars=/lib/ra.jar

    Deploying files: ra.jar
    Total file size is: 0.03MB

    Continue?  (Y/n): y
    Member  | Deployed JAR | Deployed JAR Location
    ------- | ------------ | --------------------------------------------------
    server1 | ra.jar       | /Users/username/my_geode/server1/ra.v1.jar
    server2 | ra.jar       | /Users/username/my_geode/server2/ra.v1.jar
    server3 | ra.jar       | /Users/username/my_geode/server2/ra.v1.jar
    ```

    Note that the `mx4j-3.0.2.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
    File saved to /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: <%=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/geode<%=vars.product_version_nodot%>/lib/geode-dependencies.jar

    Successfully connected to: JMX Manager [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
    This command will replace the existing cluster configuration, if any, The old configuration will be backed up in the working directory.

    Continue?  (Y/n): y
    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: <%=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.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
    -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
    -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
    Class-Path: /Users/username/geode<%=vars.product_version_nodot%>/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: <%=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.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
    -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
    -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
    Class-Path: /Users/username/geode<%=vars.product_version_nodot%>/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].
    ```
