home | help 
NEWFS_HAMMER2(8)	     System Manager's Manual		NEWFS_HAMMER2(8)

NAME
     newfs_hammer2 -- construct a new HAMMER2 file system

SYNOPSIS
     newfs_hammer2 [-b bootsize] [-r auxsize] [-V version] [-L label ...]
		   [-s size] special ...

DESCRIPTION
     The  newfs_hammer2 utility prepares a HAMMER2 volume on the specified block
     device.  HAMMER2 volumes can contain  any	number	of  named  PFSs  (Pseudo
     FileSystems).

     The  newfs_hammer2 program always creates a PFS called "LOCAL" which may be
     used for device-specific configuration.  This PFS should never be used  for
     generic data.

     If no -L option is specified, newfs_hammer2 will create "DATA".

     You can override the default PFS name by specifying one or more -L options.

     You can specify -L none if you do not want newfs_hammer2 to create any PFSs
     other than "LOCAL".

     HAMMER2 file systems are sector-size agnostic, however the DragonFly imple-
     mentation	requires the sector size to be no larger than 16K.  HAMMER2 file
     systems start at a relative offset of 0  and  leave  no  room  for  in-band
     disklabels  (old,	traditional BSD labels).  They may only be created using
     out-of-band disk labels, which is the default  on	DragonFly  via	(diskla-
     bel(5)  or gpt(8) labels), or with old style disklabels as long as the par-
     tition does not overlap the label area (have a starting sector greater than
     16).

     HAMMER2 file systems are designed for large storage systems, up  to  1  Ex-
     abyte, and may not operate efficiently on small storage systems.  The mini-
     mum  recommended  file system size is 50GB.  In addition, HAMMER2 file sys-
     tems operating normally, with automatic snapshots, do not	immediately  re-
     claim  space when files are deleted.  A regular system maintenance job runs
     once a day by periodic(8) to handle reclamation.

     HAMMER2 works best when the machine's normal workload would  not  otherwise
     fill the file system up in the course of 60 days of operation.

     The options are as follows:

     -b bootsize
	     Specify a fixed area in which a boot related kernel and data can be
	     stored.   The  bootsize  is  specified in bytes.  By default a boot
	     area of approximately 64MB will be created.  This area is not  cur-
	     rently used for booting and may be repurposed in the future.

     -r auxsize
	     Specify a fixed area in which an aux related kernel and data can be
	     stored.  The auxsize is specified in bytes.  By default an aux area
	     of approximately 256MB will be created.  This area is not currently
	     used and may be repurposed in the future.

     -V version
	     Specify  the  HAMMER2  file  system  version to format.  By default
	     newfs_hammer2 formats the file system using the highest  production
	     version  number  supported  by  the  HAMMER2  VFS	by  checking the
	     vfs.hammer2.supported_version sysctl.  If you need to maintain com-
	     patibility with an older version of HAMMER2  you  may  specify  the
	     version with this option.

     -L label
	     By  default newfs_hammer2 always creates a local master PFSs on the
	     new volume called "LOCAL" and "DATA".

	     If you specify one or more label options to create your  own  named
	     local  PFSs,  newfs_hammer2  will	not create any conditional PFSs.
	     However, "LOCAL" is still always created and should not  be  speci-
	     fied  with  this  option.	If you don't want any PFSs to be created
	     (other than "LOCAL"), use -L none.

     -s size
	     The size of the file system in bytes.  This value defaults  to  the
	     total  size  of  the  raw partitions specified in special (in other
	     words, newfs_hammer2 will use the entire  partition  for  the  file
	     system).  The size must be 1GiB or larger.

     The  bootsize, auxsize and size must be given with a suffix of K, M, G or T
     meaning kilobyte, megabyte, gigabyte and terabyte.  Lower case can also  be
     used  for suffix.	The bootsize and auxsize create reserved blocks of space
     on the target volume but are not currently used by the filesystem for  any-
     thing.

EXIT STATUS
     The newfs_hammer2 utility exits 0 on success, and >0 if an error occurs.

SEE ALSO
     hammer2(8), mount_hammer2(8)

HISTORY
     The  newfs_hammer2  utility first appeared in DragonFly 3.1 but was not en-
     abled unconditionally until DragonFly 4.9.

AUTHORS
     Matthew Dillon <dillon@backplane.com>

     The newfs_hammer2 utility was ported to FreeBSD, NetBSD and OpenBSD by
     Tomohiro Kusumi <tkusumi@netbsd.org>.

FreeBSD ports 15.quarterly	December 11, 2023		NEWFS_HAMMER2(8)
home | help