This is an automated email from the ASF dual-hosted git repository. kmiller pushed a commit to branch develop in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/develop by this push: new d118ea6 GEODE-3538 Update doc section Running Geode Server Processes (#945) d118ea6 is described below commit d118ea68b85b904b150095f73c15e4da8ea4734f Author: Karen Miller <karensmolermil...@users.noreply.github.com> AuthorDate: Wed Oct 18 16:22:20 2017 -0700 GEODE-3538 Update doc section Running Geode Server Processes (#945) * GEODE-3538 Update doc section Running Geode Server Processes Also corrected a typo and improved wording in the gfsh start server command reference page. * GEODE-3858 Spelling correction, requested in a review. --- .../running/running_the_cacheserver.html.md.erb | 121 +++++++++------------ .../gfsh/command-pages/start.html.md.erb | 2 +- 2 files changed, 52 insertions(+), 71 deletions(-) diff --git a/geode-docs/configuring/running/running_the_cacheserver.html.md.erb b/geode-docs/configuring/running/running_the_cacheserver.html.md.erb index 37d864f..b97be1a 100644 --- a/geode-docs/configuring/running/running_the_cacheserver.html.md.erb +++ b/geode-docs/configuring/running/running_the_cacheserver.html.md.erb @@ -22,24 +22,22 @@ A <%=vars.product_name%> server is a process that runs as a long-lived, configur <a id="running_the_cacheserver__section_6C2B495518C04064A181E7917CA81FC1"></a> The <%=vars.product_name%> server is used primarily for hosting long-lived data regions and for running standard <%=vars.product_name%> processes such as the server in a client/server configuration. You can start and stop servers using the following methods: -- The `gfsh` tool allows you to manage <%=vars.product_name%> server processes from the command line. -- You can also start, stop and manage the <%=vars.product_name%> servers through the `org.apache.geode.distributed.ServerLauncher` API. The `ServerLauncher` API can only be used for <%=vars.product_name%> Servers that were started with `gfsh` or with the `ServerLauncher` class itself. See the JavaDocs for additional specifics on using the `ServerLauncher` API. +- The `gfsh` command-line tool. +- Programmatically, through the `org.apache.geode.distributed.ServerLauncher` API. The `ServerLauncher` API can only be used for <%=vars.product_name%> Servers that were started with `gfsh` or with the `ServerLauncher` class itself. ## <a id="running_the_cacheserver__section_E15FB1B039CE4F6CB2E4B5618D7ECAA1" class="no-quick-link"></a>Default Server Configuration and Log Files The `gfsh` utility uses a working directory for its configuration files and log files. These are the defaults and configuration options: - When you start a standalone server using `gfsh`, `gfsh` will automatically load the required JAR file `lib/geode-dependencies.jar` into the CLASSPATH of the JVM process. If you start a standalone server using the ServerLauncher API, you must specify this JAR file inside your command to launch the process. For more information on CLASSPATH settings in <%=vars.product_name%>, see [Setting Up the CLASSPATH](../../getting_started/setup_classpath.html). -- Servers are configured like any other <%=vars.product_name%> process, with `gemfire.properties` and shared cluster configuration files. It is not programmable except through application plug-ins. Typically, you provide the `gemfire.properties` file and the `gfsecurity.properties` file (if you are using a separate, restricted access security settings file). You can also specify a `cache.xml` file in the cache server’s working directory. -- By default, a new server started with `gfsh` receives its initial cache configuration from the cluster configuration service, assuming the locator is running the cluster configuration service. If you specify a group when starting the server, the server also receives configurations that apply to a group. The shared configuration consists of `cache.xml` files, `gemfire.properties` files, and deployed jar files. You can disable use of the cluster configuration service by specifying `--u [...] +- Servers are configured like any other <%=vars.product_name%> process, with `gemfire.properties` and shared cluster configuration files. It is not programmable except through application plug-ins. Typically, you provide the `gemfire.properties` file and the `gfsecurity.properties` file. You can also specify a `cache.xml` file in the cache server’s working directory. +- By default, a new server started with `gfsh` receives its initial cache configuration from the cluster configuration service, assuming the locator is running the cluster configuration service. If you specify a group when starting the server, the server also receives configurations that apply to a group. The shared configuration consists of `cache.xml` files, `gemfire.properties` files, and deployed jar files. You can disable use of the cluster configuration service by specifying `--u [...] - See [Overview of the Cluster Configuration Service](../cluster_config/gfsh_persist.html#concept_r22_hyw_bl). - -- If you are using the Spring Framework, you can specify a Spring ApplicationContext XML file when starting up your server in `gfsh` by using the `--spring-xml-location` command-line option. This option allows you to bootstrap your <%=vars.product_name%> server process with your Spring application's configuration. See [Spring documentation](http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/resources.html#resources-app-ctx) for more information on this file. -- For logging output, log file output defaults to `server_name.log` in the cache server's working directory. If you restart a server with the same server name, the existing *server\_name*.log file is automatically renamed for you (for example, `server1-01-01.log` or `server1-02-01.log`). You can modify the level of logging details in this file by specifying a level in the `--log-level` argument when starting up the server. -- By default, the server will start in a subdirectory (named after the server's specified `--name`) under the directory where `gfsh` is executed. This subdirectory is considered the current working directory. You can also specify a different working directory when starting the cache server in `gfsh`. +- If you are using the Spring Framework, you can specify a Spring ApplicationContext XML file when starting up your server in `gfsh` by using the `--spring-xml-location` command-line option. This option allows you to bootstrap your <%=vars.product_name%> server process with your Spring application's configuration. See [Spring documentation](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/resources.html#resources-app-ctx) for more information on this file. +- For logging output, log file output defaults to `<server-name>.log` in the cache server's working directory. If you restart a server with the same server name, the existing log file is automatically renamed, for example, `server1-01-01.log` and `server1-02-01.log`. You can modify the level of logging details in this file by specifying a level in the `--log-level` argument when starting up the server. +- By default, the server will start in a subdirectory, named after the server's specified name, under the directory where `gfsh` is executed. This subdirectory is considered the current working directory. You can also specify a different working directory when starting the cache server in `gfsh`. - By default, a server process that has been shutdown and disconnected due to a network partition event or member unresponsiveness will restart itself and automatically try to reconnect to the existing distributed system. See [Handling Forced Cache Disconnection Using Autoreconnect](../../managing/member-reconnect.html#concept_22EE6DDE677F4E8CAF5786E17B4183A9) for more details. -- You can pass JVM parameters to the server's JVM by using the `--J=-Dproperty.name=value` upon server startup. These parameters can be Java properties or <%=vars.product_name%> configuration properties such as `gemfire.jmx-manager`. For example: +- You can pass JVM parameters to the server's JVM by using the `--J=-Dproperty.name=value` upon server startup. These parameters can be Java properties or <%=vars.product_name%> properties such as `gemfire.jmx-manager`. For example: ``` pre gfsh>start server --name=server1 --J=-Dgemfire.jmx-manager=true \ @@ -48,64 +46,45 @@ The `gfsh` utility uses a working directory for its configuration files and log - We recommend that you do not use the `-XX:+UseCompressedStrings` and `-XX:+UseStringCache` JVM configuration properties when starting up servers. These JVM options can cause issues with data corruption and compatibility. -## <a id="running_the_cacheserver__section_07001480D33745139C3707EDF8166D86" class="no-quick-link"></a>Start the Server - -The startup syntax for <%=vars.product_name%> servers in `gfsh` is: +## <a id="running_the_cacheserver__section_07001480D33745139C3707EDF8166D86" class="no-quick-link"></a>Start the Server with gfsh -``` pre -start server --name=value [--assign-buckets(=value)] [--bind-address=value] - [--cache-xml-file=value] [--classpath=value] [--disable-default-server(=value)] - [--disable-exit-when-out-of-memory(=value)] [--enable-time-statistics(=value)] - [--force(=value)] [--include-system-classpath(=value)] [--properties-file=value] - [--security-properties-file=value] - [--group=value] [--locators=value] [--locator-wait-time=value] [--log-level=value] - [--mcast-address=value] [--mcast-port=value] [--memcached-port=value] - [--memcached-protocol=value] [--rebalance(=value)] [--server-bind-address=value] - [--server-port=value] [--spring-xml-location=value] - [--statistic-archive-file=value] [--dir=value] [--initial-heap=value] - [--max-heap=value] [--use-cluster-configuration(=value)] [--J=value(,value)*] - [--critical-heap-percentage=value] [--critical-off-heap-percentage=value] - [--eviction-heap-percentage=value] [--eviction-off-heap-percentage=value] - [--hostname-for-clients=value] [--max-connections=value] - [--message-time-to-live=value] [--max-message-count=value] [--max-threads=value] - [--socket-buffer-size=value] [--lock-memory=value] [--off-heap-memory-size=value] -``` +See the [`gfsh start server`](../../tools_modules/gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A) command reference page for syntax information. -**Note:** -When both `--max-heap` and `--initial-heap` are specified during server startup, additional GC parameters are specified internally by <%=vars.product_name%>'s Resource Manager. If you do not want the additional default GC properties set by the Resource Manager, then use the `-Xms` & `-Xmx` JVM options. See [Controlling Heap Use with the Resource Manager](../../managing/heap_use/heap_management.html#configuring_resource_manager) for more information. - -The following `gfsh start server` start sequences specify a `cache.xml` file for cache configuration, and use different incoming client connection ports: +These example `gfsh start server` start commands specify a `cache.xml` file for cache configuration, and use different incoming client connection ports: ``` pre -gfsh>start server --name=server1 --mcast-port=10338 \ +gfsh>start server --name=server1 \ --cache-xml-file=../ServerConfigs/cache.xml --server-port=40404 -gfsh>start server --name=server2 --mcast-port=10338 \ +gfsh>start server --name=server2 \ --cache-xml-file=../ServerConfigs/cache.xml --server-port=40405 ``` -Here is a portion of a `gemfire.properties` file that sets the location of a`cache.xml` file for the server and sets the mcast-port: - -``` pre -mcast-port=10338 -cache-xml-file=D:\gfeserver\cacheCS.xml -``` - -To start the server using this `gemfire.properties` file, enter: +The location of the `cache.xml` file and the setting for the client +connection port could instead be defined within a +`gemfire.properties` file. +Then, start the server specifying the `gemfire.properties` file, +as in the example command: ``` pre gfsh>start server --name=server1 \ ---properties-file=D:\gfeserver\gemfire.properties +--properties-file=/home/username/cluster/gemfire.properties ``` -To start a server with an embedded JMX Manager, you can enter the following command: +To start a server with an embedded JMX Manager: ``` pre gfsh>start server --name=server2 \ --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true ``` -To start a server and provide JVM configuration settings, you can issue a command like the following: +When both `--max-heap` and `--initial-heap` are specified during +server startup, +additional GC parameters are specified on your behalf. +If you do not want additional default GC properties set, +then use the `-Xms` & `-Xmx` JVM options to set just these parameters. +See [Controlling Heap Use with the Resource Manager](../../managing/heap_use/heap_management.html#configuring_resource_manager) for more information. +To start a server, providing JVM configuration settings: ``` pre gfsh>start server --name=server3 \ @@ -114,7 +93,12 @@ gfsh>start server --name=server3 \ ## Start the Server Programmatically -Use `org.apache.geode.distributed.ServerLauncher` API to start the cache server process inside your code. Use the `ServerLauncher.Builder` class to construct an instance of the `ServerLauncher`, and then use the `start()` method to start the server service. The other methods in the `ServerLauncher` class provide status information about the server and allow you to stop the server. +Use the `org.apache.geode.distributed.ServerLauncher` API to start the cache +server process inside your code. +Use the `ServerLauncher.Builder` class to construct an instance of +the `ServerLauncher`, +and then use the `start()` method to start the server service. +The other methods in the `ServerLauncher` class provide status information about the server and allow you to stop the server. ``` pre import org.apache.geode.distributed.ServerLauncher; @@ -124,21 +108,22 @@ import org.apache.geode.distributed.ServerLauncher; public static void main(String[] args){ ServerLauncher serverLauncher = new ServerLauncher.Builder() .setMemberName("server1") - .setServerPort(40405) + .setServerPort(40405) .set("jmx-manager", "true") .set("jmx-manager-start", "true") .build(); - serverLauncher.start(); + serverLauncher.start(); - System.out.println("Cache server successfully started"); - } + System.out.println("Cache server successfully started"); } +} ``` ## <a id="running_the_cacheserver__section_F58F229D5C7048E9915E0EC470F9A923" class="no-quick-link"></a>Check Server Status -If you are connected to the distributed system in `gfsh`, you can check the status of a running cache server by providing the server name. For example: +Once connected to the distributed system in `gfsh`, +check the status of a running cache server by providing the server name: ``` pre gfsh>status server --name=server1 @@ -153,34 +138,32 @@ gfsh>status server --pid=2484 or ``` pre -% gfsh status server --dir=<server_working_directory> +% gfsh status server --dir=server1 ``` -where <*server\_working\_directory*> corresponds to the local working directory where the cache server is running. - -If successful, the command returns the following information (with the JVM arguments that were provided at startup): +If successful, the output provides information as in this sample: ``` pre % gfsh status server --dir=server4 -Server in /home/user/server4 on ubuntu.local[40404] as server4 is currently online. -Process ID: 3324 -Uptime: 1 minute 5 seconds -GemFire Version: 8.0.0 -Java Version: 1.7.0_65 -Log File: /home/user/server4/server4.log +Server in /home/username/server4 on 192.0.2.0[40404] as server4 is currently online. +Process ID: 49008 +Uptime: 2 minutes 4 seconds +<%=vars.product_name %> Version: <%=vars.product_version %> +Java Version: 1.8.0_144 +Log File: /home/username/server4/server4.log JVM Arguments: ... ``` ## <a id="running_the_cacheserver__section_0E4DDED6AB784B0CAFBAD538B227F487" class="no-quick-link"></a>Stop Server -If you are connected to the distributed system in `gfsh`, you can stop a running cache server by providing the server name. For example: +When connected to the distributed system in `gfsh`, stop a running cache server by providing the server name: ``` pre gfsh>stop server --name=server1 ``` -If you are not connected to a distributed system, you can stop a local cache server by specify the server's current working directory or the process ID. For example: +If not connected, you can stop a local cache server by specify the server's current working directory or the process ID. For example: ``` pre gfsh>stop server --pid=2484 @@ -189,9 +172,7 @@ gfsh>stop server --pid=2484 or ``` pre -gfsh>stop server --dir=<server_working_directory> +gfsh>stop server --dir=server1 ``` -where <*server\_working\_directory*> corresponds to the local working directory where the cache server is running. - -You can also use the `gfsh` `shutdown` command to shut down all cache servers in an orderly fashion. This is useful if you are using persistent regions. See [Starting Up and Shutting Down Your System](starting_up_shutting_down.html) for more details. +You can also use the `gfsh shutdown` command to shut down all cache servers in an orderly fashion. Doing a `shutdown` is the correct approach for systems with persistent regions. See [Starting Up and Shutting Down Your System](starting_up_shutting_down.html) for more details. diff --git a/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb b/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb index 28a76b7..f0883a4 100644 --- a/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb +++ b/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb @@ -455,7 +455,7 @@ start pulse --url=http://gemfire.example.com:7070/pulse Start a <%=vars.product_name%> cache server process. -**Note:** When both <span class="keyword parmname">\\-\\-max-heap</span> and <span class="keyword parmname">\\-\\-initial-heap</span> are specified during locator startup, additional GC parameters are specified internally by <%=vars.product_name%>'s Resource Manager. If you do not want the additional default GC properties set by the Resource Manager, then use the `-Xms` and `-Xmx` JVM options. See [Controlling Heap Use with the Resource Manager](../../../managing/heap_use/heap_management [...] +**Note:** When both <span class="keyword parmname">\\-\\-max-heap</span> and <span class="keyword parmname">\\-\\-initial-heap</span> are specified during server startup, additional GC parameters are specified on your behalf. If you do not want the additional default GC properties set, then use the `-Xms` and `-Xmx` JVM options to set just these parameters. See [Controlling Heap Use with the Resource Manager](../../../managing/heap_use/heap_management.html#configuring_resource_manager) f [...] **Availability:** Online or offline. -- To stop receiving notification emails like this one, please contact ['"commits@geode.apache.org" <commits@geode.apache.org>'].