1 .\" Copyright (c) 1987, 1988, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Symmetric Computer Systems.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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 the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94
32 .\" $FreeBSD: src/sbin/disklabel/disklabel.8,v 1.15.2.22 2003/04/17 17:56:34 trhodes Exp $
39 .Nd read and write 64 bit disk pack label
52 .Op Ar disktype Ns / Ns Cm auto Op Ar packid
74 .Oo Ar disktype Ns / Ns Cm auto Oc
84 .Op Ar disktype Ns / Ns Cm auto Op Ar packid
94 .Oo Ar disktype Ns / Ns Cm auto Oc
99 installs, examines or modifies a 64 bit label on a disk drive or pack.
101 the label, it can be used to change the drive identification, the disk
102 partitions on the drive, or to replace a damaged label.
103 There are several forms
104 of the command that read (display), install or edit the label on a disk.
108 can install bootstrap code.
109 .Ss Raw or in-core label
110 The disk label resides close to or at the beginning of each disk slice.
111 For faster access, the kernel maintains a copy in core at all times.
113 default, most forms of the
115 command access the in-core copy of the label.
116 To access the raw (on-disk)
120 This option allows a label to be installed on a disk without kernel
121 support for a label, such as when labels are first installed on a system; it
122 must be used when first installing a label on a disk.
123 The specific effect of
125 is described under each command.
129 forms require a disk device name, which should always be the raw
130 device name representing the disk or slice.
132 uses the following scheme for slice numbering:
133 If the disk doesn't use GPT (typically laid out by
135 but e.g.\& MBR (typically laid out by
139 represents the entire disk regardless of any DOS partitioning.
140 Slice 0 is called the compatibility slice,
141 and slice 1 and onward, e.g.\&
146 If the disk does use GPT, then all slices are
148 slices, slice 0 isn't special, it is just the first slice on the disk.
149 You do not have to include the
151 path prefix when specifying the device.
154 utility will automatically prepend it.
155 .Ss Reading the disk label
156 To examine the label on a disk drive, use
165 represents the raw disk in question, and may be in the form
169 It will display all of the parameters associated with the drive and its
174 the kernel's in-core copy of the label is displayed;
175 if the disk has no label, or the partition types on the disk are incorrect,
176 the kernel may have constructed or modified the label.
181 reads the label from the raw disk and displays it.
182 Both versions are usually
183 identical except in the case where a label has not yet been initialized or
185 .Ss Writing a standard label
186 To write a standard label, use the form
193 .Op Ar disktype Ns / Ns Cm auto Op Ar packid
195 The required argument to
197 is the drive to be labeled.
198 The first optional argument is the drive type as described in the
200 file, from which the drive parameters and partitions are taken.
201 If not specified, then the
203 type is assumed to make a virgin label for the disk as described below.
205 different disks of the same physical type are to have different partitions, it
206 will be necessary to have separate disktab entries describing each, or to edit
207 the label after installation as described below.
208 The optional argument is a
209 pack identification string, up to 63 characters long.
211 quoted if it contains blanks.
215 flag is given, no data will be written to the device, and instead the
216 disklabel that would have been written will be printed to stdout.
220 flag is given, the disk sectors containing the label and bootstrap
221 will be written directly.
222 A side-effect of this is that any existing bootstrap code will be overwritten
223 and the disk rendered unbootable.
224 See the boot options below for a method of
225 writing the label and the bootstrap at the same time.
229 the existing label will be updated via the in-core copy and any bootstrap
230 code will be unaffected.
231 If the disk does not already have a label, the
234 In either case, the kernel's in-core label is replaced.
236 For a virgin disk that is not known to
241 In this case, the driver is requested to produce a virgin label for the
243 This might or might not be successful, depending on whether the
244 driver for the disk is able to get the required data without reading
245 anything from the disk at all.
246 It will likely succeed for all SCSI
247 disks, most IDE disks, and vnode devices.
248 Writing a label to the
249 disk is the only supported operation.
251 For most harddisks, a label based on percentages for most partitions (and
252 one partition with a size of
254 will produce a reasonable configuration.
256 PC-based systems have special requirements in order for the BIOS to properly
260 Older systems may require what is known as a
261 .Dq dangerously dedicated
262 disklabel, which creates a fake DOS partition to work around problems older
263 BIOSes have with modern disk geometries.
264 On newer systems you generally want
265 to create a normal DOS partition using
269 disklabel within that slice.
271 later on in this page.
273 Installing a new disklabel does not in of itself allow your system to boot
274 a kernel using that label.
275 You must also install boot blocks, which is
276 described later on in this manual page.
277 .Ss Editing an existing disk label
278 To edit an existing disk label, use the form
286 This command reads the label from the in-core kernel copy, or directly from the
289 flag is also specified.
290 The label is written to a file in ASCII and then
291 supplied to an editor for changes.
292 If no editor is specified in an
294 environment variable,
297 When the editor terminates, the label file is used to rewrite the disk label.
298 Existing bootstrap code is unchanged regardless of whether
303 is specified, no data will be written to the device, and instead the
304 disklabel that would have been written will be printed to stdout.
306 useful to see how a partitioning scheme will work out for a specific disk.
307 .Ss Restoring a disk label from a file
308 To restore a disk label from a file, use the form
314 .Ar disk Ar protofile
317 is capable of restoring a disk label that was previously saved in a file
319 The prototype file used to create the label should be in the same format
320 as that produced when reading or editing a label.
321 Comments are delimited by
324 As when writing a new label, any existing bootstrap code will be
327 is specified and will be unaffected otherwise.
328 See the boot options below for a
329 method of restoring the label and writing the bootstrap at the same time.
332 is used, no data will be written to the device, and instead the
333 disklabel that would have been written will be printed to stdout.
335 useful to see how a partitioning scheme will work out for a specific disk.
336 .Ss Enabling and disabling writing to the disk label area
337 By default, it is not possible to write to the disk label area at the beginning
339 The disk driver arranges for
341 and similar system calls
344 on any attempt to do so.
346 to write to this area (for example, to obliterate the label), use the form
352 To disallow writing to the label area after previously allowing it,
358 .Ss Installing bootstraps
359 The final three forms of
361 are used to install bootstrap code, which allows boot from a
367 If you are creating a
368 .Dq dangerously-dedicated
369 slice for compatibility with older PC systems,
370 you generally want to specify the compatibility slice, such as
372 If you are creating a label within an existing DOS slice,
374 the slice name such as
376 Making a slice bootable can be tricky.
377 If you are using a normal DOS
378 slice you typically install (or leave) a standard MBR on the base disk and
381 bootblocks in the slice.
390 .Oo Ar disktype Ns / Ns Cm auto Oc
392 This form installs the bootstrap only.
393 It does not change the disk label.
394 You should never use this command on the compatibility slice unless you
396 .Dq dangerously-dedicated
399 This command is typically run on a
413 .Op Ar disktype Ns / Ns Cm auto Op Ar packid
415 This form corresponds to the
417 command described above.
418 In addition to writing a new volume label, it also installs the bootstrap.
419 If run on the compatibility slice this command will create a
420 .Dq dangerously-dedicated
422 This command is normally run on a
424 slice rather than the compatibility slice.
427 is used, no data will be written to the device, and instead the
428 disklabel that would have been written will be printed to stdout.
438 .Ar disk Ar protofile
439 .Oo Ar disktype Ns / Ns Cm auto Oc
441 This form corresponds to the
443 command described above.
444 In addition to restoring the volume label, it also installs the bootstrap.
445 If run on the compatibility slice this command will create a
446 .Dq dangerously-dedicated
448 This command is normally run on a
450 slice rather than the compatibility
453 The bootstrap commands always access the disk directly,
454 so it is not necessary to specify the
459 is used, no data will be written to the device, and instead the
460 disklabel that would have been written will be printed to stdout.
462 The bootstrap code is comprised of two boot programs.
463 Specify the name of the
464 boot programs to be installed in one of these ways:
467 Specify the names explicitly with the
473 indicates the primary boot program and
475 the secondary boot program.
476 The boot programs are normally located in
483 flags are not specified, but
485 was specified, the names of the programs are taken from the
491 entry for the disk if the disktab entry exists and includes those parameters.
493 Otherwise, the default boot image names are used:
497 for the standard stage1 and stage2 boot images.
499 .Ss Initializing/Formatting a bootable disk from scratch
500 To initialize a disk from scratch the following sequence is recommended.
501 Please note that this will wipe everything that was previously on the disk,
511 to initialize the hard disk, and create a GPT or MBR slice table,
513 .Dq "partition table"
521 to define partitions on
523 slices created in the previous step.
527 .Xr newfs_hammer2 8 ,
530 to create file systems on new partitions.
533 A typical partitioning scheme would be to have an
535 partition of approximately 1 GB for
537 to hold the current, old (and backup) kernels and modules, a
539 partition for swap (suggested to be at least the same size as the
543 partition for the root file system (usually all remaining space).
544 Your mileage may vary.
546 .Dl "gpt init -f -B da0"
547 .Dl "disklabel64 -B -r -w da0s1"
548 .Dl "disklabel64 -e da0s1"
549 .Ss Expanding the disklabel
552 option may be used to expand an existing disklabel to cover an expanded
553 storage device. This is useful when an image is copied to larger underlying
554 storage. If specified twice, the last partition will also be expanded to
555 fill the area. Mounted HAMMER2 filesystems can also be expanded to cover
556 the new space in the partition.
559 .Dl "disklabel64 -xx da0s1"
560 .Dl "hammer2 growfs /blahblah"
562 When a virgin disklabel64 is laid down a
564 or later kernel will align the partition start offset relative to the
565 physical drive instead of relative to the slice start.
566 This overcomes the issue of fdisk creating a badly aligned slice by default.
567 The kernel will use a 1MiB (1024 * 1024 byte) alignment.
568 The purpose of this alignment is to match swap and cluster operations
569 against the physical block size of the underlying device.
571 Even though nearly all devices still report a logical sector size of 512,
572 newer hard drives are starting to use larger physical sector sizes
573 and, in particular, solid state drives (SSDs) use a physical block size
574 of 64K (SLC) or 128K (MLC). We choose a 1 megabyte alignment to cover our
575 bases down the road. 64-bit disklabels are not designed to be put on
576 ultra-tiny storage devices.
578 It is worth noting that aligning cluster operations is particularly
579 important for SSDs and doubly so when
582 Swapcache is able to use large bulk writes which greatly reduces the degree
583 of write magnification on SSD media and it is possible to get upwards of
584 5x more endurance out of the device than the vendor spec sheet indicates.
586 .Bl -tag -width ".Pa /boot/boot2_64" -compact
587 .It Pa /boot/boot1_64
588 Default stage1 boot image.
589 .It Pa /boot/boot2_64
590 Default stage2 boot image.
592 Disk description file.
594 .Sh SAVED FILE FORMAT
599 version of the label when examining, editing, or restoring a disk label.
600 An example shows as below:
601 .Bd -literal -offset 4n
604 # Calculated informational fields for the slice:
606 # boot space: 1012224 bytes
607 # data space: 156286976 blocks # 152624.00 MB (160037863424 bytes)
609 # NOTE: The partition data base and stop are physically
610 # aligned instead of slice-relative aligned.
612 # All byte equivalent offsets must be aligned.
614 diskid: 5dc53a64-c5e5-11e7-8aec-011d0988acd3
616 boot2 data base: 0x000000001000
617 partitions data base: 0x0000000f8200
618 partitions data stop: 0x0025430f8200
619 backup label: 0x002543157200
620 total size: 0x002543158200 # 152625.34 MB
622 display block size: 1024 # for partition display and edit only
625 # size offset fstype fsuuid
626 a: 1048576 0 4.2BSD # 1024.000MB
627 b: 16777216 1048576 swap # 16384.000MB
628 d: 138461184 17825792 HAMMER # 135216.000MB
629 a-stor_uuid: 7f1ff0ee-c5ec-11e7-8aec-011d0988acd3
630 b-stor_uuid: 7f1ff0fc-c5ec-11e7-8aec-011d0988acd3
631 d-stor_uuid: 7f1ff108-c5ec-11e7-8aec-011d0988acd3
634 Lines starting with a
637 The specifications which can be changed are:
640 is an optional label, set by the
642 option when writing a label.
643 .It Ar "the partition table"
646 partition table, not the
648 partition table described in
652 The partition table can have up to 16 entries.
653 It contains the following information:
654 .Bl -tag -width indent
656 The partition identifier is a single letter in the range
661 The size of the partition in sectors,
665 (megabytes - 1024*1024),
667 (gigabytes - 1024*1024*1024),
669 (terabytes - 1024*1024*1024*1024),
671 (percentage of free space
673 removing any fixed-size partitions),
675 (all remaining free space
677 fixed-size and percentage partitions).
678 Lowercase versions of
683 Size and type should be specified without any spaces between them.
685 Example: 2097152, 1G, 1024M and 1048576K are all the same size
686 (assuming 512-byte sectors).
688 The offset of the start of the partition from the beginning of the
693 calculate the correct offset to use (the end of the previous partition plus
696 The name of the filesystem type for the partition (case insensitive).
699 file systems, use type
703 file systems, use type
707 file systems, use type
713 For Vinum drives, use type
715 Other common types are
722 also knows about a number of other partition types,
723 none of which are in current use.
731 The remainder of the line is a comment and shows the size of
734 .Dl "disklabel64 da0s1"
736 Display the in-core label for the first slice of the
738 disk, as obtained via
741 .Dq dangerously-dedicated ,
742 the compatibility slice name should be specified, such as
745 .Dl "disklabel64 da0s1 > savedlabel"
747 Save the in-core label for
751 This file can be used with the
753 option to restore the label at a later date.
755 .Dl "disklabel64 -e -r da0s1"
757 Read the on-disk label for
759 edit it, and reinstall in-core as well as on-disk.
760 Existing bootstrap code is unaffected.
762 .Dl "disklabel64 -e -r -n da0s1"
764 Read the on-disk label for
766 edit it, and display what the new label would be.
769 install the new label either in-core or on-disk.
771 .Dl "disklabel64 -r -w da0s1"
773 Try to auto-detect the required information from
775 and write a new label to the disk.
778 command to edit the partitioning information.
780 .Dl "disklabel64 -R da0s1 savedlabel"
782 Restore the on-disk and in-core label for
786 Existing bootstrap code is unaffected.
788 .Dl "disklabel64 -R -n da0s1 label_layout"
790 Display what the label would be for
792 using the partition layout in
794 This is useful for determining how much space would be allotted for various
795 partitions with a labelling scheme using
801 .Dl "disklabel64 -B da0s1"
803 Install a new bootstrap on
805 The boot code comes from
809 On-disk and in-core labels are unchanged.
811 .Dl "disklabel64 -w -B /dev/da0s1 -b newboot1 -s newboot2"
813 Install a new label and bootstrap, with bootstrap code comes from the files
818 .Dl "dd if=/dev/zero of=/dev/da0 bs=512 count=32"
820 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
821 .Dl "disklabel64 -w -B da0s1"
822 .Dl "disklabel64 -e da0s1"
824 Completely wipe any prior information on the disk, creating a new bootable
825 disk with a DOS partition table containing one
829 initialize the slice, then edit it to your needs.
832 commands are optional, but may be necessary for some BIOSes to properly
835 .Dl "disklabel64 -W da0s1"
836 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
837 .Dl "disklabel32 -r -w da0s1"
838 .Dl "disklabel32 -N da0s1"
840 Completely wipe any prior information on the slice,
841 and install the old 32-bit label.
842 The wiping is needed because both
847 won't do any operations if label with other format is already installed.
849 This is an example disklabel that uses some of the new partition size types
854 which could be used as a source file for:
856 .Dl "disklabel64 -R ad0s1 new_label_file"
857 .Bd -literal -offset 4n
860 # Calculated informational fields for the slice:
862 # boot space: 1012224 bytes
863 # data space: 156286976 blocks # 152624.00 MB (160037863424 bytes)
865 # NOTE: The partition data base and stop are physically
866 # aligned instead of slice-relative aligned.
868 # All byte equivalent offsets must be aligned.
870 diskid: 5dc53a64-c5e5-11e7-8aec-011d0988acd3
872 boot2 data base: 0x000000001000
873 partitions data base: 0x0000000f8200
874 partitions data stop: 0x0025430f8200
875 backup label: 0x002543157200
876 total size: 0x002543158200 # 152625.34 MB
878 display block size: 1024 # for partition display and edit only
881 # size offset fstype fsuuid
894 The kernel device drivers will not allow the size of a disk partition
895 to be decreased or the offset of a partition to be changed while it is open.
896 Some device drivers create a label containing only a single large partition
897 if a disk is unlabeled; thus, the label must be written to the
899 partition of the disk while it is open.
900 This sometimes requires the desired
901 label to be set in two steps, the first one creating at least one other
902 partition, and the second setting the label on the new partition while
920 .Xr newfs_hammer2 8 ,
926 does not perform all possible error checking.
930 overlap; if an absolute offset does not match the expected offset; if a
931 partition runs past the end of the device; and a number of other errors; but
932 no warning is given if space remains unused.
936 support is not implemented.
projects / dragonfly.git / blob