36a20ed7427e03317d800abf61ed320b77ef6dbc
[dragonfly.git] / sbin / disklabel / disklabel.8
1 .\" Copyright (c) 1987, 1988, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Symmetric Computer Systems.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
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. All advertising materials mentioning features or use of this software
16 .\"    must display the following acknowledgment:
17 .\"     This product includes software developed by the University of
18 .\"     California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\"    may be used to endorse or promote products derived from this software
21 .\"    without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\"     @(#)disklabel.8 8.2 (Berkeley) 4/19/94
36 .\" $FreeBSD: src/sbin/disklabel/disklabel.8,v 1.15.2.22 2003/04/17 17:56:34 trhodes Exp $
37 .\" $DragonFly: src/sbin/disklabel/disklabel.8,v 1.30 2008/09/16 20:45:36 thomas Exp $
38 .\"
39 .Dd September 28, 2009
40 .Dt DISKLABEL 8
41 .Os
42 .Sh NAME
43 .Nm disklabel
44 .Nd read and write 32 bit disk pack label
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl r
48 .Ar disk
49 .Nm
50 .Fl w
51 .Op Fl r
52 .Op Fl n
53 .Ar disk Ar disktype Ns / Ns Cm auto
54 .Oo Ar packid Oc
55 .Nm
56 .Fl e
57 .Op Fl r
58 .Op Fl n
59 .Ar disk
60 .Nm
61 .Fl R
62 .Op Fl r
63 .Op Fl n
64 .Ar disk Ar protofile
65 .Nm
66 .Op Fl NW
67 .Ar disk
68 .Pp
69 .Nm
70 .Fl B
71 .Oo
72 .Fl b Ar boot1
73 .Fl s Ar boot2
74 .Oc
75 .Ar disk
76 .Oo Ar disktype Ns / Ns Cm auto Oc
77 .Nm
78 .Fl w
79 .Fl B
80 .Op Fl n
81 .Oo
82 .Fl b Ar boot1
83 .Fl s Ar boot2
84 .Oc
85 .Ar disk Ar disktype Ns / Ns Cm auto
86 .Oo Ar packid Oc
87 .Nm
88 .Fl R
89 .Fl B
90 .Op Fl n
91 .Oo
92 .Fl b Ar boot1
93 .Fl s Ar boot2
94 .Oc
95 .Ar disk Ar protofile
96 .Oo Ar disktype Ns / Ns Cm auto Oc
97 .Nm
98 .Fl f Ar slice_start_lba
99 .Oo Ar options Oc
100 .Sh DESCRIPTION
101 The
102 .Nm
103 utility
104 installs, examines or modifies a 32 bit label on a disk drive or pack.
105 When writing
106 the label, it can be used to change the drive identification, the disk
107 partitions on the drive, or to replace a damaged label.
108 There are several forms
109 of the command that read (display), install or edit the label on a disk.
110 In
111 addition,
112 .Nm
113 can install bootstrap code.
114 .Ss Raw or in-core label
115 The disk label resides close to or at the beginning of each disk slice.
116 For faster access, the kernel maintains a copy in core at all times.
117 By
118 default, most forms of the
119 .Nm
120 command access the in-core copy of the label.
121 To access the raw (on-disk)
122 copy, use the
123 .Fl r
124 option.
125 This option allows a label to be installed on a disk without kernel
126 support for a label, such as when labels are first installed on a system; it
127 must be used when first installing a label on a disk.
128 The specific effect of
129 .Fl r
130 is described under each command.
131 .Ss Disk device name
132 All
133 .Nm
134 forms require a disk device name, which should always be the raw
135 device name representing the disk or slice.
136 .Dx
137 uses the following scheme for slice numbering:
138 If the disk doesn't use GPT (typically laid out by
139 .Xr gpt 8 ) ,
140 but e.g.\& MBR (typically laid out by
141 .Xr fdisk 8 ) ,
142 then slice 0, e.g.\&
143 .Pa da0s0 ,
144 represents the entire disk regardless of any DOS partitioning.
145 Slice 0 is called the compatibility slice,
146 and slice 1 and onward, e.g.\&
147 .Pa da0s1 ,
148 represents a
149 .Bx
150 slice.
151 If the disk does use GPT, then all slices are
152 .Bx
153 slices, slice 0 isn't special, it is just the first slice on the disk.
154 You do not have to include the
155 .Pa /dev/
156 path prefix when specifying the device.
157 The
158 .Nm
159 utility will automatically prepend it.
160 .Ss Reading the disk label
161 To examine the label on a disk drive, use
162 .Nm
163 without options:
164 .Pp
165 .Nm
166 .Op Fl r
167 .Ar disk
168 .Pp
169 .Ar disk
170 represents the raw disk in question, and may be in the form
171 .Pa da0s1
172 or
173 .Pa /dev/da0s1 .
174 It will display all of the parameters associated with the drive and its
175 partition layout.
176 Unless the
177 .Fl r
178 flag is given,
179 the kernel's in-core copy of the label is displayed;
180 if the disk has no label, or the partition types on the disk are incorrect,
181 the kernel may have constructed or modified the label.
182 If the
183 .Fl r
184 flag is given,
185 .Nm
186 reads the label from the raw disk and displays it.
187 Both versions are usually
188 identical except in the case where a label has not yet been initialized or
189 is corrupt.
190 .Ss Writing a standard label
191 To write a standard label, use the form
192 .Pp
193 .Nm
194 .Fl w
195 .Op Fl r
196 .Op Fl n
197 .Ar disk Ar disktype Ns / Ns Cm auto
198 .Oo Ar packid Oc
199 .Pp
200 The required arguments to
201 .Nm
202 are the drive to be labeled and the drive type as described in the
203 .Xr disktab 5
204 file.
205 The drive parameters and partitions are taken from that file.
206 If
207 different disks of the same physical type are to have different partitions, it
208 will be necessary to have separate disktab entries describing each, or to edit
209 the label after installation as described below.
210 The optional argument is a
211 pack identification string, up to 16 characters long.
212 The pack id must be
213 quoted if it contains blanks.
214 .Pp
215 If the
216 .Fl n
217 flag is given, no data will be written to the device, and instead the
218 disklabel that would have been written will be printed to stdout.
219 .Pp
220 If the
221 .Fl r
222 flag is given, the disk sectors containing the label and bootstrap
223 will be written directly.
224 A side-effect of this is that any existing bootstrap code will be overwritten
225 and the disk rendered unbootable.
226 See the boot options below for a method of
227 writing the label and the bootstrap at the same time.
228 If
229 .Fl r
230 is not specified,
231 the existing label will be updated via the in-core copy and any bootstrap
232 code will be unaffected.
233 If the disk does not already have a label, the
234 .Fl r
235 flag must be used.
236 In either case, the kernel's in-core label is replaced.
237 .Pp
238 For a virgin disk that is not known to
239 .Xr disktab 5 ,
240 .Ar disktype
241 can be specified as
242 .Cm auto .
243 In this case, the driver is requested to produce a virgin label for the
244 disk.
245 This might or might not be successful, depending on whether the
246 driver for the disk is able to get the required data without reading
247 anything from the disk at all.
248 It will likely succeed for all SCSI
249 disks, most IDE disks, and vnode devices.
250 Writing a label to the
251 disk is the only supported operation, and the
252 .Ar disk
253 itself must be provided as the canonical name, i.e.\& not as a full
254 path name.
255 .Pp
256 For most harddisks, a label based on percentages for most partitions (and
257 one partition with a size of
258 .Ql * )
259 will produce a reasonable configuration.
260 .Pp
261 PC-based systems have special requirements in order for the BIOS to properly
262 recognize a
263 .Dx
264 disklabel.
265 Older systems may require what is known as a
266 .Dq dangerously dedicated
267 disklabel, which creates a fake DOS partition to work around problems older
268 BIOSes have with modern disk geometries.
269 On newer systems you generally want
270 to create a normal DOS partition using
271 .Ar fdisk
272 and then create a
273 .Dx
274 disklabel within that slice.
275 This is described
276 later on in this page.
277 .Pp
278 Installing a new disklabel does not in of itself allow your system to boot
279 a kernel using that label.
280 You must also install boot blocks, which is
281 described later on in this manual page.
282 .Ss Editing an existing disk label
283 To edit an existing disk label, use the form
284 .Pp
285 .Nm
286 .Fl e
287 .Op Fl r
288 .Op Fl n
289 .Ar disk
290 .Pp
291 This command reads the label from the in-core kernel copy, or directly from the
292 disk if the
293 .Fl r
294 flag is also specified.
295 The label is written to a file in ASCII and then
296 supplied to an editor for changes.
297 If no editor is specified in an
298 .Ev EDITOR
299 environment variable,
300 .Xr vi 1
301 is used.
302 When the editor terminates, the label file is used to rewrite the disk label.
303 Existing bootstrap code is unchanged regardless of whether
304 .Fl r
305 was specified.
306 If
307 .Fl n
308 is specified, no data will be written to the device, and instead the
309 disklabel that would have been written will be printed to stdout.
310 This is
311 useful to see how a partitioning scheme will work out for a specific disk.
312 .Ss Restoring a disk label from a file
313 To restore a disk label from a file, use the form
314 .Pp
315 .Nm
316 .Fl R
317 .Op Fl r
318 .Op Fl n
319 .Ar disk Ar protofile
320 .Pp
321 .Nm
322 is capable of restoring a disk label that was previously saved in a file
323 in ASCII format.
324 The prototype file used to create the label should be in the same format
325 as that produced when reading or editing a label.
326 Comments are delimited by
327 .Ql #
328 and newline.
329 As when writing a new label, any existing bootstrap code will be
330 clobbered if
331 .Fl r
332 is specified and will be unaffected otherwise.
333 See the boot options below for a
334 method of restoring the label and writing the bootstrap at the same time.
335 If
336 .Fl n
337 is used, no data will be written to the device, and instead the
338 disklabel that would have been written will be printed to stdout.
339 This is
340 useful to see how a partitioning scheme will work out for a specific disk.
341 .Ss Enabling and disabling writing to the disk label area
342 By default, it is not possible to write to the disk label area at the beginning
343 of a disk.
344 The disk driver arranges for
345 .Xr write 2
346 and similar system calls
347 to return
348 .Er EROFS
349 on any attempt to do so.
350 If you need
351 to write to this area (for example, to obliterate the label), use the form
352 .Pp
353 .Nm
354 .Fl W
355 .Ar disk
356 .Pp
357 To disallow writing to the label area after previously allowing it,
358 use the command
359 .Pp
360 .Nm
361 .Fl N
362 .Ar disk
363 .Ss Installing bootstraps
364 The final three forms of
365 .Nm
366 are used to install bootstrap code, which allows boot from a
367 .Xr UFS 5
368 file system.
369 If you are creating a
370 .Dq dangerously-dedicated
371 slice for compatibility with older PC systems,
372 you generally want to specify the compatibility slice, such as
373 .Pa da0s0 .
374 If you are creating a label within an existing DOS slice,
375 you should specify
376 the slice name such as
377 .Pa da0s1 .
378 Making a slice bootable can be tricky.
379 If you are using a normal DOS
380 slice you typically install (or leave) a standard MBR on the base disk and
381 then install the
382 .Dx
383 bootblocks in the slice.
384 .Pp
385 .Nm
386 .Fl B
387 .Oo
388 .Fl b Ar boot1
389 .Fl s Ar boot2
390 .Oc
391 .Ar disk
392 .Oo Ar disktype Ns / Ns Cm auto Oc
393 .Pp
394 This form installs the bootstrap only.
395 It does not change the disk label.
396 You should never use this command on the compatibility slice unless you
397 intend to create a
398 .Dq dangerously-dedicated
399 disk, such as
400 .Ar da0s0 .
401 This command is typically run on a
402 .Bx
403 slice such as
404 .Ar da0s1 .
405 .Pp
406 .Nm
407 .Fl w
408 .Fl B
409 .Op Fl n
410 .Oo
411 .Fl b Ar boot1
412 .Fl s Ar boot2
413 .Oc
414 .Ar disk Ar disktype Ns / Ns Cm auto
415 .Oo Ar packid Oc
416 .Pp
417 This form corresponds to the
418 .Dq write label
419 command described above.
420 In addition to writing a new volume label, it also installs the bootstrap.
421 If run on the compatibility slice this command will create a
422 .Dq dangerously-dedicated
423 label.
424 This command is normally run on a
425 .Bx
426 slice rather than the compatibility slice.
427 If
428 .Fl n
429 is used, no data will be written to the device, and instead the
430 disklabel that would have been written will be printed to stdout.
431 .Pp
432 .Nm
433 .Fl R
434 .Fl B
435 .Op Fl n
436 .Oo
437 .Fl b Ar boot1
438 .Fl s Ar boot2
439 .Oc
440 .Ar disk Ar protofile
441 .Oo Ar disktype Ns / Ns Cm auto Oc
442 .Pp
443 This form corresponds to the
444 .Dq restore label
445 command described above.
446 In addition to restoring the volume label, it also installs the bootstrap.
447 If run on the compatibility slice this command will create a
448 .Dq dangerously-dedicated
449 label.
450 This command is normally run on a
451 .Bx
452 slice rather than the compatibility
453 slice.
454 .Pp
455 The bootstrap commands always access the disk directly,
456 so it is not necessary to specify the
457 .Fl r
458 flag.
459 If
460 .Fl n
461 is used, no data will be written to the device, and instead the
462 disklabel that would have been written will be printed to stdout.
463 .Pp
464 The bootstrap code is comprised of two boot programs.
465 Specify the name of the
466 boot programs to be installed in one of these ways:
467 .Bl -enum
468 .It
469 Specify the names explicitly with the
470 .Fl b
471 and
472 .Fl s
473 flags.
474 .Fl b
475 indicates the primary boot program and
476 .Fl s
477 the secondary boot program.
478 The boot programs are normally located in
479 .Pa /boot .
480 .It
481 If the
482 .Fl b
483 and
484 .Fl s
485 flags are not specified, but
486 .Ar disktype
487 was specified, the names of the programs are taken from the
488 .Dq b0
489 and
490 .Dq b1
491 parameters of the
492 .Xr disktab 5
493 entry for the disk if the disktab entry exists and includes those parameters.
494 .It
495 Otherwise, the default boot image names are used:
496 .Pa /boot/boot1
497 and
498 .Pa /boot/boot2
499 for the standard stage1 and stage2 boot images.
500 .El
501 .Ss Initializing/Formatting a bootable disk from scratch
502 To initialize a disk from scratch the following sequence is recommended.
503 Please note that this will wipe everything that was previously on the disk,
504 including any
505 .No non- Ns Dx
506 slices.
507 .Bl -enum
508 .It
509 Use
510 .Xr gpt 8
511 or
512 .Xr fdisk 8
513 to initialize the hard disk, and create a GPT or MBR slice table,
514 referred to as the
515 .Dq "partition table"
516 in
517 .Tn DOS .
518 .It
519 Use
520 .Nm
521 or
522 .Xr disklabel64 8
523 to define partitions on
524 .Dx
525 slices created in the previous step.
526 .It
527 Finally use
528 .Xr newfs_hammer 8
529 or
530 .Xr newfs 8
531 to create file systems on new partitions.
532 .El
533 .Pp
534 A typical partitioning scheme would be to have an
535 .Ql a
536 partition
537 of approximately 512MB to hold the root file system, a
538 .Ql b
539 partition for
540 swap (usually 4GB), a
541 .Ql d
542 partition for
543 .Pa /var
544 (usually 2GB), an
545 .Ql e
546 partition for
547 .Pa /var/tmp
548 (usually 2GB), an
549 .Ql f
550 partition for
551 .Pa /usr
552 (usually around 4GB),
553 and finally a
554 .Ql g
555 partition for
556 .Pa /home
557 (usually all remaining space).
558 If you are tight on space all sizes can be halved.
559 Your mileage may vary.
560 .Pp
561 .Dl "fdisk -BI da0"
562 .Dl "disklabel -w -B da0s1 auto"
563 .Dl "disklabel -e da0s1"
564 .Ss Manual offset
565 .Dx
566 no longer snoop-adjusts the on-disk label when reading or writing
567 raw labels.
568 .Nm
569 is now responsible for adjusting the label when operating in raw mode.
570 Traditional (32 bit
571 .Bx )
572 disklabels store offsets as absolute block numbers
573 rather than slice-relative block numbers.
574 If
575 .Nm
576 is unable to issue the
577 .Dv DIOCGPART
578 ioctl to get slice information it will
579 refuse to read or write the label in raw mode.
580 The
581 .Fl f
582 option may be used to force the operation by supplying a manual offset.
583 .Sh FILES
584 .Bl -tag -width ".Pa /etc/disktab" -compact
585 .It Pa /boot/boot1
586 Default stage1 boot image.
587 .It Pa /boot/boot2
588 Default stage2 boot image.
589 .It Pa /etc/disktab
590 Disk description file.
591 .El
592 .Sh SAVED FILE FORMAT
593 The
594 .Nm
595 utility uses an
596 .Tn ASCII
597 version of the label when examining, editing, or restoring a disk label.
598 The format is:
599 .Bd -literal -offset 4n
600 # /dev/ad4s4:
601 type: unknown
602 disk: amnesiac
603 label: fictitious
604 flags:
605 bytes/sector: 512
606 sectors/track: 63
607 tracks/cylinder: 24
608 sectors/cylinder: 1512
609 cylinders: 161098
610 sectors/unit: 243581184
611 rpm: 3600
612 interleave: 1
613 trackskew: 0
614 cylinderskew: 0
615 headswitch: 0           # milliseconds
616 track-to-track seek: 0  # milliseconds
617 drivedata: 0
618
619 16 partitions:
620 #          size     offset    fstype
621   a:    1048560         16    4.2BSD    #     511.992MB
622   b:    8388608    1048576      swap    #    4096.000MB
623   c:  243581184          0    unused    #  118936.125MB
624   d:    4194304    9437184    4.2BSD    #    2048.000MB
625   e:    4194304   13631488    4.2BSD    #    2048.000MB
626   f:    8388608   17825792    4.2BSD    #    4096.000MB
627   h:  196395264   26214400    HAMMER    #   95896.125MB
628   i:   10485760  222609664       ccd    #    5120.000MB
629   j:   10485760  233095424     vinum    #    5120.000MB
630 .Ed
631 .Pp
632 Lines starting with a
633 .Ql #
634 mark are comments.
635 Most of the other specifications are no longer used.
636 The ones which must still be set correctly are:
637 .Bl -inset
638 .It Ar label
639 is an optional label, set by the
640 .Ar packid
641 option when writing a label.
642 .It Ar flags
643 may be
644 .Cm removable , ecc
645 or
646 .Cm badsect .
647 .Cm removable
648 is set for removable media drives, but no current
649 .Dx
650 driver evaluates this
651 flag.
652 .Cm ecc
653 is no longer supported;
654 .Cm badsect
655 specifies that the drive can perform bad sector remapping.
656 .It Ar sectors/unit
657 describes the total size of the disk.
658 This value must be correct.
659 .It Ar "the partition table"
660 is the
661 .Ux
662 partition table, not the
663 .Tn DOS
664 partition table described in
665 .Xr fdisk 8 .
666 .El
667 .Pp
668 The partition table can have up to 16 entries.
669 It contains the following information:
670 .Bl -tag -width indent
671 .It Ar #
672 The partition identifier is a single letter in the range
673 .Ql a
674 to
675 .Ql p .
676 By convention, partition
677 .Ql c
678 is reserved to describe the entire disk.
679 .It Ar size
680 The size of the partition in sectors,
681 .Cm K
682 (kilobytes - 1024),
683 .Cm M
684 (megabytes - 1024*1024),
685 .Cm G
686 (gigabytes - 1024*1024*1024),
687 .Cm %
688 (percentage of free space
689 .Em after
690 removing any fixed-size partitions other than partition
691 .Ql c ) ,
692 or
693 .Cm *
694 (all remaining free space
695 .Em after
696 fixed-size and percentage partitions).
697 For partition
698 .Ql c ,
699 a size of
700 .Cm *
701 indicates the entire disk.
702 Lowercase versions of
703 .Cm K , M ,
704 and
705 .Cm G
706 are allowed.
707 Size and type should be specified without any spaces between them.
708 .Pp
709 Example: 2097152, 1G, 1024M and 1048576K are all the same size
710 (assuming 512-byte sectors).
711 .It Ar offset
712 The offset of the start of the partition from the beginning of the
713 drive in sectors, or
714 .Cm *
715 to have
716 .Nm
717 calculate the correct offset to use (the end of the previous partition plus
718 one, ignoring partition
719 .Ql c .
720 For partition
721 .Ql c ,
722 .Cm *
723 will be interpreted as an offset of 0.
724 .It Ar fstype
725 Describes the purpose of the partition.
726 The example shows all currently used partition types.
727 For
728 .Xr UFS 5
729 file systems, use type
730 .Cm 4.2BSD .
731 For
732 .Xr HAMMER 5
733 file systems, use type
734 .Cm HAMMER .
735 For
736 .Xr ccd 4
737 partitions, use type
738 .Cm ccd .
739 For Vinum drives, use type
740 .Cm vinum .
741 Other common types are
742 .Cm swap
743 and
744 .Cm unused .
745 By convention, partition
746 .Ql c
747 represents the entire slice and should be of type
748 .Cm unused ,
749 though
750 .Nm
751 does not enforce this convention.
752 The
753 .Nm
754 utility
755 also knows about a number of other partition types,
756 none of which are in current use.
757 (See
758 .Dv fstypenames
759 in
760 .In sys/dtype.h
761 for more details).
762 .El
763 .Pp
764 The remainder of the line is a comment and shows the size of
765 the partition in MB.
766 .Sh EXAMPLES
767 .Dl "disklabel da0s1"
768 .Pp
769 Display the in-core label for the first slice of the
770 .Pa da0
771 disk, as obtained via
772 .Pa /dev/da0s1 .
773 (If the disk is
774 .Dq dangerously-dedicated ,
775 the compatibility slice name should be specified, such as
776 .Pa da0s0 . )
777 .Pp
778 .Dl "disklabel da0s1 > savedlabel"
779 .Pp
780 Save the in-core label for
781 .Pa da0s1
782 into the file
783 .Pa savedlabel .
784 This file can be used with the
785 .Fl R
786 option to restore the label at a later date.
787 .Pp
788 .Dl "disklabel -w -r /dev/da0s1 da2212 foo"
789 .Pp
790 Create a label for
791 .Pa da0s1
792 based on information for
793 .Dq da2212
794 found in
795 .Pa /etc/disktab .
796 Any existing bootstrap code will be clobbered
797 and the disk rendered unbootable.
798 .Pp
799 .Dl "disklabel -e -r da0s1"
800 .Pp
801 Read the on-disk label for
802 .Pa da0s1 ,
803 edit it, and reinstall in-core as well as on-disk.
804 Existing bootstrap code is unaffected.
805 .Pp
806 .Dl "disklabel -e -r -n da0s1"
807 .Pp
808 Read the on-disk label for
809 .Pa da0s1 ,
810 edit it, and display what the new label would be (in sectors).
811 It does
812 .Em not
813 install the new label either in-core or on-disk.
814 .Pp
815 .Dl "disklabel -r -w da0s1 auto"
816 .Pp
817 Try to auto-detect the required information from
818 .Pa da0s1 ,
819 and write a new label to the disk.
820 Use another
821 .Nm Fl e
822 command to edit the
823 partitioning and file system information.
824 .Pp
825 .Dl "disklabel -R da0s1 savedlabel"
826 .Pp
827 Restore the on-disk and in-core label for
828 .Pa da0s1
829 from information in
830 .Pa savedlabel .
831 Existing bootstrap code is unaffected.
832 .Pp
833 .Dl "disklabel -R -n da0s1 label_layout"
834 .Pp
835 Display what the label would be for
836 .Pa da0s1
837 using the partition layout in
838 .Pa label_layout .
839 This is useful for determining how much space would be allotted for various
840 partitions with a labelling scheme using
841 .Cm % Ns -based
842 or
843 .Cm *
844 partition sizes.
845 .Pp
846 .Dl "disklabel -B da0s1"
847 .Pp
848 Install a new bootstrap on
849 .Pa da0s1 .
850 The boot code comes from
851 .Pa /boot/boot1
852 and possibly
853 .Pa /boot/boot2 .
854 On-disk and in-core labels are unchanged.
855 .Pp
856 .Dl "disklabel -w -B /dev/da0s1 -b newboot1 -s newboot2 da2212"
857 .Pp
858 Install a new label and bootstrap.
859 The label is derived from disktab information for
860 .Dq da2212
861 and installed both in-core and on-disk.
862 The bootstrap code comes from the files
863 .Pa newboot1
864 and
865 .Pa newboot2 .
866 .Pp
867 .Dl "dd if=/dev/zero of=/dev/da0 bs=512 count=32"
868 .Dl "fdisk -BI da0"
869 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
870 .Dl "disklabel -w -B da0s1 auto"
871 .Dl "disklabel -e da0s1"
872 .Pp
873 Completely wipe any prior information on the disk, creating a new bootable
874 disk with a DOS partition table containing one
875 .Dq whole-disk
876 slice.
877 Then
878 initialize the slice, then edit it to your needs.
879 The
880 .Pa dd
881 commands are optional, but may be necessary for some BIOSes to properly
882 recognize the disk.
883 .Pp
884 .Dl "disklabel -W da0s1"
885 .Dl "dd if=/dev/zero of=/dev/da0s1 bs=512 count=32"
886 .Dl "disklabel64 -r -w da0s1 auto"
887 .Dl "disklabel64 -N da0s1"
888 .Pp
889 Completely wipe any prior information on the slice,
890 changing label format to 64 bit.
891 The wiping is needed as
892 .Nm disklabel64
893 and
894 .Nm ,
895 as a safety measure,
896 won't do any operations if label with other format is already installed.
897 .Pp
898 This is an example disklabel that uses some of the new partition size types
899 such as
900 .Cm % , M , G ,
901 and
902 .Cm * ,
903 which could be used as a source file for
904 .Pp
905 .Dl "disklabel -R ad0s1 new_label_file"
906 .Bd -literal -offset 4n
907 # /dev/ad0s1:
908 type: ESDI
909 disk: ad0s1
910 label:
911 flags:
912 bytes/sector: 512
913 sectors/track: 63
914 tracks/cylinder: 16
915 sectors/cylinder: 1008
916 cylinders: 40633
917 sectors/unit: 40959009
918 rpm: 3600
919 interleave: 1
920 trackskew: 0
921 cylinderskew: 0
922 headswitch: 0           # milliseconds
923 track-to-track seek: 0  # milliseconds
924 drivedata: 0
925
926 16 partitions:
927 #          size     offset    fstype
928   a:       400M          0    4.2BSD
929   b:         1G          *      swap
930   c:          *          *    unused
931   e:     204800          *    4.2BSD
932   f:         5g          *    4.2BSD
933   g:          *          *    4.2BSD
934 .Ed
935 .Sh DIAGNOSTICS
936 The kernel device drivers will not allow the size of a disk partition
937 to be decreased or the offset of a partition to be changed while it is open.
938 Some device drivers create a label containing only a single large partition
939 if a disk is unlabeled; thus, the label must be written to the
940 .Ql a
941 partition of the disk while it is open.
942 This sometimes requires the desired
943 label to be set in two steps, the first one creating at least one other
944 partition, and the second setting the label on the new partition while
945 shrinking the
946 .Ql a
947 partition.
948 .Pp
949 On some machines the bootstrap code may not fit entirely in the area
950 allocated for it by some file systems.
951 As a result, it may not be possible to have file systems on some partitions
952 of a
953 .Dq bootable
954 disk.
955 When installing bootstrap code,
956 .Nm
957 checks for these cases.
958 If the installed boot code would overlap a partition of type
959 .Dv FS_UNUSED
960 it is marked as type
961 .Dv FS_BOOT .
962 The
963 .Xr newfs 8
964 utility will disallow creation of file systems on
965 .Dv FS_BOOT
966 partitions.
967 Conversely, if a partition has a type other than
968 .Dv FS_UNUSED
969 or
970 .Dv FS_BOOT ,
971 .Nm
972 will not install bootstrap code that overlaps it.
973 .Sh COMPATIBILITY
974 Due to
975 .Xr disklabel 5
976 storing sector numbers in 32 bit format
977 .Nm
978 is restricted to 2TB, using the prevalent sector size of 512B.
979 .Xr disklabel64 5
980 labels should be used to partition larger disks.
981 .Pp
982 The various
983 .Bx Ns s
984 use slightly different versions of
985 .Bx
986 disklabels
987 and are not generally compatible.
988 The
989 .Dx
990 kernel can often use labels from other
991 .Bx Ns s
992 for read-only operation.
993 .Sh SEE ALSO
994 .Xr dd 1 ,
995 .Xr ccd 4 ,
996 .Xr disklabel 5 ,
997 .Xr disktab 5 ,
998 .Xr boot0cfg 8 ,
999 .Xr diskinfo 8 ,
1000 .Xr disklabel64 8 ,
1001 .Xr fdisk 8 ,
1002 .Xr gpt 8 ,
1003 .Xr newfs 8 ,
1004 .Xr newfs_hammer 8 ,
1005 .Xr vinum 8
1006 .Sh BUGS
1007 For the i386 architecture, the primary bootstrap sector contains
1008 an embedded
1009 .Em fdisk
1010 table.
1011 The
1012 .Nm
1013 utility takes care to not clobber it when installing a bootstrap only
1014 .Pq Fl B ,
1015 or when editing an existing label
1016 .Pq Fl e ,
1017 but it unconditionally writes the primary bootstrap program onto
1018 the disk for
1019 .Fl w
1020 or
1021 .Fl R ,
1022 thus replacing the
1023 .Em fdisk
1024 table by the dummy one in the bootstrap program.
1025 This is only of
1026 concern if the disk is fully dedicated, so that the
1027 .Bx
1028 disklabel
1029 starts at absolute block 0 on the disk.
1030 .Pp
1031 The
1032 .Nm
1033 utility
1034 does not perform all possible error checking.
1035 Warning
1036 .Em is
1037 given if partitions
1038 overlap; if an absolute offset does not match the expected offset; if the
1039 .Ql c
1040 partition does not start at 0 or does not cover the entire slice; if a
1041 partition runs past the end of the device; and a number of other errors; but
1042 no warning is given if space remains unused.