create_zone_pool.sh(8)

NAME

create_zone_pool.sh - create the zpool and datasets of a SYNC or ASYNC zone

SYNOPSIS

/opt/omnicube/sbin/create_zone_pool.sh -z zone [-s pool_size] [-k record_size] [-e]

DESCRIPTION

create_zone_pool.sh provisions the storage of one zone across every node of the cluster and then creates the two ZFS datasets the zone needs. It is an operator command, run once per zone at provisioning time.

The node list comes from the SMF property config/nodes of svc:/omnicube/sysadm:default, or of the instance named by OC_SMF_INSTANCE, read by the shared library into the nodes array. Each entry is the full host name and is used as the ssh target; pool, dataset and mount point paths use the short name, that is the entry truncated at the first hyphen. Remote privileged commands are run as pfexec on the peer. Every peer other than the local host must answer an ssh pre-flight probe before anything is created, because pool creation is an all-or-nothing operation spanning several nodes and a peer that turns out to be unreachable half way through leaves orphaned datasets, raw files and mounts behind with no automatic cleanup.

On every node, including the local one, the script first creates the dataset short_node/raw/zone mounted at /short_node/raw/zone and a sparse raw file /short_node/raw/zone/zone-disk0.raw of pool_size GB. What happens next depends on the mode.

SYNC mode (default)

One single zpool named after the zone is created on the local host as an n-way mirror of all the nodes' raw files. To make the peers' files visible locally, each peer's raw directory is NFS-mounted on the same path with

vers=4,rsize=131072,wsize=131072,actimeo=0,retry=36000,nocto,
timeo=60,noforcedirectio

and the local raw directory is created on each peer so the mount is symmetric. The pool is created with primarycache=metadata, mountpoint=none, compression=lz4, atime=off and autoexpand=on. Only the datasets zone/zones and zone/zones/zone are created afterwards, on the local host only, since the pool itself is shared.

ASYNC mode (-e)

No NFS mount and no mirror. An independent zpool named after the zone is created on each node from that node's own raw file, with the same pool properties. The zone/zones and zone/zones/zone datasets are created locally, and zone/zones is additionally created on every peer, so that replication with autosync(8) or manage_zone.sh -S has a place to land.

The shared run-level guard applies: the command exits 0 without doing anything when the host is at run level 0, 1, 5, 6, S or s, or when /etc/nologin exists, unless OC_IGNORE_RUNLEVEL is set.

OPTIONS

-z zone

Zone name. Mandatory. Used as the zpool name, as the raw LUN directory name and as the leaf dataset name. Must match [a-zA-Z0-9][a-zA-Z0-9._-]*.

-s pool_size

Size in GB of the raw file created on each node, and therefore of the resulting pool. Positive integer; default 100.

-k record_size

recordsize of the zone/zones/zone dataset, in KB; the value is passed to zfs create with a k suffix. Positive integer. When omitted, the internal value stays -1 and the dataset is created without an explicit recordsize, so it inherits the ZFS default of 128K.

-e

ASYNC mode: create one independent zpool per node instead of a single mirrored pool. Default is SYNC mode.

Any other option prints the usage summary and exits.

EXAMPLES

Example 1: a mirrored SYNC pool of the default size

create_zone_pool.sh -z zbeio01

Example 2: a 500 GB SYNC pool with a 4K record size for a database VM

create_zone_pool.sh -z zbeio01 -s 500 -k 4

Example 3: an ASYNC zone replicated between nodes

create_zone_pool.sh -z zfoo -s 200 -e

EXIT STATUS

0

The pool or pools and the datasets were created.

1

No zone name was given, an unknown option was used, or the per-node raw LUN creation failed.

2

The zone name, one of the node names from config/nodes, pool_size or record_size failed validation.

3

Pool creation failed: the mirrored zpool create in SYNC mode, or one of the per-node zpool create calls in ASYNC mode.

4

At least one peer did not pass the ssh pre-flight probe. Nothing was created.

78

Raised while sourcing the shared library when config/site is not set on the selected SMF instance.

The NFS mount phase of SYNC mode returns 2 from its own function, which the caller reports as exit status 3.

FILES

/opt/omnicube/sbin/create_zone_pool.sh

This command.

/opt/omnicube/lib/common/utils.sh

Shared library: SMF configuration, node list, logging, ssh helpers, validation, run-level guard.

/short_node/raw/zone/zone-disk0.raw

Raw file created on each node and used as a pool vdev.

/zones/zone

Mount point of the zone dataset created by this command.

ENVIRONMENT

OC_SMF_INSTANCE

Selects the svc:/omnicube/sysadm instance whose config/site and config/nodes properties are used.

OC_IGNORE_RUNLEVEL

When set to a non-empty value, bypasses the run-level guard.

SECURITY

All zfs, zpool, truncate, mkdir and mount calls run under pfexec, locally and on the peers, using the root-equivalent OmniCube Administration profile. The zone name, every node name read from config/nodes, and both numeric options are validated before they reach a privileged command line or an ssh command string. ssh runs with BatchMode=yes and StrictHostKeyChecking=yes, so each peer's host key must already be known.

SEE ALSO

omnicube_utils(3), oc_ssh(3), oc_validate(3), vm_tpl.cfg(5), omnicube(7), autosync(8), create_iscsi_lun.sh(8), create_zone_config.sh(8), manage_zone.sh(8), pool_monitor.sh(8), sync_pool.sh(8).

NOTES

The command is not idempotent and has no rollback. A failure after the raw files have been created leaves them, and any NFS mounts already made, in place on several nodes; clean up by hand before retrying. The status of the final dataset creation step is not checked either, so the command can exit 0 after the pool was built but zone/zones or zone/zones/zone failed; verify with zfs list -r afterwards.

In SYNC mode the pool exists on one node at a time only. It is the pool that manage_zone.sh -l hands over between nodes, and the NFS mounts are what make the mirror members of the other nodes reachable, so an actimeo=0 NFS path is on the write path of the zone: peer or network problems show up as pool latency. In ASYNC mode each node has its own pool and the zone data is moved by replication instead.

The record_size option only affects the leaf dataset zone/zones/zone and nothing else. The pool-wide properties, including compression=lz4, are fixed in the script.