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