zpool-scrub.8 (4980B)
- .\"
- .\" 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 (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
- .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
- .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
- .\" Copyright (c) 2017 Datto Inc.
- .\" Copyright (c) 2018, 2021 George Melikov. All Rights Reserved.
- .\" Copyright 2017 Nexenta Systems, Inc.
- .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
- .\"
- .Dd November 18, 2024
- .Dt ZPOOL-SCRUB 8
- .Os
- .
- .Sh NAME
- .Nm zpool-scrub
- .Nd begin or resume scrub of ZFS storage pools
- .Sh SYNOPSIS
- .Nm zpool
- .Cm scrub
- .Op Ns Fl e | Ns Fl p | Fl s Ns | Fl C Ns
- .Op Fl w
- .Ar pool Ns …
- .
- .Sh DESCRIPTION
- Begins a scrub or resumes a paused scrub.
- The scrub examines all data in the specified pools to verify that it checksums
- correctly.
- For replicated
- .Pq mirror, raidz, or draid
- devices, ZFS automatically repairs any damage discovered during the scrub.
- The
- .Nm zpool Cm status
- command reports the progress of the scrub and summarizes the results of the
- scrub upon completion.
- .Pp
- Scrubbing and resilvering are very similar operations.
- The difference is that resilvering only examines data that ZFS knows to be out
- of date
- .Po
- for example, when attaching a new device to a mirror or replacing an existing
- device
- .Pc ,
- whereas scrubbing examines all data to discover silent errors due to hardware
- faults or disk failure.
- .Pp
- When scrubbing a pool with encrypted filesystems the keys do not need to be
- loaded.
- However, if the keys are not loaded and an unrepairable checksum error is
- detected the file name cannot be included in the
- .Nm zpool Cm status Fl v
- verbose error report.
- .Pp
- Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows
- one at a time.
- .Pp
- A scrub is split into two parts: metadata scanning and block scrubbing.
- The metadata scanning sorts blocks into large sequential ranges which can then
- be read much more efficiently from disk when issuing the scrub I/O.
- .Pp
- If a scrub is paused, the
- .Nm zpool Cm scrub
- resumes it.
- If a resilver is in progress, ZFS does not allow a scrub to be started until the
- resilver completes.
- .Pp
- Note that, due to changes in pool data on a live system, it is possible for
- scrubs to progress slightly beyond 100% completion.
- During this period, no completion time estimate will be provided.
- .
- .Sh OPTIONS
- .Bl -tag -width "-s"
- .It Fl s
- Stop scrubbing.
- .It Fl p
- Pause scrubbing.
- Scrub pause state and progress are periodically synced to disk.
- If the system is restarted or pool is exported during a paused scrub,
- even after import, scrub will remain paused until it is resumed.
- Once resumed the scrub will pick up from the place where it was last
- checkpointed to disk.
- To resume a paused scrub issue
- .Nm zpool Cm scrub
- or
- .Nm zpool Cm scrub
- .Fl e
- again.
- .It Fl w
- Wait until scrub has completed before returning.
- .It Fl e
- Only scrub files with known data errors as reported by
- .Nm zpool Cm status Fl v .
- The pool must have been scrubbed at least once with the
- .Sy head_errlog
- feature enabled to use this option.
- Error scrubbing cannot be run simultaneously with regular scrubbing or
- resilvering, nor can it be run when a regular scrub is paused.
- .It Fl C
- Continue scrub from last saved txg (see zpool
- .Sy last_scrubbed_txg
- property).
- .El
- .Sh EXAMPLES
- .Ss Example 1
- Status of pool with ongoing scrub:
- .sp
- .Bd -literal -compact
- .No # Nm zpool Cm status
- ...
- scan: scrub in progress since Sun Jul 25 16:07:49 2021
- 403M / 405M scanned at 100M/s, 68.4M / 405M issued at 10.0M/s
- 0B repaired, 16.91% done, 00:00:04 to go
- ...
- .Ed
- .Pp
- Where metadata which references 403M of file data has been
- scanned at 100M/s, and 68.4M of that file data has been
- scrubbed sequentially at 10.0M/s.
- .Sh PERIODIC SCRUB
- On machines using systemd, scrub timers can be enabled on per-pool basis.
- .Nm weekly
- and
- .Nm monthly
- timer units are provided.
- .Bl -tag -width Ds
- .It Xo
- .Xc
- .Nm systemctl
- .Cm enable
- .Cm zfs-scrub-\fIweekly\fB@\fIrpool\fB.timer
- .Cm --now
- .It Xo
- .Xc
- .Nm systemctl
- .Cm enable
- .Cm zfs-scrub-\fImonthly\fB@\fIotherpool\fB.timer
- .Cm --now
- .El
- .
- .Sh SEE ALSO
- .Xr systemd.timer 5 ,
- .Xr zpool-iostat 8 ,
- .Xr zpool-resilver 8 ,
- .Xr zpool-status 8