1.\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
2.\"
3.\" This code is derived from software contributed to The DragonFly Project
4.\" by Matthew Dillon <dillon@backplane.com>
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\"
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in
14.\"    the documentation and/or other materials provided with the
15.\"    distribution.
16.\" 3. Neither the name of The DragonFly Project nor the names of its
17.\"    contributors may be used to endorse or promote products derived
18.\"    from this software without specific, prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.Dd October 31, 2016
34.Dt NEWFS_HAMMER 8
35.Os
36.Sh NAME
37.Nm newfs_hammer
38.Nd construct a new HAMMER file system
39.Sh SYNOPSIS
40.Nm
41.Fl L Ar label
42.Op Fl \&Efh
43.Op Fl b Ar bootsize
44.Op Fl m Ar savesize
45.Op Fl u Ar undosize
46.Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
47.Op Fl V Ar version
48.Ar special ...
49.Sh DESCRIPTION
50The
51.Nm
52utility creates a
53.Nm HAMMER
54file system on device(s)
55.Ar special .
56If multiple devices are specified a single
57.Nm HAMMER
58file system is created
59which spans all of them.
60Each
61.Ar special
62will constitute a volume which the
63.Nm HAMMER
64file system is built on.
65The first
66.Ar special
67specified becomes the
68.Ar root-volume .
69.Nm HAMMER
70file systems are sector-size agnostic, however the
71.Dx
72implementation requires the sector size to be no larger than 16KB.
73.Nm HAMMER
74file systems start at a relative offset of 0 and may only be created
75under out-of-band disk labels
76.Po
77.Xr disklabel64 5
78or
79.Xr gpt 8
80labels
81.Pc ,
82or in
83.Xr disklabel32 5
84partitions which do not overlap the label area (have a starting sector
85greater than 16).
86.Pp
87.Nm HAMMER
88file systems are designed for large storage systems, up to 1 Exabyte, and
89will not operate efficiently on small storage systems.
90The minimum recommended file system size is 50GB.
91.Nm HAMMER
92must reserve 512MB to 1GB of its storage for reblocking and UNDO/REDO FIFO.
93In addition,
94.Nm HAMMER
95file systems operating normally, with full history
96retention and daily snapshots, do not immediately reclaim space when
97files are deleted.
98A regular system maintenance job runs once a day by
99.Xr periodic 8
100to handle reclamation.
101.Pp
102.Nm HAMMER
103works best when the machine's normal workload would not otherwise fill
104the file system up in the course of 60 days of operation.
105.Pp
106The options are as follows:
107.Bl -tag -width indent
108.It Fl L Ar label
109All
110.Nm HAMMER
111file systems must be named and names should be unique on a
112per-machine basis, although
113.Nm
114does not prevent from making file systems with the same label.
115.It Fl f
116Force operation.
117This is needed for the creation of a
118.Nm HAMMER
119file system less than 10GB size or
120with less than 512MB UNDO/REDO FIFO.
121This should not be used under normal circumstances.
122.It Fl E
123Use TRIM to erase the device's data before creating the file system.
124The underlying device must have the TRIM sysctl enabled.
125Only devices that support TRIM will have such a sysctl option
126.Va ( kern.cam.da.X.trim_enabled ) .
127.It Fl h
128Show usage.
129.It Fl b Ar bootsize
130Specify a fixed area in which a boot related kernel and data can be stored.
131This area is currently unused.
132The
133.Ar bootsize
134is specified in bytes with a suffix of
135.Cm K , M , G
136or
137.Cm T .
138.It Fl m Ar savesize
139Specify a fixed area which
140.Nm HAMMER
141may use as a memory log.
142This area is currently unused.
143The
144.Ar savesize
145is specified in bytes with a suffix of
146.Cm K , M , G
147or
148.Cm T .
149.It Fl u Ar undosize
150Specify the size of the fixed UNDO/REDO FIFO.
151The
152.Ar undosize
153is specified in bytes with a suffix of
154.Cm K , M , G
155or
156.Cm T .
157By default 0.1% of the root
158volume's size is used, with a reasonable minimum and a reasonable cap.
159The UNDO/REDO FIFO is used to sequence meta-data out to the media for
160instant crash recovery.
161.It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead
162Refer to the same option in
163.Xr hammer 8 .
164.It Fl V Ar version
165Specify the
166.Nm HAMMER
167file system version to format.
168By default
169.Nm
170formats the file system using the highest production version number
171supported by the
172.Nm HAMMER
173VFS by checking the
174.Va vfs.hammer.supported_version
175sysctl.
176If you need to maintain compatibility with an older version of
177.Nm HAMMER
178you may specify the version with this option.
179.El
180.Pp
181The
182.Ar bootsize ,
183.Ar savesize
184and
185.Ar undosize
186must be given with a suffix of
187.Cm K , M , G
188or
189.Cm T
190meaning kilobyte, megabyte, gigabyte and terabyte.
191Lower case can also be used for suffix.
192.Sh EXIT STATUS
193.Ex -std
194.Sh EXAMPLES
195Create a file system named
196.Sq HOME
197on
198.Pa /dev/ad0s1d :
199.Bd -literal -offset indent
200newfs_hammer -L HOME /dev/ad0s1d
201.Ed
202.Pp
203Create a file system named
204.Sq TEMP
205on
206.Pa /dev/ad0s1d
207and
208.Pa /dev/ad1s1d :
209.Bd -literal -offset indent
210newfs_hammer -L TEMP /dev/ad0s1d /dev/ad1s1d
211.Ed
212.Sh SEE ALSO
213.Xr disklabel32 5 ,
214.Xr disklabel64 5 ,
215.Xr HAMMER 5 ,
216.Xr fdisk 8 ,
217.Xr gpt 8 ,
218.Xr hammer 8 ,
219.Xr mount_hammer 8 ,
220.Xr newfs 8
221.Sh HISTORY
222The
223.Nm
224utility first appeared in
225.Dx 1.11 .
226.Sh AUTHORS
227.An Matthew Dillon Aq Mt dillon@backplane.com
228