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