xref: /freebsd/sbin/bsdlabel/bsdlabel.8 (revision e4e9813eb92cd7c4d4b819a8fbed5cbd3d92f5d8) 
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.\" 4. 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.
18.\"
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
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)disklabel.8	8.2 (Berkeley) 4/19/94
32.\" $FreeBSD$
33.\"
34.Dd September 17, 2005
35.Dt BSDLABEL 8
36.Os
37.Sh NAME
38.Nm bsdlabel
39.Nd read and write disk pack label
40.Sh SYNOPSIS
41.Nm
42.Op Fl A
43.Ar disk | Fl f Ar file
44.Nm
45.Fl w
46.Op Fl \&An
47.Op Fl B Op Fl b Ar boot
48.Op Fl m Ar machine
49.Ar disk | Fl f Ar file
50.Op Ar type
51.Nm
52.Fl e
53.Op Fl \&An
54.Op Fl B Op Fl b Ar boot
55.Op Fl m Ar machine
56.Ar disk | Fl f Ar file
57.Nm
58.Fl R
59.Op Fl \&An
60.Op Fl B Op Fl b Ar boot
61.Op Fl m Ar machine
62.Op Fl f
63.Ar disk | Fl f Ar file
64.Ar protofile
65.Sh DESCRIPTION
66The
67.Nm
68utility
69installs, examines or modifies the
70.Bx
71label on a disk partition, or on a file containing a partition image.
72In addition,
73.Nm
74can install bootstrap code.
75.Ss Disk Device Name
76When specifying the device (i.e., when the
77.Fl f
78option is not used),
79the
80.Pa /dev/
81path prefix may be omitted;
82the
83.Nm
84utility will automatically prepend it.
85.Ss General Options
86The
87.Fl A
88option enables processing of the historical parts of the
89.Bx
90label.
91If the option is not given, suitable values are set for these fields.
92.Pp
93The
94.Fl f
95option tells
96.Nm
97that the program will operate on a file instead of a disk partition.
98.Pp
99The
100.Fl n
101option stops the
102.Nm
103program right before the disk would have been modified, and displays
104the result instead of writing it.
105.Pp
106The
107.Fl m Ar machine
108argument forces
109.Nm
110to use a layout suitable for a different architecture.
111Current valid values are
112.Cm i386 , amd64 , ia64 , pc98 ,
113and
114.Cm alpha .
115If this option is omitted,
116.Nm
117will use a layout suitable for the current machine.
118.Ss Reading the Disk Label
119To examine the label on a disk drive, use
120.Nm
121without options:
122.Pp
123.Nm
124.Op Fl A
125.Op Fl m Ar machine
126.Ar disk
127.Pp
128.Ar disk
129represents the disk in question, and may be in the form
130.Pa da0
131or
132.Pa /dev/da0 .
133It will display the partition layout.
134.Ss Writing a Standard Label
135To write a standard label, use the form
136.Pp
137.Nm
138.Fl w
139.Op Fl \&An
140.Op Fl m Ar machine
141.Ar disk
142.Op Ar type
143.Pp
144If the drive type is specified, the entry of that name in the
145.Xr disktab 5
146file is used; otherwise a default layout is used.
147.Ss Editing an Existing Disk Label
148To edit an existing disk label, use the form
149.Pp
150.Nm
151.Fl e
152.Op Fl \&An
153.Op Fl m Ar machine
154.Ar disk
155.Pp
156This command opens the disk label in the default editor, and when the editor
157exits, the label is validated and if OK written to disk.
158.Ss Restoring a Disk Label From a File
159To restore a disk label from a file, use the form
160.Pp
161.Nm
162.Fl R
163.Op Fl \&An
164.Op Fl m Ar machine
165.Ar disk protofile
166.Pp
167.Nm
168is capable of restoring a disk label that was previously saved in a file in
169.Tn ASCII
170format.
171The prototype file used to create the label should be in the same format as that
172produced when reading or editing a label.
173Comments are delimited by
174.Ql #
175and newline.
176.Ss Installing Bootstraps
177If the
178.Fl B
179argument is specified, bootstrap code will be read from the file
180.Pa /boot/boot
181and written to the disk.
182The
183.Fl b Ar boot
184argument allows a different file to be used.
185.Sh FILES
186.Bl -tag -width ".Pa /etc/disktab" -compact
187.It Pa /boot/boot
188Default boot image.
189.It Pa /etc/disktab
190Disk description file.
191.El
192.Sh SAVED FILE FORMAT
193The
194.Nm
195utility
196uses an
197.Tn ASCII
198version of the label when examining, editing, or restoring a disk
199label.
200The format is:
201.Bd -literal -offset 4n
202
2038 partitions:
204#        size   offset    fstype   [fsize bsize bps/cpg]
205  a:    81920       16    4.2BSD     1024  8192    16
206  b:   160000    81936      swap
207  c:  1173930        0    unused        0     0         # "raw" part, don't edit
208.Ed
209.Pp
210If the
211.Fl A
212option is specified, the format is:
213.Bd -literal -offset 4n
214# /dev/da1c:
215type: SCSI
216disk: da0s1
217label:
218flags:
219bytes/sector: 512
220sectors/track: 51
221tracks/cylinder: 19
222sectors/cylinder: 969
223cylinders: 1211
224sectors/unit: 1173930
225rpm: 3600
226interleave: 1
227trackskew: 0
228cylinderskew: 0
229headswitch: 0           # milliseconds
230track-to-track seek: 0  # milliseconds
231drivedata: 0
232
2338 partitions:
234#        size   offset    fstype   [fsize bsize bps/cpg]
235  a:    81920       16    4.2BSD     1024  8192    16
236  b:   160000    81936      swap
237  c:  1173930        0    unused        0     0         # "raw" part, don't edit
238.Ed
239.Pp
240Lines starting with a
241.Ql #
242mark are comments.
243.Pp
244The partition table can have up to 8 entries.
245It contains the following information:
246.Bl -tag -width indent
247.It Ar #
248The partition identifier is a single letter in the range
249.Ql a
250to
251.Ql h .
252By convention, partition
253.Ql c
254is reserved to describe the entire disk.
255.It Ar size
256The size of the partition in sectors,
257.Cm K
258(kilobytes - 1024),
259.Cm M
260(megabytes - 1024*1024),
261.Cm G
262(gigabytes - 1024*1024*1024),
263.Cm %
264(percentage of free space
265.Em after
266removing any fixed-size partitions other than partition
267.Ql c ) ,
268or
269.Cm *
270(all remaining free space
271.Em after
272fixed-size and percentage partitions).
273For partition
274.Ql c ,
275a size of
276.Cm *
277indicates the entire disk.
278Lowercase versions of
279.Cm K , M ,
280and
281.Cm G
282are allowed.
283Size and type should be specified without any spaces between them.
284.Pp
285Example: 2097152, 1G, 1024M and 1048576K are all the same size
286(assuming 512-byte sectors).
287.It Ar offset
288The offset of the start of the partition from the beginning of the
289drive in sectors, or
290.Cm *
291to have
292.Nm
293calculate the correct offset to use (the end of the previous partition plus
294one, ignoring partition
295.Ql c .
296For partition
297.Ql c ,
298.Cm *
299will be interpreted as an offset of 0.
300The first partition should start at offset 16, because the first 16 sectors are
301reserved for metadata.
302.It Ar fstype
303Describes the purpose of the partition.
304The example shows all currently used partition types.
305For
306.Tn UFS
307file systems and
308.Xr ccd 4
309partitions, use type
310.Cm 4.2BSD .
311For Vinum drives, use type
312.Cm vinum .
313Other common types are
314.Cm swap
315and
316.Cm unused .
317By convention, partition
318.Ql c
319represents the entire slice and should be of type
320.Cm unused ,
321though
322.Nm
323does not enforce this convention.
324The
325.Nm
326utility
327also knows about a number of other partition types,
328none of which are in current use.
329(See the definitions starting with
330.Dv FS_UNUSED
331in
332.In sys/disklabel.h
333for more details.)
334.It Ar fsize
335For
336.Cm 4.2BSD
337and
338.Tn LFS
339file systems only, the fragment size.
340Defaults to 1024 for partitions smaller than 1GB,
3414096 for partitions 1GB or larger.
342.It Ar bsize
343For
344.Cm 4.2BSD
345and
346.Tn LFS
347file systems only, the block size.
348Defaults to 8192 for partitions smaller than 1GB,
34916384 for partitions 1GB or larger.
350.It Ar bps/cpg
351For
352.Cm 4.2BSD
353file systems, the number of cylinders in a cylinder group.
354For
355.Tn LFS
356file systems, the segment shift value.
357Defaults to 16 for partitions smaller than 1GB,
35864 for partitions 1GB or larger.
359.El
360.Sh EXAMPLES
361.Dl "bsdlabel da0s1"
362.Pp
363Display the label for the first slice of the
364.Pa da0
365disk, as obtained via
366.Pa /dev/da0s1 .
367.Pp
368.Dl "bsdlabel da0s1 > savedlabel"
369.Pp
370Save the in-core label for
371.Pa da0s1
372into the file
373.Pa savedlabel .
374This file can be used with the
375.Fl R
376option to restore the label at a later date.
377.Pp
378.Dl "bsdlabel -w /dev/da0s1"
379.Pp
380Create a label for
381.Pa da0s1 .
382.Pp
383.Dl "bsdlabel -e da0s1"
384.Pp
385Read the label for
386.Pa da0s1 ,
387edit it, and install the result.
388.Pp
389.Dl "bsdlabel -e -n da0s1"
390.Pp
391Read the on-disk label for
392.Pa da0s1 ,
393edit it, and display what the new label would be (in sectors).
394It does
395.Em not
396install the new label either in-core or on-disk.
397.Pp
398.Dl "bsdlabel -w da0s1"
399.Pp
400Write a default label on
401.Pa da0s1 .
402Use another
403.Nm Fl e
404command to edit the
405partitioning and file system information.
406.Pp
407.Dl "bsdlabel -R da0s1 savedlabel"
408.Pp
409Restore the on-disk and in-core label for
410.Pa da0s1
411from information in
412.Pa savedlabel .
413.Pp
414.Dl "bsdlabel -R -n da0s1 label_layout"
415.Pp
416Display what the label would be for
417.Pa da0s1
418using the partition layout in
419.Pa label_layout .
420This is useful for determining how much space would be allotted for various
421partitions with a labeling scheme using
422.Cm % Ns -based
423or
424.Cm *
425partition sizes.
426.Pp
427.Dl "bsdlabel -B da0s1"
428.Pp
429Install a new bootstrap on
430.Pa da0s1 .
431The boot code comes from
432.Pa /boot/boot .
433.Pp
434.Dl "bsdlabel -w -B -b newboot /dev/da0s1"
435.Pp
436Install a new label and bootstrap.
437The bootstrap code comes from the file
438.Pa newboot
439in the current working directory.
440.Bd -literal -offset indent
441dd if=/dev/zero of=/dev/da0 bs=512 count=32
442fdisk -BI da0
443dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
444bsdlabel -w -B da0s1
445bsdlabel -e da0s1
446.Ed
447.Pp
448Completely wipe any prior information on the disk, creating a new bootable
449disk with a
450.Tn DOS
451partition table containing one slice, covering the whole disk.
452Initialize the label on this slice,
453then edit it.
454The
455.Xr dd 1
456commands are optional, but may be necessary for some
457.Tn BIOS Ns es
458to properly
459recognize the disk.
460.Pp
461This is an example disk label that uses some of the new partition size types
462such as
463.Cm % , M , G ,
464and
465.Cm * ,
466which could be used as a source file for
467.Dq Li "bsdlabel -R ad0s1c new_label_file" :
468.Bd -literal -offset 4n
469# /dev/ad0s1c:
470
4718 partitions:
472#        size   offset    fstype   [fsize bsize bps/cpg]
473  a:   400M       16    4.2BSD     4096 16384    75 	# (Cyl.    0 - 812*)
474  b:     1G        *      swap
475  c:      *        *    unused
476  e: 204800        *    4.2BSD
477  f:     5g        *    4.2BSD
478  g:      *        *    4.2BSD
479.Ed
480.Sh DIAGNOSTICS
481The kernel device drivers will not allow the size of a disk partition
482to be decreased or the offset of a partition to be changed while it is open.
483.Sh COMPATIBILITY
484Due to the use of an
485.Vt u_int32_t
486to store the number of sectors,
487.Bx
488labels are restricted to a maximum of 2^32-1 sectors.
489This usually means 2TB of disk space.
490Larger disks should be partitioned using another method such as
491.Xr gpt 8 .
492.Pp
493The various
494.Bx Ns s
495all use slightly different versions of
496.Bx
497labels and
498are not generally compatible.
499.Sh SEE ALSO
500.Xr ccd 4 ,
501.Xr geom 4 ,
502.Xr md 4 ,
503.\" Xr bsdlabel 5 ,
504.Xr disktab 5 ,
505.Xr boot0cfg 8 ,
506.Xr fdisk 8 ,
507.Xr gpt 8
508