Pre-populate a FlexCache volume in the cluster

09/11/2024 Contributors

PDFs

PATCH /storage/flexcache/flexcaches/{uuid}

Introduced In: 9.8

Prepopulates a FlexCache volume in the cluster, or modifies configuration of the FlexCache volume.

Required properties

uuid - FlexCache volume UUID.

Recommended optional properties

prepopulate.exclude_dir_paths - List of directory-paths to be excluded from prepopulation for the FlexCache volume.
prepopulate.dir_paths - List of directory-paths to be prepopulated for the FlexCache volume.
writeback.enabled - false. This property specifies whether writeback is enabled for the FlexCache volume.
relative_size.enabled - This property specifies whether the relative sizing is enabled for the FlexCache volume.
relative_size.percentage - This property specifies the percent size FlexCache volume should have relative to the total size of the origin volume.
atime_scrub.enabled - This property specifies whether the atime based scrub is enabled for the FlexCache volume.
atime_scrub.period - This property specifies the duration in days after which inactive files can be scrubbed from FlexCache volume.
cifs_change_notify.enabled - This property specifies whether a CIFS change notification is enabled for the FlexCache volume.

Default property values

If not specified in PATCH, the following default property value is assigned:

prepopulate.recurse - Default value is "true".

volume flexcache prepopulate start
volume flexcache config modify

Learn more

DOC /storage/flexcache/flexcaches

Parameters

Name	Type	In	Required	Description
uuid	string	path	True	Unique identifier of the FlexCache volume.
return_timeout	integer	query	False	The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202. Default value: 1 Max value: 120 Min value: 0

Name

Type

Required

Description

uuid

string

path

True

Unique identifier of the FlexCache volume.

return_timeout

integer

query

False

The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202.

Default value: 1
Max value: 120
Min value: 0

Request Body

Name	Type	Description
_links	_links
aggregates	array[aggregates]
atime_scrub	atime_scrub	FlexCache volume atime-based scrub
cifs_change_notify	cifs_change_notify	Notifies that a change has been made to the FlexCache volume CIFS.
constituents_per_aggregate	integer	Number of FlexCache constituents per aggregate when the 'aggregates' field is mentioned.
dr_cache	boolean	If set to true, a DR cache is created.
global_file_locking_enabled	boolean	Specifies whether or not a FlexCache volume has global file locking mode enabled. Global file locking mode is a mode where protocol read locking semantics are enforced across all FlexCaches and origins of a FlexCache volume. When global file locking mode is enabled, the "is_disconnected_mode_off_for_locks" flag is always set to "true".
guarantee	guarantee
name	string	FlexCache name
origins	array[flexcache_relationship]
override_encryption	boolean	If set to true, a plaintext FlexCache volume for an encrypted origin volume is created.
path	string	The fully-qualified path in the owning SVM's namespace at which the FlexCache is mounted. The path is case insensitive and must be unique within a SVM's namespace. Path must begin with '/' and must not end with '/'. Only one FlexCache be mounted at any given junction path.
prepopulate	prepopulate	FlexCache prepopulate
relative_size	relative_size	FlexCache Relative Size
size	integer	Physical size of the FlexCache. The recommended size for a FlexCache is 10% of the origin volume. The minimum FlexCache constituent size is 1GB.
svm	svm	FlexCache SVM
use_tiered_aggregate	boolean	Specifies whether or not a Fabricpool-enabled aggregate can be used in FlexCache creation. The use_tiered_aggregate is only used when auto-provisioning a FlexCache volume.
uuid	string	FlexCache UUID. Unique identifier for the FlexCache.
writeback	writeback	FlexCache Writeback

Name

Type

Description

_links

aggregates

array[aggregates]

atime_scrub

FlexCache volume atime-based scrub

cifs_change_notify

Notifies that a change has been made to the FlexCache volume CIFS.

constituents_per_aggregate

integer

Number of FlexCache constituents per aggregate when the 'aggregates' field is mentioned.

dr_cache

boolean

If set to true, a DR cache is created.

global_file_locking_enabled

boolean

Specifies whether or not a FlexCache volume has global file locking mode enabled. Global file locking mode is a mode where protocol read locking semantics are enforced across all FlexCaches and origins of a FlexCache volume. When global file locking mode is enabled, the "is_disconnected_mode_off_for_locks" flag is always set to "true".

guarantee

name

string

FlexCache name

origins

array[flexcache_relationship]

override_encryption

boolean

If set to true, a plaintext FlexCache volume for an encrypted origin volume is created.

path

string

The fully-qualified path in the owning SVM's namespace at which the FlexCache is mounted. The path is case insensitive and must be unique within a SVM's namespace. Path must begin with '/' and must not end with '/'. Only one FlexCache be mounted at any given junction path.

prepopulate

FlexCache prepopulate

relative_size

FlexCache Relative Size

size

integer

Physical size of the FlexCache. The recommended size for a FlexCache is 10% of the origin volume. The minimum FlexCache constituent size is 1GB.

svm

FlexCache SVM

use_tiered_aggregate

boolean

Specifies whether or not a Fabricpool-enabled aggregate can be used in FlexCache creation. The use_tiered_aggregate is only used when auto-provisioning a FlexCache volume.

uuid

string

FlexCache UUID. Unique identifier for the FlexCache.

writeback

FlexCache Writeback

Example request

{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "aggregates": [
    {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "aggr1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    }
  ],
  "guarantee": {
    "type": "string"
  },
  "name": "vol1",
  "origins": [
    {
      "cluster": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "cluster1",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "create_time": "2018-06-04 15:00:00 -0400",
      "ip_address": "10.10.10.7",
      "size": 0,
      "state": "string",
      "svm": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "svm1",
        "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
      },
      "volume": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "volume1",
        "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
      }
    }
  ],
  "path": "/user/my_fc",
  "prepopulate": {
    "dir_paths": [
      "/dir1"
    ],
    "exclude_dir_paths": [
      "/dir1/dir2"
    ]
  },
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
}

Response

Status: 200, Ok

Name	Type	Description
job	job_link

Name

Type

Description

job

job_link

Example response

{
  "job": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "uuid": "string"
  }
}

Response

Status: 202, Accepted

Error

Status: Default

ONTAP Error Response Codes

Error Code	Description
66846921	Failed to prepopulate. Empty path list
66846922	FlexCache volume does not exist in the SVM
66846923	Failed to prepopulate FlexCache volume because the origin volume is not reachable
66846924	FlexCache volume is offline
66846925	FlexCache volume is not mounted or the junction-path is not active
66846926	The junction-path of FlexCache volume is not active
66846927	FlexCache volume does not have an origin volume
66846928	FlexCache volume does not exist
66846929	Using FlexCache prepopulate requires an effective cluster version of 9.8.0 or later
66846930	Using FlexCache prepopulate in a MetroCluster configuration requires an effective cluster version of 9.8.0 or later on both the local and remote clusters
66846931	Internal Error. FlexCache prepopulate job queue failed. Wait a few minutes, and then try the operation again
66846936	Failed to lookup root file handle for origin of FlexCache volume. Wait a few minutes, and then try the operation again
66846937	Internal error. Failed to initialize thread
66846939	Internal error. Failed to get the MSID of the origin volume for FlexCache volume
66846943	Failed to prepopulate because dir_path does not exist
66846944	Failed to get root constituent for FlexCache volume
66846945	Origin of FlexCache volume is not mounted or the junction-path is not active
66846946	The junction-path of origin of FlexCache volume is not active
66846947	FlexCache prepopulate job for FlexCache volume already exists
66846948	FlexCache prepopulate job for FlexCache volume could not be queued because the node is offline
66846958	Exclude path(s) does not exist in origin volume
66846988	Cannot enable writeback for FlexCache volume because the origin is a data protection volume. Writeback is only supported on FlexCache volumes with origins that are read-write volumes
66846995	Using FlexCache relative-size requires an effective cluster version of 9.13.1 or later
66846997	Failed to modify the relative-size-percentage property of the FlexCache volume because the used size of the FlexCache Volume is greater than the newly calculated size based on the value of the relative-size-percentage property
66846997	Failed to modify the relative-size-percentage property of FlexCache volume because the relative-size-percentage property is not valid
66846998	Failed to modify the relative-size-percentage property of FlexCache volume because the is-relative-size-enabled property is false
66847010	Failed to modify the relative-size-percentage property of FlexCache volume because autosize is enabled on the FlexCache volume
66847026	Failed to enable the atime-scrub-enabled property for the FlexCache volume because the atime-update-property is false
66847027	Failed to modify atime-scrub-period property of the FlexCache volume because the atime-scrub-enabled property is false

Name	Type	Description
error	returned_error

Name

Type

Description

error

returned_error

Example error

{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name	Type	Description
href	string

Name

Type

Description

href

string

_links

Name	Type	Description
self	href

Name

Type

Description

self

href

aggregates

Aggregate

Name	Type	Description
_links	_links
name	string
uuid	string

Name

Type

Description

_links

name

string

uuid

string

atime_scrub

FlexCache volume atime-based scrub

Name	Type	Description
enabled	boolean	Specifies whether scrubbing of inactive files based on atime is enabled for the FlexCache volume. When scrubbing is enabled, file

Name

Type

Description

enabled

boolean

Specifies whether scrubbing of inactive files based on atime is enabled for the FlexCache volume. When scrubbing is enabled, file

Pre-populate a FlexCache volume in the cluster

Creating your file...

Required properties

Recommended optional properties

Default property values

Related ONTAP commands

Learn more

Parameters

Request Body

Response

Response

Error

Definitions