/
hammer.8
333 lines (327 loc) · 12.8 KB
/
hammer.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
.\" Copyright (c) 2007 The DragonFly Project. All rights reserved.
.\"
.\" This code is derived from software contributed to The DragonFly Project
.\" by Matthew Dillon <dillon@backplane.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.31 2008/07/07 00:27:22 dillon Exp $
.Dd June 26, 2008
.Dt HAMMER 8
.Os
.Sh NAME
.Nm hammer
.Nd HAMMER file system utility
.Sh SYNOPSIS
.Nm
.Op Fl hrv
.Op Fl c Ar cyclefile
.Op Fl f Ar blkdev[:blkdev]*
.Op Fl s Ar linkpath
.Op Fl t Ar timeout
.Ar command
.Ar ...
.Sh DESCRIPTION
The
.Nm
utility provides miscellaneous functions related to managing a HAMMER
filesystem.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl h
Get help
.It Fl r
Specify recursion for those commands which support it.
.It Fl c Ar cyclefile
When pruning and reblocking you can instruction HAMMER to start at the
object id stored in the specified file. If the file does not exist
HAMMER will start at the beginning. If HAMMER is told to run for a
specific period of time and is unable to complete the operation it will
write out the current obj_id so the next run can pick up where it left
off. If HAMMER runs to completion it will delete the cyclefile.
.It Fl f Ar blkdev[:blkdev]*
Specify the volumes making up a HAMMER filesystem.
.It Fl s Ar linkpath
When pruning a filesystem you can instruct HAMMER to create softlinks
to available snapshots.
.It Fl t Ar timeout
When pruning and reblocking you can tell the utility to stop after a
certain period of time. This option is used along with the cycle file
option to prune or reblock a portion of the filesystem incrementally.
.It Fl v
Increase verboseness. May be specified multiple times.
.El
.Pp
The commands are as follows:
.Bl -tag -width indent
.It Ar synctid Ar filesystem Op quick
Generates a guaranteed, formal 64 bit transaction id representing the
current state of the specified HAMMER filesystem. The filesystem will
be synced to the media.
.Pp
If the
.Ar quick
keyword is specified the filesystem will be soft-synced, meaning that a
crash might still undo the state of the filesystem as of the transaction
id returned but any new modifications will occur after the returned
transaction id as expected.
.It Ar bstats Op interval
Output HAMMER B-Tree statistics until interrupted. The default interval
is one second.
.It Ar iostats Op interval
Output HAMMER I/O statistics until interrupted. The default interval
is one second.
.It Ar history Ar path
Show the modification history for a HAMMER file's inode and data.
.It Ar show Op vol_no[:clu_no]
Dump the B-Tree starting at the specified volume and cluster, or
at the root volume if not specified.
The B-Tree is dumped recursively if the
.Fl r
option is specified.
.It Ar blockmap
Dump the btree, record, large-data, and small-data blockmaps, showing
physical block assignments and free space percentages.
.It Ar namekey Ar filename
Generate a HAMMER 64 bit directory hash for the specified file name.
The low 32 bits are used as an iterator for hash collisions and will be
output as 0.
.It Ar namekey32 Ar filename
Generate the top 32 bits of a HAMMER 64 bit directory hash for the specified
file name.
.It Ar prune Ar softlink-dir
Prune the filesystem based on previously created snapshot softlinks.
The target directory is expected to contain softlinks pointing to
snapshots of the filesystems you wish to retain. The directory is scanned
non-recursively and the mount points and transaction ids stored in the
softlinks are extracted and sorted.
The filesystem is then explicitly pruned according to what is found.
Cleaning out portions of the filesystem is as simple as removing a softlink
and then running the
.Ar prune
command.
.Pp
As a safety measure pruning only occurs if one or more softlinks are found
containing the @@ snapshot id extension.
.Pp
Currently the scanned softlink directory must contain softlinks pointing
to a single HAMMER mount. The softlinks may specify absolute or relative
paths. Softlinks must use 20-character (@@0x%016llx) transaction ids,
as might be returned from 'hammer synctid <filesystem>'.
.Pp
Example, lets say your snapshot directory contains the following links:
.Bd -literal
lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
/usr/obj/@@0x10d2cd05b7270d16
lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
/usr/obj/@@0x10d2cd13f3fde98f
lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
/usr/obj/@@0x10d2cd222adee364
.Ed
.Pp
If you were to run the prune command on this directory, then the HAMMER
.Pa /usr/obj
mount will be pruned to retain the above three snapshots.
In addition, modifications made to the filesystem older than the oldest
snapshot will be destroyed and potentially fine-grained modifications made
to the filesystem more recently than the most recent snapshot will be
retained.
.Pp
If you then delete the snap2 softlink and rerun the prune command,
modifications pertaining to that snapshot would be destroyed.
.It Ar prune-everything Ar filesystem
This command will remove all historical records from the filesystem.
This directive is not normally used on a production system.
.Pp
Note that pruning a filesystem may not immediately free-up space,
though typically some space will be freed if a large number of records are
pruned out. The filesystem must be reblocked to completely recover all
available space.
.It Ar snapshot Ar snapshot-dir
.It Ar snapshot Ar filesystem snapshot-dir
Takes a snapshot of the filesystem either explicitly given by
.Ar filesystem
or implicitly derived from the
.Ar snapshot-dir
argument and creates a symlink in the directory provided by
.Ar snapshot-dir
pointing to the snapshot.
If
.Ar snapshot-dir
is no directory, it is assumed to be a format string
passed to
.Xr strftime 3
with the current time as parameter.
If
.Ar snapshot-dir
refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
is assumed and used as name for the newly created symlink.
Assuming that
.Pa /mysnapshots
is on filesystem
.Pa /
and that
.Pa /obj
is a filesystem on its own, the following invocations:
.Bd -literal
hammer snapshot /mysnapshots
hammer snapshot /mysnapshots/%Y-%m-%d
hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
.Ed
.Pp
would create symlinks similar to:
.Bd -literal
/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
.Ed
.It Ar reblock Ar filesystem Op Ar fill_percentage
.It Ar reblock-btree Ar filesystem Op Ar fill_percentage
.It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
.It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
.It Ar reblock-data Ar filesystem Op Ar fill_percentage
Attempt to defragment and free space for reuse by reblocking a live
HAMMER filesystem.
Big blocks cannot be reused by HAMMER until they are completely free.
This command also has the effect of reordering all elements, effectively
defragmenting the filesystem.
.Pp
The default fill percentage is 100% and will cause the filesystem to be
completely defragmented. All specified element types will be reallocated
and rewritten. If you wish to quickly free up space instead try specifying
a smaller fill percentage, such as 90% or 80% (the '%' suffix is not needed).
.Pp
Since this command may rewrite the entire contents of the disk it is
best to do it incrementally from a cron job along with the
.Fl c Ar cyclefile
and
.Fl t Ar timeout
options to limit the run time.
The filesystem would thus be defragmented over long period of time.
.Pp
It is recommended that separate invocations be used for each data type.
Btree nodes, inodes, and directories are typically the most important
elements needing defragmentation. Data can be defragmented over a longer
period of time.
.It Ar pfs-status Ar dirpath
Retrieve the mirroring configuration parameters for the specified
HAMMER filesystem or pseudo-filesystem.
.It Ar pfs-create Ar dirpath Op options
Create a pseudo-filesystem inside a HAMMER filesystem. Up to 65535 such
filesystems can be created. Each one uses an independant inode numbering
space making it suitable for use as a replication source or target.
.Pp
Note that rm -rf'ing a pseudo-fs will not allow the pseudo-id to be reused
until all historical data has been pruned out and the pseudo-fs is truely
empty.
.It Ar pfs-update Ar dirpath Op options
Update the configuration parameters for an existing HAMMER filesystem
or pseudo-filesystem. Options that may be specified:
.Pp
.Bl -tag -width indent
.It sync-beg-tid=0x16llx
This is the automatic snapshot access TID for mirroring slaves.
This parameter is normally updated automatically by the
.Ar mirror-write
directive.
.Pp
It is important to note that accessing a mirroring slave
with a transaction id greater then the last fully synchronized transaction
id can result in an unreliable snapshot since you will be accessing
data that is still undergoing synchronization.
.Pp
Manually modifying this field is dangerous and can result in a broken
mirror.
.It sync-end-tid=0x16llx
This is the current synchronization target for mirroring slaves.
This parameter is normally updated automatically by the
.Ar mirror-write
directive.
.Pp
Manually modifying this field is dangerous and can result in a broken
mirror.
.It shared-uuid=<uuid>
Set the shared uuid for this filesystem. All mirrors must have the same
shared uuid. For safety purposes the mirror-write directives will refuse
to operate on a target with a different shared uuid.
.Pp
Changing the shared uuid on an existing, non-empty mirroring target,
including an empty but not completely pruned target, can lead
to corruption of the mirroring target.
.It unique-uuid=<uuid>
Set the unique uuid for this filesystem. This uuid should not be used
anywhere else, even on exact copies of the filesystem.
.It master=<num>
Set the master id for multi-master mirroring. Only values between 0 and 15
inclusive may be specified. All masters sharing the same
.Ar shared-uuid
must have different ids.
Up to 16 masters will eventually be supported.
Multi-master mirroring is not supported yet and the master id should be
set to 0 on the single master when mirroring to one or more slaves.
.It no-mirror
This disables the ability to use this filesystem as a mirroring source
or target. You can still do full scans with mirror-read but incremental
scans will not work.
.It slave
Sets slave mode, allowing the mirror to be used as a slave. Except for
the mirror-write directive all accesses to the mirror will be made read-only
and will be as-of the
.Ar sync_beg_tid .
.It label=<string>
Set a descriptive label for this filesystem.
.El
.It Ar mirror-read Ar filesystem Op Ar <begin-tid>
Generate a mirroring stream to stdout.
.It Ar mirror-write Ar filesystem Op Ar
Take a mirroring stream on stdin and output it to stdout.
.Pp
This command will fail if the
.Ar shared_uuid
configuration field for the two filesystems do not match.
.It Ar mirror-dump
A mirror-read can be piped into a mirror-dump to dump an ascii
representation of the mirroring stream.
.It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
This is a shortcut which pipes a mirror-read command to a mirror-write
command. If a remote host specification is made the program forks an
ssh and execs the mirror-read and/or mirror-write on the appropriate host.
.El
.\".Sh EXAMPLES
.Sh DIAGNOSTICS
.Ex -std
.Sh SEE ALSO
.Xr newfs_hammer 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Dx 1.11 .
.Sh AUTHORS
.An Matthew Dillon Aq dillon@backplane.com