volume create

Create a new volume

Availability: This command is available to cluster and Vserver administrators at the admin privilege level.

Description

The volume create command creates a volume on a specified Vserver and storage aggregates. You can optionally specify the following attributes for the new volume:

Parameters

-vserver <vserver name> - Vserver Name
This specifies the Vserver on which the volume is located. If only one data Vserver exists, you do not need to specify this parameter.
-volume <volume name> - Volume Name
This specifies the name of the volume that is to be created. A volume's name must start with an alphabetic character (a to z or A to Z) and be 197 or fewer characters in length for FlexGroups, and 203 or fewer characters in length for all other volume types. Volume names must be unique within a Vserver.
{ -aggregate <aggregate name> - Aggregate Name
This specifies the storage aggregate on which the volume is to be created. This parameter only applies to FlexVol volumes.
| -aggr-list <aggregate name>, ... - List of Aggregates for FlexGroup Constituents
Specifies an array of names of aggregates to be used for FlexGroup constituents. Each entry in the list will create a constituent on the specified aggregate. An aggregate may be specified multiple times to have multiple constituents created on it. This parameter only applies to FlexGroups.
[-aggr-list-multiplier <integer>] - Aggregate List Repeat Count
Specifies the number of times to iterate over the aggregates listed with the -aggr-list parameter when creating a FlexGroup. The aggregate list will be repeated the specified number of times. Example:
-aggr-list aggr1,aggr2 -aggr-list-multiplier 2
will cause four constituents to be created in the order aggr1, aggr2, aggr1, aggr2.

The default value is 4.

This parameter only applies to FlexGroups

| -auto-provision-as <FlexGroup> - Automatically Provision as Volume of Type

Use this parameter to automatically select existing aggregates for provisioning FlexGroup volumes. Note that the fastest aggregate type with at least one aggregate on each node of the cluster will be selected. When auto provisioning a FlexGroup volume, the size of the FlexGroup volume should be a minimum of 800 GB per node.

This parameter only applies to FlexGroups.

[-support-tiering {true|false}] - Automatically Provision FlexGroup on FabricPools

This parameter specifies whether or not FabricPools are selected when provisioning a FlexGroup during the protection workflows using the auto-provision-as parameter. Only FabricPool aggregates are used if this parameter is set to true and only non FabricPool aggregates are used if this parameter is set to false. Tiering support for a FlexGroup can be changed by moving all of the constituents to the required aggregates. The default value is false

This parameter only applies to FlexGroups created using the -auto-provision-as parameter.

[-nodes {<nodename>|local}, ...]} - List of Nodes Hosting the Volume
Specifies an array of node names to be used for provisioning the FlexGroup. If an array of node names is specified, only aggregates from the specified nodes will be considered for provisioning. If no value is specified, all nodes in the cluster will be used.
[-size {<integer>[KB|MB|GB|TB|PB]}] - Volume Size
This optionally specifies the size of the volume. The size is specified as a number followed by a unit designation: k (kilobytes), m (megabytes), g (gigabytes), or t (terabytes). If the unit designation is not specified, bytes are used as the unit, and the specified number is rounded up to the nearest 4 KB. The minimum size for a FlexVol volume is 20 MB. The minimum size for a volume guaranteed FlexGroup is 20 MB per constituent. The minimum size for a none guaranteed FlexGroup is 200 MB per constituent. However, the recommended size for all FlexGroups is a minimum of 100 GB per constituent. For all volumes, the default size is set to the minimum size. The volume's maximum size is limited by the platform maximum. If the volume's guarantee is set to volume, the volume's maximum size can also be limited by the available space in the hosting aggregates. Volumes can be increased and decreased in size with the volume modify command. The maximum number of files a volume is configured for is listed under "Total Files" when running the command volume show -instance.
[-state {online|restricted|offline|force-online|force-offline|mixed}] - Volume State
This optionally specifies the volume's state. A restricted volume does not provide client access to data but is available for administrative operations.
Note: The mixed state applies to FlexGroups only and cannot be specified as a target state.
[-policy <text>] - Export Policy
This optionally specifies the ID number of the export policy associated with the volume. For information on export policies, see the documentation for the vserver export-policy create command. FlexGroups do not support policies that allow NFSv4 protocol access.
[-user <user name>] - User ID
This optionally specifies the name or ID of the user that is set as the owner of the volume's root.
[-group <group name>] - Group ID
This optionally specifies the name or ID of the group that is set as the owner of the volume's root.
[-security-style <security style>] - Security Style
This optionally specifies the security style for the volume. Possible values include unix (for UNIX mode bits), ntfs (for CIFS ACLs), mixed (for mixed NFS and CIFS permissions) and unified (for mixed NFS and CIFS permissions with unified ACLs). Regardless of the security style, both NFS and CIFS clients can read from and write to the volume.
[-unix-permissions <unix perm>] - UNIX Permissions
This optionally specifies the default UNIX permissions for files on the volume. Specify UNIX permissions either as a four-digit octal value (for example, 0700) or in the style of the UNIX ls command (for example, -rwxr-x---). For information on UNIX permissions, see the UNIX or Linux documentation. The default setting is 0755 or ---rwxr-xr-x.
[-junction-path <junction path>] - Junction Path
This optionally specifies the volume's junction path. The junction path name is case insensitive and must be unique within a Vserver's namespace.
[-junction-active {true|false}] - Junction Active (privilege: advanced)
This optionally specifies whether the volume's junction path is active. The default setting is true. If the junction path is inactive, the volume does not appear in the Vserver's namespace. This parameter is available only at the advanced privilege level and higher.
[-vsroot {true|false}] - Vserver Root Volume (privilege: advanced)
This optionally specifies whether the volume is the root volume of its Vserver. The default setting is false. If this parameter is set to true, the default size of the newly created volume is 1GB. This parameter is not supported on FlexGroups.
[-comment <text>] - Comment
This optionally specifies a comment for the volume.
[-max-autosize {<integer>[KB|MB|GB|TB|PB]}] - Maximum Autosize
This parameter allows the user to specify the maximum size to which a volume can grow. The default for volumes is 120% of the volume size. If the value of this parameter is invalidated by manually resizing the volume, the maximum size is reset to 120% of the volume size. The value for -max-autosize cannot be set larger than the platform-dependent maximum volume size. If you specify a larger value, the value of -max-autosize is automatically reset to the supported maximum without returning an error.
[-min-autosize {<integer>[KB|MB|GB|TB|PB]}] - Minimum Autosize
This parameter specifies the minimum size to which the volume can automatically shrink. If the volume was created with the grow_shrink autosize mode enabled, then the default minimum size is equal to the initial volume size. If the value of the -min-autosize parameter is invalidated by a manual volume resize, the minimum size is reset to the volume size.
[-autosize-grow-threshold-percent <percent>] - Autosize Grow Threshold Percentage
This parameter specifies the used space threshold for the automatic growth of the volume. When the volume’s used space becomes greater than this threshold, the volume will automatically grow unless it has reached the maximum autosize.
[-autosize-shrink-threshold-percent <percent>] - Autosize Shrink Threshold Percentage
This parameter specifies the used space threshold for the automatic shrinking of the volume. When the amount of used space in the volume drops below this threshold, the volume will shrink unless it has reached the specified minimum size.
[-autosize-mode {off|grow|grow_shrink}] - Autosize Mode
This parameter specifies the autosize mode for the volume. The supported autosize modes are:
  • off - The volume will not grow or shrink in size in response to the amount of used space.
  • grow - The volume will automatically grow when used space in the volume is above the grow threshold.
  • grow_shrink - The volume will grow or shrink in size in response to the amount of used space.
By default, -autosize-mode is off for new volumes, except for data protection mirrors, for which the default value is grow_shrink. The grow and grow_shrink modes work together with Snapshot autodelete to automatically reclaim space when a volume is about to become full. The volume parameter -space-mgmt-try-first controls the order in which these two space reclamation policies are attempted.
[-maxdir-size {<integer>[KB|MB|GB|TB|PB]}] - Maximum Directory Size (privilege: advanced)
This optionally specifies the maximum directory size. The default maximum directory size is model-dependent and optimized for the size of system memory.
{ [-space-slo {none|thick|semi-thick}] - Space SLO
This optionally specifies the Service Level Objective for space management (the space SLO setting) for the volume. The space SLO value is used to enforce volume settings so that sufficient space is set aside to meet the space SLO. The default setting is none. There are three supported values: none, thick and semi-thick.
  • none: The value of none does not provide any guarantee for overwrites or enforce any restrictions. It should be used if the admin plans to manually manage space consumption in the volume and aggregate, and out of space errors.
  • thick: The value of thick guarantees that the hole fills and overwrites to space-reserved files in this volume will always succeed by reserving space. To meet this space SLO, the following volume-level settings are automatically set and cannot be modified:
    • Space Guarantee: volume - The entire size of the volume is preallocated in the aggregate. Changing the volume's space-guarantee type is not supported.
    • Fractional Reserve: 100 - 100% of the space required for overwrites is reserved. Changing the volume's fractional-reserve setting is not supported.
  • semi-thick: The value of semi-thick is a best-effort attempt to ensure that overwrites succeed by restricting the use of features that share blocks and auto-deleting backups and Snapshot copies in the volume. To meet this space SLO, the following volume-level settings are automatically set and cannot be modified:
    • Space Guarantee: volume - The entire size of the volume is preallocated in the aggregate. Changing the volume's space-guarantee type is not supported.
    • Fractional Reserve: 0 - No space will be reserved for overwrites by default. However, changing the volume's fractional-reserve setting is supported. Changing the setting to 100 means that 100% of the space required for overwrites is reserved.
    • Snapshot Autodelete: enabled - Automatic deletion of Snapshot copies is enabled to reclaim space. To ensure that the overwrites can be accommodated when the volume reaches threshold capacity, the following volume snapshot autodelete parameters are set automatically to the specified values and cannot be modified:
      • enabled: true
      • commitment: destroy
      • trigger: volume
      • defer-delete: none
      • destroy-list: vol_clone, lun_clone, file_clone, cifs_share
    In addition, with a value of semi-thick, the following technologies are not supported for the volume:
    • File Clones with autodelete disabled: Only full file clones of files, LUNs or NVMe namespaces that can be autodeleted can be created in the volume. The use of autodelete for file clone create is required.
    • Partial File Clones: Only full file clones of files or LUNs that can be autodeleted can be created in the volume. The use of range for file clone create is not supported.
    • Volume Efficiency: Enabling volume efficiency is not supported to allow autodeletion of Snapshot copies.
| [-space-guarantee | -s {none|volume}] - Space Guarantee Style
This optionally specifies the space guarantee style for the volume. A value of volume reserves space on the aggregates for the entire volume. A value of none reserves no space on the aggregates, meaning that writes can fail if an aggregate runs out of space. Because CIFS does not handle out-of-space conditions, do not use the value none if the volume is accessible to CIFS clients. The default setting for the volumes on All Flash FAS systems is none, otherwise the default setting is volume. The file setting is no longer supported.
[-type {RW|DP}]} - Volume Type
This optionally specifies the volume's type, either read-write (RW) or data-protection (DP). If you do not specify a value for this parameter, a RW volume is created by default.
[-percent-snapshot-space <percent>] - Space Reserved for Snapshot Copies
This optionally specifies the amount of space that is reserved in the volume for Snapshot copies. The default setting is 5 percent, except for data protection mirrors for which the default is 0 percent.
[-snapshot-policy <snapshot policy>] - Snapshot Policy
This optionally specifies the Snapshot policy for the volume. The default is the Snapshot policy for all volumes on the Vserver, as specified by the -snapshot-policy parameter of the vserver create and vserver modify commands. The schedules associated with the snapshot-policy for a FlexGroup cannot have an interval shorter than 30 minutes.
[-language <Language code>] - Language
This optionally specifies the language encoding setting for the volume. By default, the volume inherits the Vserver language encoding setting.
Note: You cannot modify the language encoding setting of a volume.
[-foreground {true|false}] - Foreground Process
This specifies whether the operation runs in the foreground. The default setting is true (the operation runs in the foreground). When set to true, the command will not return until the operation completes. This parameter applies only to FlexGroups. For FlexVol volumes, the command always runs in the foreground.
[-nvfail {on|off}] - NVFAIL Option
Setting this optional parameter to true causes the volume to set the in-nvfailed-state flag to true, if committed writes to the volume are lost due to a failure. The in-nvfailed-state flag fences the volume from further data access and prevents possible corruption of the application data. Without specifying a value, this parameter is automatically set to false.
[-constituent-role <Constituent Roles>] - Constituent Volume Role
This parameter is no longer supported.
{ [-qos-policy-group <text>] - QoS Policy Group Name
This optional parameter specifies which QoS policy group to apply to the volume. This policy group defines measurable service level objectives (SLOs) that do not adjust based on the volume allocated space or used space. If you do not assign a policy group to a volume, the system will not monitor and control the traffic to it.
| [-qos-adaptive-policy-group <text>]} - QoS Adaptive Policy Group Name
This optional parameter specifies which QoS adaptive policy group to apply to the volume. This policy group defines measurable service level objectives (SLOs) and Service Level Agreements (SLAs) that adjust based on the volume allocated space or used space.
[-caching-policy <text>] - Caching Policy Name
This optionally specifies the caching policy to apply to the volume. A caching policy defines how the system caches this volume's data in a Flash Pool aggregate or Flash Cache modules. If a caching policy is not assigned to this volume, the system uses auto as the default caching policy.
Both metadata and user data are eligible for caching. Metadata consists of directories, indirect blocks and system metafiles. They are eligible for read caching only. When a random write pattern is detected on user data, the first such write is eligible for read caching while all subsequent overwrites are eligible for write caching. The available caching policies are:
  • none - Does not cache any user data or metadata blocks.
  • auto - Read caches all metadata and randomly read user data blocks, and write caches all randomly overwritten user data blocks.
  • meta - Read caches only metadata blocks.
  • random_read - Read caches all metadata and randomly read user data blocks.
  • random_read_write - Read caches all metadata, randomly read and randomly written user data blocks.
  • all_read - Read caches all metadata, randomly read and sequentially read user data blocks.
  • all_read_random_write - Read caches all metadata, randomly read, sequentially read and randomly written user data.
  • all - Read caches all data blocks read and written. It does not do any write caching.
  • noread-random_write - Write caches all randomly overwritten user data blocks. It does not do any read caching.
  • meta-random_write - Read caches all metadata and write caches randomly overwritten user data blocks.
  • random_read_write-random_write - Read caches all metadata, randomly read and randomly written user data blocks. It also write caches randomly overwritten user data blocks.
  • all_read-random_write - Read caches all metadata, randomly read and sequentially read user data blocks. It also write caches randomly overwritten user data blocks.
  • all_read_random_write-random_write - Read caches all metadata, randomly read, sequentially read and randomly written user data. It also write caches randomly overwritten user data blocks.
  • all-random_write - Read caches all data blocks read and written. It also write caches randomly overwritten user data blocks.
Note that in a caching-policy name, a hyphen (-) separates read and write policies. Default caching-policy is auto.
[-cache-retention-priority {normal|low|high}] - Cache Retention Priority (privilege: advanced)
This optionally specifies the cache retention priority to apply to the volume. A cache retention priority defines how long the blocks of a volume will be cached in flash pool once they become cold. If a cache retention priority is not assigned to this volume, the system uses the default policy. This parameter is available only at the advanced privilege level and higher.
The available cache retention priority are:
  • low - Cache the cold blocks for the lowest time.
  • normal - Cache the cold blocks for the default time.
  • high - Cache the cold blocks for the highest time.
[-is-autobalance-eligible {true|false}] - Is Eligible for Auto Balance Aggregate (privilege: advanced)
If the Auto Balance feature is enabled, this parameter specifies whether the volume might be considered for system workload balancing. When set to true, the Auto Balance Aggregate feature might recommend moving this volume to another aggregate. The default value is true.
[-max-constituent-size {<integer>[KB|MB|GB|TB|PB]}] - Maximum size of a FlexGroup Constituent (privilege: advanced)
This optionally specifies the maximum size of a FlexGroup constituent. The default value is determined by checking the maximum FlexVol size setting on all nodes used by the FlexGroup. The smallest value found is selected as the default for the -max-constituent-size for the FlexGroup. This parameter applies to FlexGroups only.
[-efficiency-policy <efficiency policy>] - Storage Efficiency Policy (privilege: advanced)
This optionally specifies which storage efficiency policy to apply to the volume. This parameter is applicable only for All-Flash FAS. This parameter is not supported on data protection volumes on any platform. To disable compression on the volume in All-Flash FAS, use the value none. The default value is inline-only.
[-vserver-dr-protection {protected|unprotected}] - Vserver DR Protection
This optionally specifies whether the volume should be protected by Vserver level SnapMirror. This parameter is applicable only if the Vserver is the source of a Vserver level SnapMirror relationship. The default value for a volume of type “RW” is protected.
[-encrypt [true]] - Enable Encryption
This parameter allows the user to create an encrypted volume. When it is set to true, a new key is generated, and the volume will be encrypted using the generated key. By default, volume created is not encrypted.
[-is-space-reporting-logical {true|false}] - Logical Space Reporting
This optionally specifies whether to report space logically on the volume. When space is reported logically, ONTAP reports the volume space such that all the physical space saved by the storage efficiency features are also reported as used. This parameter is not supported on FlexGroups. The default setting is false.
[-is-space-enforcement-logical {true|false}] - Logical Space Enforcement
This optionally specifies whether to perform logical space accounting on the volume. When space is enforced logically, ONTAP enforces volume settings such that all the physical space saved by the storage efficiency features will be calculated as used. This parameter is not supported on FlexGroups. The default setting is false.
[-tiering-policy {snapshot-only|auto|none|backup}] - Volume Tiering Policy
This optional parameter specifies the tiering policy to apply to the volume. This policy determines whether the user data blocks of a volume in a FabricPool will be tiered to the capacity tier when they become cold. FabricPool combines flash (performance tier) with an object store (external capacity tier) into a single aggregate. The default tiering policy is 'snapshot-only' for a FlexVol and 'none' for a FlexGroup. Temperature of a volume block increases if it is accessed frequently and decreases when it is not.
The available tiering policies are:
  • snapshot-only - This policy allows tiering of only the volume Snapshot copies not associated with the active file system. The default minimum cooling period is 2 days. The -tiering-minimum-cooling-days parameter can be used to override the default.
  • auto - This policy allows tiering of both snapshot and active file system user data to the capacity tier. The default cooling period is 31 days. The -tiering-minimum-cooling-days parameter can be used to override the default.
  • none - Volume blocks will not be tiered to the capacity tier.
  • backup - On DP volumes this policy allows all transferred user data blocks to start in the capacity tier.
[-tiering-minimum-cooling-days <integer>] - Volume Tiering Minimum Cooling Days (privilege: advanced)
This optional parameter specifies the minimum number of days that user data blocks of the volume must be cooled before they can be considered cold and tiered out to the capacity tier. This parameter is only used for tiering purpose and does not affect the reporting of inactive data. The value specified should be greater than the frequency that applications in the volume shift between different sets of data. Valid values are between 2 and 63. You cannot set this parameter on 'none' or 'backup' volume tiering policy. The default value for this option is tied to the volume's tiering-policy. See the tiering-policy section of this man page for corresponding default values. If the tiering policy on the volume gets changed, then this option will be reset to the default value corresponding to the new tiering policy.

Examples

Specifies the number of times to iterate over the aggregates listed with the -aggr-list parameter when creating a FlexGroup. The aggregate list will be repeated the specified number of times. Example:
-aggr-list aggr1,aggr2 -aggr-list-multiplier 2
The following example creates a new volume named user_jdoe on a Vserver named vs0 and a storage aggregate named aggr1. Upon its creation, the volume is placed in the online state. It uses the export policy named default_expolicy. The owner of the volume's root is a user named jdoe whose primary group is named dev. The volume's junction path is /user/jdoe. The volume is 250 GB in size, space for the entire volume is reserved on the aggregate, and the create operation runs in the background.
cluster1::> volume create -vserver vs0 -volume user_jdoe -aggregate aggr1 
            -state online -policy default_expolicy -user jdoe -group dev
            -junction-path /user/jdoe -size 250g  -space-guarantee volume 
            -percent-snapshot-space 20 -foreground false
        
The following example creates a new volume named vol_cached on a Vserver named vs0 and a Flash Pool storage aggregate named aggr1. The newly created volume is placed online and uses auto as the caching policy.
cluster1::> volume create -vserver vs0 -volume vol_cached -aggregate aggr1 
            -state online -caching-policy auto
        
The following example creates a new FlexGroup named media_vol on a Vserver named vs0 with four constituents on aggregates aggr1 and aggr2. Upon its creation, the volume is placed in the online state. The volume's junction path is /media. The volume is 200 TB in size, no space for the volume is reserved on the aggregates, and the create operation runs in the background.
cluster1::> volume create -vserver vs0 -volume media_vol 
            -aggr-list aggr1,aggr1,aggr2,aggr2 -junction-path /media -size 200TB 
            -space-guarantee none -foreground false
        
The following example creates a new FlexGroup volume named fg on a Vserver named vs0 on aggregates selected by Data ONTAP.
cluster1::> volume create -vserver vs0 -volume fg -auto-provision-as flexgroup