# pool.create

Create a new ZFS Pool.

This method is a job.

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: data

#### data

Type: object

Configuration for creating a new storage pool.

No Additional Properties

##

#### Name

Type: string

Name for the new storage pool.

Must be at least `1` characters long

##

#### Encryption

Type: boolean Default: false

If set, create a ZFS encrypted root dataset for this pool.

##

#### Dedup Table Quota

Type: enum (of null or string) Default: "AUTO"

How to manage the deduplication table quota allocation.

##### Must be one of:

- "AUTO"
- "CUSTOM"
- null

##

#### Dedup Table Quota Value

Default: null

Custom quota value in bytes when `dedup_table_quota` is set to CUSTOM.

## Any of

Type: integer

Value must be strictly greater than `0`

Type: null

##

#### Deduplication

Type: enum (of null or string) Default: null

Make sure no block of data is duplicated in the pool. If set to `VERIFY` and two blocks have similar signatures, byte-to-byte comparison is performed to ensure that the blcoks are identical. This should be used in special circumstances as it carries a significant overhead.

##### Must be one of:

- "ON"
- "VERIFY"
- "OFF"
- null

##

#### Checksum

Type: enum (of null or string) Default: null

Checksum algorithm to use for data integrity verification.

##### Must be one of:

- "ON"
- "OFF"
- "FLETCHER2"
- "FLETCHER4"
- "SHA256"
- "SHA512"
- "SKEIN"
- "EDONR"
- "BLAKE3"
- null

##

#### PoolCreateEncryptionOptions

Type: object

Specify configuration for encryption of root dataset.

No Additional Properties

##

#### Generate Key

Type: boolean Default: false

Automatically generate the key to be used for dataset encryption.

##

#### Pbkdf2Iters

Type: integer Default: 1300000

Number of PBKDF2 iterations for key derivation from passphrase. Higher iterations improve security against brute force attacks but increase unlock time.

Value must be greater or equal to `1300000`

##

#### Algorithm

Type: enum (of string) Default: "AES-256-GCM"

Encryption algorithm to use for dataset encryption.

##### Must be one of:

- "AES-128-CCM"
- "AES-192-CCM"
- "AES-256-CCM"
- "AES-128-GCM"
- "AES-192-GCM"
- "AES-256-GCM"

##

#### Passphrase

Default: null

Must be specified if encryption for root dataset is desired with a passphrase as a key.

## Any of

Type: string

Must be at least `8` characters long

Type: null

##

#### Key

Default: null

A hex-encoded key specified as an alternative to using `passphrase`.

## Any of

Type: string

Must be at least `64` characters long

Must be at most `64` characters long

Type: null

##

#### PoolCreateTopology

Type: object

Physical layout and configuration of vdevs in the pool.

No Additional Properties
Example:

    {
        "cache": [
            {
                "disks": [
                    "da4"
                ],
                "type": "STRIPE"
            }
        ],
        "data": [
            {
                "disks": [
                    "da1",
                    "da2",
                    "da3"
                ],
                "type": "RAIDZ1"
            }
        ],
        "log": [
            {
                "disks": [
                    "da5"
                ],
                "type": "STRIPE"
            }
        ],
        "spares": [
            "da6"
        ]
    }

##

#### Data

Type: array

All vdevs must be of the same `type`.

Must contain a minimum of `1` items

No Additional Items

##### Each item of this array must be:

## One of

#### PoolCreateTopologyVdevDRAID

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of distributed RAID configuration.

##### Must be one of:

- "DRAID1"
- "DRAID2"
- "DRAID3"

##

#### Disks

Type: array of string

Array of disk names to use in this DRAID vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Draid Data Disks

Default: null

Defaults to `zfs.VDEV_DRAID_MAX_CHILDREN`.

## Any of

Type: integer
Type: null

##

#### Draid Spare Disks

Type: integer Default: 0

Number of distributed spare disks in the DRAID configuration.

#### PoolCreateTopologyVdevNonDRAID

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of vdev configuration.

##### Must be one of:

- "RAIDZ1"
- "RAIDZ2"
- "RAIDZ3"
- "MIRROR"
- "STRIPE"

##

#### Disks

Type: array of string

Array of disk names to use in this vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Special

Type: array Default: []

Array of special vdev configurations for metadata storage.

No Additional Items

##### Each item of this array must be:

## One of

#### PoolCreateTopologyVdevDRAID

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of distributed RAID configuration.

##### Must be one of:

- "DRAID1"
- "DRAID2"
- "DRAID3"

##

#### Disks

Type: array of string

Array of disk names to use in this DRAID vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Draid Data Disks

Default: null

Defaults to `zfs.VDEV_DRAID_MAX_CHILDREN`.

## Any of

Type: integer
Type: null

##

#### Draid Spare Disks

Type: integer Default: 0

Number of distributed spare disks in the DRAID configuration.

#### PoolCreateTopologyVdevNonDRAID

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of vdev configuration.

##### Must be one of:

- "RAIDZ1"
- "RAIDZ2"
- "RAIDZ3"
- "MIRROR"
- "STRIPE"

##

#### Disks

Type: array of string

Array of disk names to use in this vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Dedup

Type: array of object Default: []

Array of deduplication table vdev configurations.

No Additional Items

##### Each item of this array must be:

#### PoolCreateTopologyDedupVdev

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of deduplication table vdev configuration.

##### Must be one of:

- "MIRROR"
- "STRIPE"

##

#### Disks

Type: array of string

Array of disk names to use in this dedup vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Cache

Type: array of object Default: []

Array of L2ARC cache vdev configurations.

No Additional Items

##### Each item of this array must be:

#### PoolCreateTopologyCacheVdev

Type: object
No Additional Properties

##

#### Type

Type: const

Type of L2ARC cache vdev configuration (always stripe).

Specific value: `"STRIPE"`

##

#### Disks

Type: array of string

Array of disk names to use in this cache vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Log

Type: array of object Default: []

Array of ZFS Intent Log (ZIL) vdev configurations.

No Additional Items

##### Each item of this array must be:

#### PoolCreateTopologyLogVdev

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of ZFS Intent Log (ZIL) vdev configuration.

##### Must be one of:

- "MIRROR"
- "STRIPE"

##

#### Disks

Type: array of string

Array of disk names to use in this log vdev.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Spares

Type: array of string Default: []

Array of spare disk names for the pool.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Allow Duplicate Serials

Type: boolean Default: false

Whether to allow disks with duplicate serial numbers in the pool.

##

#### All Sed

Type: boolean Default: false

When set, all disks in the pool must be SED based.

##

#### PoolEntry

Type: object

Information about the newly created pool.

No Additional Properties

##

#### Id

Type: integer

Unique identifier for this storage pool.

##

#### Name

Type: string

Name of the storage pool.

##

#### Guid

Type: string

Globally unique identifier (GUID) for this pool.

##

#### All Sed

Set when pool is made up of SED disks.

## Any of

Type: boolean
Type: null

##

#### Status

Type: string

Current status of the pool.

Examples:

    "ONLINE"

    "DEGRADED"

    "FAULTED"

##

#### Path

Type: string

Filesystem path where the pool is mounted.

##

Information about the most recent scrub or resilver operation. `null` if no scan data is available.

## Any of

#### PoolScan

Type: object
No Additional Properties

##

#### Function

Type: enum (of string)

Type of ZFS pool scan.

##### Must be one of:

- "RESILVER"
- "SCRUB"

##

#### State

Type: enum (of string)

Current lifecycle state of the scan.

##### Must be one of:

- "SCANNING"
- "FINISHED"
- "CANCELED"

##

#### Start Time

Type: string Format: date-time

Scan start time.

##

#### End Time

Scan end time (`null` while the scan is still running).

## Any of

Type: string Format: date-time
Type: null

##

#### Percentage

Type: number

Scan progress (between 0 and 100%).

##

#### Bytes To Process

Type: integer

Total bytes located by scanner.

##

#### Bytes Processed

Type: integer

Total bytes to scan.

##

#### Bytes Issued

Type: integer

Issued bytes per scan pass.

##

#### Pause

Pause time of a scrub pass (`null` if the scan is not paused).

## Any of

Type: string Format: date-time
Type: null

##

#### Errors

Type: integer

Number of scan errors.

##

#### Total Secs Left

Number of seconds left (`null` if the scan is not running).

## Any of

Type: integer
Type: null
Type: null

##

#### Expand

Information about any active pool expansion operation. `null` if no expansion is running.

## Any of

Type: object
Example:

    {
        "bytes_reflowed": 978944,
        "bytes_to_reflow": 835584,
        "end_time": null,
        "expanding_vdev": 0,
        "percentage": 85.35564853556485,
        "start_time": null,
        "state": "FINISHED",
        "total_secs_left": null,
        "waiting_for_resilver": 0
    }

Type: null

##

#### Is Upgraded

Type: boolean Default: false

Whether this pool has been upgraded to the latest feature flags.

##

#### Healthy

Type: boolean

Whether the pool is in a healthy state with no errors or warnings.

##

#### Warning

Type: boolean

Whether the pool has warning conditions that require attention.

##

#### Status Code

Detailed status code for the pool condition. `null` if not applicable.

## Any of

Type: string
Type: null

##

#### Status Detail

Human-readable description of the pool status. `null` if not available.

## Any of

Type: string
Type: null

##

#### Size

Total size of the pool in bytes. `null` if not available.

## Any of

Type: integer
Type: null

##

#### Allocated

Amount of space currently allocated in the pool in bytes. `null` if not available.

## Any of

Type: integer
Type: null

##

#### Free

Amount of free space available in the pool in bytes. `null` if not available.

## Any of

Type: integer
Type: null

##

#### Freeing

Amount of space being freed (in bytes) by ongoing operations. `null` if not available.

## Any of

Type: integer
Type: null

##

#### Dedup Table Size

Size of the deduplication table in bytes. `null` if deduplication is not enabled.

## Any of

Type: integer
Type: null

##

#### Dedup Table Quota

Quota limit for the deduplication table. `null` if no quota is set.

## Any of

Type: string
Type: null

##

#### Fragmentation

Percentage of pool fragmentation as a string. `null` if not available.

## Any of

Type: string
Type: null

##

#### Size Str

Human-readable string representation of the pool size. `null` if not available.

## Any of

Type: string
Type: null

##

#### Allocated Str

Human-readable string representation of allocated space. `null` if not available.

## Any of

Type: string
Type: null

##

#### Free Str

Human-readable string representation of free space. `null` if not available.

## Any of

Type: string
Type: null

##

#### Freeing Str

Human-readable string representation of space being freed. `null` if not available.

## Any of

Type: string
Type: null

##

#### Autotrim

Type: object

Auto-trim configuration for the pool indicating whether automatic TRIM operations are enabled.

Example:

    {
        "parsed": "off",
        "rawvalue": "off",
        "source": "DEFAULT",
        "value": "off"
    }

##

Physical topology and structure of the pool including vdevs. `null` if not available.

## Any of

#### PoolTopology

Type: object
No Additional Properties

##

#### Data

Type: array

Array of data vdev configurations in the pool.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Log

Type: array

Array of ZFS Intent Log (ZIL) vdev configurations.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Cache

Type: array

Array of L2ARC cache vdev configurations.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Spare

Type: array

Array of spare disk configurations.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Special

Type: array

Array of special vdev configurations for metadata.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Dedup

Type: array

Array of deduplication table vdev configurations.

No Additional Items

##### Each item of this array must be:

Type: object
Type: null

Required roles: POOL_WRITE