This topic describes the alter command in gfsh, the VMware Tanzu GemFire command-line interface.
Use this command to modify an existing VMware Tanzu GemFire resource.
-
Modifies attributes of an async event queue
-
Modifies or removes a region from an offline disk-store.
-
Modifies attributes of a gateway-sender.
-
Alter configuration details of the query configuration service.
-
Alters the configuration of a region.
-
Alters configuration properties for all members or a subset of members while the member or members are running.
alter async-event-queue
Alter attributes of a specified asynchronous event queue. Each server hosting the specified async event queue must be restarted for the new attribute settings to take effect on that server.
Availability: Online. You must be connected in gfsh to a JMX Manager member to use this command.
Syntax:
alter async-event-queue --id=value [--batch-size=value] [--batch-time-interval=value]
[--max-queue-memory=value] [--if-exists(=value)] [--pause-event-processing(=value)]
The required option, --id, identifies the async event queue to be altered.
Parameters, alter async-event-queue
| Name | Description |
|---|---|
| ‑‑id | Required. ID of the async event queue to be changed |
| ‑‑batch‑size | Maximum number of events that a batch can contain |
| ‑‑batch‑time‑interval | Maximum amount of time, in ms, that can elapse before a batch is delivered |
| ‑‑max‑queue‑memory | Maximum amount of memory, in megabytes, that the queue can consume before overflowing to disk |
| ‑‑if‑exists | If the specified async event queue does not exist, gfsh responds with a message to that effect. If this parameter is true, the response is prefixed with the label "Skipping: ". Useful for scripted tests. Default if the parameter is not specified: false. Default (if the parameter is specified without value): true. |
| ‑‑pause‑event‑processing | Specifies whether event dispatching from the queue to the listeners will be paused when the AsyncEventQueue is started. Default if the parameter is not specified: false. Default if the parameter is specified without value: true. |
Example Commands:
alter async-event-queue --id=myAsyncEventQueue --batch-size=50 --if-exists
alter disk-store
Modify or remove a region from an offline disk-store.
When modifying a region’s configuration, it is customary to take the region off-line and restart using the new configuration. You can use the alter disk-store command to change the configuration of the region stored in the disk-store to match the configuration you will use at restart.
Availability: Offline.
Syntax:
alter disk-store --name=value --region=value --disk-dirs=value(,value)*
[--compressor(=value)] [--concurrency-level=value]
[--enable-statistics=value] [--initial-capacity=value] [--load-factor=value]
[--lru-algorithm=value] [--lru-action=value] [--lru-limit=value]
[--off-heap(=value)] [--remove(=value)]
The three required options, --name, --region, and --disk-dirs, identify the disk store and region to be altered. If no additional options are specified, gfsh displays the current configuration without making any changes.
Parameters, alter disk-store
| Name | Description |
|---|---|
| ‑‑name | Required. Name of the disk-store whose contents will be altered. |
| ‑‑region | Required. Name (including path) of the region using the disk store. |
| ‑‑disk-dirs | Required. Directories where the data for the disk store was previously written. |
| ‑‑compressor | The fully-qualified class name of the compressor to use when compressing region entry values. A value of none removes the compressor. |
| ‑‑concurrency-level | An estimate of the maximum number of application threads that will concurrently access a region entry. Together with ‑‑initial-capacity and ‑‑load-factor, sets the parameters on the underlying java.util.ConcurrentHashMap used for storing region entries. This attribute does not apply to partitioned regions. |
| ‑‑enable-statistics | Enables statistics for the region specified by the --region option. Valid values are true or false. If the parameter is specified without a value, the value defaults to true. |
| ‑‑initial-capacity | Together with ‑‑concurrency-level and ‑‑load-factor, sets the parameters on the underlying java.util.ConcurrentHashMap used for storing region entries. |
| ‑‑load-factor | Together with ‑‑concurrency-level and ‑‑initial-capacity, sets the parameters on the underlying java.util.ConcurrentHashMap used for storing region entries. This must be a floating point number between 0 and 1, inclusive. |
| ‑‑lru-action | Action to take when evicting entries from the region. Valid values are:
|
| ‑‑lru-algorithm | Least recently used eviction algorithm. Valid types are:
|
| ‑‑lru-limit | Number of entries allowed in the region before eviction occurs. |
| ‑‑off-heap | Specifies whether the region values are in heap memory or off-heap memory. When true, region values are in off-heap memory. If the parameter is specified without a value, the value defaults to true. |
| ‑‑remove | Specifies whether to remove the region from the disk-store. If the parameter is specified without a value, the value defaults to true. Note: ‑‑remove deletes all persistent data for the region. You might want to copy the disk store files to a backup before using this option to allow you to retrieve the data at a later time. |
Example Commands:
alter disk-store --name=DiskStore1 --region=region1 --disk-dirs=/Disks/DiskStore1 --off-heap
alter disk-store --name=DiskStore1 --region=region1 --disk-dirs=/Disks/DiskStore1 --remove
alter gateway-sender
Alter attributes of a specified gateway sender on one or more members of a cluster.
Availability: Online. You must be connected in gfsh to a JMX Manager member to use this command.
Syntax:
alter gateway-sender --id=value [--members=value(,value)*] [--groups=value(,value)*]
[--alert-threshold=value] [--batch-size=value] [--batch-time-interval=value]
[--gateway-event-filter=value(,value)*] [--group-transaction-events(=value)?]
The required option, --id, identifies the gateway sender to be altered.
Parameters, alter gateway-sender
| Name | Description |
|---|---|
| ‑‑id | Required. ID of the gateway sender to be changed |
| ‑‑members | Name or ID of the members whose configuration is to be altered at runtime. If you do not specify this parameter, the configuration properties are modified for all cluster members using the cluster configuration service. |
| ‑‑groups | Name of the groups whose members' runtime configurations are to be altered. If you do not specify this parameter, the configuration properties are modified for all cluster members using the cluster configuration service. |
| ‑‑alert-threshold | Maximum time, in milliseconds, that a region event can remain in the gateway sender queue before Tanzu GemFire logs an alert. |
| ‑‑batch-size | Maximum number of messages that a batch can contain. |
| ‑‑batch-time-interval | Maximum amount of time, in ms, that can elapse before a batch is delivered, when no events are found in the queue to reach the batch-size. |
| ‑‑gateway-event-filter | A list of fully-qualified class names of GatewayEventFilters (separated by commas) to be associated with the GatewaySender. This serves as a callback for users to filter out events before dispatching to a remote cluster. For example: In case no value is provided, all existing filters will be removed. |
| ‑‑group-transaction-events | Boolean value to ensure that all the events of a transaction are sent in the same batch, i.e., they are never spread across different batches. Only allowed to be set on gateway senders with the Note: In order to work for a transaction, the regions to which the transaction events belong must be replicated by the same set of senders with this flag enabled. |
Example Commands:
alter gateway-sender --id=sender1 --alert-threshold=100 --batch-size=200 --group-transaction-events
alter query-service
Alter configuration details of the query configuration service.
Availability: Online. You must be connected in gfsh to a JMX Manager member to use this command.
Syntax:
alter query-service --method-authorizer=value
[--authorizer-parameters=value(;value)*] [--force-update(=value)]
Parameters, alter query-service
| Name | Description |
|---|---|
| ‑‑method-authorizer | Required. Fully qualified class name of the MethodInvocationAuthorizer to be used for query authorization. |
| ‑‑authorizer-parameters | A semicolon-separated list of parameters to be used by the specified MethodInvocationAuthorizer. This requires that a method-authorizer option has been specified. |
| ‑‑force-update | Specifies whether to forcibly update the MethodInvocationAuthorizer, even when there are continuous queries registered in the member. Default (if the parameter is not specified): false. Default (if the parameter is specified without value): true. Note: when set as true, any registered CQ will pick up the new MethodInvocationAuthorizer and invalidate its internal cache; consider checking that the new MethodInvocationAuthorizer allows the methods invoked by the CQs before using this option. |
Example Commands:
alter query-service --method-authorizer=org.apache.geode.cache.query.security.UnrestrictedMethodAuthorizer
alter query-service --method-authorizer=org.apache.geode.cache.query.security.UnrestrictedMethodAuthorizer --force-update=true
alter query-service --method-authorizer=org.apache.geode.cache.query.security.JavaBeanAccessorMethodAuthorizer --authorizer-parameters=java.lang;java.util
alter region
Alters the configuration of a region.
See Specifying JSON within Command-Line Options for syntax details.
Availability: Online. You must be connected in gfsh to a JMX Manager member to use this command.
Syntax:
alter region --name=value [--groups=value(,value)*]
[--entry-idle-time-expiration=value]
[--entry-idle-time-expiration-action(=value)?]
[--entry-time-to-live-expiration=value]
[--entry-time-to-live-expiration-action(=value)?]
[--entry-idle-time-custom-expiry=value] [--entry-time-to-live-custom-expiry=value]
[--region-idle-time-expiration=value]
[--region-idle-time-expiration-action(=value)?]
[--region-time-to-live-expiration=value]
[--region-time-to-live-expiration-action(=value)?]
[--cache-listener=value(,value)*] [--cache-loader=value]
[--cache-writer=value] [--async-event-queue-id=value(,value)*]
[--gateway-sender-id=value(,value)*] [--enable-cloning(=value)?]
[--eviction-max(=value)?]
Parameters, alter region
| Name | Description | Default Value | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ‑‑async-event-queue-id | IDs of the Async Event Queues that will be used for write-behind operations. | |||||||||
| ‑‑cache-listener | Fully qualified class name of a plug-in to be instantiated for receiving after-event notification of changes to the region and its entries. Any number of cache listeners can be configured. A fully qualified class name may be appended with a JSON specification that will be parsed to become the fields of the parameter to the init() method for a class that implements the Declarable interface. |
|||||||||
| ‑‑cache-loader | Fully qualified class name of a plug-in to be instantiated for receiving notification of cache misses in the region. At most, one cache loader can be defined in each member for the region. For distributed regions, a cache loader may be invoked remotely from other members that have the region defined. A fully qualified class name may be appended with a JSON specification that will be parsed to become the fields of the parameter to the initialize() method for a class that implements the Declarable interface. |
|||||||||
| ‑‑cache-writer | Fully qualified class name of a plug-in to be instantiated for receiving before-event notification of changes to the region and its entries. The plug-in may cancel the event. At most, one cache writer can be defined in each member for the region. A fully qualified class name may be appended with a JSON specification that will be parsed to become the fields of the parameter to the init() method for a class that implements the Declarable interface. |
|||||||||
| ‑‑enable-cloning | Determines how |
false |
||||||||
| ‑‑entry-idle-time-expiration | Number of seconds before a region or an entry expires. Specify -1 to indicate that there is no expiration of this type |
-1 | ||||||||
| ‑‑entry-idle-time-expiration-action | Action that should take place when a region or an entry expires.
Select one of the following expiration actions:
|
invalidate |
||||||||
| ‑‑entry-time-to-live-expiration | Number of seconds before a region or an entry expires. Specify -1 to indicate that there is no expiration of this type. |
-1 | ||||||||
| ‑‑entry-time-to-live-expiration-action | Action that should take place when a region or an entry expires.
Select one of the following expiration actions:
|
invalidate |
||||||||
| ‑‑entry-idle-time-custom-expiry | The name of a class implementing CustomExpiry for entry idle time. Append a JSON string for initialization properties. | |||||||||
| ‑‑entry-time-to-live-custom-expiry | The name of a class implementing CustomExpiry for entry time to live. Append a JSON string for initialization properties. | |||||||||
| ‑‑eviction-max | Maximum value for the Eviction Attributes that the eviction algorithm uses to determine when to perform its eviction action. The unit of the maximum value is determined by the Eviction Algorithm. | 0 | ||||||||
| ‑‑gateway-sender-id | IDs of the Gateway Senders where data is routed. | |||||||||
| ‑‑groups | Groups of members where the region will be altered. | |||||||||
| ‑‑name | Required. Name (including path) of the region. | |||||||||
| ‑‑region-idle-time-expiration | Number of seconds before a region or an entry expires. If timeout is not specified, it defaults to zero (which means no expiration). | -1 | ||||||||
| ‑‑region-idle-time-expiration-action | Action that should take place when a region or an entry expires.
Select one of the following expiration actions:
|
invalidate |
||||||||
| ‑‑region-time-to-live-expiration | Number of seconds before a region or an entry expires. If timeout is not specified, it defaults to zero (which means no expiration). | -1 | ||||||||
| ‑‑region-time-to-live-expiration-action | Action that should take place when a region or an entry expires.
Select one of the following expiration actions:
|
invalidate |
Example Commands:
alter region --name=region1 --eviction-max=5000 [-group=all]
Sample Output:
gfsh>alter region --name=customer --eviction-max=5000
Member | Status
------- | ----------------------------------
server1 | Region "/customer" altered on "server1"
alter runtime
Alters configuration properties for all servers or a subset of servers while the member or members are running. Alter runtime is a cluster configuration command that takes immediate effect on the existing members of the cluster, as well as on any new members added to the cluster.
The alter runtime command does not apply to locators.
For more information about these configuration properties, see cache.xml and configuration parameter reference.
Availability: Online. You must be connected in gfsh to a JMX Manager member to use this command.
Syntax:
alter runtime [--members=value(,value)*] [--groups=value(,value)*]
[--archive-disk-space-limit=value]
[--archive-file-size-limit=value] [--log-disk-space-limit=value]
[--log-file-size-limit=value] [--log-level=value]
[--statistic-archive-file=value] [--statistic-sample-rate=value]
[--enable-statistics=value] [--copy-on-read(=value)?] [--lock-lease=value]
[--lock-timeout=value] [--message-sync-interval=value] [--search-timeout=value]
Parameters, alter runtime
| Name | Description | Default Value |
|---|---|---|
| ‑‑members | Name or ID of the members whose configuration is to be altered at runtime. If you do not specify this parameter, the configuration properties are modified for all cluster members using the cluster configuration service. | If not specified, all members using the cluster configuration service |
| ‑‑groups | Name of the groups whose members's runtime configuration is to be altered. If you do not specify this parameter, the configuration properties are modified for all cluster members using the cluster configuration service. | If not specified, all members using the cluster configuration service |
| ‑‑archive-disk-space-limit | Archive disk space limit. Maximum size (in megabytes) of all inactive statistic archive files combined. If this limit is exceeded, inactive archive files are deleted, oldest first, until the total size is within the limit. If set to zero, disk space use is unlimited. Valid values are (in megabytes): 0 to 1000000. | 0 |
| ‑‑archive-file-size-limit | Archive file size limit. The maximum size (in megabytes) of a single statistic archive file. Once this limit is exceeded, a new statistic archive file is created, and the current archive file becomes inactive. If set to zero, file size is unlimited. Valid values are (in megabytes): 0 to 1000000. | 0 |
| ‑‑log-disk-space-limit | Log disk space limit. Maximum size in megabytes of all inactive log files combined. If this limit is exceeded, inactive log files are deleted, oldest first, until the total size is within the limit. If set to zero, disk space use is unlimited. Valid values are (in megabytes): 0 to 1000000. | 0 |
| ‑‑log-file-size-limit | Log file size limit. Maximum size in megabytes of a log file before it is closed and logging rolls on to a new (child) log file. If set to zero, log rolling is deactivated. Valid values are (in megabytes): 0 to 1000000. | 0 |
| ‑‑log-level | The new log level. This option is required and you must specify a value. Valid values are: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF. |
INFO |
| ‑‑statistic-archive-file | The file to which the running system member writes statistic samples. For example: "StatisticsArchiveFile.gfs". Must be defined to store the archiving to a file. Adding the .gz suffix to the file name causes it to be compressed. See Statistics. |
not set |
| ‑‑statistic-sample-rate | Statistic sampling rate. Valid values are (in milliseconds): 1000 to 60000. See Statistics. | 1000 |
| ‑‑enable-statistics | Whether statistic sampling should be enabled. Specify --statistic-archive-file to store the statistics to a file. Valid values are: true and false. See Statistics. |
true |
| ‑‑copy-on-read | True or false. Sets the copy on read region attribute for cache read operations. See Copy on Read Behavior. | false |
| ‑‑lock-lease | Sets the length, in seconds, of distributed lock leases obtained by this cache. See Setting Cache Timeouts. | 120 |
| ‑‑lock-timeout | Sets the number of seconds a cache operation may wait to obtain a distributed lock lease before timing out. See Setting Cache Timeouts. | 60 |
| ‑‑message-sync-interval | Sets the frequency (in seconds) at which a message will be sent by the primary cache-server node to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue. See Change Server Queue Synchronization Frequency. | 1 |
| ‑‑search-timeout | Sets the number of seconds a cache get operation can spend searching for a value. See Setting Cache Timeouts. | 300 |
Example Commands:
alter runtime --members=server1 --log-level=WARN --enable-statistics=true
Sample Output:
gfsh>alter runtime --members=server1 --log-level=WARN --enable-statistics=true
Runtime configuration altered successfully for the following member(s)
192.0.2.0(server1:240)<v1>:64871
