volume modify

Modifies an existing volume. Permissions required: m or fc on the volume.

An error occurs if the name or path refers to a non-existent volume, or cannot be resolved.

Syntax

CLI
maprcli volume modify
    [ -cluster <cluster name> ]
    -name <volume name>
    [ -advisoryquota <advisory quota> ]
    [ -ae <accounting entity> ]
    [ -aetype <aetype> ]
    [ -allowgrant true|false ]
    [ -auditenabled true|false ]
    [ -autooffloadthresholdgb <offload size threshold> ]
    [ -coalesce <interval in mins> ]
    [ -compactionoverheadthreshold <compaction_overhead> ]
    [ -compactionschedule <compaction_schedule_ID> ]
    [ -containerallocationfactor <positive integer> ]
    [ -criticalrereplicationtimeoutsec ]
    [ -dataauditops <+|- operations> ]
    [ -dbindexlagsecalarmthresh <threshold> ]
    [ -dbrepllagsecalarmthresh <threshold> ]
    [ -ecenable true|false ]
    [ -ecscheme <ec_scheme> ]
    [ -ectopology <path> ]
    [ -enforceminreplicationforio true|false ]
    [ -forceauditenable true|false ]
    [ -group <list of group:allowMask> ]
    [ -maxinodesalarmthreshold <threshold> ]
    [ -maxnssizembalarmthreshold <threshold> ]
    [ -metricsenabled true|false ]
    [ -minreplication <minimum replication> ]
    [ -mirrorschedule <mirror schedule ID> ]
    [ -mirrorthrottle true|false ]
    [ -namecontainerdatathreshold <size>  ] (available from version 6.0.1) 
    [ -nsminreplication <minimum replication factor> ]
    [ -nsreplication <replication factor> ]
    [ -offloadschedule <schedule ID> ]
    [ -quota <quota> ]
    [ -readAce <Access Control Expression> ]
    [ -readonly <readonly> ]
    [ -recallexpirytime <expiry time> ]
    [ -replication <replication> ]
    [ -rereplicationtimeoutsec <timeout in seconds> ]
    [ -schedule <schedule ID> ]
    [ -source <source volume> ]
    [ -tierencryption true|false ]       
    [ -tieringrule <rule name> ]
    [ -tierkey <tier encryption key> ]
    [ -tiername <tier name> ]
    [ -type rw|mirror ]
    [ -user <list of user:allowMask> ]
    [ -wiresecurityenabled true|false ]
    [ -writeAce <Access Control Expression> ]
REST
Request Type POST
Request URL
http[s]://<host>:<port>/rest/volume/modify?<parameters> 

Parameters

Parameter

Description

advisoryquota The advisory quota for the volume as integer plus unit. Example: quota=500G; Units: B, K, M, G, T, P
ae The accounting entity that owns the volume.
aetype The type of accounting entity:
  • 0=user
  • 1=group
allowgrant Specifies whether the volume as a parent grants permission for a child volume to inherit its properties. True or false. Default: false.
auditenabled Specifies whether to turn auditing on for the volume. If auditing is also enabled at the cluster level with the maprcli audit data command, setting this value to true causes auditing to start for any directories, files, tables, or streams that are already enabled for auditing. If none are yet so enabled, enabling auditing on any of them causes auditing of them to start.
Note: This must be set to true to enable auditing on directories, files, tables, and streams in the volume.
You must have the fc permission on the cluster to use this parameter. See acl for details about this permission.
autooffloadthresholdgb The size of the volume in GB (threshold). When this threshold is reached or exceeded, volume data is automatically offloaded by the Automatic Tiering Scheduler. To use the global size threshold (of 1024 GB), set the value for this to 0, which is the default value.
cluster The cluster on which to run the command.
coalesce The interval of time during which READ, WRITE, or GETATTR operations on one file from one client IP address are logged only once, if auditing is enabled.

For example, suppose that a client application reads a single file three times in 6 minutes, so that there is one read at 0 minutes, another at 3 minutes, and a final read at 6 minutes. If the coalesce interval is at least 6 minutes, then only the first read operation is logged. However, if the interval is between 4 minutes, then only the first and third read operations are logged. If the interval is 2 minutes, all three read operations are logged.

The default value is 60 minutes. Setting this field to a larger number helps prevent audit logs from growing quickly.

compactionoverheadthreshold Specifies the percentage of offloaded data that must have been deleted on the MapR cluster to qualify the data for compaction (or deletion from the tier). The default value is 30%.
compactionschedule Specifies the schedule to use for running the compactor. By default, the compactor runs on an automatic internal schedule.
containerallocationfactor Specifies the number of containers to create when the first write from a remote client is sent to the volume. The pre-created containers are distributed equally across topologies, servers, MapR Filesystem instances, SPs, and CLDB also takes into consideration the load (IO/Space) when selecting target SPs for containers. Value must be a positive integer. The default value is 0. Value can be up to twice the number of SPs in the volume’s topology.
criticalrereplicationtimeoutsec Timeout (in seconds) before re-replicating critically under-replicated containers only. If both rereplicationtimeoutsec and criticalrereplicationtimeoutsec are set and if the value of:
  • rereplicationtimeoutsec is less than criticalrereplicationtimeoutsec, rereplicationtimeoutsec will override criticalrereplicationtimeoutsec setting for both under-replicated and critically under-replicated containers.
  • rereplicationtimeoutsec is greater than criticalrereplicationtimeoutsec, criticalrereplicationtimeoutsec will override rereplicationtimeoutsec setting for critically under-replicated containers only; rereplicationtimeoutsec setting is still applicable for under-replicated containers.
Default value for this parameter is 0 (which indicates no timeout). Value can be 0, or >= 300 seconds and <= 3600 seconds.
dataauditops The comma separated list of filesystem operations to include (specified with a preceding plus sign (+)) or exclude (specified with a preceding minus sign (-)) from auditing.
Note: If the first operation in the list (of operations) is to be excluded from auditing, it must be preceded by two minus (--) signs. Subsequent operations to exclude must be preceded by only a single minus (-) sign, whether or not the first operation was included (using a plus (+) sign) or excluded (using two minus (--) signs). If neither sign is specified, the given operation is included for auditing.
The operations that can be included (+) or excluded (-) from auditing are listed here. You can, alternatively, group all the operations using the keyword all, which:
  • If included (+), cannot be specified with a list of other included operations.
  • If excluded (-), cannot be specified with a list of other excluded operations.

You can specify a mixed list of included and excluded operations. There will be no change to operations that are not specified with the command.

dbindexlagsecalarmthresh Specifies the threshold (in seconds) to raise an alarm for index update lag. Default: 0
dbrepllagsecalarmthresh Specifies the threshold (in seconds) to raise an alarm for DB replication lag. Default: 0
ecenable Enable (true) warm tiering for the volume only if it is already not enabled. If this is specified, you cannot specify tiername to use an existing warm-tier; when the command runs, a new tier is created for the volume.
Note: You cannot enable warm tiering if it was disabled or disable warm tiering if it was enabled when the volume was being created.
ecscheme The number of data chunks and the number of partify chunks separated by a plus (+) sign. The default scheme is 4+2. For information on the supported schemes, see Selecting an Erasure Coding Scheme.
ectopology The topology of the erasure coded volume if it is already not set. You cannot change the topology of an erasure coded volume using this command. To change the topology of an erasure coded volume, use volume move.
enforceminreplicationforio Specifies whether (true) or not (false) to enforce minimum number of replicas for the (read-write) volume during IO. This ensures that further updates (writes) to volume are successful only when minimum number of copies of the container is available. Setting this to true ensures that if writes succeed, then it has been applied to at least the minimum number of copies and if writes fail, it may have been applied to zero or more copies.
Note: If this is enabled, volume dump and volume snapshot create operations may stall if the minimum number of copies of the container are not available.
If this parameter was not set on a volume or if this parameter was modified from false to true, restart all the nodes where the containers associated with the volume exist for the changes to take effect.
Note: This flag, if set on Mirror Volumes, is ignored.
forceauditenable Specifies whether (1) or not (0) to force audit of operations on all files, tables, and streams in the volume if auditing is enabled at the cluster level and at the volume level, irrespective of the audit setting on the individual directory, file, table, and stream. Value can be:
  • true — force audit of all content
  • false — do not force audit
By default, this is disabled (0). To force audit of all directories, files, tables, and streams in the volume irrespective of the audit setting on the directories, files, tables, and streams, the auditenabled parameter value must also be set to true.
group Space-separated list of group:permission pairs.
maxinodesalarmthreshold The number of inodes, which when exceeded raises the INODES_EXCEEDED alarm.
maxnssizembalarmthreshold The namespace container size, which when exceeded raises the INODES_EXCEEDED alarm.
metricsenabled Specifies whether (true) or not (false) to enable metrics collection for a volume.
minreplication The minimum replication level. Default: 0
Tip: For more information, see Understanding Replication.
mirrorschedule The schedule ID corresponding to the schedule to be used for mirroring. Pre-assigned IDs include 1 for critical data, 2 for important data, and 3 for normal data. Custom schedules are assigned ID numbers in sequence. To determine the ID number, use the schedule list command.
mirrorthrottle Specifies whether mirror throttling is enabled (true) or disabled (false). The default is true. Throttling is set on the source volume and applies to all its mirrors.
namecontainerdatathreshold (Available from v6.0.1) Limits the size of the name container. Value must be in MB. If this is set and the name container size limit:
  • Has not yet been reached, the first 64 KB of data is stored in the name container until the limit is reached. Once the limit is reached, only the metadata is stored in the name container and data is stored in data containers.
  • Has already been reached, only metadata is stored in the name container and all new data is spread across data containers. For example, if the current name container size is 200GB and the limit is set to 100GB, all new data is stored in data containers.

    If this paramter is set to 0, there is no limit on the size of data stored in the name container.

nsminreplication The minimum replication level for the namespace container. Default: 2 When the replication factor falls below this minimum, re-replication occurs as aggressively as possible to restore the replication level. If any containers in the CLDB volume fall below the minimum replication factor, writes are disabled until aggressive re-replication restores the minimum level of replication. When enabled, the CLDB manages the namespace container replication separate from the data container replication. This capability is used when you have low volume replication but want to have higher namespace replication.
Note: This parameter must be the same or larger than the equivalent data replication parameter, minreplication.
See also: Understanding Replication.
nsreplication The desired namespace container replication level. Default: 3. When the number of copies falls below the desired replication factor, but remains equal to or above the minimum replication factor, re-replication occurs after the timeout specified in the cldb.fs.mark.rereplicate.sec parameter. This timeout is the time given for a down node to come back online. After this timeout period, the CLDB takes action to restore the replication factor. When enabled, the CLDB manages the namespace container replication separate from the data container replication. This capability is used when you have low volume replication but want to have higher namespace replication.
Note: This parameter must be the same or larger than the equivalent data replication parameter, replication.
See also: Understanding Replication.
name The name of the volume to modify.
offloadschedule The ID of the schedule to associate with the volume for offloading volume data to the tier. To disable schedule-based offload, set value to 0.
quota The quota for the volume as integer plus unit. Example: quota=500G; Units: B, K, M, G, T, P

Note that quotas for source and mirror volumes must match.

readAce Specifies Access Control Expressions (ACEs) that grant permissions at the volume level to read files and tables in the volume. The default value is p, which grants access to all users.
Note: An ACE (up to 2KB in length) is a combination of users, groups, and/or roles for whom access (to volume data) is defined using boolean expressions and subexpressions within single quotes. When you pass in an access type that has already been set, the new value will replace the existing value for that access type. There will be no change to access types that are not passed in with the command, whether or not they were set.
readonly Specifies whether the volume is read-only.
  • 0 = read/write
  • 1 = read-only
recallexpirytime The amount of time to keep the recalled data before purging or offloading it. Value must be greater than 1 and lesser than 7500. The default value is 1 day.
replication The desired replication level. Default: 0
Tip: For more information, see Understanding Replication.
rereplicationtimeoutsec Timeout (in seconds) before attempting re-replication of replica containers. This volume property defines the timeout period until CLDB starts re-replicating the containers on the node of the volume when CLDB stops receiving a heartbeat from the node.

When a node is down, CLDB gives the node an hour to come back online before it takes any action for the containers on this node. This parameter can be set on volumes to reduce the default 1 hour to a shorter time period. This option is provided mainly for local volumes, repl=1 so that when an MapR Filesystem is down, CLDB can give up quickly and decide that the container has no master. This forces the TT to give up on local containers and take appropriate recovery action of deleting the mapred volume and creating another one.

schedule A schedule ID. If a schedule ID is provided, then the volume will automatically create snapshots (normal volume) or sync with its source volume (mirror volume) on the specified schedule.
source (Mirror volumes only) The source volume from which a mirror volume receives updates, specified in the format <volume>@<cluster>.
tierencryption (For cold tier only) Specifies whether to enable (true) or disable (false) encryption of data. If enabled, user data is encrypted before written to the object and HTTPs protocol is used for communication with the object store to ensure data is encrypted both on the wire and on the tier.
Note: This can be set only if a tier name is also specified and cannot be modified once set.

If true, you can also specify a custom key using the tierkey parameter. If true, MAST Gateway uses HTTPS to upload data to the cold-tier. If the cold tier does not support HTTPS, all tier related operations will fail. If the cold tier does not support HTTPS, you must explicitly set the value for this to false at the time of associating a tier with the volume because the default value for this parameter is true.

Tip: For warm tier, use -dare option on the front-end volume to enable or disable encryption of data-at-rest.
tieringrule The name of the rule to use for offloading data to the tier.
tierkey (For cold tier only) The 32 character HEX string to use for encryption. If this is not specified, CLDB generates a 32 character HEX string to use for encrypting the data to offload to the tier.
Note: You cannot modify the tierkey that is already associated with the volume.
tiername The name of the tier to use for offloading data. This can be set only once and after it is set, it cannot be modified.
type If type = mirror, the volume is converted from a rw (read/write) volume to a mirror volume.

If type = rw, the volume is converted from a mirror volume to a rw (read/write) volume.

user Space-separated list of user:permission pairs.
wiresecurityenabled Enables (true) or disables (false) on-wire encryption for all files, tables, and streams in the volume. If true, this setting overrides all file, table, and stream level encryption settings (set using hadoop mfs command) and enables on-wire encryption for all files, tables, and streams. If this is disabled (false) at the volume level and is enabled at the file, table, and/or stream level, the file, table, and/or stream level encryption setting overrides this setting on those files, tables, and streams where it is enabled; for all other files, tables, and streams where encryption is not enabled at the file, table, and/or stream level, on-wire encryption is disabled.
writeAce Specifies Access Control Expressions (ACEs) that grant permission at the volume level to write to files and tables in the volume. The default value is p, which grants access to all users.
Note: An ACE (up to 2KB in length) is a combination of users, groups, and/or roles for whom access is defined using boolean expressions and subexpressions within single quotes. When you pass in an access type that has already been set, the new value will replace the existing value for that access type. There will be no change to access types that are not passed in with the command, whether or not they were set.

Examples

Change the source volume of the mirror "test-mirror":

maprcli volume modify -name test-mirror -source volume-2@my-cluster
curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=test-mirror&source=volume-2@my-cluster' --user mapr:mapr

Create a volume with namespace container replicas

# maprcli volume modify -name testVol -nsminreplication 2 -nsreplication 4 -json
{
	"timestamp":1526528489360,
	"timeofday":"2018-05-16 08:41:29.360 GMT-0700 PM",
	"status":"OK",
	"total":0,
	"data":[
		
	]
}
# curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=testVol&nsminreplication=2&nsreplication=4' --user mapr:mapr
{"timestamp":1526528556748,"timeofday":"2018-05-16 08:42:36.748 GMT-0700 PM","status":"OK","total":0,"data":[]}

Modify a volume to allow inheritance by a child volume

Sub-volumes (children) can inherit properties from their parent volume. The maprcli volume create and volume modify commands provide parameters for setting the inheritance feature. In order for child volume to inherit from a parent volume, the parent volume must grant permission and the child volume must be created specifying the volume name of the parent. In the following example, the parent volume, parentVol, grants of inheritance to child volumes.

maprcli volume modify -name parentVol -allowgrant true
# curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=parentVol?allowgrant=true' --user mapr:mapr

Set and modify ACEs on a volume

In the following example, the command will set and modify access (defined using ACEs) to the volume data. When the command runs, new values will:
  • Overwrite existing values for access types that were previously set.
  • Be set for access types that were not set.
Note: There will be no change to the readAce access type, which is not specified with the command, whether or not it was set before.
maprcli volume modify -name testVol -writeAce 'g:group1&(!u:user1|!r:role1)'
curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=testVol&writeAce=g%3Agroup1%26%28%21u%3Auser1%7C%21r%3Arole1%29' --user mapr:mapr

Modify the list of operations that are audited

In the following example, the create operation is included for auditing and the lookup operation is excluded from auditing. There are no changes to operations that are not specified.

maprcli volume modify -name parentVol -dataauditops +create,-lookup
curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=p1&dataauditops=%2Bcreate%2C-lookup' --user mapr:mapr

Modify an existing volume to enable on-wire encryption:

# maprcli volume modify -name local2 -wiresecurityenabled true -json
{
        "timestamp":1505205889697,
        "timeofday":"2017-09-12 01:44:49.697 GMT-0700",
        "status":"OK",
        "total":0,
        "data":[

        ]
}
# curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=p1&wiresecurityenabled=true' --user mapr:mapr
{"timestamp":1526569299139,"timeofday":"2018-05-17 08:01:39.139 GMT-0700 AM","status":"OK","total":0,"data":[]}
Associate an offload rule with a tiering-enabled volume:
/opt/mapr/bin/maprcli volume modify -name sampleVol -tieringrule ksTestRule -json
{
	"timestamp":1526569498559,
	"timeofday":"2018-05-17 08:04:58.559 GMT-0700 AM",
	"status":"OK",
	"total":0,
	"data":[
		
	]
}
curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=sampleVol&tieringrule=ksTestRule' --user mapr:mapr
{"timestamp":1526569554743,"timeofday":"2018-05-17 08:05:54.743 GMT-0700 AM","status":"OK","total":0,"data":[]}
Modify a volume to set a schedule for data offload and set number of days to three days to keep recalled data:
/opt/mapr/bin/maprcli volume modify -name sampleVol -offloadschedule 3 -recallexpirytime 3 -json
{
	"timestamp":1526569615285,
	"timeofday":"2018-05-17 08:06:55.285 GMT-0700 AM",
	"status":"OK",
	"total":0,
	"data":[
		
	]
}
curl -k -X POST 'https://abc.sj.us:8443/rest/volume/modify?name=sampleVol&offloadschedule=3&recallexpirytime=3' --user mapr:mapr
{"timestamp":1526569653267,"timeofday":"2018-05-17 08:07:33.267 GMT-0700 AM","status":"OK","total":0,"data":[]}