# pool.create

Create a new ZFS Pool.

Create a pool named “tank”: RAIDZ1 with three disks, one cache disk, one ZIL/log disk, and one hot spare disk:

    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "pool.create",
        "params": [{
            "name": "tank",
            "topology": {
                "data": [
                    {"type": "RAIDZ1", "disks": ["da1", "da2", "da3"]}
                ],
                "cache": [
                    {"type": "STRIPE", "disks": ["da4"]}
                ],
                "log": [
                    {"type": "RAIDZ1", "disks": ["da5"]}
                ],
                "spares": ["da6"]
            }
        }]
    }

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

Must be at most `50` 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: ""

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: ""

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

#### PoolCreateTopologyDataVdevDRAID

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.

#### PoolCreateTopologyDataVdevNonDRAID

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 of object Default: []

Array of special vdev configurations for metadata storage.

No Additional Items

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

#### PoolCreateTopologySpecialVdev

Type: object
No Additional Properties

##

#### Type

Type: enum (of string)

Type of special vdev configuration for metadata storage.

##### Must be one of:

- "MIRROR"
- "STRIPE"

##

#### Disks

Type: array of string

Array of disk names to use in this special 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.

##

#### 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.

##

#### Status

Type: string

Current status of the pool.

Examples:

    "ONLINE"

    "DEGRADED"

    "FAULTED"

##

#### Path

Type: string

Filesystem path where the pool is mounted.

##

#### Scan

Information about any active scrub or resilver operation. `null` if no operation is running.

## Any of

Type: object
Example:

    {
        "bytes_issued": null,
        "bytes_processed": null,
        "bytes_to_process": null,
        "end_time": null,
        "errors": null,
        "function": null,
        "pause": null,
        "percentage": null,
        "start_time": null,
        "state": null,
        "total_secs_left": 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