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