Auto update

This commit is contained in:
Andrea Mazzoleni 2026-10-29 06:56:28 +01:00
parent 571b049f31
commit e9821a3a0b
16 changed files with 9425 additions and 1748 deletions

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

View file

@ -114,7 +114,7 @@
<div class="manual-section-level-1">
<h1 id="sec1" class="manual-title-level-1">
Synopsis
概要 (Synopsis)
</h1>
<pre>
snapraid [-c, --conf CONFIG]
@ -142,7 +142,7 @@ snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]
</div>
<div class="manual-section-level-1">
<h1 id="sec2" class="manual-title-level-1">
Description
説明 (Description)
</h1>
<p>SnapRAIDは、ディスクアレイ用のバックアッププログラムで、最大6台のディスク障害が発生した場合の
データ復旧のためにパリティ情報を保存します。
@ -185,19 +185,35 @@ SnapRAIDはデータをロックしません。いつでも再フォーマット
</div>
<div class="manual-section-level-1">
<h1 id="sec3" class="manual-title-level-1">
Limitations
制限事項 (Limitations)
</h1>
<p>SnapRAIDはRAIDとバックアッププログラムのハイブリッドであり、両方の利点を組み合わせることを
目指しています。ただし、使用する前に考慮すべきいくつかの制限があります。
</p><p>主な制限は、ディスクが故障し、最近 <b>sync</b> を実行していない場合、完全に復旧できない
可能性があることです。
より具体的には、最後の <b>sync</b> 操作以降に変更または削除されたファイルのサイズまでのデータが
復旧できない可能性があります。
これは、変更または削除されたファイルが故障したディスク上にない場合でも発生します。
このため、SnapRAIDは**めったに変更されない**データに適しています。
</p><p>一方で、新しく追加されたファイルは、既に存在するファイルの復旧を妨げません。
新しく追加されたファイルが故障したディスク上にある場合にのみ、それらのファイルが失われます。
</p><p>その他のSnapRAIDの制限は次のとおりです。
目指しています。ただし、使用する前に考慮すべきいくつかの制限事項があります。
</p><p>主な制限事項は、ディスクが故障した場合、最後の <b>sync</b>(同期)処理の状態までしか
データを復元できないことです。最後の同期以降に追加されたデータや、故障したディスク上で行われた
変更はすべて失われます。
</p><p>そのため、SnapRAIDは主にデータの変更がほとんどない環境に適しています。
</p><p>最後の同期時にすでに存在していたデータについて、復元の信頼性は <b>snapshot</b>(スナップショット)
オプションが使用されているかどうかによって異なります。
</p><ul>
<li>
スナップショットサポートがある場合(Btrfs、ZFS、Bcachefs、およびNTFSで利用可能):
SnapRAIDはサポートされている各データファイルシステムの独立した凍結されたリファレンスを
自動的に維持できます。
これにより、同期中または同期後にライブファイルシステム上のファイルを変更または削除した場合でも、
復元プロセスの整合性と信頼性が保たれます。
</li>
</ul>
<ul>
<li>
スナップショットサポートがない場合:
<b>sync</b> 後にファイルを削除または変更すると、他の故障したディスクの完全な復元が妨げられる
可能性があります。これは、変更されたファイルが故障したディスク上にない場合でも、
パリティが変更後のファイルと一致しなくなるために発生します。一方で、新しく追加されたファイルが
すでに存在するファイルの復元を妨げることはありません。
</li>
</ul>
<p>その他のSnapRAIDの制限は次のとおりです。
</p><ul>
<li>
SnapRAIDでは、各ディスクに対して**個別のファイルシステム**が保持されます。
@ -223,7 +239,7 @@ SnapRAIDは**限られた数のディスク障害**からのみデータを復
</div>
<div class="manual-section-level-1">
<h1 id="sec4" class="manual-title-level-1">
Getting Started
はじめに (Getting Started)
</h1>
<p>SnapRAIDを使用するには、まずディスクアレイ内の1つのディスクを <b>parity</b> 情報専用に
選択する必要があります。パリティ用に1つのディスクを使用すると、RAID5と同様に、単一のディスク障害から
@ -290,7 +306,7 @@ snapraid sync
更新できます。
</p><div class="manual-section-level-2">
<h2 id="sec4-1" class="manual-title-level-2">
Scrubbing
スクラブ (Scrubbing)
</h2>
<p>データとパリティのエラーを定期的にチェックするには、<b>scrub</b> コマンドを
実行できます。
@ -331,11 +347,11 @@ snapraid -p bad scrub
</p></div>
<div class="manual-section-level-2">
<h2 id="sec4-2" class="manual-title-level-2">
Pooling
プーリング (Pooling)
</h2>
<p>注: ここで説明するプーリング機能は、**mergerfs** ツールに取って代わられました。
mergerfs は、SnapRAIDコミュニティのLinuxユーザーに推奨されるオプションです。
Mergefs は、複数のドライブを単一の統合されたマウントポイントにプールするための、
Mergerfs は、複数のドライブを単一の統合されたマウントポイントにプールするための、
より柔軟で効率的な方法を提供し、シンボリックリンクに頼ることなくアレイ全体の
ファイルにシームレスにアクセスできます。これは、パリティ保護のためにSnapRAIDと
うまく統合されており、OpenMediaVault (OMV) やカスタムNAS構成などのセットアップで
@ -404,7 +420,7 @@ fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1
</div>
<div class="manual-section-level-2">
<h2 id="sec4-3" class="manual-title-level-2">
Undeleting
削除取り消し (Undeleting)
</h2>
<p>SnapRAIDはRAIDシステムよりもバックアッププログラムのように機能し、
-f, --filter オプションを使用してファイルを以前の状態に復元または削除解除するために
@ -429,7 +445,7 @@ snapraid fix -m
</div>
<div class="manual-section-level-2">
<h2 id="sec4-4" class="manual-title-level-2">
Recovering
回復 (Recovering)
</h2>
<p>最悪の事態が発生し、1台以上のディスクを失いました!
</p><p>**パニックにならないでください!** 復旧できます!
@ -514,27 +530,27 @@ snapraid sync
</div>
<div class="manual-section-level-1">
<h1 id="sec5" class="manual-title-level-1">
Commands
コマンド (Commands)
</h1>
<p>SnapRAIDは、次のことを可能にするいくつかの簡単なコマンドを提供します。
<p>SnapRAIDは、以下の操作を行ういくつかのシンプルなコマンドを提供します。
</p><ul>
<li>
アレイの状態の概要を出力 -&gt; <b>status</b>
アレイの状態を表示する -&gt; <b>status</b>
</li>
<li>
ディスクの制御 -&gt; <b>smart</b>、<b>probe</b>、<b>up</b>、<b>down</b>
ディスクを制御する -&gt; <b>smart</b>、<b>probe</b>、<b>up</b>、<b>down</b>
</li>
<li>
バックアップ/スナップショットの作成 -&gt; <b>sync</b>
バックアップ/復元ポイントを作成する -&gt; <b>sync</b>
</li>
<li>
データの定期的なチェック -&gt; <b>scrub</b>
データを定期的にチェックする -&gt; <b>scrub</b>
</li>
<li>
最後のバックアップ/スナップショットの復元 -&gt; <b>fix</b>。
最後のバックアップ/復元ポイントを復元する -&gt; <b>fix</b>
</li>
</ul>
<p>コマンドは**小文字**で記述する必要があります。
<p>コマンドは小文字で入力する必要があります。
</p><div class="manual-section-level-2">
<h2 id="sec5-1" class="manual-title-level-2">
status
@ -699,9 +715,10 @@ updated
<div class="manual-tag-name">
moved
</div><div class="manual-tag-description">
同じディスク上の異なるディレクトリに移動されたファイル。
同じ名前、サイズ、タイムスタンプ、およびinodeを持ちますが、ディレクトリが
異なることで識別されます。
同じinodeを保持したまま、同じディスク上で移動または
名前変更されたファイル。同じinode、サイズ、およびタイムスタンプを
持ちますが、パスが異なることで識別されます。ファイル名が異なって
いても構いません。
</div>
</div>
<div class="manual-tag-entry">
@ -720,14 +737,12 @@ copied
<div class="manual-tag-name">
relocated
</div><div class="manual-tag-description">
オリジナルが消失した、同じディスクまたは別のディ
スクに移動されたファイル。
これらは、同じ名前、サイズ、およびタイムスタンプを持つこと
によって識別されます。
サブ秒のタイムスタンプがゼロの場合、識別するにはフルパスが
一致する必要があります。
同じディスク上の 'moved' ファイルとは異なり、再配置された
ファイルは異なる inode を持ちます。
元のファイルが消失し、inodeが保持されていない、
別のディレクトリまたはディスクに移動されたファイル。
これらは、同じ名前、サイズ、およびタイムスタンプを持つことに
よって識別されます。サブ秒のタイムスタンプがゼロの場合、
識別するにはフルパスが一致する必要があります。'moved' ファイルとは
異なり、再配置されたファイルはファイル名が同一である必要があります。
</div>
</div>
<div class="manual-tag-entry">
@ -815,12 +830,12 @@ full - すべてをスクラブします。
<h2 id="sec5-9" class="manual-title-level-2">
fix
</h2>
<p>すべてのファイルとパリティデータを修正します。
</p><p>すべてのファイルとパリティデータは、最後の <b>sync</b> で保存されたスナップショット状態と
比較されます。
違いが見つかった場合、保存されたスナップショットに**元に戻されます**。
</p><p>**警告!** <b>fix</b> コマンドは、エラーと意図的な変更を区別しません。
ファイルの_状態を_最後の <b>sync</b> に**無条件に元に戻します**。
<p>すべてのファイルとパリティデータを修復(復元)します。
</p><p>すべてのファイルとパリティデータが、最後の <b>sync</b> で保存された状態と比較されます。
差異が見つかった場合、保存されていた状態に巻き戻されます。
</p><p>警告!
<b>fix</b> コマンドは、エラーと意図的な変更を区別しません。
ファイルの変更状態を無条件で最後の <b>sync</b> の状態に戻します。
</p><p>他のオプションが指定されていない場合、アレイ全体が処理されます。
フィルタオプションを使用して、操作するファイルまたはディスクのサブセットを
選択します。
@ -965,7 +980,7 @@ locate
</div>
<div class="manual-section-level-1">
<h1 id="sec6" class="manual-title-level-1">
Options
オプション (Options)
</h1>
<p>SnapRAIDには、次のオプションがあります。
</p><div class="manual-option-list">
@ -1143,7 +1158,7 @@ DAYS は、ブロックがスクラブされるための最小経過日数であ
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-t, --tail サイズ
-t, --tail SIZE
</div><div class="manual-option-description">
ファイルリストを、パリティディスクの指定された末尾サイズ以下を
使用しているものに制限します。
@ -1282,7 +1297,7 @@ SnapRAIDが一部のディスクがUUIDを変更したことを検出した場
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-W, --force-realloc-tail サイズ
-W, --force-realloc-tail SIZE
</div><div class="manual-option-description">
-R, --force-realloc と同様に動作しますが、各パリティファイルの
指定された末尾部分(最後の「サイズ」バイト)に制限されます。
@ -1349,7 +1364,8 @@ locate -t, --tail を使用して、影響を受けるファイルを事前に
指定されたブロック番号から処理を開始します。
これは、破損したディスクの場合に特定のブロックを再試行してチェックまたは修正するのに
役立ちます。
このオプションは、主に高度な手動復旧を目的としています。
このオプションは、主に高度な手動復旧を目的としており、<b>check</b> と <b>fix</b> でのみ
サポートされています。
</div>
</div>
</div>
@ -1359,7 +1375,8 @@ locate -t, --tail を使用して、影響を受けるファイルを事前に
-B, --count BLKCOUNT
</div><div class="manual-option-description">
指定された数のブロックのみを処理します。
このオプションは、主に高度な手動復旧を目的としています。
このオプションは、主に高度な手動復旧を目的としており、<b>check</b> と <b>fix</b> でのみ
サポートされています。
</div>
</div>
</div>
@ -1420,7 +1437,7 @@ locate -t, --tail を使用して、影響を受けるファイルを事前に
</div>
<div class="manual-section-level-1">
<h1 id="sec7" class="manual-title-level-1">
Configuration
設定 (Configuration)
</h1>
<p>SnapRAIDは、ディスクアレイの場所とパリティ情報の保存場所を知るために、構成ファイルを
必要とします。
@ -1510,6 +1527,10 @@ data NAME DIR
NAME はディスクを識別するために使用され、**一意である**必要があります。
DIR はファイルシステム内のディスクの**マウントポイント**です。
</p><p>NAME を固定したままにしておけば、必要に応じてマウントポイントを変更できます。
</p><p>ただし、設定されたパスは常に同じ基礎データに解決される必要があります。
パスにシンボリックリンクが含まれている場合、そのリンク先は固定されている
必要があります。シンボリックリンクの参照先を変更して実行時にデータ
ディレクトリを切り替えることはサポートされていません。
</p><p>アレイ内のデータディスクごとに1つのオプションを使用する必要があります。
</p><p>構成ファイルで直接 NAME を変更してから <b>sync</b> コマンドを実行することで、
後でディスクの名前を変更できます。
@ -1528,6 +1549,26 @@ extra NAME DIR
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-7" class="manual-title-level-2">
snapshot
</h2>
<p><b>sync</b>、<b>scrub</b>、<b>check</b>、および <b>fix</b> コマンドでファイルシステムスナップショットの
使用を有効にします。
</p><p>有効にすると、SnapRAIDは <b>sync</b> の開始時にサポートされている各データファイルシステムの
読み取り専用スナップショットを作成します。これにより各ファイルシステムの安定したビューが
提供され、後からの変更によってパリティ計算に使用されるデータが変わるのを防ぎます。
</p><p>これにより復元が大幅に向上します。ライブファイルシステムからファイルが削除されても、
スナップショット内に保存され続けます。これにより、そのブロックのパリティが「破損」するのを防ぎ、
別のディスクが故障した場合でもデータを正常に復元できるようになります。
</p><p>このオプションは、LinuxのBtrfs、Bcachefs、ZFS、およびWindowsのNTFSでフォーマットされた
データディスクにのみ適用されます。
パリティディスク、または他のファイルシステムを使用しているデータディスクは、常にファイルシステムの
ライブバージョンを使用します。
</p><p>スナップショットの作成と削除には管理者権限が必要です。
このオプションが有効な場合は、SnapRAIDが必要な権限(例:sudo)で実行されていることを確認してください。
</p><p>スナップショットのライフサイクルの詳細な説明については、SNAPSHOTSのセクションを参照してください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
nohidden
</h2>
<p>すべての隠しファイルとディレクトリを除外します。
@ -1535,7 +1576,7 @@ Unixでは、隠しファイルは <b>.</b> で始まるファイルです。
Windowsでは、隠し属性を持つファイルです。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
exclude/include PATTERN
</h2>
<p>syncプロセスで除外または含めるファイルまたはディレクトリのパターンを定義します。
@ -1544,11 +1585,14 @@ exclude/include PATTERN
<b>include</b> の場合、ファイルは含まれます。
パターンが一致しない場合、最後に指定されたパターンが <b>include</b> の場合はファイルは除外され、
<b>exclude</b> の場合は含まれます。
</p><p>フィルタリングはディレクトリの走査時に階層的に実行されることに注意してください。
ディレクトリが <b>exclude</b> ルールに一致した場合、そのディレクトリ全体がスキップ(プルーニング)され、
その内部にあるファイルやサブディレクトリに対する <b>include</b> ルールは評価されません。
</p><p>パターン仕様の詳細については、PATTERNセクションを参照してください。
</p><p>このオプションは複数回使用できます。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
blocksize SIZE_IN_KIBIBYTES
</h2>
<p>パリティの基本ブロックサイズをキビバイト単位で定義します。
@ -1585,7 +1629,7 @@ mkfs.ext4 -m 0 -T largefile4 DEVICE
浪費スペースなしで各データディスクで約460,000ファイルが可能になります。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
hashsize SIZE_IN_BYTES
</h2>
<p>保存されたブロックのハッシュサイズをバイト単位で定義します。
@ -1595,28 +1639,28 @@ hashsize SIZE_IN_BYTES
</p><p>異なるハッシュサイズを使用する理由の1つは、システムのメモリが制限されている場合です。
経験則として、SnapRAIDは通常、アレイ内のデータ16 TBごとに1 GiBのRAMを必要とします。
</p><p>具体的には、データのハッシュを保存するために、SnapRAIDは
約 $TS \cdot (1 + HS) / BS$ バイトのRAMを必要とします。
約 TS*(1+HS)/BS バイトのRAMを必要とします。
ここで、TSはディスクアレイの合計サイズ(バイト)、BSはブロックサイズ(バイト)、HSはハッシュサイズ(バイト)です。
</p><p>たとえば、4 TBのディスク8台、ブロックサイズ256 KiB(1 KiB = 1024バイト)、
ハッシュサイズ16の場合:
</p><pre>
RAM = $(8 \cdot 4 \cdot 10^{12}) \cdot (1 + 16) / (256 \cdot 2^{10}) = 1.93 \text{ GiB}$
RAM = (8 * 4 * 10^12) * (1+16) / (256 * 2^10) = 1.93 GiB
</pre>
<p>ハッシュサイズを8に切り替えると:
</p><pre>
RAM = $(8 \cdot 4 \cdot 10^{12}) \cdot (1 + 8) / (256 \cdot 2^{10}) = 1.02 \text{ GiB}$
RAM = (8 * 4 * 10^12) * (1+8) / (256 * 2^10) = 1.02 GiB
</pre>
<p>ブロックサイズを512に切り替えると:
</p><pre>
RAM = $(8 \cdot 4 \cdot 10^{12}) \cdot (1 + 16) / (512 \cdot 2^{10}) = 0.96 \text{ GiB}$
RAM = (8 * 4 * 10^12) * (1+16) / (512 * 2^10) = 0.96 GiB
</pre>
<p>ハッシュサイズを8、ブロックサイズを512の両方に切り替えると:
</p><pre>
RAM = $(8 \cdot 4 \cdot 10^{12}) \cdot (1 + 8) / (512 \cdot 2^{10}) = 0.51 \text{ GiB}$
RAM = (8 * 4 * 10^12) * (1+8) / (512 * 2^10) = 0.51 GiB
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
autosave SIZE_IN_GIGABYTES
</h2>
<p>処理された指定されたGB量後に、同期またはスクラビング時に状態を自動的に保存します。
@ -1624,7 +1668,7 @@ autosave SIZE_IN_GIGABYTES
長い <b>sync</b> コマンドを最初から再起動するのを避けるのに役立ちます。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
temp_limit TEMPERATURE_CELSIUS
</h2>
<p>許容される最大ディスク温度を摂氏で設定します。指定されている場合、
@ -1650,14 +1694,14 @@ SnapRAIDの動作には影響しません。プログラムの動作は、実際
すべてのディスクの温度を表示するには、-A または --stats オプションを使用します。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
temp_sleep TIME_IN_MINUTES
</h2>
<p>温度制限に達したときのスタンバイ時間(分単位)を設定します。この期間中、ディスクは
スピンダウンしたままです。デフォルトは5分です。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
pool DIR
</h2>
<p><b>pool</b> コマンドを使用してディスクアレイの仮想ビューが作成されるプーリングディレクトリを
@ -1665,7 +1709,7 @@ pool DIR
</p><p>ディレクトリは既に存在している必要があります。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
share UNC_DIR
</h2>
<p>ディスクにリモートでアクセスするために必要なWindows UNCパスを定義します。
@ -1678,7 +1722,7 @@ share UNC_DIR
</p><p>このオプションはWindowsでのみ必要です。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
smartctl DISK/PARITY OPTIONS...
</h2>
<p>各ディスクのSMART属性を取得するためのカスタムsmartctlオプションを定義します。
@ -1691,6 +1735,8 @@ PARITY はパリティ名のいずれかです:<b>parity</b>、<b>2-parity</b>
</p><p>指定された OPTIONS で、<b>%s</b> 文字列はデバイス名に置き換えられます。
RAIDコントローラーの場合、デバイスは固定されている可能性が高いため、
<b>%s</b> を使用する必要はないかもしれません。
</p><p>デフォルトの <b>-a</b> オプションを置き換えるために、<b>[info: ...]</b> タグを使用して
カスタム情報オプション文字列を指定することもできます。
</p><p>使用可能なオプションについては、smartmontoolsのドキュメントを参照してください。
</p><pre>
<a href="https://www.smartmontools.org/wiki/Supported_RAID-Controllers">https://www.smartmontools.org/wiki/Supported_RAID-Controllers</a>
@ -1698,11 +1744,12 @@ RAIDコントローラーの場合、デバイスは固定されている可能
</pre>
<p>例:
</p><pre>
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl parity -d sat %s
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
smartignore DISK/PARITY ATTR [ATTR...]
</h2>
<p>ディスク障害の確率を計算するときに、指定されたSMART属性を無視します。
@ -1712,18 +1759,23 @@ smartignore DISK/PARITY ATTR [ATTR...]
PARITY はパリティ名のいずれかです:<b>parity</b>、<b>2-parity</b>、<b>3-parity</b>、
<b>4-parity</b>、<b>5-parity</b>、<b>6-parity</b>、または <b>z-parity</b>。
特殊な値 <b>*</b> は、すべてのディスクで属性を無視するために使用できます。
</p><p>例として、すべてのディスクで <b>Current Pending Sector Count</b> 属性を無視するには:
</p><p>複数の属性をスペースで区切って指定できます。
各属性は1から255までの数値、または大文字と小文字を区别しない名前
(例: <b>Current_Pending_Sector</b>)として指定できます。
</p><p>例として、すべてのディスクで <b>Current Pending Sector Count</b> と
<b>Reallocated Sectors Count</b> 属性を番号または名前で無視するには:
</p><pre>
smartignore * 197
smartignore * 197 5
smartignore * Current_Pending_Sector Reallocated_Sector_Ct
</pre>
<p>最初のパリティディスクでのみ無視するには:
</p><pre>
smartignore parity 197
smartignore parity 197 5
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
Examples
<h2 id="sec7-19" class="manual-title-level-2">
例 (Examples)
</h2>
<p>Unixの一般的な構成の例は次のとおりです。
</p><pre>
@ -1735,7 +1787,7 @@ data d2 /mnt/disk2/
data d3 /mnt/disk3/
exclude /lost+found/
exclude /tmp/
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/sg0
smartctl 2-parity -d areca,2/1 /dev/sg0
@ -1751,7 +1803,7 @@ data d3 I:\array\
exclude Thumbs.db
exclude \$RECYCLE.BIN
exclude \System Volume Information
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/arcmsr0
smartctl 2-parity -d areca,2/1 /dev/arcmsr0
@ -1760,7 +1812,148 @@ smartctl 2-parity -d areca,2/1 /dev/arcmsr0
</div>
<div class="manual-section-level-1">
<h1 id="sec8" class="manual-title-level-1">
Pattern
スナップショット (Snapshots)
</h1>
<p>設定でスナップショットオプションが有効になっている場合、SnapRAIDは
ファイルシステムのスナップショットを使用して、操作中に読み取られるデータを安定に保ちます。
これは、ライブファイルシステム上のファイルが後から変更または削除された場合でも同様です。
</p><p>スナップショットの管理は完全に自動かつ透過的です。
バックグラウンドで完全に処理されるスナップショットによる追加の保護を受けながら、
これまでとまったく同じようにSnapRAIDを使用し続けることができます。
</p><p>これには主に2つのメリットがあります。
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
整合性
</div><div class="manual-tag-description">
長時間かかるsyncやscrubの実行中にライブファイルシステム上でファイルが変更されても、
スナップショットされた各ファイルシステムは操作中変更されないため、
パリティの不一致や処理の中断は発生しません。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
復元
</div><div class="manual-tag-description">
ライブファイルシステムからファイルが更新または削除されても、スナップショット内に保存され続けます。
次のsyncが実行される前にディスク故障が発生した場合、SnapRAIDはスナップショットに保存されている
データを使用して、故障したディスクを再構築します。
アクティブなsync処理中にディスクが故障した場合、SnapRAIDは前のパリティ計算の
スナップショットと現在のスナップショットの両方から自動的に読み取ることも可能です。
これにより、同期の間にブロックが変更または削除されていた場合でも、パリティ方程式を解くために
必要な正確なデータブロックへのアクセスが提供され、完全な復元の可能性が最大化されます。
スナップショットがない場合、正常なディスク上の更新または削除されたファイルはデータブロックの欠損を
招き、他の故障したディスクを修復するために必要となるブロックが失われる可能性があります。
</div>
</div>
</div>
<p>スナップショットはデータディスクに対してのみ、かつ基礎となるファイルシステムがその機能をサポートして
いる場合にのみ作成されます。パリティディスクは常にライブファイルシステムを使用します。
</p><p>現在、これはLinuxのBtrfs、Bcachefs、ZFS、およびWindowsのNTFSでサポートされています。
</p><p>異なるファイルシステムを持つデータディスクを混在させることができます。スナップショットをサポートして
いるディスクのみがそれを利用し、他のディスクはライブファイルシステム上で直接動作し続けます。
</p><p>スナップショットの作成と削除には管理者権限が必要です。
スナップショットが有効な場合は、SnapRAIDが必要な権限(例:sudo)で実行されていることを確認してください。
</p><div class="manual-section-level-2">
<h2 id="sec8-1" class="manual-title-level-2">
スナップショット使用時のコマンドの挙動 (Command Behavior with Snapshots)
</h2>
<p><b>sync</b> および <b>scrub</b> コマンドは、ファイルシステムがサポートしているデータディスクに対して
スナップショットを使用します。スナップショットされたディスクでは、コマンドはライブファイルシステムへの
同時変更の影響を受けない安定したファイルシステムイメージを参照します。
<b>sync</b> の実行中、サポートされている各データファイルシステムに対して独立して新しいスナップショットが
作成されます。これらのスナップショットは全体としてパリティ計算に使用されるデータを提供します。
対照的に、<b>scrub</b> コマンドは、既存のパリティと一致する信頼できる参照ポイントを維持するために、
最も直近の同期中に作成された最後のスナップショットを利用します。
</p><p><b>check</b> および <b>fix</b> コマンドの場合、最後のスナップショットの使用は、
-d, --filter-disk オプションを使用して特定のディスクがターゲットに指定されているかどうかによって異なります。
</p><div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-d を介して明示的に選択されたディスク(操作の「ターゲット」)は、常にライブファイルシステムを使用します。
</div><div class="manual-option-description">
</div>
</div>
</div>
<p><b>fix</b> の場合、これによりアクティブな交換ディスクにデータを復元できます。
<b>check</b> の場合、同じ条件下で <b>fix</b> 操作をシミュレートできます。
</p><p>他のすべてのデータディスク(「参照」ディスク)は、それぞれのスナップショットを介してアクセスされます。
これにより、復旧の進行中に正常なディスク上のファイルを変更している場合でも、SnapRAIDは
パリティ方程式を解くための安定した凍結された参照を持つことができます。
</p><div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-d オプションが指定されていない場合、SnapRAIDは操作がアレイ全体に適用されると想定します。
</div><div class="manual-option-description">
</div>
</div>
</div>
<p>この場合、<b>check</b> と <b>fix</b> はライブファイルシステムのみを排他的に使用します。
</p><p>他のすべてのコマンドは、ライブファイルシステム上でのみ動作します。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
スナップショットのライフサイクル (Snapshots Lifecycle)
</h1>
<p>SnapRAIDは、各データサブボリュームのルートにある隠しディレクトリ内で、
<b>stable</b>(安定)、<b>pending</b>(保留)、および <b>scan</b>(スキャン)という3つの特定のスナップショットを管理します。
Btrfs、Bcachefs、およびNTFSでは <b>.snapraid/</b> ディレクトリが使用され、
ZFSでは標準の <b>.zfs/snapshot/</b> が使用されます。
</p><p><b>stable</b> スナップショットは、最後に正常に完了した <b>sync</b> の状態を表し、
現在のパリティの計算に使用された正確なデータを含んでいます。これは、
<b>scrub</b>、<b>check</b>、および <b>fix</b> コマンドの主要なデータソースとして機能します。
</p><p><b>scan</b> スナップショットは、スキャンとパリティ計算のための凍結された状態を提供するために、
<b>sync</b> の開始時に作成される一時的なイメージです。
スキャンを実行し、新しいコンテンツ状態を保存した後、以前の <b>pending</b> スナップショットを置き換えます。
</p><p><b>pending</b> スナップショットは、中断された <b>sync</b> によって使用されるイメージです。
操作が正常に完了すると、以前の <b>stable</b> スナップショットが削除され、
<b>pending</b> スナップショットが新しい安定した参照として昇格します。
</p><p><b>sync</b> が中断された場合、<b>pending</b> スナップショットは保持されます。
パリティが部分的にしか同期されていない場合でも、.content ファイルに記録されたファイルシステム状態と
一致するため、その後の <b>scrub</b>、<b>check</b>、および <b>fix</b> コマンドはこの保留中のスナップショットを使用します。
</p><p><b>sync</b> が中断された場合、<b>check</b> および <b>fix</b> コマンドは <b>stable</b> スナップショットからも
読み取りを行い、同期中に更新または削除されたファイルからデータブロックを取得します。
これは、.content ファイルが同期プロセス全体を通じて、変更または削除されたすべてのファイルの
メタデータを保持しているために可能です。
この履歴情報は、syncが正常に終了し、.content ファイルの最終バージョンが保存されたときにのみクリアされます。
</p><p>中断後に <b>sync</b> が再開されると、既存の保留中(pending)のスナップショットは削除され、
ライブファイルシステムの現在の状態をキャプチャするために新しいスナップショットが作成されます。
ただし、<b>sync</b> が中断された場合は、その後の <b>sync</b> が正常に完了するまで、
ファイルの変更、削除、置換、または移動を行わないでください。
パリティには、中断された sync で使用されたスナップショットから計算されたブロックが
まだ含まれている可能性があります。その後の sync によりそのスナップショットが
置き換えられ、中間バージョンのファイルが復元できなくなる可能性があります。
</p><div class="manual-section-level-2">
<h2 id="sec9-1" class="manual-title-level-2">
ファイルシステムスナップショットと外部バックアップ (External backups with filesystem snapshots)
</h2>
<p>ファイルシステムスナップショットが有効な場合、SnapRAIDは各データサブボリューム、
ボリューム、またはデータセットのルートにあるスナップショットにアクセスまたは作成します。
</p><p>外部ツールとの干渉を避ける簡単な方法は、<b>data</b> 設定をサブボリュームまたは
ボリューム内の通常のサブディレクトリ(例えば <b>/mnt/subvol</b> の代わりに
<b>/mnt/subvol/data</b>)に指定することです。SnapRAIDは常にサブボリュームのルートに
スナップショットディレクトリを作成するため(例えば <b>/mnt/subvol/.snapraid/</b>)、
データサブディレクトリがクリーンに保たれ、スナップショットはそのディレクトリ内で
動作するバックアップツールから見えない状態のままになります。
</p><p>一方、設定された <b>data</b> ディレクトリ自体がサブボリュームまたはボリュームの
ルートである場合、SnapRAIDはその直下に <b>.snapraid/</b> ディレクトリを作成します(Btrfs、
Bcachefs、およびNTFS)。SnapRAID自身のスキャンからは自動的に除外されますが、
外部のバックアップツールやファイル同期ツールはそのディレクトリを検出します。
除外設定を行わない場合、スナップショットやディレクトリリンク内を走査して凍結された
データツリー全体をコピーしてしまい、データが重複してバックアップストレージを使い果たす
可能性があります。外部バックアップツールでは、必ず <b>.snapraid/</b> ディレクトリを
除外するように設定してください。
</p><p>ZFSでは、スナップショットは <b>.snapraid/</b> ではなく標準の仮想ディレクトリ
<b>.zfs/snapshot/</b> 経由で公開されます。デフォルト(<b>snapdir=hidden</b>)では、ZFSはこの
ディレクトリを一覧表示から隠すため、外部バックアップツールが走査することはありません。
<b>snapdir=visible</b> を有効にしている場合は、バックアップツールが <b>.zfs/</b> ディレクトリを
除外するように設定してください。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
パターン (Pattern)
</h1>
<p>パターンは、含めるファイルまたは除外するファイルをフィルタリングするための柔軟な方法を
提供します。グロブ文字を使用することで、すべてのパスを手動でリストすることなく、
@ -1772,23 +1965,25 @@ Pattern
ディレクトリの境界を越えることはありません。スラッシュで停止するため、
単一のパスコンポーネント内での一致に適しています。これは、シェルの
グロブでおなじみの標準的なワイルドカードの動作です。
</p><p>ダブルアスタリスク <b>**</b> はより強力で、ディレクトリ区切り文字を含む
任意の文字列に一致します。これにより、パターンが複数のディレクトリレベルを
またいで一致できるようになります。<b>**</b> がパターン内に直接埋め込まれている場合、
周囲のリテラルテキストの間にあるスラッシュを含む0文字以上の文字に一致します。
</p><p><b>**</b> の最も重要な使い方は、特別な形式である <b>/**/</b> です。これは
0個以上の完全なディレクトリレベルに一致し、正確なパス構造を知らなくても、
ディレクトリツリー内の任意の深さにあるファイルと一致させることができます。
例えば、パターン <b>src/**/main.js</b> は <b>src/main.js</b>(ディレクトリを0個スキップ)、
<b>src/ui/main.js</b>(1個スキップ)、<b>src/ui/components/main.js</b>(2個スキップ)
に一致します。
</p><p>ダブルアスタリスクのワイルドカード <b>**</b> は、ディレクトリ区切り文字に隣接
している場合(スラッシュの前または後にある場合)にのみ、ディレクトリ区切り
文字をまたいで一致します。この形式では、複数のディレクトリレベルにわたって
0個以上の文字に一致します。例えば、<b>foo/**/bar</b> は <b>foo/bar</b>、<b>foo/a/bar</b>、
および <b>foo/a/b/bar</b> に一致し、<b>**/build</b> は <b>build</b> および <b>foo/bar/build</b> に
一致し、<b>src/**.js</b> は <b>src/main.js</b> および <b>src/ui/components/main.js</b> に一致します。
単独の形式 <b>/**/</b> は完全なパターンとして受け入れられません。
</p><p><b>**</b> がスラッシュに隣接していない場合、<b>*</b> と同様に動作し、ディレクトリ区切り
文字には一致しません。例えば、<b>**.jpg</b> はカレントディレクトリ内の <b>photo.jpg</b> に
一致しますが、<b>dir/photo.jpg</b> には一致しません。その目的には <b>**/*.jpg</b> を
使用してください。
</p><p>角括弧 <b>[]</b> を使用した文字クラスは、指定されたセットまたは範囲の
任意の1文字に一致します。他の単一文字パターンと同様に、
ディレクトリ区切り文字には一致しません。クラスは範囲と、感嘆符を
使用した否定をサポートしています。
</p><p>覚えておくべき根本的な違いは、<b>*</b>、<b>?</b>、および文字クラスはすべて
ディレクトリの境界を尊重し、単一のパスコンポーネント内でのみ一致するのに対し、
<b>**</b> はディレクトリ区切り文字をまたいで一致できる唯一のパターンであるということです。
<b>**</b> はスラッシュに隣接している場合にのみディレクトリ区切り文字を
またいで一致できるということです。
</p><p>4つの異なる種類のパターンがあります。
</p><div class="manual-option-list">
<div class="manual-option-entry">
@ -1881,6 +2076,23 @@ include /movies/
include /musics/
include /pictures/
</pre>
<p>ディレクトリを除外すると(DIR/ または /PATH/DIR/ を使用)、SnapRAID がそのディレクトリに入って
スキャンすることが防止されることに注意してください。したがって、除外された親ディレクトリ内に
存在するファイルやサブディレクトリを <b>include</b> ルールで再度含めることはできません(スキャナが
そのディレクトリ内を走査しないため)。
</p><p>例えば、以下の設定では <b>/keep/</b> がプルーニングされるため、<b>file.dat</b> は含まれません:
</p><pre>
# 意図通りに動作しません: /keep/ は完全にスキップされます
include /keep/file.dat
exclude /keep/
</pre>
<p>特定のファイルを残しつつディレクトリ内のファイルを一括除外するには、ディレクトリ自体を除外するのではなく、
ディレクトリ内のファイルパターンを除外してください:
</p><pre>
# 意図通りに動作します: /keep/ は走査され、内部の他のファイルのみが除外されます
include /keep/file.dat
exclude /keep/*
</pre>
<p>コマンドラインで -f オプションを使用する場合、<b>include</b> パターンのみを
使用できます。例:
</p><pre>
@ -1892,11 +2104,11 @@ snapraid -f "*.mp3" check
防ぐために引用符で囲む必要があります。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Ignore File
<h1 id="sec11" class="manual-title-level-1">
除外ファイル (Ignore File)
</h1>
<p>設定ファイルのグローバルルールに加えて、アレイ内の任意のディレクトリに
.snapraidignore ファイルを配置して、分散型の除外ルールを定義できます。
<b>.snapraidignore</b> ファイルを配置して、分散型の除外ルールを定義できます。
</p><p><b>.snapraidignore</b> で定義されたルールは、設定ファイルのルールの後に
適用されます。これは、それらがより高い優先度を持ち、グローバル設定で
以前に含まれていたファイルを除外するために使用できることを意味します。
@ -1957,18 +2169,21 @@ build/
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
Content
<h1 id="sec12" class="manual-title-level-1">
コンテンツ (Content)
</h1>
<p>SnapRAIDは、ファイルの一覧とチェックサムをコンテンツファイルに保存します。
</p><p>これはバイナリファイルであり、ディスクアレイに存在するすべてのファイルと、
それらの整合性を検証するためのすべてのチェックサムを一覧表示します。
</p><p>このファイルは <b>sync</b> および <b>scrub</b> コマンドによって読み書きされ、
<b>fix</b>、<b>check</b>、および <b>status</b> コマンドによって読み取られます。
</p><p>コンテンツファイルは <b>sync</b>、<b>scrub</b>、<b>touch</b>、および <b>rehash</b>
コマンドによって読み書きされます。<b>status</b>、<b>diff</b>、<b>check</b>、
<b>fix</b>、<b>list</b>、<b>dup</b>、<b>locate</b>、および <b>pool</b> コマンドによって読み取られ、
<b>smart</b>、<b>probe</b>、<b>up</b>、<b>down</b>、および <b>devices</b> コマンドによって
完全に無視されます。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec11" class="manual-title-level-1">
Parity
<h1 id="sec13" class="manual-title-level-1">
パリティ (Parity)
</h1>
<p>SnapRAIDは、アレイのパリティ情報をパリティファイルに保存します。
</p><p>これらはバイナリファイルであり、<b>content</b> ファイルで定義されたすべてのブロックの
@ -1977,17 +2192,281 @@ Parity
<b>scrub</b> および <b>check</b> コマンドによって**読み取られるだけ**です。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec12" class="manual-title-level-1">
Encoding
<h1 id="sec14" class="manual-title-level-1">
エンコーディング (Encoding)
</h1>
<p>UnixのSnapRAIDは、エンコーディングを無視します。ファイルシステムで使用されている
のと同じエンコーディングでファイル名を読み取り、保存します。
</p><p>Windowsでは、ファイルシステムから読み取られたすべての名前はUTF-8形式に変換され、
処理されます。
</p><p>ファイル名を正しく出力するには、<b>chcp 65001</b> コマンドでWindowsコンソールをUTF-8モードに設定し、
コンソールフォントとして <b>Lucida Console</b> などのTrueTypeフォントを**使用する**必要があります。
コンソールフォントとして <b>Lucida Console</b> などのTrueTypeフォントを使用する必要があります。
これは出力されるファイル名にのみ影響します。コンソール出力をファイルにリダイレクトする場合、
結果のファイルは常にUTF-8形式になります。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec15" class="manual-title-level-1">
終了コード (Exit Code)
</h1>
<p>SnapRAIDは以下のエラーコードで終了します:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
0
</div><div class="manual-tag-description">
すべて正常。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
1
</div><div class="manual-tag-description">
コマンドでエラーが発生しました。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2
</div><div class="manual-tag-description">
<b>diff</b> コマンドはすべて正常であると判定しましたが、 <b>sync</b> が必要です。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
3
</div><div class="manual-tag-description">
ディスクデバイスコマンド(<b>probe</b>、<b>smart</b>、<b>devices</b>、<b>up</b>、<b>down</b>)は完了しましたが、
少なくとも1つのファイルシステムがデバイス不足のためデグレード(縮退)モードで動作しています。
</div>
</div>
</div>
</div>
<div class="manual-section-level-1">
<h1 id="sec16" class="manual-title-level-1">
既知の問題 (Known Issues)
</h1>
<div class="manual-section-level-2">
<h2 id="sec16-1" class="manual-title-level-2">
ファイルシステムの境界
</h2>
<p>SnapRAIDは、データディスクのスキャン中にファイルシステム、マウントポイント、
またはサブボリュームの境界を越えません。そのような境界が検出された場合、
SnapRAIDは警告(WARNING)を報告し、その先をスキャンしません。
</p><p>そのような境界の先にあるファイルはデータディスクに含まれないため、保護する
必要がある場合は個別に設定する必要があります。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-2" class="manual-title-level-2">
ファイルシステムスナップショット使用時のマウントポイント
</h2>
<p>ファイルシステムスナップショットが有効になっている場合、データディスク内の
ネストされたマウントポイントおよびバインドマウントはサポートされません。
</p><p>マウントポイントは稼働中システムのマウント名前空間の一部であり、ファイルシステムの
スナップショットには保持されません。その結果、スナップショットをスキャンする際、
稼働中ファイルシステムでマウントポイントによって隠されていたディレクトリが
見えるようになる場合があります。
</p><p>ファイルシステムスナップショットが有効な場合は、データディスク内にネストされた
マウントポイントやバインドマウントを配置しないでください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-3" class="manual-title-level-2">
ファイルシステムスナップショット使用時の複数設定
</h2>
<p>同じファイルシステムのスナップショット名前空間を使用する複数の独立した
SnapRAID設定で、スナップショットサポートを安全に共有することはできません。
</p><p>BtrfsおよびBcachefsでは、スナップショットサポートが有効なSnapRAID設定は、
同一サブボリューム内のデータディレクトリを1つしか使用できません。ZFSでは
同じ制限がデータセットに、NTFSではボリュームに適用されます。
</p><p>同じスナップショット名前空間を共有する複数の設定は、同一の <b>stable</b>、
<b>pending</b>、および <b>scan</b> スナップショットを使用します。そのため、一方の設定を
実行すると、もう一方の設定で必要なリカバリスナップショットが置換または
削除される可能性があります。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-4" class="manual-title-level-2">
タイムスタンプの変更を伴わないインプレースファイル変更
</h2>
<p>SnapRAIDは、ファイルサイズと変更タイムスタンプ(mtime)を比較することによって
ファイルの変更を検出します。
</p><p>アプリケーションがファイルサイズを変更せず、変更タイムスタンプも更新せずに
インプレースでファイルを変更した場合、"diff" および "sync" はファイルが
変更されたことを検出できず、そのパリティは更新されません。
</p><p>SnapRAIDにそのような変更を確実に認識させるには、ファイルの変更タイムスタンプ
を更新してください(たとえば、"touch" ユーティリティなどを使用)。そうしない
場合、その差分は後続の "scrub" または "check" 中のハッシュ不一致としてのみ
検出されます。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-5" class="manual-title-level-2">
Windowsにおける非ASCII文字の大文字・小文字の一致
</h2>
<p>SnapRAIDはすべてのプラットフォームで標準的で予測可能なUTF-8エンコーディング
を使用し、大文字・小文字を区別しないマッチングをASCII文字に限定しています。
</p><p>Windowsファイルシステムは、任意のシステム依存のフォールディングテーブルを介して
Unicodeファイル名全体で大文字・小文字の不区別を強制するというレガシーな設計の
影響を受けています。その結果、Windowsは全く異なるUnicodeバイトシーケンスをあたかも
同じファイルであるかのように扱い、ファイルシステムの実態を覆い隠してしまいます。
</p><p>たとえば、<b>À.txt</b> と <b>à.txt</b> は明確に異なるUnicode名ですが、Windowsは非論理的にも
これらを同一として扱い、SnapRAIDはそれらの本来の区別を維持します。
</p><p>この制限は、WindowsによるUnicodeファイル名の非一貫な処理と、大文字・小文字を区別
しないエイリアスへの固執によって引き起こされます。Windowsの大文字・小文字フォール
ディングに起因する不一致を防ぐため、設定パスおよびフィルター内の非ASCII文字には
常に正確な大文字・小文字を指定してください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-6" class="manual-title-level-2">
部分的な fix による回復
</h2>
<p><b>fix</b> を <b>-S, --start</b> または <b>-B, --count</b> で制限した場合、
SnapRAID は選択されたブロックのみを処理し、ファイルレベルの完了処理や
隔離を行いません。
</p><p>回復によって現在の内容を表していると証明できないベストエフォートのデータが
生成された場合でも、それらのブロックは通常のファイル名で書き込まれる
可能性があります。これらの回復されたブロックに関連する不確実性は、コマンドの
終了後には保持されません。
</p><p>その結果、後続の <b>fix</b> はこれらの読み取り可能なブロックを有効なファイルデータ
として扱い、再度の回復を試みません。これにより、ファイル内に不完全または
古いデータが残っているにもかかわらず、後続の回復が成功と報告される場合が
あります。
</p><p><b>-S</b> および <b>-B</b> オプションは、通常の <b>fix</b> が失敗した後の高度な手動回復
のみを目的としています。部分的な <b>fix</b> で回復不能なデータが報告された場合は、
別の回復を試みる前に対象のファイルを削除または名前変更するか、その内容を手動で
確認してください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-7" class="manual-title-level-2">
NTFS ハードリンクと除外されたパス
</h2>
<p>NTFS では、ディレクトリエントリが各ハードリンクのファイルサイズとタイム
スタンプを個別にキャッシュします。ファイルがいずれか1つのリンクを通じて
変更された場合、同じファイルを参照している他のリンクのディレクトリエントリ
は、それらにアクセスされるまで古いメタデータを保持し続けることがあります。
</p><p>SnapRAID は、スキャン中に同じファイルへのハードリンクが2つ以上見つかった
場合、この状態を自動的に検出して正規化します。しかし、他のリンクがフィルタ
によって除外されているか、またはデータディスクのパスの外部にあるために
1つのハードリンクのみがスキャンされた場合、SnapRAID は inode の衝突を検出
できず、単一の見えているリンクのキャッシュされたメタデータに依存します。
</p><p>その結果、除外されたリンクや外部のハードリンクを通じて加えられた変更は、
対象のファイルがアクセスされたりそのパスを通じて開かれたりして OS により
含まれるリンクのメタデータが更新されるまで、SnapRAID に気付かれない可能性
があります。
</p><p>この制限を回避するには、SnapRAID から除外されているハードリンクを通じて
保護対象のファイルを変更しないようにするか、SnapRAID が正常に正規化
できるように、ファイルへのすべてのハードリンクがスキャンに含まれるように
してください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-8" class="manual-title-level-2">
中断されたマルチパリティ sync 後の回復
</h2>
<p>複数のパリティディスクを持つアレイにおいて、<b>sync</b> が中断されると、
異なるパリティレベル間で更新状態が一時的に不一致になることがあります。
たとえば、パリティ 1 にはすでに新しく更新されたデータが含まれている一方、
パリティ 2 にはまだ古いデータが残っているといった状況です。
</p><p><b>check</b> または <b>fix</b> の実行中、SnapRAID はさまざまなパリティの組み合わせを
試し、既知のブロックハッシュ(ブロック全体、通常 256 KiB をカバー)に
対して再構築されたデータを検証します。
</p><p>SnapRAID が新旧のパリティが混在する不整合な組み合わせを使用して再構築を
試みた場合、線形 RAID 方程式は誤ったデータを生成します。このような無効な
組み合わせが誤って受け入れられるには、同じストライプ内の他の非同期ブロックが
不正なデータで再構築されているにもかかわらず、方程式が偶然にも少なくとも
1つの完全な 256 KiB ブロックを完璧に再構築してハッシュを一致させる必要が
あります。
</p><p>この事態はハッシュの衝突によるものではありません。むしろ、混在した
パリティ方程式自体が偶然にも元の正確な 256 KiB ブロック内容を生成する
必要があります。これは特別に作成されたデータや極めて反復的なデータでは
数学的に考えられますが、実際のデータでは事実上不可能です。
</p><p>すべてのディスクが正常な場合は、それ以上の変更を加える前に中断された <b>sync</b>
を完了させることで、この不確実性を排除できます。ディスクに障害が発生して
回復が必要な場合は、<b>check</b> または <b>fix</b> を実行する前にデータディスクを
変更しないようにしてください。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-9" class="manual-title-level-2">
予約済みのファイル名およびディレクトリ名
</h2>
<p>SnapRAID は内部処理のために一部のファイル名、ディレクトリ名、
スナップショット名を予約しています。これらの名前をユーザーデータに
使用しないでください:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraidignore
</div><div class="manual-tag-description">
ローカル除外ルールファイル。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraid
</div><div class="manual-tag-description">
スナップショットコンテナディレクトリ。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
snapraid-*
</div><div class="manual-tag-description">
SnapRAID が管理する ZFS スナップショット名。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
*.unrecoverable
</div><div class="manual-tag-description">
回復中に隔離された破損ファイル。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.tmp
</div><div class="manual-tag-description">
content 更新用の一時ファイル。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.lock
</div><div class="manual-tag-description">
content ロックファイル。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
PARITY.spaceholder
</div><div class="manual-tag-description">
Windows でのパリティ割り当て時の一時的な
プレースホルダーファイル。
</div>
</div>
</div>
<p>これらの名前を無関係なデータに使用すると、ファイルやスナップショットが
無視されたり、メタデータとして誤認されたり、上書き、名前変更、または
削除されたりする可能性があります。
</p><p>Windows では、大文字と小文字を区別するように構成された NTFS
ディレクトリであっても、すべての大文字・小文字のバリエーションが
同様に予約されます(例: .SNAPRAIDIGNORE、.SnapRaid、CONTENT.TMP、
CONTENT.Lock)。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec17" class="manual-title-level-1">
翻訳 (Translation)
</h1>
<p>この文書は英語版マニュアルの自動翻訳です。
正確な記述については英語版マニュアルを参照してください。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec18" class="manual-title-level-1">
著作権 (Copyright)
</h1>
<p>This file is Copyright (C) 2026 Andrea Mazzoleni
</p></div>
<div class="manual-section-level-1">
<h1 id="sec19" class="manual-title-level-1">
関連項目 (See Also)
</h1>
<p>snapraid_log(1), snapraidd(1), rsync(1)
</p></div>

File diff suppressed because it is too large Load diff

View file

@ -179,6 +179,11 @@ is escaped to \\.
<p>Some tags are output only when the <b>--gui</b> or <b>--gui-verbose</b> option
is used. They provide extra verbose state and runtime progress only
useful for a GUI interface.
In GUI mode, the structured log is intended to be consumed by the GUI.
Fatal errors are therefore not duplicated to standard error when they
are successfully written to the log. If the log is unavailable or
writing it fails, the fatal error is printed to standard error as a
fallback.
</p><p>Integer values are marked as <b>uint</b> when they are unsigned and as <b>int</b>
when they are signed. However, for practical purposes you can treat
all of them as signed integers.
@ -3695,6 +3700,16 @@ smartctl command.
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
attr:&lt;device_file&gt;:&lt;disk_name&gt;[/&lt;split_index&gt;]:power:unknown
</div><div class="manual-option-description">
Logs that the device power state could not be determined
after a status probe.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
stat:&lt;disk_name&gt;:&lt;access_number&gt;
</div><div class="manual-option-description">
Logs the total number of read and write accesses done on the
@ -3849,27 +3864,27 @@ commands that access files and parities.
<div class="manual-option-name">
error[_io|_data]:&lt;block&gt;:&lt;disk_name&gt;:&lt;file&gt;:&lt;msg&gt;
</div><div class="manual-option-description">
Logs file access errors (open, read, file changed) during the
data disk read operation for parity calculation or verification.
Logs errors affecting data files.
</div>
</div>
</div>
<div class="manual-tag-list">
<p>With no suffix, <b>error</b> indicates a soft or logical error not
classified as a hardware I/O or silent data error.
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
_io
</div><div class="manual-tag-description">
Indicates a physical Input/Output error.
The disk was unable to read or write a specific block,
typically signaling a failing sector or cable issue.
Indicates a physical Input/Output error, typically
signaling a failing sector, device, or cable issue.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
_data
</div><div class="manual-tag-description">
Indicates the data was read successfully but failed
the checksum/hash verification. This signals <b>silent</b>
Indicates data that was read successfully but failed
the checksum/hash verification, signaling <b>silent</b>
corruption or an unsuccessful parity match.
</div>
</div>
@ -3877,7 +3892,13 @@ corruption or an unsuccessful parity match.
<div class="manual-tag-name">
&lt;block&gt;
</div><div class="manual-tag-description">
The zero-based index of the block where the error occurred (uint).
The zero-based SnapRAID parity position associated with
the error (uint). It identifies the logical position affected
by the failed operation, not necessarily the physical sector
that caused the failure. Data file open/create errors occurring
while processing a position report the current block. The field
is empty when the error cannot be associated with a specific
position, such as for close errors.
</div>
</div>
<div class="manual-tag-entry">
@ -3910,34 +3931,39 @@ error (e.g., <b>Open/Read/Write error</b>,
<div class="manual-option-name">
parity_error[_io|_data]:&lt;block&gt;:&lt;level&gt;:&lt;msg&gt;
</div><div class="manual-option-description">
Logs errors during parity disk read or write operations.
Logs errors affecting parity.
</div>
</div>
</div>
<div class="manual-tag-list">
<p>With no suffix, <b>parity_error</b> indicates a soft or logical error
not classified as a hardware I/O or silent data error.
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
_io
</div><div class="manual-tag-description">
Indicates a physical Input/Output error.
The disk was unable to read or write a specific block,
typically signaling a failing sector or cable issue.
Indicates a physical Input/Output error, typically
signaling a failing sector, device, or cable issue.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
_data
</div><div class="manual-tag-description">
Indicates the data was read successfully but failed
the checksum/hash verification. This signals <b>silent</b>
corruption or an unsuccessful parity match.
Indicates data that was read successfully but failed
the parity verification, signaling <b>silent</b> corruption.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
&lt;block&gt;
</div><div class="manual-tag-description">
The zero-based index of the block where the error occurred (uint).
The zero-based SnapRAID parity position associated with
the error (uint). Parity open/create errors report block 0 as
a retry marker; this does not mean that parity block 0 is bad.
Parity access is attempted again by subsequent commands. The
field is empty when the error cannot be associated with a
specific position, such as for close errors.
</div>
</div>
<div class="manual-tag-entry">
@ -3953,7 +3979,7 @@ The configuration name of the parity level (e.g.,
&lt;msg&gt;
</div><div class="manual-tag-description">
A descriptive message indicating the nature of the
error (e.g., <b>Read/Write error</b>,
error (e.g., <b>Open/Read/Write error</b>,
<b>Data error, diff bits &lt;diff&gt;/&lt;bits&gt;</b>).
</div>
</div>

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

View file

@ -114,7 +114,7 @@
<div class="manual-section-level-1">
<h1 id="sec1" class="manual-title-level-1">
Synopsis
Синопсис (Synopsis)
</h1>
<pre>
snapraid [-c, --conf CONFIG]
@ -142,7 +142,7 @@ snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]
</div>
<div class="manual-section-level-1">
<h1 id="sec2" class="manual-title-level-1">
Description
Описание (Description)
</h1>
<p>SnapRAID — это программа резервного копирования, разработанная для дисковых массивов,
хранящая информацию четности для восстановления данных в случае сбоя
@ -188,22 +188,36 @@ SnapRAID не блокирует ваши данные; вы можете пре
</div>
<div class="manual-section-level-1">
<h1 id="sec3" class="manual-title-level-1">
Limitations
Ограничения (Limitations)
</h1>
<p>SnapRAID — это гибрид программы RAID и программы резервного копирования,
стремящийся объединить лучшие преимущества обеих. Однако у него есть
некоторые ограничения, которые следует учитывать перед использованием.
</p><p>Основное ограничение заключается в том, что если диск выходит из строя, а вы
недавно не выполняли синхронизацию, вы можете не восстановить данные полностью.
В частности, вы можете не восстановить данные в объеме, равном размеру
измененных или удаленных файлов с момента последней операции синхронизации.
Это происходит, даже если измененные или удаленные файлы не находятся
на отказавшем диске. Вот почему SnapRAID лучше подходит для
данных, которые редко меняются.
</p><p>С другой стороны, недавно добавленные файлы не препятствуют восстановлению уже
существующих файлов. Вы потеряете только недавно добавленные файлы,
если они находятся на отказавшем диске.
</p><p>Другие ограничения SnapRAID:
<p>SnapRAID — это гибрид между RAID и программой резервного копирования, стремящийся сочетать
в себе лучшие преимущества обоих подходов. Однако у него есть некоторые ограничения, которые вам
следует учесть перед использованием.
</p><p>Основное ограничение заключается в том, что в случае сбоя диска вы можете восстановить данные только до
состояния последней операции синхронизации (<b>sync</b>). Любые данные, добавленные или измененные
с момента последней синхронизации и находящиеся на отказавшем диске, будут потеряны.
</p><p>Следовательно, SnapRAID в первую очередь подходит для данных, которые редко меняются.
</p><p>Для данных, которые уже существовали на момент последней синхронизации, надежность восстановления зависит
от того, используется ли опция снимка (<b>snapshot</b>):
</p><ul>
<li>
При наличии поддержки снимков (доступно на Btrfs, ZFS, Bcachefs и NTFS),
SnapRAID может автоматически поддерживать независимую замороженную копию
каждой поддерживаемой файловой системы данных.
Это гарантирует, что даже если вы измените или удалите файлы в вашей живой файловой системе
во время или после синхронизации, процесс восстановления останется согласованным и надежным.
</li>
</ul>
<ul>
<li>
Без поддержки снимков удаление или изменение файлов после <b>sync</b>
может предотвратить полное восстановление других отказавших дисков. Это происходит
потому, что четность больше не соответствует измененным файлам, даже если
эти файлы находятся не на отказавшем диске. С другой стороны, недавно добавленные
файлы не препятствуют восстановлению уже существующих файлов.
</li>
</ul>
<p>Другие ограничения SnapRAID:
</p><ul>
<li>
Со SnapRAID у вас все еще отдельные файловые системы для каждого диска.
@ -230,7 +244,7 @@ SnapRAID может восстановить данные только при о
</div>
<div class="manual-section-level-1">
<h1 id="sec4" class="manual-title-level-1">
Getting Started
Начало работы (Getting Started)
</h1>
<p>Чтобы использовать SnapRAID, вам нужно сначала выбрать один диск в вашем дисковом массиве
для выделения под информацию <b>четности</b> (parity). С одним диском для четности, вы
@ -304,7 +318,7 @@ snapraid sync
обновлять информацию четности, запуская команду <b>sync</b>.
</p><div class="manual-section-level-2">
<h2 id="sec4-1" class="manual-title-level-2">
Scrubbing
Скрабирование (Scrubbing)
</h2>
<p>Для периодической проверки данных и четности на наличие ошибок, вы можете
запустить команду <b>scrub</b>.
@ -344,11 +358,11 @@ snapraid -p bad scrub
</p></div>
<div class="manual-section-level-2">
<h2 id="sec4-2" class="manual-title-level-2">
Pooling
Объединение (Pooling)
</h2>
<p>Примечание: Функция объединения (pooling), описанная ниже, была заменена инструментом
mergerfs, который теперь является рекомендуемым вариантом для пользователей Linux
в сообществе SnapRAID. Mergefs предоставляет более гибкий и эффективный
в сообществе SnapRAID. Mergerfs предоставляет более гибкий и эффективный
способ объединения нескольких дисков в единую точку монтирования,
обеспечивая беспрепятственный доступ к файлам по всему массиву без
опоры на символические ссылки. Он хорошо интегрируется со SnapRAID для
@ -419,7 +433,7 @@ fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1
</div>
<div class="manual-section-level-2">
<h2 id="sec4-3" class="manual-title-level-2">
Undeleting
Восстановление удаленных файлов (Undeleting)
</h2>
<p>SnapRAID функционирует скорее как программа резервного копирования, чем как система RAID,
и может использоваться для восстановления или отмены удаления файлов до их
@ -444,7 +458,7 @@ snapraid fix -m
</div>
<div class="manual-section-level-2">
<h2 id="sec4-4" class="manual-title-level-2">
Recovering
Восстановление (Recovering)
</h2>
<p>Случилось худшее, и вы потеряли один или несколько дисков!
</p><p>НЕ ПАНИКУЙТЕ! Вы сможете их восстановить!
@ -532,27 +546,27 @@ snapraid sync
</div>
<div class="manual-section-level-1">
<h1 id="sec5" class="manual-title-level-1">
Commands
Команды (Commands)
</h1>
<p>SnapRAID предоставляет несколько простых команд, которые позволяют:
</p><ul>
<li>
Печатать статус массива -&gt; <b>status</b>
Вывести статус массива -&gt; <b>status</b>
</li>
<li>
Управлять дисками -&gt; <b>smart</b>, <b>probe</b>, <b>up</b>, <b>down</b>
</li>
<li>
Сделать резервную копию/снимок -&gt; <b>sync</b>
Создать точку резервного копирования/восстановления -&gt; <b>sync</b>
</li>
<li>
Периодически проверять данные -&gt; <b>scrub</b>
</li>
<li>
Восстановить последнюю резервную копию/снимок -&gt; <b>fix</b>.
Восстановить последнюю точку резервного копирования/восстановления -&gt; <b>fix</b>.
</li>
</ul>
<p>Команды должны быть написаны строчными буквами.
<p>Команды должны быть написаны строчными (маленькими) буквами.
</p><div class="manual-section-level-2">
<h2 id="sec5-1" class="manual-title-level-2">
status
@ -703,9 +717,10 @@ updated
<div class="manual-tag-name">
moved
</div><div class="manual-tag-description">
Файлы, перемещенные в другой каталог на том же диске.
Они идентифицируются как имеющие то же имя, размер, метку времени
и inode, но другой каталог.
Файлы, перемещенные или переименованные на том же диске с
сохранением того же inode. Они идентифицируются по совпадению
inode, размера и метки времени, но имеют другой путь. Имя файла
также может отличаться.
</div>
</div>
<div class="manual-tag-entry">
@ -724,14 +739,13 @@ copied
<div class="manual-tag-name">
relocated
</div><div class="manual-tag-description">
файлы, перемещенные на тот же или другой диск, где
оригинал исчез.
Файлы, перемещенные в другой каталог или на другой диск,
где исходный файл исчез, а inode не сохранился.
Они идентифицируются по совпадению имени, размера и метки
времени.
Если дробная часть метки времени равна нулю, для идентификации
должен совпадать полный путь.
В отличие от файлов 'moved' на том же диске, перемещенные файлы
имеют другой inode.
времени. Если дробная часть метки времени равна нулю, для
идентификации должен совпадать полный путь. В отличие от файлов
'moved', перемещенные (relocated) файлы требуют, чтобы имя файла
оставалось прежним.
</div>
</div>
<div class="manual-tag-entry">
@ -813,13 +827,12 @@ full - Проверить все.
<h2 id="sec5-9" class="manual-title-level-2">
fix
</h2>
<p>Исправляет все файлы и данные четности.
</p><p>Все файлы и данные четности сравниваются с состоянием снимка,
сохраненным при последнем <b>sync</b>.
Если обнаружено различие, оно возвращается к сохраненному снимку.
</p><p>ВНИМАНИЕ! Команда <b>fix</b> не различает ошибки и
преднамеренные изменения. Она безусловно возвращает состояние файла
к последнему <b>sync</b>.
<p>Восстанавливает все файлы и данные четности.
</p><p>Все файлы и данные четности сравниваются с состоянием, сохраненным во время
последней синхронизации <b>sync</b>. Если обнаружено отличие, оно возвращается к сохраненному состоянию.
</p><p>ВНИМАНИЕ!
Команда <b>fix</b> не делает различий между ошибками и преднамеренными изменениями.
Она безоговорочно возвращает состояние файлов к моменту последней <b>sync</b>.
</p><p>Если не указана другая опция, обрабатывается весь массив.
Используйте опции фильтрации, чтобы выбрать подмножество файлов или дисков для работы.
</p><p>Чтобы исправить только блоки, помеченные как плохие во время <b>sync</b> и <b>scrub</b>,
@ -952,7 +965,7 @@ locate
</div>
<div class="manual-section-level-1">
<h1 id="sec6" class="manual-title-level-1">
Options
Параметры (Options)
</h1>
<p>SnapRAID предоставляет следующие опции:
</p><div class="manual-option-list">
@ -1131,14 +1144,14 @@ DAYS — это минимальный возраст в днях для бло
</div><div class="manual-option-description">
Применяет глобальное ограничение пропускной способности для всех дисков. RATE — это
количество байтов в секунду. Вы можете указать множитель,
например K, M или G (например, --bw-limit 1G).
например K, M, G или T (например, --bw-limit 1G).
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-t, --tail РАЗМЕР
-t, --tail SIZE
</div><div class="manual-option-description">
Ограничивает список файлов теми, которые используют не более
указанного размера хвоста дисков четности.
@ -1294,10 +1307,10 @@ DAYS — это минимальный возраст в днях для бло
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-W, --force-realloc-tail РАЗМЕР
-W, --force-realloc-tail SIZE
</div><div class="manual-option-description">
Работает как -R, --force-realloc, но ограничивается указанной хвостовой
частью (последние РАЗМЕР байт) каждого файла четности.
частью (последние SIZE байт) каждого файла четности.
Принудительно перераспределяет (перемещает) любые фрагменты/блоки файлов,
хранящиеся в данный момент в этой хвостовой части, позволяя разместить
их в любом месте файла(ов) четности, где есть свободное место
@ -1365,7 +1378,8 @@ SnapRAID.
Начинает обработку с указанного
номера блока. Это может быть полезно для повторной попытки проверить
или исправить конкретные блоки в случае поврежденного диска.
Эта опция в основном предназначена для расширенного ручного восстановления.
Эта опция в основном предназначена для расширенного ручного восстановления
и поддерживается только командами <b>check</b> и <b>fix</b>.
</div>
</div>
</div>
@ -1375,7 +1389,8 @@ SnapRAID.
-B, --count BLKCOUNT
</div><div class="manual-option-description">
Обрабатывает только указанное количество блоков.
Эта опция в основном предназначена для расширенного ручного восстановления.
Эта опция в основном предназначена для расширенного ручного восстановления
и поддерживается только командами <b>check</b> и <b>fix</b>.
</div>
</div>
</div>
@ -1441,7 +1456,7 @@ SnapRAID.
</div>
<div class="manual-section-level-1">
<h1 id="sec7" class="manual-title-level-1">
Configuration
Конфигурация (Configuration)
</h1>
<p>SnapRAID требует файл конфигурации, чтобы знать, где находится ваш дисковый массив
и где хранить информацию четности.
@ -1538,6 +1553,10 @@ data NAME DIR
файловой системе.
</p><p>Вы можете изменять точку монтирования по мере необходимости, пока вы
сохраняете NAME фиксированным.
</p><p>Однако настроенный путь должен постоянно указывать на те же
базовые данные. Если путь содержит символические ссылки,
их целевые объекты должны оставаться неизменными. Перенаправление
таких ссылок для смены каталога данных на лету не поддерживается.
</p><p>Вы должны использовать одну опцию для каждого диска данных в массиве.
</p><p>Вы можете переименовать диск позже, изменив NAME непосредственно
в файле конфигурации, а затем запустив команду <b>sync</b>.
@ -1558,6 +1577,29 @@ extra NAME DIR
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-7" class="manual-title-level-2">
snapshot
</h2>
<p>Включает использование снимков файловой системы для команд <b>sync</b>, <b>scrub</b>,
<b>check</b> и <b>fix</b>.
</p><p>Если опция включена, SnapRAID создает снимок только для чтения каждой поддерживаемой
файловой системы данных в начале операции 'sync'. Это обеспечивает стабильный срез
каждой файловой системы, предотвращая изменение данных, используемых для вычисления
четности, последующими модификациями.
</p><p>Это значительно улучшает восстановление: если файл удаляется из живой файловой системы,
он остается сохраненным в снимке. Это предотвращает «нарушение» четности
для этого блока, гарантируя, что вы все еще сможете успешно восстановить данные
в случае сбоя другого диска.
</p><p>Эта опция применяется исключительно к дискам с данными, отформатированным в файловых
системах Btrfs, Bcachefs или ZFS в Linux и NTFS в Windows.
Диски четности или диски с данными, использующие другие файловые системы, всегда будут использовать
живую версию файловой системы.
</p><p>Создание и удаление снимков требуют прав администратора.
Убедитесь, что SnapRAID запущен с необходимыми привилегиями (например, sudo), когда
включена эта опция.
</p><p>Подробное объяснение жизненного цикла снимков см. в разделе SNAPSHOTS.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
nohidden
</h2>
<p>Исключает все скрытые файлы и каталоги.
@ -1565,7 +1607,7 @@ nohidden
В Windows — это те, у которых есть скрытый атрибут.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
exclude/include PATTERN
</h2>
<p>Определяет шаблоны файлов или каталогов для исключения или включения
@ -1576,11 +1618,15 @@ exclude/include PATTERN
Если ни один шаблон не совпадает, файл исключается, если последний
указанный шаблон — это <b>include</b>, или включается, если последний шаблон
— это <b>exclude</b>.
</p><p>Обратите внимание, что фильтрация выполняется иерархически во время
обхода каталогов. Если каталог совпадает с правилом <b>exclude</b>, весь
каталог пропускается (отсекается), и любые правила <b>include</b> для
файлов или подкаталогов внутри него не будут оцениваться.
</p><p>Подробнее о спецификациях шаблонов см. в разделе PATTERN.
</p><p>Эту опцию можно использовать несколько раз.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
blocksize SIZE_IN_KIBIBYTES
</h2>
<p>Определяет базовый размер блока в кибибайтах для четности.
@ -1622,7 +1668,7 @@ mkfs.ext4 -m 0 -T largefile4 DEVICE
каких-либо потерь пространства.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
hashsize SIZE_IN_BYTES
</h2>
<p>Определяет размер хэша в байтах для сохраненных блоков.
@ -1657,7 +1703,7 @@ RAM = (8 * 4 * 10^12) * (1+8) / (512 * 2^10) = 0.51 GiB
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
autosave SIZE_IN_GIGABYTES
</h2>
<p>Автоматически сохраняет состояние при синхронизации или проверке после
@ -1666,7 +1712,7 @@ autosave SIZE_IN_GIGABYTES
с нуля, если они были прерваны сбоем машины или любым другим событием.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
temp_limit TEMPERATURE_CELSIUS
</h2>
<p>Устанавливает максимально допустимую температуру диска в Цельсиях. Если указано,
@ -1697,14 +1743,14 @@ SnapRAID периодически проверяет температуру вс
Чтобы отобразить температуру всех дисков, используйте опцию -A или --stats.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
temp_sleep TIME_IN_MINUTES
</h2>
<p>Устанавливает время ожидания, в минутах, когда достигается предел температуры.
В течение этого периода диски остаются остановленными. По умолчанию — 5 минут.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
pool DIR
</h2>
<p>Определяет каталог объединения (pooling), где создается виртуальное представление
@ -1712,7 +1758,7 @@ pool DIR
</p><p>Каталог должен уже существовать.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
share UNC_DIR
</h2>
<p>Определяет путь UNC Windows, необходимый для удаленного доступа к дискам.
@ -1726,7 +1772,7 @@ share UNC_DIR
</p><p>Эта опция требуется только для Windows.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
smartctl DISK/PARITY OPTIONS...
</h2>
<p>Определяет пользовательские опции smartctl для получения атрибутов SMART для
@ -1740,6 +1786,8 @@ PARITY — это одно из имен четности: <b>parity</b>, <b>2-p
</p><p>В указанных OPTIONS строка <b>%s</b> заменяется
именем устройства. Для контроллеров RAID устройство,
вероятно, фиксировано, и вам может не потребоваться использовать <b>%s</b>.
</p><p>Вы также можете указать пользовательскую строку параметров информации с помощью
тега <b>[info: ...]</b>, чтобы заменить параметр по умолчанию <b>-a</b>.
</p><p>Возможные опции см. в документации smartmontools:
</p><pre>
<a href="https://www.smartmontools.org/wiki/Supported_RAID-Controllers">https://www.smartmontools.org/wiki/Supported_RAID-Controllers</a>
@ -1747,11 +1795,12 @@ PARITY — это одно из имен четности: <b>parity</b>, <b>2-p
</pre>
<p>Например:
</p><pre>
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl parity -d sat %s
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
smartignore DISK/PARITY ATTR [ATTR...]
</h2>
<p>Игнорирует указанный атрибут SMART при вычислении вероятности
@ -1761,19 +1810,23 @@ smartignore DISK/PARITY ATTR [ATTR...]
PARITY — это одно из имен четности: <b>parity</b>, <b>2-parity</b>, <b>3-parity</b>,
<b>4-parity</b>, <b>5-parity</b>, <b>6-parity</b> или <b>z-parity</b>.
Специальное значение * может использоваться для игнорирования атрибута на всех дисках.
</p><p>Например, чтобы игнорировать атрибут <b>Current Pending Sector Count</b> на
всех дисках:
</p><p>Можно указать несколько атрибутов, разделенных пробелами.
Каждый атрибут может быть указан как число от 1 до 255 или как имя,
нечувствительное к регистру (например, <b>Current_Pending_Sector</b>).
</p><p>Например, чтобы игнорировать атрибуты <b>Current Pending Sector Count</b> и
<b>Reallocated Sectors Count</b> на всех дисках по их номеру или имени:
</p><pre>
smartignore * 197
smartignore * 197 5
smartignore * Current_Pending_Sector Reallocated_Sector_Ct
</pre>
<p>Чтобы игнорировать его только на первом диске четности:
<p>Чтобы игнорировать их только на первом диске четности:
</p><pre>
smartignore parity 197
smartignore parity 197 5
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
Examples
<h2 id="sec7-19" class="manual-title-level-2">
Примеры (Examples)
</h2>
<p>Пример типичной конфигурации для Unix:
</p><pre>
@ -1785,7 +1838,7 @@ data d2 /mnt/disk2/
data d3 /mnt/disk3/
exclude /lost+found/
exclude /tmp/
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/sg0
smartctl 2-parity -d areca,2/1 /dev/sg0
@ -1801,7 +1854,7 @@ data d3 I:\array\
exclude Thumbs.db
exclude \$RECYCLE.BIN
exclude \System Volume Information
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/arcmsr0
smartctl 2-parity -d areca,2/1 /dev/arcmsr0
@ -1810,7 +1863,149 @@ smartctl 2-parity -d areca,2/1 /dev/arcmsr0
</div>
<div class="manual-section-level-1">
<h1 id="sec8" class="manual-title-level-1">
Pattern
Снимки (Snapshots)
</h1>
<p>Если в конфигурации включена опция снимков, SnapRAID использует снимки
файловой системы для сохранения стабильности данных, считываемых во время
операции, даже если файлы в живых файловых системах впоследствии изменяются
или удаляются.
</p><p>Управление снимками происходит полностью автоматически и прозрачно.
Вы можете продолжать использовать SnapRAID точно так же, как и раньше, получая
дополнительную защиту, обеспечиваемую снимками, которые полностью обрабатываются в
фоновом режиме.
</p><p>Это дает два основных преимущества:
</p><p>Согласованность — Файлы, измененные в живой файловой системе во время длительного
</p><p>процесса sync или scrub, не вызовут несоответствия четности или прерывания
операций, поскольку каждая файловая система со снимком остается неизменной
на протяжении всей операции.
</p><p>Восстановление — Если файл обновляется или удаляется из живой файловой системы,
</p><p>он остается сохраненным в снимке. Если сбой диска произойдет
до запуска следующей синхронизации sync, SnapRAID использует данные, сохраненные
в снимке, для реконструкции отказавшего диска.
</p><p>В случае сбоя диска во время активного процесса sync,
SnapRAID также может автоматически читать как из снимка предыдущего
вычисления четности, так и из текущего.
Это максимизирует вероятность полного восстановления, предоставляя
доступ к точным блокам данных, необходимым для решения уравнений четности,
даже если эти блоки были изменены или удалены между синхронизациями.
</p><p>Без снимков обновленный или удаленный файл на исправном диске
приводит к отсутствию блоков данных, которые могут потребоваться для
восстановления других отказавших дисков.
</p><p>Снимки создаются только для дисков с данными и только в том случае, если базовая
файловая система поддерживает эту функциональность. Диски четности всегда используют
живую файловую систему.
</p><p>В настоящее время это поддерживается на Btrfs, Bcachefs и ZFS в Linux
и на NTFS в Windows.
</p><p>Вы можете комбинировать диски с данными с различными файловыми системами. Только те из них,
которые поддерживают снимки, будут использовать их, в то время как другие диски продолжат
работать напрямую с живой файловой системой.
</p><p>Создание и удаление снимков требуют прав администратора.
Убедитесь, что SnapRAID запущен с необходимыми привилегиями (например, sudo),
когда снимки включены.
</p><div class="manual-section-level-2">
<h2 id="sec8-1" class="manual-title-level-2">
Поведение команд при использовании снимков
</h2>
<p>Команды <b>sync</b> и <b>scrub</b> используют снимки для дисков с данными, чьи
файловые системы их поддерживают. На диске со снимком команда видит
стабильный образ файловой системы, не затронутый одновременными изменениями
в живой файловой системе.
Во время <b>sync</b> новый снимок создается независимо для каждой поддерживаемой
файловой системы данных. Эти снимки в совокупности предоставляют данные,
используемые для вычисления четности.
Напротив, команда <b>scrub</b> использует последний снимок, созданный во время
самой последней синхронизации, чтобы поддерживать надежную точку отсчета,
соответствующую существующей четности.
</p><p>Для команд <b>check</b> и <b>fix</b> использование последнего снимка
зависит от того, нацелены ли конкретные диски с помощью опции
-d, --filter-disk.
</p><p>Диск, явно выбранный с помощью -d («цель» операции),
всегда использует живую файловую систему. Для <b>fix</b> это позволяет восстановить
данные на активную замену диска. Для <b>check</b> это позволяет симулировать
операцию <b>fix</b> при тех же условиях.
</p><p>Доступ ко всем остальным дискам с данными («справочным» дискам) будет осуществляться через
их снимки. Это гарантирует, что даже если вы изменяете файлы
на своих исправных дисках во время восстановления, SnapRAID
имеет стабильную, замороженную точку отсчета для решения уравнений четности.
</p><p>Если опция -d не предоставлена, SnapRAID предполагает, что операция применяется
ко всему массиву; в этом случае <b>check</b> и <b>fix</b> будут использовать исключительно
живые файловые системы.
</p><p>Все остальные команды работают исключительно с живой файловой системой.
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Жизненный цикл снимков (Snapshots Lifecycle)
</h1>
<p>SnapRAID управляет тремя конкретными снимками, <b>stable</b>, <b>pending</b> и <b>scan</b>,
внутри скрытого каталога в корне каждого подтома данных.
В Btrfs, Bcachefs и NTFS используется каталог <b>.snapraid/</b>,
в ZFS — стандартный <b>.zfs/snapshot/</b>.
</p><p>Снимок <b>stable</b> представляет собой состояние последней успешно
завершенной синхронизации <b>sync</b>, содержащей точные данные, использованные для
вычисления текущей четности. Он служит основным источником данных
для команд <b>scrub</b>, <b>check</b> и <b>fix</b>.
</p><p>Снимок <b>scan</b> — это временный образ, создаваемый в начале
<b>sync</b> для обеспечения замороженного состояния для сканирования и вычисления четности.
После сканирования и сохранения нового состояния содержимого он заменяет предыдущий
снимок <b>pending</b>.
</p><p>Снимок <b>pending</b> — это образ, используемый прерванной синхронизацией <b>sync</b>.
После успешного завершения операции предыдущий снимок <b>stable</b>
удаляется, а снимок <b>pending</b> повышается в статусе, чтобы
занять его место в качестве нового стабильного ориентира.
</p><p>Если процесс <b>sync</b> прерывается, снимок <b>pending</b> сохраняется.
Последующие команды <b>scrub</b>, <b>check</b> и <b>fix</b> будут использовать этот
ожидающий снимок, так как он соответствует состоянию файловой системы, записанному в
файле .content, даже если четность синхронизирована лишь частично.
</p><p>В случае прерывания <b>sync</b> команды <b>check</b> и <b>fix</b>
также читают данные из снимка <b>stable</b> для извлечения блоков данных
из файлов, которые были обновлены или удалены во время синхронизации.
Это возможно потому, что файл .content сохраняет метаданные для
всех измененных или удаленных файлов на протяжении всего процесса sync.
Эта историческая информация очищается только после успешного завершения sync
и сохранения финальной версии файла .content.
</p><p>Если <b>sync</b> перезапускается после прерывания, существующий
ожидающий (pending) снимок удаляется, и создается новый для
фиксации текущего состояния живой файловой системы.
Однако, если <b>sync</b> был прерван, избегайте изменения, удаления,
замены или перемещения файлов до тех пор, пока последующий <b>sync</b> не завершится
успешно. Четность все еще может содержать блоки, вычисленные на основе снимка,
использованного прерванной синхронизацией. Более поздняя синхронизация может
заменить этот снимок, сделав промежуточные версии файлов недоступными для
восстановления.
</p><div class="manual-section-level-2">
<h2 id="sec9-1" class="manual-title-level-2">
Внешнее резервное копирование со снимками файловой системы (External backups with filesystem snapshots)
</h2>
<p>Когда снимки файловой системы включены, SnapRAID обращается к снимкам или
создает их в корне каждого подтома, тома или набора данных (dataset).
</p><p>Простой способ избежать любых конфликтов со сторонними инструментами —
указать в директиве <b>data</b> обычный подкаталог внутри подтома или тома
(например, <b>/mnt/subvol/data</b> вместо <b>/mnt/subvol</b>). SnapRAID всегда
создает каталог снимков в корне подтома (например,
<b>/mnt/subvol/.snapraid/</b>), оставив подкаталог данных чистым, благодаря
чему снимки останутся снаружи и будут невидимы для программ резервного
копирования, работающих внутри него.
</p><p>В противном случае, если настроенный каталог <b>data</b> сам по себе является
корнем подтома или тома, SnapRAID создает каталог <b>.snapraid/</b> прямо внутри
него (в Btrfs, Bcachefs и NTFS). Хотя SnapRAID автоматически исключает этот
каталог из собственного сканирования, внешние утилиты резервного
копирования или синхронизации файлов обнаружат его. Если каталог не
исключен, они могут войти в снимки или ссылки на каталоги и скопировать
все замороженное дерево данных, дублируя файлы и исчерпывая место в
хранилище резервных копий. Всегда настраивайте внешние утилиты резервного
копирования на исключение каталога <b>.snapraid/</b>.
</p><p>В ZFS снимки доступны через стандартный виртуальный каталог
<b>.zfs/snapshot/</b>, а не через <b>.snapraid/</b>. По умолчанию (<b>snapdir=hidden</b>)
ZFS скрывает этот каталог из списков директорий, поэтому внешние утилиты
резервного копирования не будут сканировать его. Если вы включили
<b>snapdir=visible</b>, обязательно настройте утилиты резервного копирования на
исключение каталога <b>.zfs/</b>.
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
Шаблон (Pattern)
</h1>
<p>Шаблоны обеспечивают гибкий способ фильтрации файлов для включения или
исключения. Используя символы подстановки (globbing), вы можете определить правила,
@ -1824,25 +2019,26 @@ Pattern
прямой косой черте, что делает ее подходящей для сопоставления внутри одного
компонента пути. Это стандартное поведение подстановочных знаков, знакомое
по оболочке (shell).
</p><p>Двойная звездочка <b>**</b> более мощная, она соответствует любой последовательности
символов, включая разделители каталогов. Это позволяет шаблонам соответствовать
нескольким уровням каталогов. Когда <b>**</b> появляется непосредственно в
шаблоне, она может соответствовать нулю или более символам, включая косые черты между
окружающим буквальным текстом.
</p><p>Наиболее важным использованием <b>**</b> является специальная форма <b>/**/</b>. Она соответствует
нулю или более полным уровням каталогов, что позволяет сопоставлять файлы
на любой глубине в дереве каталогов, не зная точной структуры пути.
Например, шаблон <b>src/**/main.js</b> соответствует <b>src/main.js</b> (пропуск
ноля каталогов), <b>src/ui/main.js</b> (пропуск одного каталога) и
<b>src/ui/components/main.js</b> (пропуск двух каталогов).
</p><p>Символ подстановки двойная звездочка <b>**</b> сопоставляется через разделители
каталогов только тогда, когда он примыкает к разделителю каталогов (перед ним
или после него стоит косая черта). В этой форме он соответствует нулю или
более символам на нескольких уровнях каталогов. Например, <b>foo/**/bar</b>
соответствует <b>foo/bar</b>, <b>foo/a/bar</b> и <b>foo/a/b/bar</b>; <b>**/build</b> соответствует
<b>build</b> и <b>foo/bar/build</b>; а <b>src/**.js</b> соответствует <b>src/main.js</b> и
<b>src/ui/components/main.js</b>.
Автономная форма <b>/**/</b> не принимается в качестве полного шаблона.
</p><p>Когда <b>**</b> не примыкает к косой черте, он ведет себя как <b>*</b> и не
соответствует разделителям каталогов. Например, <b>**.jpg</b> соответствует
<b>photo.jpg</b> в текущем каталоге, но не соответствует <b>dir/photo.jpg</b>. Для этой
цели используйте <b>**/*.jpg</b>.
</p><p>Классы символов с использованием квадратных скобок <b>[]</b> соответствуют одному символу из
заданного набора или диапазона. Как и другие односимвольные шаблоны, они
не соответствуют разделителям каталогов. Классы поддерживают диапазоны и отрицание с
использованием восклицательного знака.
</p><p>Фундаментальное различие, которое следует помнить, заключается в том, что <b>*</b>, <b>?</b> и классы
символов соблюдают границы каталогов и соответствуют только внутри одного
компонента пути, в то время как <b>**</b> — единственный шаблон, который может соответствовать
через разделители каталогов.
компонента пути, в то время как <b>**</b> может соответствовать через разделители
каталогов только тогда, когда примыкает к косой черте.
</p><p>Существует четыре различных типа шаблонов:
</p><div class="manual-option-list">
<div class="manual-option-entry">
@ -1930,6 +2126,25 @@ include /movies/
include /musics/
include /pictures/
</pre>
<p>Обратите внимание, что исключение каталога (с помощью DIR/ или /PATH/DIR/)
предотвращает вход SnapRAID в этот каталог и его сканирование.
Следовательно, невозможно повторно включить файл или подкаталог,
находящийся внутри исключенного родительского каталога, поскольку сканер
никогда не переходит в него.
</p><p>Например, следующая конфигурация НЕ включит <b>file.dat</b>, поскольку
<b>/keep/</b> отсекается до того, как <b>file.dat</b> сможет быть проверен:
</p><pre>
# НЕ работает как ожидается: /keep/ полностью пропускается
include /keep/file.dat
exclude /keep/
</pre>
<p>Чтобы исключить файлы внутри каталога, сохранив определенные файлы,
исключайте шаблон файлов внутри каталога, а не сам каталог:
</p><pre>
# Работает: /keep/ сканируется, но остальные файлы внутри него исключаются
include /keep/file.dat
exclude /keep/*
</pre>
<p>В командной строке, используя опцию -f, вы можете использовать только шаблоны <b>include</b>.
Например:
</p><pre>
@ -1941,8 +2156,8 @@ snapraid -f "*.mp3" check
заключить их в кавычки, чтобы предотвратить их расширение оболочкой.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Ignore File
<h1 id="sec11" class="manual-title-level-1">
Файл исключений (Ignore File)
</h1>
<p>В дополнение к глобальным правилам в файле конфигурации, вы можете
размещать файлы <b>.snapraidignore</b> в любом каталоге внутри массива для
@ -2007,18 +2222,20 @@ build/
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
Content
<h1 id="sec12" class="manual-title-level-1">
Содержимое (Content)
</h1>
<p>SnapRAID хранит список и контрольные суммы ваших файлов в файле content.
</p><p>Это бинарный файл, который перечисляет все файлы, присутствующие в вашем дисковом массиве,
вместе со всеми контрольными суммами для проверки их целостности.
</p><p>Этот файл считывается и записывается командами <b>sync</b> и <b>scrub</b> и
считывается командами <b>fix</b>, <b>check</b> и <b>status</b>.
</p><p>Файл content считывается и записывается командами <b>sync</b>, <b>scrub</b>,
<b>touch</b> и <b>rehash</b>. Он считывается командами <b>status</b>, <b>diff</b>, <b>check</b>,
<b>fix</b>, <b>list</b>, <b>dup</b>, <b>locate</b> и <b>pool</b>, и полностью игнорируется
командами <b>smart</b>, <b>probe</b>, <b>up</b>, <b>down</b> и <b>devices</b>.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec11" class="manual-title-level-1">
Parity
<h1 id="sec13" class="manual-title-level-1">
Четность (Parity)
</h1>
<p>SnapRAID хранит информацию четности вашего массива в файлах parity.
</p><p>Это бинарные файлы, содержащие вычисленную четность всех
@ -2027,8 +2244,8 @@ Parity
только считываются командами <b>scrub</b> и <b>check</b>.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec12" class="manual-title-level-1">
Encoding
<h1 id="sec14" class="manual-title-level-1">
Кодировка (Encoding)
</h1>
<p>SnapRAID в Unix игнорирует любое кодирование. Он считывает и хранит
имена файлов с тем же кодированием, которое используется файловой системой.
@ -2040,6 +2257,279 @@ Encoding
Это влияет только на печатаемые имена файлов; если вы
перенаправляете вывод консоли в файл, результирующий файл всегда
в формате UTF-8.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec15" class="manual-title-level-1">
Код возврата (Exit Code)
</h1>
<p>SnapRAID завершает работу со следующими кодами ошибок:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
0
</div><div class="manual-tag-description">
Все в порядке.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
1
</div><div class="manual-tag-description">
Команда обнаружила ошибки.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2
</div><div class="manual-tag-description">
Команда <b>diff</b> определила, что все в порядке, но требуется <b>sync</b>.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
3
</div><div class="manual-tag-description">
Команда дискового устройства (<b>probe</b>, <b>smart</b>, <b>devices</b>, <b>up</b>,
<b>down</b>) завершена, но по крайней мере одна файловая система работает
в деградированном режиме с отсутствующими устройствами.
</div>
</div>
</div>
</div>
<div class="manual-section-level-1">
<h1 id="sec16" class="manual-title-level-1">
Известные проблемы (Known Issues)
</h1>
<div class="manual-section-level-2">
<h2 id="sec16-1" class="manual-title-level-2">
Границы файловой системы
</h2>
<p>SnapRAID не пересекает границы файловых систем, точек монтирования или
подтомов при сканировании диска данных. При обнаружении такой границы
SnapRAID сообщает ПРЕДУПРЕЖДЕНИЕ и не выполняет сканирование за ее пределами.
</p><p>Файлы, расположенные за такими границами, не включаются в диск данных и
должны настраиваться отдельно, если их необходимо защитить.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-2" class="manual-title-level-2">
Точки монтирования со снимками файловой системы
</h2>
<p>Когда снимки файловой системы включены, вложенные точки монтирования и
bind-монтирования внутри диска данных не поддерживаются.
</p><p>Точки монтирования являются частью пространства имен монтирования работающей
системы и не сохраняются в снимках файловой системы. Следовательно, при
сканировании снимка каталог, скрытый точкой монтирования в активной файловой
системе, может стать видимым.
</p><p>Не размещайте вложенные точки монтирования или bind-монтирования внутри дисков
данных, когда включены снимки файловой системы.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-3" class="manual-title-level-2">
Несколько конфигураций со снимками файловой системы
</h2>
<p>Поддержка снимков не может безопасно совместно использоваться несколькими
независимыми конфигурациями SnapRAID, использующими одно и то же
пространство имен снимков файловой системы.
</p><p>В Btrfs и Bcachefs только одна конфигурация SnapRAID с включенной поддержкой
снимков может использовать каталоги данных в пределах одного и того же
подтома. В ZFS то же ограничение применяется к датасету, а в NTFS — к тому.
</p><p>Несколько конфигураций, использующих одно и то же пространство имен снимков,
работают с одними и теми же снимками <b>stable</b>, <b>pending</b> и <b>scan</b>. Запуск
одной конфигурации может перезаписать или удалить снимки восстановления,
необходимые другой.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-4" class="manual-title-level-2">
Изменения файлов на месте без изменения временных меток
</h2>
<p>SnapRAID обнаруживает изменения файлов путем сравнения размеров файлов и
временных меток модификации (mtime).
</p><p>Если приложение изменяет файл на месте без изменения его размера или
обновления временной метки модификации, "diff" и "sync" не обнаружат
изменение файла, и его четность не будет обновлена.
</p><p>Чтобы SnapRAID гарантированно распознал такие изменения, обновите временную
метку модификации файла (например, с помощью утилиты "touch"). В противном
случае различие будет обнаружено только как несоответствие хэша во время
последующего "scrub" или "check".
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-5" class="manual-title-level-2">
Сопоставление регистра символов non-ASCII в Windows
</h2>
<p>SnapRAID использует стандартную, предсказуемую кодировку UTF-8 на всех
платформах, ограничивая нечувствительное к регистру сопоставление символами
ASCII.
</p><p>Файловые системы Windows страдают от устаревшего архитектурного решения,
навязывающего нечувствительность к регистру для имен файлов Unicode с помощью
произвольных, зависящих от системы таблиц сопоставления. В результате Windows
искажает реальность файловой системы, обрабатывая совершенно разные
последовательности байтов Unicode так, как если бы они были одним и тем же
файлом.
</p><p>Например, <b>À.txt</b> и <b>à.txt</b> — это разные имена Unicode, однако Windows
нелогично считает их идентичными, тогда как SnapRAID сохраняет их подлинное
различие.
</p><p>Это ограничение вызвано непоследовательной обработкой имен файлов Unicode в
Windows и ее упорным стремлением к псевдонимизации без учета регистра. Чтобы
предотвратить расхождения, возникающие из-за преобразования регистра в Windows,
всегда указывайте точный регистр для любых символов non-ASCII в путях
конфигурации и фильтрах.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-6" class="manual-title-level-2">
Восстановление с частичным fix
</h2>
<p>Когда <b>fix</b> ограничен с помощью <b>-S, --start</b> или <b>-B, --count</b>,
SnapRAID работает только с выбранными блоками и не выполняет финализацию
на уровне файлов или помещение в карантин.
</p><p>Если в результате восстановления получаются данные наилучшей попытки (best-effort),
для которых нельзя доказать, что они соответствуют текущему содержимому, такие
блоки все равно могут быть записаны под обычным именем файла. Неопределенность,
связанная с этими восстановленными блоками, не сохраняется после завершения команды.
</p><p>Как следствие, последующий <b>fix</b> будет рассматривать эти читаемые блоки как
корректные данные файла и не попытается восстановить их снова. Это может привести
к тому, что последующее восстановление сообщит об успехе, оставив в файле
неполные или устаревшие данные.
</p><p>Параметры <b>-S</b> и <b>-B</b> предназначены только для расширенного ручного
восстановления, обычно после сбоя обычного <b>fix</b>. Если частичный <b>fix</b> сообщает
о невосстановимых данных, удалите или переименуйте затронутые файлы перед
попыткой повторного восстановления либо проверьте их содержимое вручную.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-7" class="manual-title-level-2">
Жесткие ссылки NTFS и исключенные пути
</h2>
<p>В NTFS записи каталогов кэшируют размер файла и временные метки независимо
для каждой жесткой ссылки. Когда файл изменяется через одну ссылку, записи
каталогов других ссылок, указывающих на тот же файл, могут сохранять
устаревшие метаданные до тех пор, пока к ним не будет осуществлен доступ.
</p><p>SnapRAID автоматически обнаруживает и нормализует это состояние всякий
раз, когда во время сканирования обнаруживаются как минимум две жесткие
ссылки на один и тот же файл. Однако если сканируется только одна жесткая
ссылка, тогда как другие исключены фильтрами или находятся за пределами
пути диска данных, SnapRAID не может обнаружить коллизию inode и полагается
на кэшированные метаданные единственной видимой ссылки.
</p><p>Следовательно, изменения, внесенные через исключенную или внешнюю жесткую
ссылку, могут остаться незамеченными SnapRAID до тех пор, пока метаданные
включенной ссылки не будут обновлены операционной системой (например,
когда к файлу обращаются или открывают его по этому пути).
</p><p>Чтобы избежать этого ограничения, не изменяйте защищенные файлы через
жесткие ссылки, исключенные из SnapRAID, либо убедитесь, что все жесткие
ссылки на файл включены в сканирование, чтобы SnapRAID мог их нормализовать.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-8" class="manual-title-level-2">
Восстановление после прерванного sync с несколькими четностями
</h2>
<p>В массиве с несколькими дисками четности прерванный <b>sync</b> может оставить
уровни четности временно рассинхронизированными относительно друг друга.
Например, четность 1 уже может содержать обновленные данные, тогда как
четность 2 все еще содержит старые данные.
</p><p>Во время выполнения <b>check</b> или <b>fix</b> SnapRAID проверяет различные
комбинации четностей и проверяет восстановленные данные по известным
хэшам блоков (охватывающим блок целиком, обычно 256 КиБ).
</p><p>Если SnapRAID пытается выполнить восстановление, используя
несогласованную смесь старой и новой четности, линейные уравнения RAID
дадут некорректные данные. Чтобы такая недействительная комбинация была
ошибочно принята, уравнения должны были бы случайно восстановить хотя бы
один полный блок размером 256 КиБ настолько идеально, чтобы его хэш
совпал, тогда как другие несинхронизированные блоки в том же страйпе
будут восстановлены с ошибочными данными.
</p><p>Этот сценарий не зависит от коллизии хэшей; напротив, сами уравнения
смешанной четности должны были бы случайно воспроизвести точное исходное
содержимое 256-КиБ блока. Хотя это математически возможно при специально
подготовленных или сильно повторяющихся данных, на реальных данных это
практически невозможно.
</p><p>Если все диски исправны, завершение прерванного <b>sync</b> перед внесением
дальнейших изменений устраняет эту неоднозначность. Если диск вышел из
строя и требуется восстановление, избегайте изменения дисков данных перед
запуском <b>check</b> или <b>fix</b>.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-9" class="manual-title-level-2">
Зарезервированные имена файлов и каталогов
</h2>
<p>SnapRAID резервирует некоторые имена файлов, каталогов и снимков для
своих внутренних операций. Не используйте эти имена для пользовательских
данных:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraidignore
</div><div class="manual-tag-description">
Локальный файл правил исключения.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraid
</div><div class="manual-tag-description">
Каталог-контейнер снимков.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
snapraid-*
</div><div class="manual-tag-description">
Имена снимков ZFS, управляемых SnapRAID.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
*.unrecoverable
</div><div class="manual-tag-description">
Поврежденные файлы, помещенные в карантин во время
восстановления.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.tmp
</div><div class="manual-tag-description">
Временный файл для обновлений файла content.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.lock
</div><div class="manual-tag-description">
Файл блокировки файла content.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
PARITY.spaceholder
</div><div class="manual-tag-description">
Временный файл резервирования места при выделении
четности в Windows.
</div>
</div>
</div>
<p>Использование этих имен для несвязанных данных может привести к тому,
что файлы или снимки будут проигнорированы, ошибочно приняты за метаданные,
перезаписаны, переименованы или удалены.
</p><p>В Windows все варианты регистра также зарезервированы, даже в каталогах
NTFS, настроенных с учетом регистра (например, .SNAPRAIDIGNORE, .SnapRaid,
CONTENT.TMP и CONTENT.Lock).
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec17" class="manual-title-level-1">
Перевод (Translation)
</h1>
<p>Этот документ является автоматическим переводом английского руководства.
Обратитесь к английскому руководству за официальной версией.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec18" class="manual-title-level-1">
Авторские права (Copyright)
</h1>
<p>Этот файл защищен авторским правом (C) 2026 Andrea Mazzoleni
</p></div>
<div class="manual-section-level-1">
<h1 id="sec19" class="manual-title-level-1">
См. также (See Also)
</h1>
<p>snapraid_log(1), snapraidd(1), rsync(1)
</p></div>

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

View file

@ -114,7 +114,7 @@
<div class="manual-section-level-1">
<h1 id="sec1" class="manual-title-level-1">
Synopsis
概要 (Synopsis)
</h1>
<pre>
snapraid [-c, --conf CONFIG]
@ -142,7 +142,7 @@ snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]
</div>
<div class="manual-section-level-1">
<h1 id="sec2" class="manual-title-level-1">
Description
描述 (Description)
</h1>
<p>SnapRAID 是一款专为磁盘阵列设计的备份程序,它存储奇偶校验信息,
以在最多六个磁盘发生故障时进行数据恢复。
@ -181,19 +181,32 @@ SnapRAID 不会锁定您的数据;您可以随时停止使用它,无需重
</div>
<div class="manual-section-level-1">
<h1 id="sec3" class="manual-title-level-1">
Limitations
限制 (Limitations)
</h1>
<p>SnapRAID 是 RAID 和备份程序之间的混合体,旨在结合两者的优点。
然而,在使用它之前,您应该考虑一些限制。
</p><p>主要的限制是,如果一个磁盘发生故障而您最近没有进行同步(sync),
您可能无法完全恢复。
更具体地说,您可能无法恢复自上次同步操作以来已更改或已删除文件的
大小所对应的部分。
即使更改或删除的文件不在发生故障的磁盘上,也会发生这种情况。
这就是为什么 SnapRAID 更适用于很少更改的数据。
</p><p>另一方面,新添加的文件不会阻止对已有文件的恢复。
您只会丢失位于发生故障磁盘上的最近添加的文件。
</p><p>SnapRAID 的其他限制包括:
<p>SnapRAID 是 RAID 和备份程序之间的混合体,旨在结合两者的最佳优势。
但是,在使用它之前,您应该考虑它的一些限制。
</p><p>主要的限制是,如果磁盘发生故障,您只能将数据恢复到上一次 <b>sync</b>(同步)操作的状态。
自上次同步以来添加的任何数据或进行的任何修改(如果位于发生故障的磁盘上)都将丢失。
</p><p>因此,SnapRAID 主要适用于很少更改的数据。
</p><p>对于上次同步时已经存在的数据,恢复的可靠性取决于是否使用了 <b>snapshot</b>(快照)选项:
</p><ul>
<li>
具有快照支持(在 Btrfs、ZFS、Bcachefs 和 NTFS 上可用),
SnapRAID 可以自动维护每个受支持的数据文件系统的独立冻结引用。
这确保了即使您在同步期间或之后在活动文件系统上修改或删除文件,
恢复过程仍保持一致且可靠。
</li>
</ul>
<ul>
<li>
在没有快照支持的情况下,在 <b>sync</b> 之后删除或更改文件
可能会阻止其他损坏磁盘的完全恢复。发生这种情况
是因为校验数据不再与修改后的文件匹配,即使
这些文件不在损坏的磁盘上。另一方面,新添加的文件
不会阻止已存在文件的恢复。
</li>
</ul>
<p>SnapRAID 的其他限制包括:
</p><ul>
<li>
使用 SnapRAID,每个磁盘仍然有单独的文件系统。
@ -219,7 +232,7 @@ SnapRAID 只能从有限数量的磁盘故障中恢复数据。
</div>
<div class="manual-section-level-1">
<h1 id="sec4" class="manual-title-level-1">
Getting Started
入门 (Getting Started)
</h1>
<p>要使用 SnapRAID,您需要首先选择磁盘阵列中的一个磁盘专用于
<b>parity</b>(奇偶校验)信息。使用一个奇偶校验磁盘,
@ -282,7 +295,7 @@ snapraid sync
</p><p>现在您可以开始随意使用您的阵列,并定期运行 <b>sync</b> 命令更新奇偶校验信息。
</p><div class="manual-section-level-2">
<h2 id="sec4-1" class="manual-title-level-2">
Scrubbing
数据擦洗 (Scrubbing)
</h2>
<p>要定期检查数据和奇偶校验的错误,您可以运行 <b>scrub</b> 命令。
</p><pre>
@ -317,11 +330,11 @@ snapraid -p bad scrub
</p></div>
<div class="manual-section-level-2">
<h2 id="sec4-2" class="manual-title-level-2">
Pooling
合并池 (Pooling)
</h2>
<p>注意:下面描述的 pooling 功能已被 mergerfs 工具取代,
mergerfs 现在是 SnapRAID 社区推荐的 Linux 用户选项。
Mergefs 提供了一种更灵活、更高效的方式,将多个驱动器汇集到一个
Mergerfs 提供了一种更灵活、更高效的方式,将多个驱动器汇集到一个
统一的挂载点中,允许跨阵列无缝访问文件,而无需依赖符号链接。
它与 SnapRAID 很好地集成以提供奇偶校验保护,常用于
OpenMediaVault (OMV) 或自定义 NAS 配置等设置中。
@ -384,7 +397,7 @@ fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1
</div>
<div class="manual-section-level-2">
<h2 id="sec4-3" class="manual-title-level-2">
Undeleting
取消删除 (Undeleting)
</h2>
<p>SnapRAID 的功能更像一个备份程序而不是 RAID 系统,
它可以使用 -f, --filter 选项来恢复或取消删除文件到其以前的状态:
@ -407,7 +420,7 @@ snapraid fix -m
</div>
<div class="manual-section-level-2">
<h2 id="sec4-4" class="manual-title-level-2">
Recovering
数据恢复 (Recovering)
</h2>
<p>最糟糕的情况发生了,您丢失了一个或多个磁盘!
</p><p>**不要惊慌!** 您将能够恢复它们!
@ -494,9 +507,9 @@ snapraid sync
</div>
<div class="manual-section-level-1">
<h1 id="sec5" class="manual-title-level-1">
Commands
命令 (Commands)
</h1>
<p>SnapRAID 提供了一些简单的命令,允许您:
<p>SnapRAID 提供了几个简单的命令,允许您:
</p><ul>
<li>
打印阵列的状态 -&gt; <b>status</b>
@ -505,22 +518,22 @@ Commands
控制磁盘 -&gt; <b>smart</b>、<b>probe</b>、<b>up</b>、<b>down</b>
</li>
<li>
进行备份/快照 -&gt; <b>sync</b>
创建备份/恢复点 -&gt; <b>sync</b>
</li>
<li>
定期检查数据 -&gt; <b>scrub</b>
</li>
<li>
恢复上次备份/快照 -&gt; <b>fix</b>。
恢复上一个备份/恢复点 -&gt; <b>fix</b>。
</li>
</ul>
<p>命令必须用小写字母书写。
<p>命令必须用小写字母编写。
</p><div class="manual-section-level-2">
<h2 id="sec5-1" class="manual-title-level-2">
status
</h2>
<p>打印磁盘阵列状态的摘要。
</p><p>它包括有关奇偶校验碎片、块未经检查有多久,以及在 scrubbing
</p><p>它包括有关奇偶校验碎片、块未经检查有多久,以及在数据擦洗 (scrubbing)
期间遇到的所有记录的静默错误的信息。
</p><p>所提供的信息指的是您上次运行 <b>sync</b> 的时间。
不考虑后来的修改。
@ -652,8 +665,9 @@ updated
<div class="manual-tag-name">
moved
</div><div class="manual-tag-description">
在同一磁盘上移动到不同目录的文件。
它们通过具有相同的名称、大小、时间戳和 inode,但目录不同来识别。
在同一磁盘上移动或重命名并保留相同 inode 的文件。
它们通过具有相同的 inode、大小和时间戳,但路径不同来识别。
文件名也可以不同。
</div>
</div>
<div class="manual-tag-entry">
@ -670,10 +684,10 @@ copied
<div class="manual-tag-name">
relocated
</div><div class="manual-tag-description">
在相同或不同磁盘上移动的文件,且原始文件已消失。
移动到不同目录或磁盘的文件,且原始文件已消失并不保留 inode。
它们通过具有相同的名称、大小和时间戳进行识别。
如果亚秒级时间戳为零,则必须完整路径匹配才能识别。
与同一磁盘上的 'moved' 文件不同,重定位的文件具有不同的 inode。
与 'moved' 文件不同,重定位的文件要求文件名保持不变。
</div>
</div>
<div class="manual-tag-entry">
@ -745,12 +759,12 @@ full - Scrub 所有内容。
<h2 id="sec5-9" class="manual-title-level-2">
fix
</h2>
<p>修复所有文件和奇偶校验数据。
</p><p>所有文件和奇偶校验数据都与上次 <b>sync</b> 中保存的快照
状态进行比较。
如果发现差异,则将其恢复到存储的快照。
</p><p>**警告!** <b>fix</b> 命令不区分错误和
故意修改。它**无条件地**将文件状态恢复到上次 <b>sync</b>。
<p>修复所有文件和校验数据。
</p><p>将所有文件和校验数据与上一次 <b>sync</b> 中保存的状态进行比较。
如果发现差异,则将其恢复到存储的状态。
</p><p>警告!
<b>fix</b> 命令不区分错误和故意修改。
它会无条件地将文件状态恢复到上一次 <b>sync</b> 的状态。
</p><p>如果未指定其他选项,则处理整个阵列。
使用过滤选项选择要操作的文件或磁盘的子集。
</p><p>要仅修复在 <b>sync</b> 和 <b>scrub</b> 期间标记为坏块的块,
@ -871,7 +885,7 @@ locate
</div>
<div class="manual-section-level-1">
<h1 id="sec6" class="manual-title-level-1">
Options
选项 (Options)
</h1>
<p>SnapRAID 提供以下选项:
</p><div class="manual-option-list">
@ -1045,7 +1059,7 @@ DAYS 是块被 scrub 的最小天数;默认值为 10。
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-t, --tail 大小
-t, --tail SIZE
</div><div class="manual-option-description">
将文件列表限制为那些使用校验盘指定尾部大小以内的文件。
您可以使用乘数,如 K、M、G 或 T(例如 --tail 1G)。
@ -1182,10 +1196,10 @@ DAYS 是块被 scrub 的最小天数;默认值为 10。
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-W, --force-realloc-tail 大小
-W, --force-realloc-tail SIZE
</div><div class="manual-option-description">
工作方式类似于 -R, --force-realloc,但仅限于每个校验文件的
指定尾部部分(最后“大小”字节)。
指定尾部部分(最后 SIZE 字节)。
它会强制重新分配(移动)当前存储在该尾部部分的任何文件分片/块,
允许它们被放置在校验文件中任何有可用空间的地方(包括现有的
空隙)。
@ -1243,7 +1257,7 @@ HHMMSS。在 Windows 批处理文件中,您必须双写 <b>%</b> 字符,
</div><div class="manual-option-description">
从指定的块号开始处理。
在磁盘损坏的情况下,这对于重试检查或修复特定块可能很有用。
此选项主要用于高级手动恢复。
此选项主要用于高级手动恢复,并且仅受 <b>check</b> 和 <b>fix</b> 支持。
</div>
</div>
</div>
@ -1253,7 +1267,7 @@ HHMMSS。在 Windows 批处理文件中,您必须双写 <b>%</b> 字符,
-B, --count BLKCOUNT
</div><div class="manual-option-description">
仅处理指定数量的块。
此选项主要用于高级手动恢复。
此选项主要用于高级手动恢复,并且仅受 <b>check</b> 和 <b>fix</b> 支持。
</div>
</div>
</div>
@ -1316,7 +1330,7 @@ HHMMSS。在 Windows 批处理文件中,您必须双写 <b>%</b> 字符,
</div>
<div class="manual-section-level-1">
<h1 id="sec7" class="manual-title-level-1">
Configuration
配置 (Configuration)
</h1>
<p>SnapRAID 需要一个配置文件来了解您的磁盘阵列
位于何处以及在哪里存储奇偶校验信息。
@ -1404,6 +1418,8 @@ data NAME DIR
NAME 用于标识磁盘,并且必须是唯一的。
DIR 是磁盘在文件系统中的挂载点。
</p><p>您可以根据需要更改挂载点,只要保持 NAME 固定即可。
</p><p>但是,配置的路径必须始终解析为相同的基础数据。如果路径包含符号链接,
其目标必须保持稳定。不支持重定向此类符号链接以在运行中切换数据目录。
</p><p>您应该为阵列中的每个数据磁盘使用一个选项。
</p><p>您可以通过直接在配置文件中更改 NAME,然后运行 <b>sync</b> 命令来
稍后重命名磁盘。
@ -1420,6 +1436,24 @@ extra NAME DIR
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-7" class="manual-title-level-2">
snapshot
</h2>
<p>为 <b>sync</b>、<b>scrub</b>、<b>check</b> 和 <b>fix</b> 命令启用文件系统快照的使用。
</p><p>启用后,SnapRAID 会在“sync”开始时为每个受支持的数据文件系统创建
只读快照。这提供了每个文件系统的稳定视图,防止后续修改改变用于
计算校验的数据。
</p><p>这显著提高了恢复能力:如果从实时文件系统中删除了一个文件,
它仍会保留在快照中。这可以防止该数据块的校验数据变得“损坏”,
从而确保在另一个磁盘发生故障时您仍能成功恢复数据。
</p><p>此选项仅适用于在 Linux 中格式化为 Btrfs、Bcachefs 或 ZFS 文件系统,
以及在 Windows 中格式化为 NTFS 的数据磁盘。
校验磁盘或使用其他文件系统的数据磁盘将始终使用文件系统的活动版本。
</p><p>快照的创建和删除需要管理权限。
启用此选项时,请确保以必要的权限(例如 sudo)运行 SnapRAID。
</p><p>有关快照生命周期的详细说明,请参阅 SNAPSHOTS(快照)部分。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
nohidden
</h2>
<p>排除所有隐藏文件和目录。
@ -1427,7 +1461,7 @@ nohidden
在 Windows 中,它们是具有隐藏属性的文件。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
exclude/include PATTERN
</h2>
<p>定义要从同步过程中排除或包含的文件或目录模式。
@ -1436,11 +1470,13 @@ exclude/include PATTERN
如果它是 <b>include</b> 模式,则包含该文件。
如果没有模式匹配,则如果指定的最后一个模式是 <b>include</b>,则排除该文件,
或者如果指定的最后一个模式是 <b>exclude</b>,则包含该文件。
</p><p>请注意,过滤是在目录遍历期间分层进行的。如果目录匹配 <b>exclude</b> 规则,
则整个目录将被跳过(修剪),并且不会评估其内部文件或子目录的任何 <b>include</b> 规则。
</p><p>有关模式规范的更多详细信息,请参阅 PATTERN 部分。
</p><p>此选项可以多次使用。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
blocksize SIZE_IN_KIBIBYTES
</h2>
<p>定义奇偶校验的基本块大小(以 KiB 为单位)。
@ -1477,7 +1513,7 @@ mkfs.ext4 -m 0 -T largefile4 DEVICE
这允许每个数据磁盘上大约 460,000 个文件而不会浪费任何空间。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
hashsize SIZE_IN_BYTES
</h2>
<p>定义保存块的散列大小(以字节为单位)。
@ -1487,37 +1523,37 @@ hashsize SIZE_IN_BYTES
</p><p>使用不同 hashsize 的一个原因是,如果您的系统内存有限。
根据经验,SnapRAID 通常每 16 TB 的阵列数据需要 1 GiB 的 RAM。
</p><p>具体来说,为了存储数据的散列,SnapRAID 大约需要
$TS*(1+HS)/BS$ 字节的 RAM,
其中 $TS$ 是您的磁盘阵列的总大小(以字节为单位),$BS$ 是块大小(以字节为单位),
$HS$ 是散列大小(以字节为单位)。
TS*(1+HS)/BS 字节的 RAM,
其中 TS 是您的磁盘阵列的总大小(以字节为单位),BS 是块大小(以字节为单位),
HS 是散列大小(以字节为单位)。
</p><p>例如,对于 8 个 4 TB 磁盘,块大小为 256 KiB
(1 KiB = 1024 字节),散列大小为 16,您将获得:
</p><pre>
RAM = $(8 * 4 * 10^{12}) * (1+16) / (256 * 2^{10}) = 1.93$ GiB
RAM = (8 * 4 * 10^12) * (1+16) / (256 * 2^10) = 1.93 GiB
</pre>
<p>切换到散列大小为 8,您将获得:
</p><pre>
RAM = $(8 * 4 * 10^{12}) * (1+8) / (256 * 2^{10}) = 1.02$ GiB
RAM = (8 * 4 * 10^12) * (1+8) / (256 * 2^10) = 1.02 GiB
</pre>
<p>切换到块大小为 512,您将获得:
</p><pre>
RAM = $(8 * 4 * 10^{12}) * (1+16) / (512 * 2^{10}) = 0.96$ GiB
RAM = (8 * 4 * 10^12) * (1+16) / (512 * 2^10) = 0.96 GiB
</pre>
<p>切换到散列大小为 8 和块大小为 512,您将获得:
</p><pre>
RAM = $(8 * 4 * 10^{12}) * (1+8) / (512 * 2^{10}) = 0.51$ GiB
RAM = (8 * 4 * 10^12) * (1+8) / (512 * 2^10) = 0.51 GiB
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
autosave SIZE_IN_GIGABYTES
</h2>
<p>在同步或 scrub 之后,处理指定数量的 GB 后,自动保存状态。
<p>在同步或 scrub 期间,每处理指定数量的 GB 后就自动保存状态。
此选项有助于避免在机器崩溃或任何其他事件中断时,
从头开始重新启动长时间的 <b>sync</b> 命令。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
temp_limit TEMPERATURE_CELSIUS
</h2>
<p>设置允许的最高磁盘温度(摄氏度)。指定后,
@ -1535,22 +1571,22 @@ SnapRAID 运行时会显示当前磁盘温度。
有助于评估系统的冷却是否足够。
此估计温度仅供参考,对 SnapRAID 的行为没有影响。
程序的动作仅基于实际测量的磁盘温度。
</p><p>要执行此分析,SnapRAID 需要一个系统温度的参考。
</p><p>要执行此分析,SnapRAID 需要一个系统温度的参考基准值。
它首先尝试从可用的硬件传感器读取。
如果无法访问系统传感器,它会使用运行时测量的最低磁盘温度
作为备用参考。
作为备用基准值。
</p><p>通常,SnapRAID 只显示最热磁盘的温度。
要显示所有磁盘的温度,请使用 -A 或 --stats 选项。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
temp_sleep TIME_IN_MINUTES
</h2>
<p>设置达到温度限制时的待机时间(以分钟为单位)。
在此期间,磁盘保持停转状态。默认值为 5 分钟。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
pool DIR
</h2>
<p>定义 <b>pooling</b> 目录,其中使用 <b>pool</b> 命令创建磁盘
@ -1558,7 +1594,7 @@ pool DIR
</p><p>目录必须已经存在。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
share UNC_DIR
</h2>
<p>定义远程访问磁盘所需的 Windows UNC 路径。
@ -1571,7 +1607,7 @@ share UNC_DIR
</p><p>此选项仅在 Windows 中需要。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
smartctl DISK/PARITY OPTIONS...
</h2>
<p>定义自定义 smartctl 选项以获取每个磁盘的 SMART 属性。
@ -1584,6 +1620,7 @@ PARITY 是奇偶校验名称之一:<b>parity</b>、<b>2-parity</b>、<b>3-pari
</p><p>在指定的 OPTIONS 中,字符串 <b>%s</b> 被设备名称替换。
对于 RAID 控制器,设备可能是固定的,
您可能不需要使用 <b>%s</b>。
</p><p>您还可以使用 <b>[info: ...]</b> 标记指定自定义信息选项字符串,以替换默认的 <b>-a</b> 选项。
</p><p>请参阅 smartmontools 文档以了解可能的选项:
</p><pre>
<a href="https://www.smartmontools.org/wiki/Supported_RAID-Controllers">https://www.smartmontools.org/wiki/Supported_RAID-Controllers</a>
@ -1591,11 +1628,12 @@ PARITY 是奇偶校验名称之一:<b>parity</b>、<b>2-parity</b>、<b>3-pari
</pre>
<p>例如:
</p><pre>
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl parity -d sat %s
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
smartignore DISK/PARITY ATTR [ATTR...]
</h2>
<p>在计算磁盘故障概率时忽略指定的 SMART 属性。
@ -1604,17 +1642,22 @@ smartignore DISK/PARITY ATTR [ATTR...]
PARITY 是奇偶校验名称之一:<b>parity</b>、<b>2-parity</b>、<b>3-parity</b>、
<b>4-parity</b>、<b>5-parity</b>、<b>6-parity</b> 或 <b>z-parity</b>。
特殊值 * 可用于在所有磁盘上忽略该属性。
</p><p>例如,要在所有磁盘上忽略 <b>Current Pending Sector Count</b> 属性:
</p><p>可以指定多个属性,用空格分隔。
每个属性可以指定为 1 到 255 之间的数字,或者不区分大小写的名称
(例如 <b>Current_Pending_Sector</b>)。
</p><p>例如,要在所有磁盘上通过编号或名称忽略 <b>Current Pending Sector Count</b> 和
<b>Reallocated Sectors Count</b> 属性:
</p><pre>
smartignore * 197
smartignore * 197 5
smartignore * Current_Pending_Sector Reallocated_Sector_Ct
</pre>
<p>要仅在第一个奇偶校验磁盘上忽略它:
<p>要仅在第一个奇偶校验磁盘上忽略它们:
</p><pre>
smartignore parity 197
smartignore parity 197 5
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
<h2 id="sec7-19" class="manual-title-level-2">
Examples
</h2>
<p>Unix 的典型配置示例如下:
@ -1627,7 +1670,7 @@ data d2 /mnt/disk2/
data d3 /mnt/disk3/
exclude /lost+found/
exclude /tmp/
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/sg0
smartctl 2-parity -d areca,2/1 /dev/sg0
@ -1643,7 +1686,7 @@ data d3 I:\array\
exclude Thumbs.db
exclude \$RECYCLE.BIN
exclude \System Volume Information
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/arcmsr0
smartctl 2-parity -d areca,2/1 /dev/arcmsr0
@ -1652,7 +1695,125 @@ smartctl 2-parity -d areca,2/1 /dev/arcmsr0
</div>
<div class="manual-section-level-1">
<h1 id="sec8" class="manual-title-level-1">
Pattern
快照 (Snapshots)
</h1>
<p>如果配置中启用了快照选项,SnapRAID 将使用文件系统快照来保持操作期间
读取的数据稳定,即使实时文件系统上的文件随后被修改或删除也是如此。
</p><p>快照的管理是完全自动且透明的。
您可以完全像以前一样继续使用 SnapRAID,而快照提供的
额外保护完全在后台处理。
</p><p>这提供了两个主要好处:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
一致性
</div><div class="manual-tag-description">
在运行时间较长的 sync 或 scrub 期间在活动文件系统上修改的文件
不会导致校验不匹配或操作中止,因为每个创建了快照的文件系统在操作期间
都保持不变。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
恢复
</div><div class="manual-tag-description">
如果从实时文件系统中更新或删除了一个文件,
它仍会保留在快照中。如果下次 sync 运行之前发生磁盘故障,
SnapRAID 会使用快照中保留的数据来重建发生故障的磁盘。
在活动同步过程中发生磁盘故障的情况下,
SnapRAID 还能自动从上一次校验计算的快照和当前的快照中读取数据。
这通过提供解校验方程所需的精确数据块访问,
最大程度地提高了完全恢复的概率,即使这些数据块在同步之间被修改或删除。
如果没有快照,健康磁盘上更新或删除的文件会导致缺少数据块,
而这些数据块可能是修复其他损坏磁盘所必需的。
</div>
</div>
</div>
<p>快照仅为数据磁盘创建,并且仅在底层文件系统支持此功能时创建。
校验磁盘始终使用实时文件系统。
</p><p>目前,Linux 上的 Btrfs、Bcachefs 和 ZFS 以及 Windows 上的 NTFS 支持此功能。
</p><p>您可以混合使用具有不同文件系统的数据磁盘。只有那些
支持快照的磁盘才会利用它们,而其他磁盘将继续直接在实时文件系统上运行。
</p><p>快照的创建和删除需要管理权限。
启用快照时,请确保以必要的权限(例如 sudo)运行 SnapRAID。
</p><div class="manual-section-level-2">
<h2 id="sec8-1" class="manual-title-level-2">
快照的命令行为
</h2>
<p><b>sync</b> 和 <b>scrub</b> 命令对支持快照的文件系统的数据磁盘使用快照。
在启用了快照的磁盘上,该命令看到的是一个不受实时文件系统并发更改影响的
稳定文件系统镜像。
在 <b>sync</b> 期间,会为每个受支持的数据文件系统独立创建新的快照。
这些快照共同提供用于校验计算的数据。
相比之下,<b>scrub</b> 命令利用上一个快照(即在最近一次同步期间创建的快照)
来维持与现有校验匹配的可靠参考点。
</p><p>对于 <b>check</b> 和 <b>fix</b> 命令,上一个快照的使用
取决于是否使用 -d, --filter-disk 选项指定了特定磁盘。
</p><p>通过 -d 明确选择的磁盘(操作的“目标”)始终使用实时文件系统。
对于 <b>fix</b>,这允许将数据恢复到活动的替代磁盘。对于 <b>check</b>,
它允许在相同条件下模拟 <b>fix</b> 操作。
</p><p>所有其他数据磁盘(“参考”磁盘)都将通过其快照进行访问。
这确保了即使您在恢复进行时修改健康磁盘上的文件,
SnapRAID 也有一个稳定、冻结的参考来求解校验方程。
</p><p>如果没有提供 -d 选项,SnapRAID 会假设该操作适用于整个阵列,
在这种情况下,<b>check</b> 和 <b>fix</b> 将排他性地使用实时文件系统。
</p><p>所有其他命令完全在实时文件系统上运行。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
快照生命周期 (Snapshots Lifecycle)
</h1>
<p>SnapRAID 在每个数据子卷根目录下的隐藏目录中管理三个特定的快照:
<b>stable</b>(稳定)、<b>pending</b>(待定)和 <b>scan</b>(扫描)。
在 Btrfs、Bcachefs 和 NTFS 中使用 <b>.snapraid/</b> 目录,
在 ZFS 中使用标准的 <b>.zfs/snapshot/</b>。
</p><p><b>stable</b> 快照代表上一次成功完成的 <b>sync</b> 的状态,
包含用于计算当前校验的准确数据。它作为 <b>scrub</b>、<b>check</b>
和 <b>fix</b> 命令的主要数据源。
</p><p><b>scan</b> 快照是在 <b>sync</b> 开始时创建的临时镜像,
用于为扫描和校验计算提供冻结状态。在扫描并保存新的内容状态后,
它将替换以前的 <b>pending</b> 快照。
</p><p><b>pending</b> 快照是中断的 <b>sync</b> 所使用的镜像。
在操作成功完成后,以前的 <b>stable</b> 快照将被删除,
并且 <b>pending</b> 快照将被提升以接替其作为新的稳定参考。
</p><p>如果 <b>sync</b> 中断,<b>pending</b> 快照将被保留。
随后的 <b>scrub</b>、<b>check</b> 和 <b>fix</b> 命令将使用此待定快照,
因为它与 .content 文件中记录的文件系统状态相匹配,即使校验仅部分同步。
</p><p>在 <b>sync</b> 中断的情况下,<b>check</b> 和 <b>fix</b> 命令
还会从 <b>stable</b> 快照中读取数据,以检索在同步期间更新或删除的文件的
数据块。这是可能的,因为 .content 文件在整个同步过程中保留了
所有修改或删除的文件的元数据。此历史信息仅在同步
成功完成并保存 .content 文件的最终版本后才会清除。
</p><p>如果 <b>sync</b> 在中断后重新启动,现有的 pending 快照将被删除,
并创建一个新快照以捕获实时文件系统的当前状态。
但是,如果 <b>sync</b> 中断,请避免在后续 <b>sync</b> 成功完成之前修改、删除、
替换或移动文件。校验可能仍包含根据中断的同步所使用的快照计算的块。
以后的同步可能会替换该快照,从而导致中间文件版本无法用于恢复。
</p><div class="manual-section-level-2">
<h2 id="sec9-1" class="manual-title-level-2">
使用文件系统快照进行外部备份 (External backups with filesystem snapshots)
</h2>
<p>当启用文件系统快照时,SnapRAID 会在每个数据子卷、卷或数据集(dataset)
的根目录下访问或创建快照。
</p><p>避免与外部工具发生冲突的一种简单方法,是将 <b>data</b> 配置指向子卷或卷内的
常规子目录(例如 <b>/mnt/subvol/data</b> 而不是 <b>/mnt/subvol</b>)。SnapRAID
始终会在子卷根目录下创建快照目录(例如 <b>/mnt/subvol/.snapraid/</b>),从而保持
数据子目录整洁,使快照保留在外部且对在该目录内运行的备份工具不可见。
</p><p>否则,如果配置的 <b>data</b> 目录本身就是子卷或卷的根目录,SnapRAID 会直接在其中
创建 <b>.snapraid/</b> 目录(在 Btrfs、Bcachefs 和 NTFS 上)。虽然 SnapRAID
会在其自身的扫描中自动排除此目录,但外部备份工具或文件同步工具会发现它。如果未
将其排除,它们可能会遍历快照或目录链接并复制整个冻结的数据树,从而导致数据
重复并耗尽备份存储空间。请务必将外部备份工具配置为排除 <b>.snapraid/</b> 目录。
</p><p>在 ZFS 上,快照是通过标准虚拟目录 <b>.zfs/snapshot/</b> 而不是 <b>.snapraid/</b>
公开的。默认情况下(<b>snapdir=hidden</b>),ZFS 会在目录列表中隐藏此目录,因此
外部备份工具不会遍历它。如果您启用了 <b>snapdir=visible</b>,请确保您的备份工具
排除 <b>.zfs/</b> 目录。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
模式 (Pattern)
</h1>
<p>模式提供了一种灵活的方法来过滤要包含或排除的文件。通过使用通配符(globbing),
您可以定义匹配特定文件名或整个目录结构的规则,而无需手动列出每个路径。
@ -1661,19 +1822,21 @@ Pattern
</p><p>单星号 <b>*</b> 匹配任何字符序列,但与问号一样,它绝不会跨越目录边界。
它在正斜杠处停止,因此适用于匹配单个路径组件内的内容。
这是 Shell 通配符中常见的标准行为。
</p><p>双星号 <b>**</b> 功能更强大,它可以匹配任何字符序列,包括目录分隔符。
这允许模式匹配跨越多个目录层级。当 <b>**</b> 直接嵌入在模式中时,
它可以匹配零个或多个字符,包括周围文字文本之间的斜杠。
</p><p><b>**</b> 最重要的用法是特殊形式 <b>/**/</b>。它可以匹配零个或多个完整的目录层级,
从而可以在不知道确切路径结构的情况下,匹配目录树中任何深度的文件。
例如,模式 <b>src/**/main.js</b> 匹配 <b>src/main.js</b>(跳过零个目录)、
<b>src/ui/main.js</b>(跳过一个目录)以及 <b>src/ui/components/main.js</b>
(跳过两个目录)。
</p><p>双星号通配符 <b>**</b> 仅在与目录分隔符相邻时(前面或后面有斜杠)才能跨越
目录分隔符进行匹配。在此形式下,它可以跨越多个目录层级匹配零个或多个字符。
例如,<b>foo/**/bar</b> 匹配 <b>foo/bar</b>、<b>foo/a/bar</b> 和 <b>foo/a/b/bar</b>;
<b>**/build</b> 匹配 <b>build</b> 和 <b>foo/bar/build</b>;<b>src/**.js</b> 匹配 <b>src/main.js</b>
和 <b>src/ui/components/main.js</b>。
单独的形式 <b>/**/</b> 不被接受为完整的模式。
</p><p>当 <b>**</b> 不与斜杠相邻时,其行为类似于 <b>*</b>,不会匹配目录分隔符。例如,
<b>**.jpg</b> 匹配当前目录中的 <b>photo.jpg</b>,但不会匹配 <b>dir/photo.jpg</b>。
如需匹配子目录中的文件,请使用 <b>**/*.jpg</b>。
</p><p>使用方括号 <b>[]</b> 的字符类匹配指定集合或范围内的单个字符。
与其他单字符模式一样,它们不匹配目录分隔符。字符类支持使用
感叹号进行范围指定和否定。
</p><p>需要记住的根本区别是,<b>*</b>、<b>?</b> 和字符类都遵循目录边界,
并且仅在单个路径组件内匹配,而 <b>**</b> 是唯一可以跨越目录分隔符匹配的模式。
并且仅在单个路径组件内匹配,而 <b>**</b> 仅在与斜杠相邻时才能跨越
目录分隔符进行匹配。
</p><p>有四种不同类型的模式:
</p><div class="manual-option-list">
<div class="manual-option-entry">
@ -1758,6 +1921,21 @@ include /movies/
include /musics/
include /pictures/
</pre>
<p>请注意,排除目录(使用 DIR/ 或 /PATH/DIR/)会阻止 SnapRAID 进入并扫描该目录。
因此,无法使用 <b>include</b> 规则重新包含位于已排除父目录内的文件或子目录,
因为扫描器根本不会遍历到该目录中。
</p><p>例如,以下配置将不会包含 <b>file.dat</b>,因为 <b>/keep/</b> 在看到 <b>file.dat</b> 之前已被修剪:
</p><pre>
# 无法按预期工作: /keep/ 会被完全跳过
include /keep/file.dat
exclude /keep/
</pre>
<p>若要排除目录中的文件但保留特定文件,请匹配目录内的文件模式,而不是排除目录本身:
</p><pre>
# 可以正常工作: 会遍历 /keep/,但其中的其他文件会被排除
include /keep/file.dat
exclude /keep/*
</pre>
<p>在命令行上,使用 -f 选项,您只能使用 <b>include</b>
模式。例如:
</p><pre>
@ -1769,8 +1947,8 @@ snapraid -f "*.mp3" check
引用它们以防止 shell 扩展它们。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Ignore File
<h1 id="sec11" class="manual-title-level-1">
忽略文件 (Ignore File)
</h1>
<p>除了配置文件中的全局规则外,您还可以在阵列内的任何目录中放置
<b>.snapraidignore</b> 文件,以定义分散的排除规则。
@ -1831,18 +2009,20 @@ build/
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
Content
<h1 id="sec12" class="manual-title-level-1">
内容 (Content)
</h1>
<p>SnapRAID 将文件列表和校验和存储在 content 文件中。
</p><p>它是一个二进制文件,列出了磁盘阵列中存在的所有文件,
以及用于验证其完整性的所有校验和。
</p><p>此文件由 <b>sync</b> 和 <b>scrub</b> 命令读取和写入,并由
<b>fix</b>、<b>check</b> 和 <b>status</b> 命令读取。
</p><p>content 文件由 <b>sync</b>、<b>scrub</b>、<b>touch</b> 和 <b>rehash</b> 命令读取和写入。
它由 <b>status</b>、<b>diff</b>、<b>check</b>、<b>fix</b>、<b>list</b>、<b>dup</b>、<b>locate</b> 和
<b>pool</b> 命令读取,并被 <b>smart</b>、<b>probe</b>、<b>up</b>、<b>down</b> 和 <b>devices</b>
命令完全忽略。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec11" class="manual-title-level-1">
Parity
<h1 id="sec13" class="manual-title-level-1">
奇偶校验 (Parity)
</h1>
<p>SnapRAID 将阵列的奇偶校验信息存储在 parity 文件中。
</p><p>这些是二进制文件,包含 <b>content</b> 文件中定义的所有
@ -1851,8 +2031,8 @@ Parity
并且仅由 <b>scrub</b> 和 <b>check</b> 命令读取。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec12" class="manual-title-level-1">
Encoding
<h1 id="sec14" class="manual-title-level-1">
编码 (Encoding)
</h1>
<p>SnapRAID 在 Unix 中忽略任何编码。它读取并存储
文件系统使用的相同编码的文件名。
@ -1863,6 +2043,234 @@ Encoding
作为控制台字体。这仅影响打印的文件名;如果
您将控制台输出重定向到文件,则生成的文件始终
采用 UTF-8 格式。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec15" class="manual-title-level-1">
退出码 (Exit Code)
</h1>
<p>SnapRAID 终止并返回以下错误代码:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
0
</div><div class="manual-tag-description">
一切正常。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
1
</div><div class="manual-tag-description">
命令遇到一些错误。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2
</div><div class="manual-tag-description">
<b>diff</b> 命令发现一切正常,但需要进行 <b>sync</b>。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
3
</div><div class="manual-tag-description">
磁盘设备命令(<b>probe</b>、<b>smart</b>、<b>devices</b>、<b>up</b>、<b>down</b>)已完成,
但至少有一个文件系统因缺少设备而以降级(degraded)模式运行。
</div>
</div>
</div>
</div>
<div class="manual-section-level-1">
<h1 id="sec16" class="manual-title-level-1">
已知问题 (Known Issues)
</h1>
<div class="manual-section-level-2">
<h2 id="sec16-1" class="manual-title-level-2">
文件系统边界
</h2>
<p>SnapRAID 在扫描数据磁盘时不会跨越文件系统、挂载点或子卷边界。
当检测到此类边界时,SnapRAID 会报告警告(WARNING)并且不会扫描其范围之外的内容。
</p><p>位于此类边界之外的文件不包含在数据磁盘中,如果需要保护它们,则必须单独配置。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-2" class="manual-title-level-2">
带有文件系统快照的挂载点
</h2>
<p>启用文件系统快照时,不支持数据磁盘内的嵌套挂载点和 bind 挂载。
</p><p>挂载点属于活动系统的挂载命名空间,不会保存在文件系统快照中。
因此,在扫描快照时,活动文件系统中被挂载点隐藏的目录可能会变为可见。
</p><p>启用文件系统快照时,请勿在数据磁盘内放置嵌套挂载点或 bind 挂载。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-3" class="manual-title-level-2">
带有文件系统快照的多套配置
</h2>
<p>使用相同文件系统快照命名空间的多套独立 SnapRAID 配置无法安全共享快照支持。
</p><p>在 Btrfs 和 Bcachefs 上,只有一套启用了快照支持的 SnapRAID 配置可以使用
同一子卷内的数据目录。在 ZFS 上,相同的限制适用于数据集,在 NTFS 上适用于卷。
</p><p>共享相同快照命名空间的多套配置使用相同的 <b>stable</b>、<b>pending</b> 和 <b>scan</b> 快照。
因此,运行其中一套配置可能会替换或删除另一套配置所需的恢复快照。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-4" class="manual-title-level-2">
未更改时间戳的原地文件修改
</h2>
<p>SnapRAID 通过比较文件大小和修改时间戳(mtime)来检测文件修改。
</p><p>如果应用程序在不更改文件大小或不更新其修改时间戳的情况下原地修改文件,
则 “diff” 和 “sync” 将不会检测到文件已更改,并且其奇偶校验也不会更新。
</p><p>为确保 SnapRAID 识别此类更改,请更新文件的修改时间戳(例如使用 “touch” 实用程序)。
否则,该差异仅在后续的 “scrub” 或 “check” 期间作为哈希不匹配被检测到。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-5" class="manual-title-level-2">
Windows 非 ASCII 大小写匹配
</h2>
<p>SnapRAID 在所有平台上均使用标准且可预测的 UTF-8 编码,仅对 ASCII 字符进行
不区分大小写的匹配。
</p><p>Windows 文件系统受到遗留设计的困扰,即通过任意的、依赖于系统的大小写折叠表在
Unicode 文件名之间强制实行不区分大小写。因此,Windows 掩盖了文件系统的真实情况,
将完全不同的 Unicode 字节序列视为同一个文件。
</p><p>例如,<b>À.txt</b> 和 <b>à.txt</b> 是不同的 Unicode 名称,但 Windows 却不合逻辑地将它们
视为相同文件,而 SnapRAID 则保留了它们的真实区别。
</p><p>该限制是由于 Windows 对 Unicode 文件名的不一致处理及其对不区分大小写别名的
执着所致。为了防止因 Windows 的大小写折叠而产生差异,请在配置路径和过滤器中
始终为非 ASCII 字符指定准确的大小写。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-6" class="manual-title-level-2">
部分 fix 恢复
</h2>
<p>当使用 <b>-S, --start</b> 或 <b>-B, --count</b> 限制 <b>fix</b> 时,
SnapRAID 仅对选定的块进行操作,而不执行文件级别的最终化处理或隔离。
</p><p>如果恢复产生了无法证实代表当前内容的尽力而为(best-effort)数据,
此类块仍可能以常规文件名写入。与这些已恢复块相关的不确定性在命令终止后
不会保留。
</p><p>因此,后续的 <b>fix</b> 会将这些可读取的块视为有效的文件数据,并且不会尝试
再次恢复它们。这可能导致后续恢复报告成功,但在文件中留下不完整或过时的数据。
</p><p><b>-S</b> 和 <b>-B</b> 选项仅适用于高级手动恢复,通常在常规 <b>fix</b> 失败后使用。
如果部分 <b>fix</b> 报告了无法恢复的数据,请在尝试另一次恢复之前删除受影响的
文件或对其重命名,或者手动验证其内容。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-7" class="manual-title-level-2">
NTFS 硬链接与排除的路径
</h2>
<p>在 NTFS 上,目录条目会为每个硬链接单独缓存文件大小和时间戳。
当通过其中一个链接修改文件时,指向同一文件的其他链接的目录条目
可能会保留过时的元数据,直到它们被访问为止。
</p><p>如果在扫描过程中遇到同一文件的至少两个硬链接,SnapRAID 会自动
检测并规范化这种情况。但是,如果仅扫描了一个硬链接,而其他硬链接
被过滤器排除或位于数据磁盘路径之外,SnapRAID 将无法检测到 inode 冲突,
并会依赖单个可见链接的缓存元数据。
</p><p>因此,通过被排除或外部的硬链接所做的修改,在操作系统刷新所包含链接
的元数据之前(例如通过该路径访问或打开文件时),可能会被 SnapRAID 忽略。
</p><p>为避免此限制,请避免通过已从 SnapRAID 中排除的硬链接来修改受保护
的文件,或者确保文件的所有硬链接都包含在扫描中,以便 SnapRAID 可以
对它们进行规范化。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-8" class="manual-title-level-2">
中断的多重奇偶校验 sync 后的恢复
</h2>
<p>在具有多个奇偶校验磁盘的阵列中,中断的 <b>sync</b> 可能会使不同奇偶校验
级别之间暂时彼此不同步。例如,奇偶校验 1 可能已经包含新更新的数据,
而奇偶校验 2 仍包含旧数据。
</p><p>在执行 <b>check</b> 或 <b>fix</b> 期间,SnapRAID 会尝试不同的奇偶校验组合,
并根据已知的块哈希(覆盖整个块,通常为 256 KiB)验证重建的数据。
</p><p>如果 SnapRAID 尝试使用新旧奇偶校验的不一致混合进行重建,线性 RAID
方程将产生不正确的数据。要错误地接受这种无效组合,这些方程必须在同一
条带中的其他未同步块被重建为错误数据的情况下,巧合地完美重建出至少一个
完整的 256 KiB 块以使其哈希完全匹配。
</p><p>这种情况并不依赖于哈希碰撞;相反,它需要混合奇偶校验方程本身碰巧
生成原始的完整 256 KiB 块内容。虽然在特别构造的数据或高度重复的数据
情况下在数学上是可能的,但在实际数据中这几乎是不可能的。
</p><p>如果所有磁盘都运行良好,在进行进一步更改之前完成中断的 <b>sync</b> 可以消除
这种不确定性。如果磁盘发生故障且需要恢复,在运行 <b>check</b> 或 <b>fix</b> 之前
请避免修改任何数据磁盘。
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-9" class="manual-title-level-2">
保留的文件和目录名称
</h2>
<p>SnapRAID 保留了一些文件、目录和快照名称用于其内部操作。请勿将这些名称
用于用户数据:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraidignore
</div><div class="manual-tag-description">
本地排除规则文件。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraid
</div><div class="manual-tag-description">
快照容器目录。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
snapraid-*
</div><div class="manual-tag-description">
由 SnapRAID 管理的 ZFS 快照名称。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
*.unrecoverable
</div><div class="manual-tag-description">
在恢复过程中被隔离的受损文件。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.tmp
</div><div class="manual-tag-description">
用于 content 更新的临时文件。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.lock
</div><div class="manual-tag-description">
content 锁定文件。
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
PARITY.spaceholder
</div><div class="manual-tag-description">
在 Windows 上分配奇偶校验期间使用的临时占位文件。
</div>
</div>
</div>
<p>将这些名称用于无关数据可能会导致文件或快照被忽略、被误认为是元数据、
被覆盖、重命名或删除。
</p><p>在 Windows 上,所有大小写变体也都被保留,即使在配置为区分大小写的 NTFS
目录中也是如此(例如 .SNAPRAIDIGNORE、.SnapRaid、CONTENT.TMP 和
CONTENT.Lock)。
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec17" class="manual-title-level-1">
翻译 (Translation)
</h1>
<p>本文档是英文手册的自动翻译。
请参阅英文手册以获取权威版本。
</p></div>
<div class="manual-section-level-1">
<h1 id="sec18" class="manual-title-level-1">
版权 (Copyright)
</h1>
<p>此文件版权所有 (C) 2026 Andrea Mazzoleni
</p></div>
<div class="manual-section-level-1">
<h1 id="sec19" class="manual-title-level-1">
参见 (See Also)
</h1>
<p>snapraid_log(1), snapraidd(1), rsync(1)
</p></div>

View file

@ -194,17 +194,32 @@ Limitations
<p>SnapRAID is a hybrid between a RAID and a backup program, aiming to combine
the best benefits of both. However, it has some limitations that you should
consider before using it.
</p><p>The main limitation is that if a disk fails and you haven't recently synced,
you may not be able to fully recover.
More specifically, you may be unable to recover up to the size of
the changed or deleted files since the last sync operation.
This occurs even if the changed or deleted files are not on the
failed disk. This is why SnapRAID is better suited for
data that rarely changes.
</p><p>On the other hand, newly added files don't prevent recovery of already
existing files. You will only lose the recently added files if they
are on the failed disk.
</p><p>Other SnapRAID limitations are:
</p><p>The main limitation is that if a disk fails, you can only recover data up to
the state of the last <b>sync</b> operation. Any data added or modifications made
since the last sync that are located on the failed disk will be lost.
</p><p>Consequently, SnapRAID is primarily suited for data that rarely changes.
</p><p>For data that already existed at the last sync, recovery reliability depends
on whether the <b>snapshot</b> option is used:
</p><ul>
<li>
With snapshot support (available on Btrfs, ZFS, Bcachefs, and NTFS),
SnapRAID can automatically maintain an independent frozen reference
of each supported data filesystem.
This ensures that even if you modify or delete files on your live
filesystem during or after a sync, the recovery process remains
consistent and reliable.
</li>
</ul>
<ul>
<li>
Without snapshot support, deleting or changing files after a <b>sync</b>
can prevent the full recovery of other failed disks. This occurs
because the parity no longer matches the modified files, even if
those files are not on the failed disk. On the other hand, newly added
files don't prevent recovery of already&nbsp;&nbsp;&nbsp;&nbsp;existing files.
</li>
</ul>
<p>Other SnapRAID limitations are:
</p><ul>
<li>
With SnapRAID, you still have separate file systems for each disk.
@ -350,7 +365,7 @@ Pooling
</h2>
<p>Note: The pooling feature described below has been superseded by the
mergerfs tool, which is now the recommended option for Linux users in
the SnapRAID community. Mergefs provides a more flexible and efficient
the SnapRAID community. Mergerfs provides a more flexible and efficient
way to pool multiple drives into a single unified mount point,
allowing seamless access to files across your array without relying
on symbolic links. It integrates well with SnapRAID for parity
@ -545,13 +560,13 @@ Print the status of the array -&gt; <b>status</b>
Control the disks -&gt; <b>smart</b>, <b>probe</b>, <b>up</b>, <b>down</b>
</li>
<li>
Make a backup/snapshot -&gt; <b>sync</b>
Make a backup/recovery point -&gt; <b>sync</b>
</li>
<li>
Periodically check data -&gt; <b>scrub</b>
</li>
<li>
Restore the last backup/snapshot -&gt; <b>fix</b>.
Restore the last backup/recovery point -&gt; <b>fix</b>.
</li>
</ul>
<p>Commands must be written in lowercase.
@ -705,9 +720,10 @@ were modified.
<div class="manual-tag-name">
moved
</div><div class="manual-tag-description">
Files moved to a different directory on the same disk.
They are identified by having the same name, size, timestamp,
and inode, but a different directory.
Files moved or renamed on the same disk while retaining
the same inode. They are identified by having the same inode,
size, and timestamp, but a different path. The file name may
also be different.
</div>
</div>
<div class="manual-tag-entry">
@ -725,12 +741,12 @@ identified, not just the name.
<div class="manual-tag-name">
relocated
</div><div class="manual-tag-description">
Files moved on the same or a different disk where
the original has disappeared. They are identified by
having the same name, size, and timestamp. If the
sub-second timestamp is zero, the full path must match
to be identified. Unlike 'moved' files on the same disk,
relocated files have a different inode.
Files moved to a different directory or disk where the
original file has disappeared and the inode is not retained.
They are identified by having the same name, size, and timestamp.
If the sub-second timestamp is zero, the full path must match to
be identified. Unlike 'moved' files, relocated files require the
file name to remain the same.
</div>
</div>
<div class="manual-tag-entry">
@ -813,9 +829,9 @@ The files in the array are NOT modified.
fix
</h2>
<p>Fixes all the files and the parity data.
</p><p>All files and parity data are compared with the snapshot
state saved in the last <b>sync</b>.
If a difference is found, it is reverted to the stored snapshot.
</p><p>All files and parity data are compared with the state saved in
the last <b>sync</b>.
If a difference is found, it is reverted to the stored state.
</p><p>WARNING! The <b>fix</b> command does not differentiate between errors and
intentional modifications. It unconditionally reverts the file state
to the last <b>sync</b>.
@ -1362,7 +1378,8 @@ However, <b>check</b> and <b>fix</b> always stop at the first error.
Starts processing from the specified
block number. This can be useful for retrying to check
or fix specific blocks in case of a damaged disk.
This option is mainly for advanced manual recovery.
This option is mainly for advanced manual recovery and
is supported only by <b>check</b> and <b>fix</b>.
</div>
</div>
</div>
@ -1372,7 +1389,8 @@ This option is mainly for advanced manual recovery.
-B, --count BLKCOUNT
</div><div class="manual-option-description">
Processes only the specified number of blocks.
This option is mainly for advanced manual recovery.
This option is mainly for advanced manual recovery and
is supported only by <b>check</b> and <b>fix</b>.
</div>
</div>
</div>
@ -1537,6 +1555,10 @@ be unique. DIR is the mount point of the disk in the
file system.
</p><p>You can change the mount point as needed, as long as
you keep the NAME fixed.
</p><p>However, the configured path must consistently resolve to the
same underlying data. If the path contains symbolic links,
their targets must remain stable. Retargeting such symlinks
to switch the data directory on the fly is unsupported.
</p><p>You should use one option for each data disk in the array.
</p><p>You can rename a disk later by changing the NAME directly
in the configuration file and then running a <b>sync</b> command.
@ -1557,6 +1579,30 @@ because they are expected to be always spinning.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-7" class="manual-title-level-2">
snapshot
</h2>
<p>Enable the use of filesystem snapshots for the <b>sync</b>, <b>scrub</b>,
<b>check</b>, and <b>fix</b> commands.
</p><p>When enabled, SnapRAID creates a read-only snapshot of each supported
data filesystem at the start of a 'sync'. This provides a stable view of
each filesystem, preventing later modifications from changing the data
used for parity computation.
</p><p>This significantly improves recovery: if a file is deleted from the live
filesystem, it remains preserved in the snapshot. This prevents the parity
from becoming "broken" for that block, ensuring you can still successfully
recover data if another disk fails.
</p><p>This option applies exclusively to data disks formatted with the
Btrfs, Bcachefs or ZFS filesystems in Linux and NTFS in Windows.
Parity disks, or data disks using other filesystems, will always use
the live version of the filesystem.
</p><p>Snapshot creation and deletion require administrative privileges.
Ensure SnapRAID is run with the necessary permissions (e.g., sudo) when
this option is enabled.
</p><p>See the SNAPSHOTS section for a detailed explanation of the snapshot
lifecycle.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
nohidden
</h2>
<p>Excludes all hidden files and directories.
@ -1564,7 +1610,7 @@ In Unix, hidden files are those starting with <b>.</b>.
In Windows, they are those with the hidden attribute.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-8" class="manual-title-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
exclude/include PATTERN
</h2>
<p>Defines the file or directory patterns to exclude or include
@ -1575,12 +1621,16 @@ is excluded. If it is an <b>include</b> one, the file is included.
If no pattern matches, the file is excluded if the last pattern
specified is an <b>include</b>, or included if the last pattern
specified is an <b>exclude</b>.
</p><p>Note that filtering occurs hierarchically during directory traversal.
If a directory matches an <b>exclude</b> rule, the entire directory is
skipped (pruned), and any <b>include</b> rules for files or subdirectories
inside it will not be evaluated.
</p><p>See the PATTERN section for more details on pattern
specifications.
</p><p>This option can be used multiple times.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-9" class="manual-title-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
blocksize SIZE_IN_KIBIBYTES
</h2>
<p>Defines the basic block size in kibibytes for the parity.
@ -1621,7 +1671,7 @@ a 4 TB disk, which allows about 460,000 files on each data disk without
any wasted space.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-10" class="manual-title-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
hashsize SIZE_IN_BYTES
</h2>
<p>Defines the hash size in bytes for the saved blocks.
@ -1656,7 +1706,7 @@ RAM = (8 * 4 * 10^12) * (1+8) / (512 * 2^10) = 0.51 GiB
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-11" class="manual-title-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
autosave SIZE_IN_GIGABYTES
</h2>
<p>Automatically saves the state when syncing or scrubbing after the
@ -1665,7 +1715,7 @@ This option is useful to avoid restarting long <b>sync</b>
commands from scratch if interrupted by a machine crash or any other event.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-12" class="manual-title-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
temp_limit TEMPERATURE_CELSIUS
</h2>
<p>Sets the maximum allowed disk temperature in Celsius. When specified,
@ -1694,7 +1744,7 @@ temperature measured at the start of the run as a fallback reference.
To display the temperature of all disks, use the -A or --stats option.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-13" class="manual-title-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
temp_sleep TIME_IN_MINUTES
</h2>
<p>Sets the standby time, in minutes, when the temperature limit is
@ -1702,7 +1752,7 @@ reached. During this period, the disks remain spun down. The default
is 5 minutes.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-14" class="manual-title-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
pool DIR
</h2>
<p>Defines the pooling directory where the virtual view of the disk
@ -1710,7 +1760,7 @@ array is created using the <b>pool</b> command.
</p><p>The directory must already exist.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-15" class="manual-title-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
share UNC_DIR
</h2>
<p>Defines the Windows UNC path required to access the disks remotely.
@ -1724,7 +1774,7 @@ file directory and name.
</p><p>This option is required only for Windows.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec7-16" class="manual-title-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
smartctl DISK/PARITY OPTIONS...
</h2>
<p>Defines custom smartctl options to obtain the SMART attributes for
@ -1737,6 +1787,8 @@ PARITY is one of the parity names: <b>parity</b>, <b>2-parity</b>, <b>3-parity</
</p><p>In the specified OPTIONS, the <b>%s</b> string is replaced by the
device name. For RAID controllers, the device is
likely fixed, and you may not need to use <b>%s</b>.
</p><p>You can also specify a custom info options string using the
<b>[info: ...]</b> tag to override the default <b>-a</b> option.
</p><p>Refer to the smartmontools documentation for possible options:
</p><pre>
<a href="https://www.smartmontools.org/wiki/Supported_RAID-Controllers">https://www.smartmontools.org/wiki/Supported_RAID-Controllers</a>
@ -1744,11 +1796,12 @@ likely fixed, and you may not need to use <b>%s</b>.
</pre>
<p>For example:
</p><pre>
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl parity -d sat %s
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-17" class="manual-title-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
smartignore DISK/PARITY ATTR [ATTR...]
</h2>
<p>Ignores the specified SMART attribute when computing the probability
@ -1758,18 +1811,23 @@ misleading values for a particular attribute.
PARITY is one of the parity names: <b>parity</b>, <b>2-parity</b>, <b>3-parity</b>,
<b>4-parity</b>, <b>5-parity</b>, <b>6-parity</b>, or <b>z-parity</b>.
The special value * can be used to ignore the attribute on all disks.
</p><p>For example, to ignore the <b>Current Pending Sector Count</b> attribute on
all disks:
</p><p>Multiple attributes can be specified separated by spaces.
Each attribute can be specified as a number from 1 to 255, or as a
case-insensitive name (e.g. <b>Current_Pending_Sector</b>).
</p><p>For example, to ignore the <b>Current Pending Sector Count</b> and
<b>Reallocated Sectors Count</b> attributes on all disks by their number
or name:
</p><pre>
smartignore * 197
smartignore * 197 5
smartignore * Current_Pending_Sector Reallocated_Sector_Ct
</pre>
<p>To ignore it only on the first parity disk:
<p>To ignore them only on the first parity disk:
</p><pre>
smartignore parity 197
smartignore parity 197 5
</pre>
</div>
<div class="manual-section-level-2">
<h2 id="sec7-18" class="manual-title-level-2">
<h2 id="sec7-19" class="manual-title-level-2">
Examples
</h2>
<p>An example of a typical configuration for Unix is:
@ -1782,7 +1840,7 @@ data d2 /mnt/disk2/
data d3 /mnt/disk3/
exclude /lost+found/
exclude /tmp/
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/sg0
smartctl 2-parity -d areca,2/1 /dev/sg0
@ -1798,7 +1856,7 @@ data d3 I:\array\
exclude Thumbs.db
exclude \$RECYCLE.BIN
exclude \System Volume Information
smartctl d1 -d sat %s
smartctl d1 [info: -H -i -c -A] -d sat %s
smartctl d2 -d usbjmicron %s
smartctl parity -d areca,1/1 /dev/arcmsr0
smartctl 2-parity -d areca,2/1 /dev/arcmsr0
@ -1807,6 +1865,162 @@ smartctl 2-parity -d areca,2/1 /dev/arcmsr0
</div>
<div class="manual-section-level-1">
<h1 id="sec8" class="manual-title-level-1">
Snapshots
</h1>
<p>If the snapshot option is enabled in the configuration, SnapRAID
uses filesystem snapshots to keep the data read during an operation
stable, even when files on the live filesystems are subsequently
modified or deleted.
</p><p>The management of snapshots is completely automatic and transparent.
You can continue to use SnapRAID exactly as before, with the
additional protection provided by snapshots handled entirely in
the background.
</p><p>This provides two primary benefits:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
Consistency
</div><div class="manual-tag-description">
Files modified on the live filesystem during a long-running
sync or scrub will not cause parity mismatches or aborted
operations, because each snapshotted filesystem remains unchanged
for the duration of the operation.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
Recovery
</div><div class="manual-tag-description">
If a file is updated or deleted from the live filesystem,
it remains preserved in the snapshot. If a disk failure occurs
before the next sync is run, SnapRAID uses the data preserved
in the snapshot to reconstruct the failed disk.
In case of a disk failure during an active sync process,
SnapRAID is also able to read automatically from both the
snapshot of the previous parity computation and the current one.
This maximizes the probability of a full recovery by
providing access to the exact data blocks required to solve
the parity equations, even if those blocks were modified
or deleted between syncs.
Without snapshots, an updated or deleted file on a healthy
disk results in missing data blocks that may be required to
fix other failed disks.
</div>
</div>
</div>
<p>Snapshots are created only for data disks and only if the underlying
filesystem supports this functionality. Parity disks always use
the live filesystem.
</p><p>At present, this is supported on Btrfs, Bcachefs, and ZFS in Linux
and on NTFS in Windows.
</p><p>You can mix data disks with different filesystems. Only those that
support snapshots will utilize them, while other disks will continue
to operate directly on the live filesystem.
</p><p>Snapshot creation and deletion require administrative privileges.
Ensure SnapRAID is run with the necessary permissions (e.g., sudo)
when snapshots are enabled.
</p><div class="manual-section-level-2">
<h2 id="sec8-1" class="manual-title-level-2">
Command Behavior with Snapshots
</h2>
<p>The <b>sync</b> and <b>scrub</b> commands use snapshots for data disks whose
filesystems support them. On a snapshotted disk, the command sees
a stable filesystem image unaffected by concurrent changes to the
live filesystem.
During a <b>sync</b>, a new snapshot is created independently for each
supported data filesystem. These snapshots collectively provide the
data used for parity computation.
In contrast, the <b>scrub</b> command utilizes the last snapshot, the one
created during the most recent sync, to maintain a reliable reference
point that matches the existing parity.
</p><p>For the <b>check</b> and <b>fix</b> commands, the use of the last snapshot
depends on whether specific disks are targeted using the
-d, --filter-disk option.
</p><p>A disk explicitly selected via -d (the "target" of the operation)
always uses the live filesystem. For <b>fix</b>, this allows restoring
data to the active disk replacement. For <b>check</b>, it allows simulating
the <b>fix</b> operation under the same conditions.
</p><p>All other data disks (the "reference" disks) will be accessed via
their snapshots. This ensures that even if you are modifying files
on your healthy disks while a recovery is in progress, SnapRAID
has a stable, frozen reference to solve the parity equations.
</p><p>If no -d option is provided, SnapRAID assumes the operation applies
to the entire array, in this case, <b>check</b> and <b>fix</b> will use the
live filesystems exclusively.
</p><p>All other commands operate exclusively on the live filesystem.
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Snapshots Lifecycle
</h1>
<p>SnapRAID manages three specific snapshots, <b>stable</b>, <b>pending</b>, and <b>scan</b>,
within a hidden directory at the root of each data subvolume.
In Btrfs, Bcachefs, and NTFS it's used the <b>.snapraid/</b> directory,
in ZFS the standard <b>.zfs/snapshot/</b>.
</p><p>The <b>stable</b> snapshot represents the state of the last
successfully completed <b>sync</b>, containing the exact data used to
compute the current parity. It serves as the primary data source
for <b>scrub</b>, <b>check</b>, and <b>fix</b> commands.
</p><p>The <b>scan</b> snapshot is a temporary image created at the start
of a <b>sync</b> to provide a frozen state for scanning and parity computation.
After scanning and saving the new content state, it replaces the previous
<b>pending</b> snapshot.
</p><p>The <b>pending</b> snapshot is the image used by an interrupted sync.
Upon successful completion of the operation, the previous <b>stable</b>
snapshot is deleted, and the <b>pending</b> snapshot is promoted to
take its place as the new stable reference.
</p><p>If a <b>sync</b> is interrupted, the <b>pending</b> snapshot is preserved.
Subsequent <b>scrub</b>, <b>check</b>, and <b>fix</b> commands will use this
pending snapshot as it matches the filesystem state recorded in
the .content file, even if the parity is only partially synchronized.
</p><p>In the event of a <b>sync</b> interruption, <b>check</b> and <b>fix</b> commands
also read from the <b>stable</b> snapshot to retrieve data blocks
from files that were updated or deleted during the sync.
This is possible because the .content file retains metadata for
all modified or deleted files throughout the sync process.
This historical information is only cleared once a sync finishes
successfully and the final version of the .content file is saved.
</p><p>If a <b>sync</b> is restarted after an interruption, the existing
pending snapshot is deleted and a new one is created to
capture the current state of the live filesystem.
However, if a <b>sync</b> is interrupted, avoid modifying, deleting,
replacing, or moving files until a subsequent <b>sync</b> completes
successfully. Parity may still contain blocks computed from the
snapshot used by the interrupted sync. A later sync may replace
that snapshot, making intermediate file versions unavailable for
recovery.
</p><div class="manual-section-level-2">
<h2 id="sec9-1" class="manual-title-level-2">
External backups with filesystem snapshots
</h2>
<p>When filesystem snapshots are enabled, SnapRAID accesses or creates
snapshots at the root of each data subvolume, volume, or dataset.
</p><p>A simple way to avoid any interference with external tools is to point
your <b>data</b> configuration to a regular subdirectory within the subvolume
or volume (for example, <b>/mnt/subvol/data</b> instead of <b>/mnt/subvol</b>).
SnapRAID always creates the snapshot directory at the subvolume root
(for example, <b>/mnt/subvol/.snapraid/</b>), leaving the data subdirectory
clean so that snapshots remain outside and invisible to backup tools
operating inside it.
</p><p>Otherwise, if your configured <b>data</b> directory is itself the subvolume
or volume root, SnapRAID creates the <b>.snapraid/</b> directory directly
inside it (on Btrfs, Bcachefs, and NTFS). While SnapRAID automatically
excludes this directory from its own scanning, external backup tools
or file synchronizers will encounter it. If not excluded, they may
traverse into the snapshots or directory links and copy the entire
frozen data tree, duplicating data and potentially exhausting backup
storage. Always configure external backup tools to exclude the
<b>.snapraid/</b> directory.
</p><p>On ZFS, snapshots are exposed through the standard <b>.zfs/snapshot/</b>
virtual directory rather than <b>.snapraid/</b>. By default (<b>snapdir=hidden</b>),
ZFS hides this directory from directory listings, so external backup
tools will not traverse it. If you have enabled <b>snapdir=visible</b>,
ensure your backup tools exclude the <b>.zfs/</b> directory.
</p></div>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
Pattern
</h1>
<p>Patterns are used to select a subset of files to exclude or include in
@ -1820,25 +2034,25 @@ question mark, it never crosses directory boundaries. It stops at the
forward slash, making it suitable for matching within a single path
component. This is the standard wildcard behavior familiar from shell
globbing.
</p><p>The double star <b>**</b> is more powerful, it matches any sequence of
characters including directory separators. This allows patterns to match
across multiple directory levels. When <b>**</b> appears embedded directly in
a pattern, it can match zero or more characters including slashes between
the surrounding literal text.
</p><p>The most important use of <b>**</b> is in the special form <b>/**/</b>. This matches
zero or more complete directory levels, making it possible to match files
at any depth in a directory tree without knowing the exact path structure.
For example, the pattern <b>src/**/main.js</b> matches <b>src/main.js</b> (skipping
zero directories), <b>src/ui/main.js</b> (skipping one directory), and
<b>src/ui/components/main.js</b> (skipping two directories).
</p><p>The double star <b>**</b> wildcard matches across directory separators only
when it is adjacent to a directory separator (preceded or followed by a
slash). In this form, it matches zero or more characters across directory
levels. For example, <b>foo/**/bar</b> matches <b>foo/bar</b>, <b>foo/a/bar</b>, and
<b>foo/a/b/bar</b>; <b>**/build</b> matches <b>build</b> and <b>foo/bar/build</b>; and
<b>src/**.js</b> matches <b>src/main.js</b> and <b>src/ui/components/main.js</b>.
The standalone form <b>/**/</b> is not accepted as a complete pattern.
</p><p>When <b>**</b> is not adjacent to a slash, it behaves like <b>*</b> and does not
match directory separators. For example, <b>**.jpg</b> matches <b>photo.jpg</b>
within the current directory, but does not match <b>dir/photo.jpg</b>. Use
<b>**/*.jpg</b> for that purpose.
</p><p>Character classes using square brackets match a single character from a
specified set or range. Like the other single character patterns, they do
not match directory separators. Classes support ranges and negation using
an exclamation mark.
</p><p>The fundamental distinction to remember is that <b>*</b>, <b>?</b>, and character
classes all respect directory boundaries and only match within a single path
component, while <b>**</b> is the only pattern that can match across directory
separators.
classes all respect directory boundaries and only match within a single path
component, while <b>**</b> can match across directory separators only when
adjacent to a slash.
</p><p>There are four different types of patterns:
</p><div class="manual-option-list">
<div class="manual-option-entry">
@ -1886,9 +2100,9 @@ the array root directory, not the local file system root directory.
Windows system directories, junctions, mount points, and other Windows
special directories are treated as files, meaning that to exclude
them, you must use a file rule, not a directory one.
</p><p>If the file name contains a <b>*</b>, <b>?</b>, <b>[</b>,
or <b>]</b> character, you must escape it to avoid having it interpreted as a
globbing character. In Unix, the escape character is <b>\</b>; in Windows, it is <b>^</b>.
</p><p>If the file name contains a <b>*</b>, <b>?</b>, <b>[</b>, or <b>]</b> character, you must
escape it to avoid having it interpreted as a globbing character.
In Unix, the escape character is <b>\</b>; in Windows, it is <b>^</b>.
When the pattern is on the command line, you must double the escape
character to avoid having it interpreted by the command shell.
</p><p>In the configuration file, you can use different strategies to filter
@ -1926,6 +2140,24 @@ include /movies/
include /musics/
include /pictures/
</pre>
<p>Note that excluding a directory (using DIR/ or /PATH/DIR/) prevents
SnapRAID from entering and scanning that directory. Consequently, it is
not possible to re-include a file or subdirectory located inside an
excluded parent directory, because the scanner never traverses into it.
</p><p>For example, the following configuration will NOT include <b>file.dat</b>
because <b>/keep/</b> is pruned before <b>file.dat</b> can be seen:
</p><pre>
# Does NOT work: /keep/ is skipped entirely
include /keep/file.dat
exclude /keep/
</pre>
<p>To exclude files inside a directory while keeping specific ones, match
the files within the directory rather than excluding the directory itself:
</p><pre>
# Works: /keep/ is traversed, but other files inside are excluded
include /keep/file.dat
exclude /keep/*
</pre>
<p>On the command line, using the -f option, you can only use <b>include</b>
patterns. For example:
</p><pre>
@ -1937,7 +2169,7 @@ snapraid -f "*.mp3" check
quote them to prevent the shell from expanding them.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
<h1 id="sec11" class="manual-title-level-1">
Ignore File
</h1>
<p>In addition to the global rules in the configuration file, you can
@ -2003,17 +2235,19 @@ build/
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
<h1 id="sec12" class="manual-title-level-1">
Content
</h1>
<p>SnapRAID stores the list and checksums of your files in the content file.
</p><p>It is a binary file that lists all the files present in your disk array,
along with all the checksums to verify their integrity.
</p><p>This file is read and written by the <b>sync</b> and <b>scrub</b> commands and
read by the <b>fix</b>, <b>check</b>, and <b>status</b> commands.
</p><p>The content file is read and written by the <b>sync</b>, <b>scrub</b>, <b>touch</b>, and
<b>rehash</b> commands. It is read by the <b>status</b>, <b>diff</b>, <b>check</b>, <b>fix</b>,
<b>list</b>, <b>dup</b>, <b>locate</b>, and <b>pool</b> commands, and it is completely
ignored by the <b>smart</b>, <b>probe</b>, <b>up</b>, <b>down</b>, and <b>devices</b> commands.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec11" class="manual-title-level-1">
<h1 id="sec13" class="manual-title-level-1">
Parity
</h1>
<p>SnapRAID stores the parity information of your array in the parity
@ -2024,7 +2258,7 @@ blocks defined in the <b>content</b> file.
only read by the <b>scrub</b> and <b>check</b> commands.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec12" class="manual-title-level-1">
<h1 id="sec14" class="manual-title-level-1">
Encoding
</h1>
<p>SnapRAID in Unix ignores any encoding. It reads and stores the
@ -2038,6 +2272,252 @@ This affects only the printed file names; if you
redirect the console output to a file, the resulting file is always
in UTF-8 format.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec15" class="manual-title-level-1">
Exit Code
</h1>
<p>SnapRAID terminates with the following error codes:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
0
</div><div class="manual-tag-description">
Everything OK.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
1
</div><div class="manual-tag-description">
The command encountered some errors.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2
</div><div class="manual-tag-description">
The <b>diff</b> command found everything is OK, but a <b>sync</b> is
needed.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
3
</div><div class="manual-tag-description">
A disk device command (<b>probe</b>, <b>smart</b>, <b>devices</b>, <b>up</b>,
<b>down</b>) completed, but at least one filesystem is running in
degraded mode with missing device(s).
</div>
</div>
</div>
</div>
<div class="manual-section-level-1">
<h1 id="sec16" class="manual-title-level-1">
Known Issues
</h1>
<div class="manual-section-level-2">
<h2 id="sec16-1" class="manual-title-level-2">
Filesystem boundaries
</h2>
<p>SnapRAID does not cross filesystem, mount, or subvolume boundaries while
scanning a data disk. When such a boundary is detected, SnapRAID reports
a WARNING and does not scan beyond it.
</p><p>Files located beyond such boundaries are not included in the data disk and
must be configured separately if they have to be protected.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-2" class="manual-title-level-2">
Mount points with filesystem snapshots
</h2>
<p>When filesystem snapshots are enabled, nested mount points and bind mounts
inside a data disk are not supported.
</p><p>Mount points are part of the live system mount namespace and are not
preserved in filesystem snapshots. Consequently, when scanning a snapshot,
a directory hidden by a mount point in the live filesystem may become
visible.
</p><p>Do not place nested mount points or bind mounts inside data disks when
filesystem snapshots are enabled.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-3" class="manual-title-level-2">
Multiple configurations with filesystem snapshots
</h2>
<p>Snapshot support cannot be safely shared by multiple independent
SnapRAID configurations using the same filesystem snapshot namespace.
</p><p>On Btrfs and Bcachefs, only one SnapRAID configuration with snapshot
support enabled may use data directories within the same subvolume.
On ZFS, the same restriction applies to a dataset, and on NTFS to a volume.
</p><p>Multiple configurations sharing the same snapshot namespace use the same
<b>stable</b>, <b>pending</b>, and <b>scan</b> snapshots. Running one configuration may
therefore replace or delete recovery snapshots required by another.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-4" class="manual-title-level-2">
In-place file modifications without timestamp changes
</h2>
<p>SnapRAID detects file modifications by comparing file sizes and
modification timestamps (mtime).
</p><p>If an application modifies a file in-place without altering its size
or updating its modification timestamp, "diff" and "sync" will not
detect that the file has changed, and its parity will not be updated.
</p><p>To ensure SnapRAID recognizes such changes, update the file's
modification timestamp (for example, with the "touch" utility).
Otherwise, the difference will only be detected as a hash mismatch
during a subsequent "scrub" or "check".
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-5" class="manual-title-level-2">
Windows non-ASCII case matching
</h2>
<p>SnapRAID uses standard, predictable UTF-8 encoding across all platforms,
limiting case-insensitive matching to ASCII characters.
</p><p>Windows filesystems suffer from the legacy design of enforcing case
insensitivity across Unicode filenames via arbitrary, system-dependent
folding tables. Consequently, Windows obscures the reality of the
filesystem by treating completely different Unicode byte sequences as if
they were the same file.
</p><p>For example, <b>À.txt</b> and <b>à.txt</b> are distinct Unicode names, yet Windows
illogically treats them as identical, while SnapRAID preserves their true
distinction.
</p><p>This limitation is caused by Windows's inconsistent handling of Unicode
filenames and its insistence on case-insensitive aliasing. To prevent
discrepancies arising from Windows's case folding, always specify the
exact case for any non-ASCII characters in configuration paths and filters.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-6" class="manual-title-level-2">
Partial fix recovery
</h2>
<p>When <b>fix</b> is restricted using <b>-S, --start</b> or <b>-B, --count</b>,
SnapRAID operates only on the selected blocks and does not perform
file-level finalization or quarantine.
</p><p>If recovery produces best-effort data that cannot be proven to represent
the current contents, such blocks may still be written under the normal
filename. The uncertainty associated with these recovered blocks is not
persisted after the command terminates.
</p><p>As a consequence, a later <b>fix</b> will treat these readable blocks as valid
file data and will not attempt to recover them again. This can cause a
subsequent recovery to report success while leaving incomplete or stale
data in the file.
</p><p>The <b>-S</b> and <b>-B</b> options are intended only for advanced manual recovery,
typically after a normal <b>fix</b> has failed. If a partial <b>fix</b> reports
unrecoverable data, remove or rename the affected files before attempting
another recovery, or verify their contents manually.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-7" class="manual-title-level-2">
NTFS hard links and excluded paths
</h2>
<p>On NTFS, directory entries cache file size and timestamps independently
for each hard link. When a file is modified through one link, the directory
entries of other links pointing to the same file may retain stale metadata
until they are accessed.
</p><p>SnapRAID automatically detects and normalizes this condition whenever at
least two hard links to the same file are encountered during a scan.
However, if only one hard link is scanned while the others are excluded by
filters or reside outside the data disk path, SnapRAID cannot detect the
inode collision and relies on the cached metadata of the single visible
link.
</p><p>Consequently, modifications made through an excluded or external hard link
may go unnoticed by SnapRAID until the metadata of the included link is
refreshed by the operating system (such as when the file is accessed or
opened through that path).
</p><p>To avoid this limitation, avoid modifying protected files through hard
links that are excluded from SnapRAID, or ensure that all hard links to a
file are included in the scan so SnapRAID can normalize them.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-8" class="manual-title-level-2">
Recovery after an interrupted multi-parity sync
</h2>
<p>In an array with multiple parity disks, an interrupted <b>sync</b> can leave
parity levels temporarily out of sync with each other. For example,
parity 1 might already contain newly updated data, while parity 2 still
contains the old data.
</p><p>During <b>check</b> or <b>fix</b>, SnapRAID tries different parity combinations
and validates reconstructed data against the known block hashes (covering
the full block, typically 256 KiB).
</p><p>If SnapRAID attempts a reconstruction using an inconsistent mix of old
and new parity, the linear RAID equations will produce incorrect data.
For this invalid combination to be falsely accepted, the equations would
have to accidentally reconstruct at least one complete 256 KiB block so
perfectly that its hash matches, while other unsynchronized blocks in the
same stripe are reconstructed with incorrect data.
</p><p>This scenario does not depend on a hash collision; rather, the mixed
parity equations themselves would have to coincidentally yield the exact
original 256 KiB block contents. While mathematically possible with
specially crafted or highly repetitive data, it is practically impossible
with real-world data.
</p><p>If all disks are healthy, completing the interrupted <b>sync</b> before making
further changes removes this ambiguity. If a disk has failed and recovery
is required, avoid modifying any data disks before running <b>check</b> or
<b>fix</b>.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec16-9" class="manual-title-level-2">
Reserved file and directory names
</h2>
<p>SnapRAID reserves some file, directory, and snapshot names for its internal
operation. Do not use these names for user data:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraidignore
</div><div class="manual-tag-description">
Local exclusion-rules file.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
.snapraid
</div><div class="manual-tag-description">
Snapshot container directory.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
snapraid-*
</div><div class="manual-tag-description">
SnapRAID-managed ZFS snapshot names.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
*.unrecoverable
</div><div class="manual-tag-description">
Damaged files quarantined during recovery.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.tmp
</div><div class="manual-tag-description">
Temporary file for content updates.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CONTENT.lock
</div><div class="manual-tag-description">
Content lock file.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
PARITY.spaceholder
</div><div class="manual-tag-description">
Temporary space-holder file during Windows parity
allocation.
</div>
</div>
</div>
<p>Using these names for unrelated data may cause files or snapshots to be
ignored, misinterpreted as metadata, overwritten, renamed, or deleted.
</p><p>On Windows, all case variants are reserved as well, even in NTFS directories
configured for case-sensitive operation (for example, .SNAPRAIDIGNORE,
.SnapRaid, CONTENT.TMP, and CONTENT.Lock).
</p></div>
</div>
</div>