# 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: 350000

Number of PBKDF2 iterations for key derivation from passphrase. Higher iterations improve security against brute force attacks but increase unlock time. Default 350,000 balances security and performance.

Value must be greater or equal to `100000`

##

#### 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: stringFormat: date-time

Scan start time.

##

#### End Time

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

## Any of

Type: stringFormat: 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: stringFormat: 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