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.

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:
  • none
  • overflow-to-disk
  • local-destroy
‑‑lru-algorithm Least recently used eviction algorithm. Valid types are:
  • none
  • lru-entry-count
  • lru-heap-percentage
  • lru-memory-size
‑‑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:
gateway-event-filter=com.user.filters.MyFilter1,com.user.filters.MyFilters2

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 parallel attribute set to false and dispatcher-threads attribute equal to 1, or on gateway senders with the parallel attribute set to true. Also, the enable-batch-conflation attribute of the gateway sender must be set to false.

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 fromDelta applies deltas to the local cache for delta propagation. When true, the updates are applied to a clone of the value and then the clone is saved to the cache. When `false`, the value is modified in place in the cache.

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:
local-destroy Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
destroy Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
invalidate Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. This is the proper choice when the region or the entry is no longer valid for any application in the cluster.
local-invalidate Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.
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:
local-destroy Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
destroy Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
invalidate Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. This is the proper choice when the region or the entry is no longer valid for any application in the cluster.
local-invalidate Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.
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:
local-destroy Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
destroy Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
invalidate Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. This is the proper choice when the region or the entry is no longer valid for any application in the cluster.
local-invalidate Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.
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:
local-destroy Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
destroy Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
invalidate Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. This is the proper choice when the region or the entry is no longer valid for any application in the cluster.
local-invalidate Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.
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
check-circle-line exclamation-circle-line close-line
Scroll to top icon