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
/opt/mapr/bin/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 on auditing for the volume. If you enable auditing at the cluster level with the 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 enabled, enabling auditing on any of them causes auditing of them to start.

Set auditenabled 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 IP address or UID are logged only once for a particular operation, 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.

Now however, if the client was also writing to the file, irrespective of the coalesce interval for the read operation in the example stated previously, the write operation is logged, as it is a different operation from reading.

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. Set this parameter to 0 to disable the compactor.
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, and SPs. CLDB also takes into consideration the load (IO/Space) when selecting target SPs for containers. The value must be a positive integer. The default value is 0. The value can be up to twice the number of SPs in the volume’s topology.
criticalrereplicationtimeoutsec Timeout (in seconds) before re-replicating only the critically under-replicated containers . If you set both rereplicationtimeoutsec and criticalrereplicationtimeoutsec,and if the value of:
  • rereplicationtimeoutsec is less than criticalrereplicationtimeoutsec, rereplicationtimeoutsec overrides the criticalrereplicationtimeoutsec setting for both under-replicated and critically under-replicated containers.
  • rereplicationtimeoutsec is greater than criticalrereplicationtimeoutsec, criticalrereplicationtimeoutsec overrides the rereplicationtimeoutsec setting only for critically under-replicated containers; 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 file system operations to include (specified with a preceding plus sign (+)) or exclude (specified with a preceding minus sign (-)) from auditing.

To exclude the first operation in the list (of operations) from auditing, precede it by two minus (--) signs. To exclude subsequent operations, precede them by only a single minus (-) sign, irrespective of whether 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 is 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.

You cannot enable warm tiering if it was disabled, or disable warm tiering if it was enabled during volume creation.

ecscheme The number of data chunks and the number of parity chunks separated by a plus (+) sign. The default scheme is 4+2. For information on the supported schemes, see Erasure Coding Scheme for Data Protection and Recovery.
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 flag ensures that further updates (writes) to volume are successful only when the minimum number of copies of the container are available. Setting this parameter to true ensures that if writes succeed, then it has been applied to at least the minimum number of copies; if writes fail, it may have been applied to zero or more copies.

Enabling this parameter, may stall volume dump and volume snapshot create operations, if the minimum number of copies of the container are not available.

If you do not set this parameter on a volume, or if you modified this parameter from false to true, then you need to restart all the nodes where the containers associated with the volume exist, for the changes to take effect.

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 and volume levels, irrespective of the audit setting on the individual directory, file, table, and stream. The value can either be:
  • true — force audit of all content
  • false — do not force audit
By default, this parameter is set to false. 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, set the auditenabled parameter 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.

Set this parameter to 0 to disable mirror scheduling.

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 Limits the size of the name container. The value must be in MB. If 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, while 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 you set the current name container size to 200GB and the limit to 100GB, then all new data is stored in data containers.

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

nsminreplication The minimum replication level for the namespace container. Default: 2

When the replication factor falls below this value, 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. You use this capability when you have low volume replication but want to have higher namespace replication.

Set the value to be the same or larger than the value of 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 node that is down to come back online. After this timeout period, the CLDB takes the action required to restore the replication factor. When enabled, the CLDB manages the namespace container replication separate from the data container replication. Use this capability when you have low volume replication but want to have higher namespace replication.

By default, the value of this parameter is the same or larger than the value of the equivalent data replication parameter, replication. However, to set the value of this parameter lower than the replication value, first set engg.manual.override to true in cldb.conf.

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 this 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.

See Access Control Expression (ACE)s.

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 after 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,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 the appropriate recovery action of deleting the mapred volume and creating another one.

schedule A schedule ID. If you provide a schedule ID, then the volume automatically creates snapshots (normal volume) or syncs with its source volume (mirror volume) on the specified schedule.

To disable the schedule, set this parameter to 0.

source The source volume from which a mirror volume receives updates, specified in the format <volume>@<cluster>.
tierencryption Specifies whether to enable (true) or disable (false) encryption of data. This parameter is applicable only for cold-tier volumes. If you enable this parameter, user data is encrypted before being written to the object, and the HTTPS protocol is used for communication with the object store to ensure that data is encrypted both on the wire and on the tier.

You can set this parameter only if you specify a tier name (see the tiername parameter) as well. You cannot modify this parameter after you set it.

If you set the value to true, you can also specify a custom key using the tierkey parameter. Once set to true, the MAST Gateway uses HTTPS to upload data to the cold-tier. If the cold tier does not support HTTPS, all tier related operations 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 The 32 character HEX string to use for encryption only for cold tier volumes. If you do not specify a string, CLDB generates a 32 character HEX string to use for encrypting the data to offload to the tier.

You cannot modify the tierkey that is already associated with the volume.

tiername The name of the tier to use for offloading data. You can set this name only once and cannot modify it.
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 the hadoop mfs command) and enables on-wire encryption for all files, tables, and streams. If you disable (false) this parameter at the volume level, but enable it at the file, table, or stream level, the file, table, 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, or stream level, the 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.

See ACEs.

Examples

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

/opt/mapr/bin/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

# /opt/mapr/bin/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. For a 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 inheritance to child volumes.

/opt/mapr/bin/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 sets and modifies access (defined using ACEs) to the volume data. When the command runs, new values:
  • Overwrite existing values for access types that were previously set.
  • Are set for access types that were not set.
Note: There is no change to the readAce access type, which is not specified with the command, irrespective of whether it is set or not.
/opt/mapr/bin/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.

/opt/mapr/bin/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:

# /opt/mapr/bin/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":[]}

Disable scheduled snapshot creation

To disable a schedule, set the schedule parameter to 0.

For example:

# /opt/mapr/bin/maprcli volume modify -name mapr.apps  -schedule 0
# /opt/mapr/bin/maprcli volume info -name mapr.apps  -json | grep schedule
                        "scheduleid":"0",
                        "schedulename":"",
                        "mirrorscheduleid":"0"