xref: /freebsd/sbin/bsdlabel/bsdlabel.8 (revision 3494f7c0) 
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.Dd October 5, 2016
32.Dt BSDLABEL 8
33.Os
34.Sh NAME
35.Nm bsdlabel
36.Nd read and write BSD label
37.Sh SYNOPSIS
38.Nm
39.Op Fl A
40.Ar disk | Fl f Ar file
41.Nm
42.Fl w
43.Op Fl \&An
44.Op Fl B Op Fl b Ar boot
45.Op Fl m Ar machine
46.Ar disk | Fl f Ar file
47.Op Ar type
48.Nm
49.Fl e
50.Op Fl \&An
51.Op Fl B Op Fl b Ar boot
52.Op Fl m Ar machine
53.Ar disk | Fl f Ar file
54.Nm
55.Fl R
56.Op Fl \&An
57.Op Fl B Op Fl b Ar boot
58.Op Fl m Ar machine
59.Op Fl f
60.Ar disk | Fl f Ar file
61.Ar protofile
62.Sh DESCRIPTION
63The
64.Nm
65utility
66installs, examines or modifies the
67.Bx
68label on a disk partition, or on a file containing a partition image.
69In addition,
70.Nm
71can install bootstrap code.
72.Ss Disk Device Name
73When specifying the device (i.e., when the
74.Fl f
75option is not used),
76the
77.Pa /dev/
78path prefix may be omitted;
79the
80.Nm
81utility will automatically prepend it.
82.Ss General Options
83The
84.Fl A
85option enables processing of the historical parts of the
86.Bx
87label.
88If the option is not given, suitable values are set for these fields.
89.Pp
90The
91.Fl f
92option tells
93.Nm
94that the program will operate on a file instead of a disk partition.
95.Pp
96The
97.Fl n
98option stops the
99.Nm
100program right before the disk would have been modified, and displays
101the result instead of writing it.
102.Pp
103The
104.Fl m Ar machine
105argument forces
106.Nm
107to use a layout suitable for a different architecture.
108Current valid values are
109.Cm i386
110and
111.Cm amd64 .
112If this option is omitted,
113.Nm
114will use a layout suitable for the current machine.
115.Ss Reading the Disk Label
116To examine the label on a disk drive, use the form
117.Pp
118.Nm
119.Op Fl A
120.Op Fl m Ar machine
121.Ar disk
122.Pp
123.Ar disk
124represents the disk in question, and may be in the form
125.Pa da0
126or
127.Pa /dev/da0 .
128It will display the partition layout.
129.Ss Writing a Standard Label
130To write a standard label, use the form
131.Pp
132.Nm
133.Fl w
134.Op Fl \&An
135.Op Fl m Ar machine
136.Ar disk
137.Op Ar type
138.Pp
139If the drive
140.Ar type
141is specified, the entry of that name in the
142.Xr disktab 5
143file is used; otherwise, or if the type is specified as 'auto', a default
144layout is used.
145.Ss Editing an Existing Disk Label
146To edit an existing disk label, use the form
147.Pp
148.Nm
149.Fl e
150.Op Fl \&An
151.Op Fl m Ar machine
152.Ar disk
153.Pp
154This command opens the disk label in the default editor, and when the editor
155exits, the label is validated and if OK written to disk.
156.Ss Restoring a Disk Label From a File
157To restore a disk label from a file, use the form
158.Pp
159.Nm
160.Fl R
161.Op Fl \&An
162.Op Fl m Ar machine
163.Ar disk protofile
164.Pp
165The
166.Nm
167utility
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
179option 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
184option 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     2048 16384  5128
206  b:  1091994    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 suffixes
279.Cm K , M ,
280and
281.Cm G
282are allowed.
283Size and suffix 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 above 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
337file systems only, the fragment size; see
338.Xr newfs 8 .
339.It Ar bsize
340For
341.Cm 4.2BSD
342file systems only, the block size; see
343.Xr newfs 8 .
344.It Ar bps/cpg
345For
346.Cm 4.2BSD
347file systems, the number of cylinders in a cylinder group; see
348.Xr newfs 8 .
349.El
350.Sh EXAMPLES
351Display the label for the first slice of the
352.Pa da0
353disk, as obtained via
354.Pa /dev/da0s1 :
355.Pp
356.Dl "bsdlabel da0s1"
357.Pp
358Save the in-core label for
359.Pa da0s1
360into the file
361.Pa savedlabel .
362This file can be used with the
363.Fl R
364option to restore the label at a later date:
365.Pp
366.Dl "bsdlabel da0s1 > savedlabel"
367.Pp
368Create a label for
369.Pa da0s1 :
370.Pp
371.Dl "bsdlabel -w /dev/da0s1"
372.Pp
373Read the label for
374.Pa da0s1 ,
375edit it, and install the result:
376.Pp
377.Dl "bsdlabel -e da0s1"
378.Pp
379Read the on-disk label for
380.Pa da0s1 ,
381edit it, and display what the new label would be (in sectors).
382It does
383.Em not
384install the new label either in-core or on-disk:
385.Pp
386.Dl "bsdlabel -e -n da0s1"
387.Pp
388Write a default label on
389.Pa da0s1 .
390Use another
391.Nm Fl e
392command to edit the
393partitioning and file system information:
394.Pp
395.Dl "bsdlabel -w da0s1"
396.Pp
397Restore the on-disk and in-core label for
398.Pa da0s1
399from information in
400.Pa savedlabel :
401.Pp
402.Dl "bsdlabel -R da0s1 savedlabel"
403.Pp
404Display what the label would be for
405.Pa da0s1
406using the partition layout in
407.Pa label_layout .
408This is useful for determining how much space would be allotted for various
409partitions with a labeling scheme using
410.Cm % Ns -based
411or
412.Cm *
413partition sizes:
414.Pp
415.Dl "bsdlabel -R -n da0s1 label_layout"
416.Pp
417Install a new bootstrap on
418.Pa da0s1 .
419The boot code comes from
420.Pa /boot/boot :
421.Pp
422.Dl "bsdlabel -B da0s1"
423.Pp
424Install a new label and bootstrap.
425The bootstrap code comes from the file
426.Pa newboot
427in the current working directory:
428.Pp
429.Dl "bsdlabel -w -B -b newboot /dev/da0s1"
430.Pp
431Completely wipe any prior information on the disk, creating a new bootable
432disk with a
433.Tn DOS
434partition table containing one slice, covering the whole disk.
435Initialize the label on this slice,
436then edit it.
437The
438.Xr dd 1
439commands are optional, but may be necessary for some
440.Tn BIOS Ns es
441to properly
442recognize the disk:
443.Bd -literal -offset indent
444dd if=/dev/zero of=/dev/da0 bs=512 count=32
445gpart create -s MBR da0
446gpart add -t freebsd da0
447gpart set -a active -i 1 da0
448gpart bootcode -b /boot/mbr da0
449dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
450bsdlabel -w -B da0s1
451bsdlabel -e da0s1
452.Ed
453.Pp
454This is an example disk label that uses some of the new partition size types
455such as
456.Cm % , M , G ,
457and
458.Cm * ,
459which could be used as a source file for
460.Dq Li "bsdlabel -R ada0s1 new_label_file" :
461.Bd -literal -offset 4n
462# /dev/ada0s1:
463
4648 partitions:
465#        size   offset    fstype   [fsize bsize bps/cpg]
466  a:   400M       16    4.2BSD     4096 16384    75    # (Cyl.    0 - 812*)
467  b:     1G        *      swap
468  c:      *        *    unused
469  e: 204800        *    4.2BSD
470  f:     5g        *    4.2BSD
471  g:      *        *    4.2BSD
472.Ed
473.Sh DIAGNOSTICS
474The kernel device drivers will not allow the size of a disk partition
475to be decreased or the offset of a partition to be changed while it is open.
476.Sh COMPATIBILITY
477Due to the use of an
478.Vt uint32_t
479to store the number of sectors,
480.Bx
481labels are restricted to a maximum of 2^32-1 sectors.
482This usually means 2TB of disk space.
483Larger disks should be partitioned using another method such as
484.Xr gpart 8 .
485.Pp
486The various
487.Bx Ns s
488all use slightly different versions of
489.Bx
490labels and
491are not generally compatible.
492.Sh SEE ALSO
493.Xr ccd 4 ,
494.Xr geom 4 ,
495.Xr md 4 ,
496.Xr disktab 5 ,
497.Xr boot0cfg 8 ,
498.Xr gpart 8 ,
499.Xr newfs 8
500.Sh HISTORY
501The
502.Nm disklabel
503utility appeared in
504.Bx 4.3 Tahoe .
505