xref: /freebsd/sbin/bsdlabel/bsdlabel.8 (revision 262e143bd46171a6415a5b28af260a5efa2a3db8) 
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        0    4.2BSD     1024  8192    16
206  b:   160000    81920      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        0    4.2BSD     1024  8192    16
236  b:   160000    81920      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.
300.It Ar fstype
301Describes the purpose of the partition.
302The example shows all currently used partition types.
303For
304.Tn UFS
305file systems and
306.Xr ccd 4
307partitions, use type
308.Cm 4.2BSD .
309For Vinum drives, use type
310.Cm vinum .
311Other common types are
312.Cm swap
313and
314.Cm unused .
315By convention, partition
316.Ql c
317represents the entire slice and should be of type
318.Cm unused ,
319though
320.Nm
321does not enforce this convention.
322The
323.Nm
324utility
325also knows about a number of other partition types,
326none of which are in current use.
327(See the definitions starting with
328.Dv FS_UNUSED
329in
330.In sys/disklabel.h
331for more details.)
332.It Ar fsize
333For
334.Cm 4.2BSD
335and
336.Tn LFS
337file systems only, the fragment size.
338Defaults to 1024 for partitions smaller than 1GB,
3394096 for partitions 1GB or larger.
340.It Ar bsize
341For
342.Cm 4.2BSD
343and
344.Tn LFS
345file systems only, the block size.
346Defaults to 8192 for partitions smaller than 1GB,
34716384 for partitions 1GB or larger.
348.It Ar bps/cpg
349For
350.Cm 4.2BSD
351file systems, the number of cylinders in a cylinder group.
352For
353.Tn LFS
354file systems, the segment shift value.
355Defaults to 16 for partitions smaller than 1GB,
35664 for partitions 1GB or larger.
357.El
358.Sh EXAMPLES
359.Dl "bsdlabel da0s1"
360.Pp
361Display the label for the first slice of the
362.Pa da0
363disk, as obtained via
364.Pa /dev/da0s1 .
365.Pp
366.Dl "bsdlabel da0s1 > savedlabel"
367.Pp
368Save the in-core label for
369.Pa da0s1
370into the file
371.Pa savedlabel .
372This file can be used with the
373.Fl R
374option to restore the label at a later date.
375.Pp
376.Dl "bsdlabel -w /dev/da0s1"
377.Pp
378Create a label for
379.Pa da0s1 .
380.Pp
381.Dl "bsdlabel -e da0s1"
382.Pp
383Read the label for
384.Pa da0s1 ,
385edit it, and install the result.
386.Pp
387.Dl "bsdlabel -e -n da0s1"
388.Pp
389Read the on-disk label for
390.Pa da0s1 ,
391edit it, and display what the new label would be (in sectors).
392It does
393.Em not
394install the new label either in-core or on-disk.
395.Pp
396.Dl "bsdlabel -w da0s1"
397.Pp
398Write a default label on
399.Pa da0s1 .
400Use another
401.Nm Fl e
402command to edit the
403partitioning and file system information.
404.Pp
405.Dl "bsdlabel -R da0s1 savedlabel"
406.Pp
407Restore the on-disk and in-core label for
408.Pa da0s1
409from information in
410.Pa savedlabel .
411.Pp
412.Dl "bsdlabel -R -n da0s1 label_layout"
413.Pp
414Display what the label would be for
415.Pa da0s1
416using the partition layout in
417.Pa label_layout .
418This is useful for determining how much space would be allotted for various
419partitions with a labeling scheme using
420.Cm % Ns -based
421or
422.Cm *
423partition sizes.
424.Pp
425.Dl "bsdlabel -B da0s1"
426.Pp
427Install a new bootstrap on
428.Pa da0s1 .
429The boot code comes from
430.Pa /boot/boot .
431.Pp
432.Dl "bsdlabel -w -B -b newboot /dev/da0s1"
433.Pp
434Install a new label and bootstrap.
435The bootstrap code comes from the file
436.Pa newboot
437in the current working directory.
438.Bd -literal -offset indent
439dd if=/dev/zero of=/dev/da0 bs=512 count=32
440fdisk -BI da0
441dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
442bsdlabel -w -B da0s1
443bsdlabel -e da0s1
444.Ed
445.Pp
446Completely wipe any prior information on the disk, creating a new bootable
447disk with a
448.Tn DOS
449partition table containing one slice, covering the whole disk.
450Initialize the label on this slice,
451then edit it.
452The
453.Xr dd 1
454commands are optional, but may be necessary for some
455.Tn BIOS Ns es
456to properly
457recognize the disk.
458.Pp
459This is an example disk label that uses some of the new partition size types
460such as
461.Cm % , M , G ,
462and
463.Cm * ,
464which could be used as a source file for
465.Dq Li "bsdlabel -R ad0s1c new_label_file" :
466.Bd -literal -offset 4n
467# /dev/ad0s1c:
468
4698 partitions:
470#        size   offset    fstype   [fsize bsize bps/cpg]
471  a:   400M        0    4.2BSD     4096 16384    75 	# (Cyl.    0 - 812*)
472  b:     1G        *      swap
473  c:      *        *    unused
474  e: 204800        *    4.2BSD
475  f:     5g        *    4.2BSD
476  g:      *        *    4.2BSD
477.Ed
478.Sh DIAGNOSTICS
479The kernel device drivers will not allow the size of a disk partition
480to be decreased or the offset of a partition to be changed while it is open.
481.Sh COMPATIBILITY
482Due to the use of an
483.Vt u_int32_t
484to store the number of sectors,
485.Bx
486labels are restricted to a maximum of 2^32-1 sectors.
487This usually means 2TB of disk space.
488Larger disks should be partitioned using another method such as
489.Xr gpt 8 .
490.Pp
491The various
492.Bx Ns s
493all use slightly different versions of
494.Bx
495labels and
496are not generally compatible.
497.Sh SEE ALSO
498.Xr ccd 4 ,
499.Xr geom 4 ,
500.Xr md 4 ,
501.\" Xr bsdlabel 5 ,
502.Xr disktab 5 ,
503.Xr boot0cfg 8 ,
504.Xr fdisk 8 ,
505.Xr gpt 8
506