.\" SPDX-License-Identifier: CDDL-1.0 .\" .\" CDDL HEADER START .\" .\" The contents of this file are subject to the terms of the .\" Common Development and Distribution License (the "License"). .\" You may not use this file except in compliance with the License. .\" .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE .\" or https://opensource.org/licenses/CDDL-1.0. .\" See the License for the specific language governing permissions .\" and limitations under the License. .\" .\" When distributing Covered Code, include this CDDL HEADER in each .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. .\" If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying .\" information: Portions Copyright [yyyy] [name of copyright owner] .\" .\" CDDL HEADER END .\" .\" Copyright 2013 Darik Horn . All rights reserved. .\" .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS .\" .Dd August 3, 2026 .Dt ZHACK 1 .Os OpenZFS . .Sh NAME .Nm zhack .Nd libzpool debugging tool .Sh DESCRIPTION This utility pokes configuration changes directly into a ZFS pool, which is dangerous and can cause data corruption. .Sh SYNOPSIS .Bl -tag -width Ds .It Xo .Nm zhack .Cm feature stat .Ar pool .Xc List feature flags. . .It Xo .Nm zhack .Cm feature enable .Op Fl d Ar description .Op Fl r .Ar pool .Ar guid .Xc Add a new feature to .Ar pool that is uniquely identified by .Ar guid , which is specified in the same form as a .Xr zfs 8 user property. .Pp The .Ar description is a short human readable explanation of the new feature. .Pp The .Fl r flag indicates that .Ar pool can be safely opened in read-only mode by a system that does not understand the .Ar guid feature. . .It Xo .Nm zhack .Cm feature ref .Op Fl d Ns | Ns Fl m .Ar pool .Ar guid .Xc Increment the reference count of the .Ar guid feature in .Ar pool . .Pp The .Fl d flag decrements the reference count of the .Ar guid feature in .Ar pool instead. .Pp The .Fl m flag indicates that the .Ar guid feature is now required to read the pool MOS. . .It Xo .Nm zhack .Cm label repair .Op Fl cu .Ar device .Xc Repair labels of a specified .Ar device according to options. .Pp Flags may be combined to do their functions simultaneously. . .Pp The .Fl c flag repairs corrupted label checksums . .Pp The .Fl u flag restores the label on a detached device .Pp Example: .Nm zhack Cm label repair Fl cu Ar device Fix checksums and undetach a device . .It Xo .Nm zhack .Cm mmp reclaim .Ar pool .Xc Import a .Ar pool whose uberblock claim cannot reach every mirror leg the configuration still expects to be present, then mark the unreachable leaves offline so that ordinary imports succeed, and export it again. .Pp This exists for one situation: a host has failed together with the mirror legs attached to it, so the surviving labels still describe those legs as healthy, and every later import demands writes to them that nobody can make. .Pp .Sy This does not make the operation safe on its own . A live host whose legs are .Em all invisible from here cannot be detected by any write and read scheme, and this command will take the pool from it. Fence the failed host, or otherwise prove it is powered off, before running this. .Pp The activity check itself is unchanged: every write the reachable legs allow, the wait, and the re-read all still happen, so a competing host which shares any leg with this one is still detected and the import is refused. Only the number of writes the claim demands is lowered, and only for mirror legs this host cannot open, each of which is then marked offline. .Pp The pool is left exported, and imports degraded with those leaves offline. Bring each one back with .Xr zpool-online 8 once the hardware returns. A leaf holding the only copy of some data cannot be offlined: it is reported and left online, and imports from other hosts stay refused. No leaf is marked offline on a pool which does not have .Sy multihost set, since no claim runs for it and an ordinary import already succeeds. Leaves of log, cache, and spare vdevs are not touched, as the claim does not write to them. . .It Xo .Nm zhack .Cm metaslab leak .Op Fl f .Ar pool .Xc Apply a fragmentation profile generated by .Sy zdb to the specified .Ar pool Ns \&. .Pp The .Fl f flag forces the profile to apply even if the vdevs in the .Ar pool don't have the same number of metaslabs as the fragmentation profile. . .El . .Sh GLOBAL OPTIONS The following can be passed to all .Nm invocations before any subcommand: .Bl -tag -width "-d dir" .It Fl c Ar cachefile Read .Ar pool configuration from the .Ar cachefile , which is .Pa /etc/zfs/zpool.cache by default. .It Fl d Ar dir Search for .Ar pool members in .Ar dir . Can be specified more than once. .It Fl o Ar var Ns = Ns Ar value Set the given tunable to the provided value. .El . .Sh EXAMPLES .Bd -literal .No # Nm zhack Cm feature stat Ar tank for_read_obj: org.illumos:lz4_compress = 0 for_write_obj: com.delphix:async_destroy = 0 com.delphix:empty_bpobj = 0 descriptions_obj: com.delphix:async_destroy = Destroy filesystems asynchronously. com.delphix:empty_bpobj = Snapshots use less space. org.illumos:lz4_compress = LZ4 compression algorithm support. .No # Nm zhack Cm feature enable Fl d No 'Predict future disk failures.' Ar tank com.example:clairvoyance .No # Nm zhack Cm feature ref Ar tank com.example:clairvoyance .Ed .Pp Recover a pool whose peer host died together with its mirror legs, after confirming that host is down: .Bd -literal .No # Nm zpool Cm import Fl f Ar tank cannot import 'tank': the multihost claim could not be written to a device the pool configuration expects to be present. If the device is permanently gone, recover with 'zhack mmp reclaim'. .No # Nm zhack Cm mmp reclaim Ar tank tank: marked absent leaf 5646371977210937898 offline .No # Nm zpool Cm import Ar tank .No # Nm zpool Cm online Ar tank Ar /dev/disk/by-id/... .Ed . .Sh SEE ALSO .Xr ztest 1 , .Xr zpool-features 7 , .Xr zpoolprops 7 , .Xr zfs 8 , .Xr zpool-import 8 , .Xr zpool-online 8