volume create
Creates a volume. Permissions required: cv
or
fc on the volume.
Syntax
- CLI
-
maprcli volume create -name <volume name> [ -advisoryquota <advisory quota> ] [ -ae <accounting entity> ] [ -aetype <accounting entity type> ] [ -allowgrant true|false ] [ -allowinherit true|false ] [ -auditenabled true|false ] [ -cluster <cluster> ] [ -coalesce <interval in mins> ] [ -createparent 0|1 ] [ -dataauditops <+|- operations> ] [ -dbrepllagsecalarmthresh ] [ -group <list of group:allowMask> ] [ -inherit <volume name> ] [ -localvolumehost <localvolumehost> ] [ -localvolumeport <localvolumeport> ] [ -maxinodesalarmthreshold <maxinodesalarmthreshold> ] [ -minreplication <minimum replication factor> ] [ -mirrorschedule <mirror schedule ID> ] (4.0.2 and later) [ -mirrorthrottle 0|1 ] [ -mount 0|1 ] [ -nsminreplication <minimum replication factor> ] [ -nsreplication <replication factor> ] [ -path <mount path> ] [ -quota <quota> ] [ -readAce <access control expression> ] [ -readonly <read-only status> ] [ -replication <replication factor> ] [ -replicationtype <type> ] [ -rereplicationtimeoutsec <seconds> ] [ -rootdirperms <root directory permissions> ] [ -schedule <ID> ] [ -source <source> ] [ -topology <topology> ] [ -type rw|mirror] (4.0.2) or [-type 0|1] (4.0.1) [ -user <list of user:allowMask> ] [ -writeAce <access control expression> ]
- REST
-
http[s]://<host>:<port>/rest/volume/create?<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:
|
allowgrant |
Specifies whether a parent volume grants permission for a child volume to inherit its properties. True or false. Default: false. |
allowinherit |
Specifies whether a new volume inherit sproperties from the parent mount point volume. True or false. Default: true. |
auditenabled |
Specifies whether to turn auditing on for the volume. If
auditing is also enabled at the cluster level with the
You must have the |
cluster |
The cluster on which to create the volume. |
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. |
createparent |
Specifies whether or not to create a parent directory to hold the volume link:
|
dataauditops |
The comma separated list of filesystem operations to include (specified
with a preceding plus sign ( 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 in Auditing Operations. You can, alternatively, group all the operations using
the keyword all , which:
NOTE:
All specified operations must either be included or excluded from auditing.
You cannot specify a mixed list of included and excluded operations.
Other than the specified operations, by default, all other operations
will be:
TIP: For more information, see Selective Auditing of Filesystem and Table Operations.
|
dbrepllagsecalarmthresh |
Specifies the threshold to raise alarm for DB replication lag. |
group | Space-separated list of group:permission pairs. |
inherit | Specifies the name of the volume from which the new volume will inherit
properties. When inherit is explicitly specified,
allowgrant is not required. See the following section on
Inheritance for more information. |
localvolumehost |
The local volume host. |
localvolumeport |
The local volume port. Default: 5660 |
maxinodesalarmthreshold |
Threshold for the INODES_EXCEEDED alarm. |
minreplication |
The minimum replication level. 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. TIP: For more information, see Determining Replication Factor. |
mirrorschedule | The ID of a mirror schedule. If a mirror schedule ID is provided, then the mirror volume will automatically sync with its source volume on the specified schedule. |
mirrorthrottle | Specifies whether throttling should be enabled at create time. |
mount |
Specifies whether the volume is mounted at creation time. |
name |
The name of the volume to create. |
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,
For more information, see
Determining Replication Factor.minreplication . |
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,
For more information, see Determining Replication Factor.
replication . |
path |
The path at which to mount the volume. The path must be relative to
|
quota |
The quota for the volume as Do not use two-letter abbreviations for quota units, such as
|
readAce |
Specifies Access Control Expressions (ACEs) that grants permissions at
the volume level to read files and tables in the volume. The default
value is 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. There will be no
change to access types that are not passed in with the command.
|
readonly |
Specifies whether or not the volume is read-only:
|
replication |
The desired 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
NOTE: For more information, see Determining Replication Factor.
|
replicationtype |
The desired replication type. You can specify
|
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 mfs 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. |
rootdirperms |
Permissions on the volume root directory. |
schedule |
The ID of a schedule. Use the schedule list command to find the ID of the named schedule you want to apply to the volume. In 4.0.1, if a schedule ID is provided, it applies to a mirror volume. The mirror volume will automatically sync with its source volume on the specified schedule. Use the schedule list command to find the ID of the named schedule you wish to apply to the volume. In 4.0.2 and later releases, if a schedule ID is provided, it
applies to either a mirror volume or a standard volume. A standard
volume will automatically create snapshots on the specified
schedule. A mirror volume will sync with its source volume on the
specified schedule. If a mirror volume is made into a standard
volume, the |
source |
For mirror volumes, the source volume to mirror, in the format
|
topology |
The rack path to the volume. NOTE: To create a volume in a specific topology, you must have the Converged
Enterprise Edition installed on your system. Without the
Converged Enterprise Edition, when you run the
maprcli volume
create command with the -topology option,
the following error message is returned:
|
type |
The type of volume to create. For 4.0.2 and later releases, these values are accepted:
For 4.0.1 and earlier releases, these values are accepted:
|
user |
Space-separated list of |
writeaAce |
Specifies Access Control Expressions (ACEs) that grants permission at
the volume level to write to files and tables in the volume. The default
value is 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.
|
Inheritance
The following table shows the list of inheritable parameters that are (Yes) and are not (No) inherited by a:
- Mirror volume from the source volume on the same cluster
- Mirror volume from the source volume on a different cluster
volume create
parameters.Inheritable Properties (which are inherited by non-mirror volumes by default) | Inherited by Mirror Volume on the same cluster as the source volume? | Inherited by Mirror Volume on a different cluster from the source volume? |
---|---|---|
advisoryquota | Yes | Yes |
ae | Yes | No |
aetype | Yes | No |
allowgrant | Yes | Yes |
allowinherit | Yes | Yes |
auditenabled | Yes | Yes |
coalesce | Yes | Yes |
dataauditops | Yes | Yes |
dbrepllagsecalarmthresh | Yes | Yes |
group | Yes | Yes |
inherit | Yes | Yes |
localvolumehost | No | No |
localvolumeport | No | No |
maxinodesalarmthreshold | Yes | Yes |
minreplication | Yes | Yes |
mirrorschedule | Yes | No |
mirrorthrottle | Yes | Yes |
nsminreplication | Yes | Yes |
nsreplication | Yes | Yes |
quota | Yes | Yes |
readonly | Yes | Yes |
replication | Yes | Yes |
replicationtype | Yes | Yes |
rereplicationtimeoutsec | Yes | Yes |
rootdirperms | Yes | Yes |
schedule | Yes | No |
source | Yes | Yes |
topology | Yes | No |
type | Yes | Yes |
user | Yes | Yes |
Examples
Create the volume "test-volume" mounted at "/test/test-volume"
- CLI
-
maprcli volume create -name test-volume -path /test/test-volume -type rw
- REST
-
https://r1n1.sj.us:8443/rest/volume/create?name=test-volume&path=/test/test-volume&type=rw
Create Volume with a Quota and an Advisory Quota
This example creates a volume with the following parameters:
- advisoryquota: 100M
- name: volumename
- path: /volumepath
- quota: 500M
- replication: 3
- schedule: 2
- topology: /East Coast
- type: rw
- CLI
-
maprcli volume create -name volumename -path /volumepath -advisoryquota 100M -quota 500M -replication 3 -schedule 2 -topology "/East Coast" -type rw
- REST
-
https://r1n1.sj.us:8443/rest/volume/create?advisoryquota=100M&name=volumename&path=/volumepath"a=500M&replication=3&schedule=2&topology=/East%20Coast&type=rw
Create the mirror volume "test-volume.mirror" from source volume "test-volume" and mount at "/test/test-volume-mirror"
- CLI
-
maprcli volume create -name test-volume.mirror -source test-volume@src-cluster-name -path /test/test-volume-mirror -type mirror
- REST
-
https://r1n1.sj.us:8443/rest/volume/create?name=test-volume.mirror&sourcetest-volume@src-cluster-name&path=/test/test-volume-mirror&type=mirror
Create volumes that inherit from a parent volume
When creating and mounting a
volume, the location of the mount path is specified by the path parameter. Volumes can
be mounted via the web console, the maprcli
commands, or the REST
commands. The maprcli
commands include volume create
-path
command and the mapcli volume mount -path
command if
the volume was previously created. Sub-volumes (children) can inherit properties from
their parent volume.
In the following example, a parent volume and two (2) child volumes are create where the
child volume inherit properties from the parent. When the inherit
flag
is explicitly used, the allowgrant
parameter for the parent volume is
not required.
- For child volumes, c1 and c2, inheritance is explicit because the
inherit
option is specified. Thus, p1.c1 and p1.c2 volumes will inherit all properties from volume p1 (note that p1 is not a parent of p1.c1) regardless of whether theallowgrant
option is set on p1 or not. In this case, there is an explicit inheritance ant theallowgrant
flag is ignored and volume properties are inherited. - For the child volume, c3, inheritance is implicit. Meaning, the child volume, p1.c3,
inherits all properties from the parent volume, p1, only if the
allowgrant
option is set on p1.
- CLI
-
maprcli volume create -name p1 -path /p1 maprcli volume create -name p1.c1 -inherit p1 maprcli volume create -name p1.c2 -path /p1/c2 -inherit p1 maprcli volume create -name p1.c3 -path /p1/c3
- REST
-
https://10.10.82.26:8443/rest/volume/create?name=p1&path=%2Fp1 https://10.10.82.26:8443/rest/volume/create?name=p1.c1&inherit=p1 https://10.10.82.26:8443/rest/volume/create?name=p1.c2&path=%2Fp1%2Fc2&inherit=p1 https://10.10.82.26:8443/rest/volume/create?name=p1.c3&path=%2Fp1%2Fc3
In the following example, the p1.child volume normally inherits from the p1 parent
volume properties because p1.child is mounted under p1 and allowgrant
option is set to true on the parent volume. However, if the child volume doesn't want to
inherit properties, then set the allowinherit
option to false (default:
true).
- CLI
-
maprcli volume create -name p1 -path /p1 -allowgrant true maprcli volume create -name p1.child -path /p1/p1.child -allowinherit false
- REST
-
https://10.10.82.26:8443/rest/volume/create?name=p1&path=%2Fp1&allowgrant=true https://10.10.82.26:8443/rest/volume/create?name=p1.child&path=%2Fp1%2Fp1.child&allowinherit=false
Create a volume with namespace container replicas
- CLI
-
maprcli volume create -name testVol -nsminreplication 1 -nsreplication 2
- REST
-
https://10.10.82.26:8443/rest/volume/create?name=testVol&nsminreplication=1&nsreplication=2
Create a volume and set ACEs
- CLI
maprcli volume create -name testVol -readAce p -writeAce 'g:group1&!u:user1'
- REST
- N/A
Create a volume with auditing disabled for specific operations
- CLI
maprcli volume create -name test-volume -auditenabled true -dataauditops --lookup,-read,-write
- REST
https://10.10.82.26:8443/rest/volume/create?name=test-volume&path=/test/test-volume&auditenabled=true&dataauditops=%2D%2Dlookup%2C%2Dread%2C%2Dwrite