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 32 bit disk pack label
48 .Ar disk Ar disktype Ns / Ns Cm auto
71 .Oo Ar disktype Ns / Ns Cm auto Oc
80 .Ar disk Ar disktype Ns / Ns Cm auto
91 .Oo Ar disktype Ns / Ns Cm auto Oc
93 .Fl f Ar slice_start_lba
99 installs, examines or modifies a 32 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
192 .Ar disk Ar disktype Ns / Ns Cm auto
195 The required arguments to
197 are the drive to be labeled and the drive type as described in the
200 The drive parameters and partitions are taken from that file.
202 different disks of the same physical type are to have different partitions, it
203 will be necessary to have separate disktab entries describing each, or to edit
204 the label after installation as described below.
205 The optional argument is a
206 pack identification string, up to 16 characters long.
208 quoted if it contains blanks.
212 flag is given, no data will be written to the device, and instead the
213 disklabel that would have been written will be printed to stdout.
217 flag is given, the disk sectors containing the label and bootstrap
218 will be written directly.
219 A side-effect of this is that any existing bootstrap code will be overwritten
220 and the disk rendered unbootable.
221 See the boot options below for a method of
222 writing the label and the bootstrap at the same time.
226 the existing label will be updated via the in-core copy and any bootstrap
227 code will be unaffected.
228 If the disk does not already have a label, the
231 In either case, the kernel's in-core label is replaced.
233 For a virgin disk that is not known to
238 In this case, the driver is requested to produce a virgin label for the
240 This might or might not be successful, depending on whether the
241 driver for the disk is able to get the required data without reading
242 anything from the disk at all.
243 It will likely succeed for all SCSI
244 disks, most IDE disks, and vnode devices.
245 Writing a label to the
246 disk is the only supported operation, and the
248 itself must be provided as the canonical name, i.e.\& not as a full
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
364 If you are creating a
365 .Dq dangerously-dedicated
366 slice for compatibility with older PC systems,
367 you generally want to specify the compatibility slice, such as
369 If you are creating a label within an existing DOS slice,
371 the slice name such as
373 Making a slice bootable can be tricky.
374 If you are using a normal DOS
375 slice you typically install (or leave) a standard MBR on the base disk and
378 bootblocks in the slice.
387 .Oo Ar disktype Ns / Ns Cm auto Oc
389 This form installs the bootstrap only.
390 It does not change the disk label.
391 You should never use this command on the compatibility slice unless you
393 .Dq dangerously-dedicated
396 This command is typically run on a
409 .Ar disk Ar disktype Ns / Ns Cm auto
412 This form corresponds to the
414 command described above.
415 In addition to writing a new volume label, it also installs the bootstrap.
416 If run on the compatibility slice this command will create a
417 .Dq dangerously-dedicated
419 This command is normally run on a
421 slice rather than the compatibility slice.
424 is used, no data will be written to the device, and instead the
425 disklabel that would have been written will be printed to stdout.
435 .Ar disk Ar protofile
436 .Oo Ar disktype Ns / Ns Cm auto Oc
438 This form corresponds to the
440 command described above.
441 In addition to restoring the volume label, it also installs the bootstrap.
442 If run on the compatibility slice this command will create a
443 .Dq dangerously-dedicated
445 This command is normally run on a
447 slice rather than the compatibility
450 The bootstrap commands always access the disk directly,
451 so it is not necessary to specify the
456 is used, no data will be written to the device, and instead the
457 disklabel that would have been written will be printed to stdout.
459 The bootstrap code is comprised of two boot programs.
460 Specify the name of the
461 boot programs to be installed in one of these ways:
464 Specify the names explicitly with the
470 indicates the primary boot program and
472 the secondary boot program.
473 The boot programs are normally located in
480 flags are not specified, but
482 was specified, the names of the programs are taken from the
488 entry for the disk if the disktab entry exists and includes those parameters.
490 Otherwise, the default boot image names are used:
494 for the standard stage1 and stage2 boot images.
496 .Ss Initializing/Formatting a bootable disk from scratch
497 To initialize a disk from scratch the following sequence is recommended.
498 Please note that this will wipe everything that was previously on the disk,
508 to initialize the hard disk, and create a GPT or MBR slice table,
510 .Dq "partition table"
518 to define partitions on
520 slices created in the previous step.
526 to create file systems on new partitions.
529 A typical partitioning scheme would be to have an
532 of approximately 512MB to hold the root file system, a
535 swap (usually 4GB), a
547 (usually around 4GB),
552 (usually all remaining space).
553 If you are tight on space all sizes can be halved.
554 Your mileage may vary.
557 .Dl "disklabel32 -w -B da0s1 auto"
558 .Dl "disklabel32 -e da0s1"
561 no longer snoop-adjusts the on-disk label when reading or writing
564 is now responsible for adjusting the label when operating in raw mode.
567 disklabels store offsets as absolute block numbers
568 rather than slice-relative block numbers.
571 is unable to issue the
573 ioctl to get slice information it will
574 refuse to read or write the label in raw mode.
577 option may be used to force the operation by supplying a manual offset.
579 .Bl -tag -width ".Pa /etc/disktab" -compact
581 Default stage1 boot image.
583 Default stage2 boot image.
585 Disk description file.
587 .Sh SAVED FILE FORMAT
592 version of the label when examining, editing, or restoring a disk label.
594 .Bd -literal -offset 4n
603 sectors/cylinder: 1512
605 sectors/unit: 243581184
610 headswitch: 0 # milliseconds
611 track-to-track seek: 0 # milliseconds
616 a: 1048560 16 4.2BSD # 511.992MB
617 b: 8388608 1048576 swap # 4096.000MB
618 c: 243581184 0 unused # 118936.125MB
619 d: 4194304 9437184 4.2BSD # 2048.000MB
620 e: 4194304 13631488 4.2BSD # 2048.000MB
621 f: 8388608 17825792 4.2BSD # 4096.000MB
622 h: 196395264 26214400 HAMMER # 95896.125MB
623 i: 10485760 222609664 ccd # 5120.000MB
624 j: 10485760 233095424 vinum # 5120.000MB
627 Lines starting with a
630 Most of the other specifications are no longer used.
631 The ones which must still be set correctly are:
634 is an optional label, set by the
636 option when writing a label.
643 is set for removable media drives, but no current
645 driver evaluates this
648 is no longer supported;
650 specifies that the drive can perform bad sector remapping.
652 describes the total size of the disk.
653 This value must be correct.
654 .It Ar "the partition table"
657 partition table, not the
659 partition table described in
663 The partition table can have up to 16 entries.
664 It contains the following information:
665 .Bl -tag -width indent
667 The partition identifier is a single letter in the range
671 By convention, partition
673 is reserved to describe the entire disk.
675 The size of the partition in sectors,
679 (megabytes - 1024*1024),
681 (gigabytes - 1024*1024*1024),
683 (gigabytes - 1024*1024*1024*1024),
685 (percentage of free space
687 removing any fixed-size partitions other than partition
691 (all remaining free space
693 fixed-size and percentage partitions).
698 indicates the entire disk.
699 Lowercase versions of
704 Size and type should be specified without any spaces between them.
706 Example: 2097152, 1G, 1024M and 1048576K are all the same size
707 (assuming 512-byte sectors).
709 The offset of the start of the partition from the beginning of the
714 calculate the correct offset to use (the end of the previous partition plus
715 one, ignoring partition
720 will be interpreted as an offset of 0.
722 Describes the purpose of the partition.
723 The example shows all currently used partition types.
726 file systems, use type
730 file systems, use type
736 For Vinum drives, use type
738 Other common types are
742 By convention, partition
744 represents the entire slice and should be of type
748 does not enforce this convention.
752 also knows about a number of other partition types,
753 none of which are in current use.
761 The remainder of the line is a comment and shows the size of
764 .Dl "disklabel32 da0s1"
766 Display the in-core label for the first slice of the
768 disk, as obtained via
771 .Dq dangerously-dedicated ,
772 the compatibility slice name should be specified, such as
775 .Dl "disklabel32 da0s1 > savedlabel"
777 Save the in-core label for
781 This file can be used with the
783 option to restore the label at a later date.
785 .Dl "disklabel32 -w -r /dev/da0s1 da2212 foo"
789 based on information for
793 Any existing bootstrap code will be clobbered
794 and the disk rendered unbootable.
796 .Dl "disklabel32 -e -r da0s1"
798 Read the on-disk label for
800 edit it, and reinstall in-core as well as on-disk.
801 Existing bootstrap code is unaffected.
803 .Dl "disklabel32 -e -r -n da0s1"
805 Read the on-disk label for
807 edit it, and display what the new label would be (in sectors).
810 install the new label either in-core or on-disk.
812 .Dl "disklabel32 -r -w da0s1 auto"
814 Try to auto-detect the required information from
816 and write a new label to the disk.
820 partitioning and file system information.
822 .Dl "disklabel32 -R da0s1 savedlabel"
824 Restore the on-disk and in-core label for
828 Existing bootstrap code is unaffected.
830 .Dl "disklabel32 -R -n da0s1 label_layout"
832 Display what the label would be for
834 using the partition layout in
836 This is useful for determining how much space would be allotted for various
837 partitions with a labelling scheme using
843 .Dl "disklabel32 -B da0s1"
845 Install a new bootstrap on
847 The boot code comes from
851 On-disk and in-core labels are unchanged.
853 .Dl "disklabel32 -w -B /dev/da0s1 -b newboot1 -s newboot2 da2212"
855 Install a new label and bootstrap.
856 The label is derived from disktab information for
858 and installed both in-core and on-disk.
859 The bootstrap code comes from the files
864 .Dl "dd if=/dev/zero of=/dev/da0 bs=512 count=32"
866 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
867 .Dl "disklabel32 -w -B da0s1 auto"
868 .Dl "disklabel32 -e da0s1"
870 Completely wipe any prior information on the disk, creating a new bootable
871 disk with a DOS partition table containing one
875 initialize the slice, then edit it to your needs.
878 commands are optional, but may be necessary for some BIOSes to properly
881 .Dl "disklabel32 -W da0s1"
882 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
883 .Dl "disklabel64 -r -w da0s1 auto"
884 .Dl "disklabel64 -N da0s1"
886 Completely wipe any prior information on the slice,
887 changing label format to 64 bit.
888 The wiping is needed as
893 won't do any operations if label with other format is already installed.
895 This is an example disklabel that uses some of the new partition size types
900 which could be used as a source file for
902 .Dl "disklabel32 -R ad0s1 new_label_file"
903 .Bd -literal -offset 4n
912 sectors/cylinder: 1008
914 sectors/unit: 40959009
919 headswitch: 0 # milliseconds
920 track-to-track seek: 0 # milliseconds
933 The kernel device drivers will not allow the size of a disk partition
934 to be decreased or the offset of a partition to be changed while it is open.
935 Some device drivers create a label containing only a single large partition
936 if a disk is unlabeled; thus, the label must be written to the
938 partition of the disk while it is open.
939 This sometimes requires the desired
940 label to be set in two steps, the first one creating at least one other
941 partition, and the second setting the label on the new partition while
946 On some machines the bootstrap code may not fit entirely in the area
947 allocated for it by some file systems.
948 As a result, it may not be possible to have file systems on some partitions
952 When installing bootstrap code,
954 checks for these cases.
955 If the installed boot code would overlap a partition of type
961 utility will disallow creation of file systems on
964 Conversely, if a partition has a type other than
969 will not install bootstrap code that overlaps it.
973 storing sector numbers in 32 bit format
975 is restricted to 2TB, using the prevalent sector size of 512B.
977 labels should be used to partition larger disks.
981 use slightly different versions of
984 and are not generally compatible.
987 kernel can often use labels from other
989 for read-only operation.
1001 .Xr newfs_hammer 8 ,
1007 does not perform all possible error checking.
1011 overlap; if an absolute offset does not match the expected offset; if the
1013 partition does not start at 0 or does not cover the entire slice; if a
1014 partition runs past the end of the device; and a number of other errors; but
1015 no warning is given if space remains unused.