| .\" |
| .\" 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 http://www.opensolaris.org/os/licensing. |
| .\" 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 July 25, 2021 |
| .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 Fl s Ns | Ns Fl p |
| .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 |
| 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 |
| again. |
| .It Fl w |
| Wait until scrub has completed before returning. |
| .El |
| .Sh EXAMPLES |
| .Bl -tag -width "Exam" |
| .It Sy Example 1 : Status of pool with ongoing scrub: |
| Output: |
| .Bd -literal -compact -offset Ds |
| .No # Nm zpool Cm status |
| ... |
| scan: scrub in progress since Sun Jul 25 16:07:49 2021 |
| 403M scanned at 100M/s, 68.4M issued at 10.0M/s, 405M total |
| 0B repaired, 16.91% done, 00:00:04 to go |
| ... |
| .Ed |
| Where: |
| .Bl -dash -offset indent |
| .It |
| 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. |
| .El |
| .El |
| .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 |