Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DISKLABEL(8)		FreeBSD	System Manager's Manual		  DISKLABEL(8)

NAME
     disklabel -- read and write disk pack label

SYNOPSIS
     disklabel [-r] disk
     disklabel -w [-r] [-n] disk disktype/auto [packid]
     disklabel -e [-r] [-n] disk
     disklabel -R [-r] [-n] disk protofile
     disklabel [-NW] disk

     disklabel -B [-b boot1 -s boot2] disk [disktype/auto]
     disklabel -w -B [-n] [-b boot1 -s boot2] disk disktype/auto [packid]
     disklabel -R -B [-n] [-b boot1 -s boot2] disk protofile [disktype/auto]

DESCRIPTION
     The disklabel utility installs, examines or modifies the label on a disk
     drive or pack.  When writing the label, it	can be used to change the
     drive identification, the disk partitions on the drive, or	to replace a
     damaged label.  There are several forms of	the command that read (dis-
     play), install or edit the	label on a disk.  In addition, disklabel can
     install bootstrap code.

   Raw or in-core label
     The disk label resides close to or	at the beginning of each disk slice.
     For faster	access,	the kernel maintains a copy in core at all times.  By
     default, most disklabel access the	in-core	copy of	the label.  To access
     the raw (on-disk) copy, use the -r	option.	 This option allows a label to
     be	installed on a disk without kernel support for a label,	such as	when
     labels are	first installed	on a system; it	must be	used when first
     installing	a label	on a disk.  The	specific effect	of -r is described
     under each	command.

   Disk	device name
     All disklabel forms require a disk	device name, which should always be
     the raw device name representing the disk or slice.  For example da0 rep-
     resents the entire	disk regardless	of any DOS partitioning, and da0s1
     represents	a slice.  Some devices,	most notably ccd, require that the
     ``whole-disk'' (or	``c'') partition be specified.	For example ccd0c.
     You do not	have to	include	the /dev/ path prefix when specifying the
     device.  The disklabel utility will automatically prepend it.

   Reading the disk label
     To	examine	the label on a disk drive, use disklabel without options:

     disklabel [-r] disk

     disk represents the raw disk in question, and may be in the form da0 or
     /dev/da0c.	 It will display all of	the parameters associated with the
     drive and its partition layout.  Unless the -r flag is given, the ker-
     nel's in-core copy	of the label is	displayed; if the disk has no label,
     or	the partition types on the disk	are incorrect, the kernel may have
     constructed or modified the label.	 If the	-r flag	is given, disklabel
     reads the label from the raw disk and displays it.	 Both versions are
     usually identical except in the case where	a label	has not	yet been ini-
     tialized or is corrupt.

   Writing a standard label
     To	write a	standard label,	use the	form

     disklabel -w [-r] [-n] disk disktype/auto [packid]

     disklabel -w [-r] [-n] disk auto

     The required arguments to disklabel are the drive to be labeled and the
     drive type	as described in	the disktab(5) file.  The drive	parameters and
     partitions	are taken from that file.  If different	disks of the same
     physical type are to have different partitions, it	will be	necessary to
     have separate disktab entries describing each, or to edit the label after
     installation as described below.  The optional argument is	a pack identi-
     fication string, up to 16 characters long.	 The pack id must be quoted if
     it	contains blanks.

     If	the -n flag is given, no data will be written to the device, and
     instead the disklabel that	would have been	written	will be	printed	to
     stdout.

     If	the -r flag is given, the disk sectors containing the label and	boot-
     strap will	be written directly.  A	side-effect of this is that any	exist-
     ing bootstrap code	will be	overwritten and	the disk rendered unbootable.
     See the boot options below	for a method of	writing	the label and the
     bootstrap at the same time.  If -r	is not specified, the existing label
     will be updated via the in-core copy and any bootstrap code will be unaf-
     fected.  If the disk does not already have	a label, the -r	flag must be
     used.  In either case, the	kernel's in-core label is replaced.

     For a virgin disk that is not known to disktab(5),	disktype can be	speci-
     fied as ``auto''.	In this	case, the driver is requested to produce a
     virgin label for the disk.	 This might or might not be successful,
     depending on whether the driver for the disk is able to get the required
     data without reading anything from	the disk at all.  It will likely suc-
     ceed for all SCSI disks, most IDE disks, and vnode	devices.  Writing a
     label to the disk is the only supported operation,	and the	disk itself
     must be provided as the canonical name, i.e. not as a full	path name.

     For most harddisks, a label based on percentages for most partitions (and
     one partition with	a size of `*') will produce a reasonable configura-
     tion.

     PC-based systems have special requirements	in order for the BIOS to prop-
     erly recognize a FreeBSD disklabel.  Older	systems	may require what is
     known as a	``dangerously dedicated'' disklabel, which creates a fake DOS
     partition to work around problems older BIOSes have with modern disk
     geometries.  On newer systems you generally want to create	a normal DOS
     partition using fdisk and then create a FreeBSD disklabel within that
     slice.  This is described later on	in this	page.

     Installing	a new disklabel	does not in of itself allow your system	to
     boot a kernel using that label.  You must also install boot blocks, which
     is	described later	on in this manual page.

   Editing an existing disk label
     To	edit an	existing disk label, use the form

     disklabel -e [-r] [-n] disk

     This command reads	the label from the in-core kernel copy,	or directly
     from the disk if the -r flag is also specified.  The label	is written to
     a file in ASCII and then supplied to an editor for	changes.  If no	editor
     is	specified in an	EDITOR environment variable, vi(1) is used.  When the
     editor terminates,	the label file is used to rewrite the disk label.
     Existing bootstrap	code is	unchanged regardless of	whether	-r was speci-
     fied.  If -n is specified,	no data	will be	written	to the device, and
     instead the disklabel that	would have been	written	will be	printed	to
     stdout.  This is useful to	see how	a partitioning scheme will work	out
     for a specific disk.

   Restoring a disk label from a file
     To	restore	a disk label from a file, use the form

     disklabel -R [-r] [-n] disk protofile

     disklabel is capable of restoring a disk label that was previously	saved
     in	a file in ASCII	format.	 The prototype file used to create the label
     should be in the same format as that produced when	reading	or editing a
     label.  Comments are delimited by # and newline.  As when writing a new
     label, any	existing bootstrap code	will be	clobbered if -r	is specified
     and will be unaffected otherwise.	See the	boot options below for a
     method of restoring the label and writing the bootstrap at	the same time.
     If	-n is used, no data will be written to the device, and instead the
     disklabel that would have been written will be printed to stdout.	This
     is	useful to see how a partitioning scheme	will work out for a specific
     disk.

   Enabling and	disabling writing to the disk label area
     By	default, it is not possible to write to	the disk label area at the
     beginning of a disk.  The disk driver arranges for	write(2) and similar
     system calls to return EROFS on any attempt to do so.  If you need	to
     write to this area	(for example, to obliterate the	label),	use the	form

     disklabel -W disk

     To	disallow writing to the	label area after previously allowing it, use
     the command

     disklabel -N disk

   Installing bootstraps
     The final three forms of disklabel	are used to install bootstrap code.
     If	you are	creating a ``dangerously-dedicated'' slice for compatibility
     with older	PC systems, you	generally want to specify the raw disk name
     such as da0.  If you are creating a label within an existing DOS slice,
     you should	specify	the partition name such	as da0s1a.  Making a slice
     bootable can be tricky.  If you are using a normal	DOS slice you typi-
     cally install (or leave) a	standard MBR on	the base disk and then install
     the FreeBSD bootblocks in the slice.

     disklabel -B [-b boot1 -s boot2] disk [disktype]

     This form installs	the bootstrap only.  It	does not change	the disk
     label.  You should	never use this command on a base disk unless you
     intend to create a	``dangerously-dedicated'' disk,	such as	da0.  This
     command is	typically run on a slice such as da0s1.

     disklabel -w -B [-n] [-b boot1 -s boot2] disk disktype [packid]

     This form corresponds to the ``write label'' command described above.  In
     addition to writing a new volume label, it	also installs the bootstrap.
     If	run on a base disk this	command	will create a
     ``dangerously-dedicated'' label.  This command is normally	run on a slice
     rather than a base	disk.  If -n is	used, no data will be written to the
     device, and instead the disklabel that would have been written will be
     printed to	stdout.

     disklabel -R -B [-n] [-b boot1 -s boot2] disk protofile [disktype]

     This form corresponds to the ``restore label'' command described above.
     In	addition to restoring the volume label,	it also	installs the boot-
     strap.  If	run on a base disk this	command	will create a
     ``dangerously-dedicated'' label.  This command is normally	run on a slice
     rather than a base	disk.

     The bootstrap commands always access the disk directly, so	it is not nec-
     essary to specify the -r flag.  If	-n is used, no data will be written to
     the device, and instead the disklabel that	would have been	written	will
     be	printed	to stdout.

     The bootstrap code	is comprised of	two boot programs.  Specify the	name
     of	the boot programs to be	installed in one of these ways:

     1.	  Specify the names explicitly with the	-b and -s flags.  -b indicates
	  the primary boot program and -s the secondary	boot program.  The
	  boot programs	are located in /boot.

     2.	  If the -b and	-s flags are not specified, but	disktype was speci-
	  fied,	the names of the programs are taken from the ``b0'' and	``b1''
	  parameters of	the disktab(5) entry for the disk if the disktab entry
	  exists and includes those parameters.

     3.	  Otherwise, the default boot image names are used: /boot/boot1	and
	  /boot/boot2 for the standard stage1 and stage2 boot images (details
	  may vary on architectures like the Alpha, where only a single-stage
	  boot is used).

   Initializing/Formatting a bootable disk from	scratch
     To	initialize a disk from scratch the following sequence is recommended.
     Please note that this will	wipe everything	that was previously on the
     disk, including any non-FreeBSD slices.

     1.	  Use fdisk(8) to initialize the hard disk, and	create a slice table,
	  referred to as the partition table in	DOS.  Here you will define
	  disk slices for your system.

     2.	  Use disklabel	to define and write partitions and mount points.  You
	  are not required to define the mount points here though, they	can be
	  defined later	using mount(8).

     3.	  Finally use newfs(8) to create a file	system on the new partition.
	  A typical partitioning scheme	would be to have an ``a'' partition of
	  approximately	128MB to hold the root file system, a ``b'' partition
	  for swap, a ``d'' partition for /var (usually	128MB),	an ``e'' par-
	  tition for /var/tmp (usually 128MB), an ``f''	partition for /usr
	  (usually around 2G), and finally a ``g'' partition for /home (usu-
	  ally all remaining space).  Your mileage may vary.

     fdisk -BI da0

     disklabel -w -B da0s1 auto

     disklabel -e da0s1

FILES
     /etc/disktab
     /boot/
     /boot/boot<n>

SAVED FILE FORMAT
     The disklabel utility uses	an ASCII version of the	label when examining,
     editing or	restoring a disk label.	 The format is:

	 # /dev/da1c:
	 type: SCSI
	 disk: da0s1
	 label:
	 flags:
	 bytes/sector: 512
	 sectors/track:	51
	 tracks/cylinder: 19
	 sectors/cylinder: 969
	 cylinders: 1211
	 sectors/unit: 1173930
	 rpm: 3600
	 interleave: 1
	 trackskew: 0
	 cylinderskew: 0
	 headswitch: 0		 # milliseconds
	 track-to-track	seek: 0	 # milliseconds
	 drivedata: 0

	 8 partitions:
	 #	  size	 offset	   fstype   [fsize bsize bps/cpg]
	   a:	 81920	      0	   4.2BSD     1024  8192    16	 # (Cyl.    0 -	84*)
	   b:	160000	  81920	     swap			 # (Cyl.   84* - 218*)
	   c:  1173930	      0	   unused	 0     0	 # (Cyl.    0 -	1211*)
	   h:	962010	 211920	    vinum			 # (Cyl.  218*-	1211*)

     Lines starting with a # mark are comments.	 Most of the other specifica-
     tions are no longer used.	The ones which must still be set correctly
     are:

     label		   is an optional label, set by	the packid option when
			   writing a label.

     flags		   Flags may be	removable, ecc or badsect.  removable
			   is set for removable	media drives, but no current
			   FreeBSD driver evaluates this flag.	ecc is no
			   longer supported; badsect specifies that the	drive
			   can perform bad sector remapping.

     sectors/unit	   describes the total size of the disk.  This value
			   must	be correct.

     the partition table   This	is the UNIX partition table, not the Microsoft
			   partition table described in	fdisk(8).

     The partition table can have up to	8 entries.  It contains	the following
     information:

     identifier	 The partition identifier is a single letter in	the range
		 ``a'' to ``h''.  By convention, partition ``c'' is reserved
		 to describe the entire	disk.

     size	 is the	size of	the partition in sectors, K (kilobytes -
		 1024),	M (megabytes - 1024*1024), G (gigabytes	-
		 1024*1024*1024), % (percentage	of free	space AFTER removing
		 any fixed-size	partitions other than partition	``c)'',	or *
		 (all remaining	free space AFTER fixed-size and	percentage
		 partitions).  For partition ``c'', a size of *	indicates the
		 entire	disk.  Lowercase versions of K,	M, and G are allowed.
		 Size and type should be specifed without any spaces between
		 them.

		 Example: 2097152, 1g, 1024m and 1048576k are all the same
		 size (assuming	512-byte sectors).

     offset	 is the	offset of the start of the partition from the begin-
		 ning of the drive in sectors, or * to have disklabel calcu-
		 late the correct offset to use	(the end of the	previous par-
		 tition	plus one, ignoring partition ``c''.  For partition
		 ``c'',	* will be interpreted as an offset of 0.

     fstype	 describes the purpose of the partition.  The example shows
		 all currently used partition types.  For UFS file systems and
		 ccd partitions, use type 4.2BSD.  For Vinum drives, use type
		 vinum.	 Other common types are	unused and swap.  By conven-
		 tion, partition ``c'' represents the entire slice and should
		 be of type unused, though disklabel does not enforce this
		 convention.  The disklabel utility also knows about a number
		 of other partition types, none	of which are in	current	use.
		 See the definitions starting with FS_UNUSED in
		 /usr/include/sys/disklabel.h for more details.

     fsize	 For 4.2BSD and	LFS file systems only, the fragment size.
		 Defaults to 1024 for partitions smaller than 1	GB, 4096 for
		 partitions 1GB	or larger.

     bsize	 For 4.2BSD and	LFS file systems only, the block size.
		 Defaults to 8192 for partitions smaller than 1	GB, 16384 for
		 partitions 1GB	or larger.

     bps/cpg	 For 4.2BSD file systems, the number of	cylinders in a cylin-
		 der group.  For LFS file systems, the segment shift value.
		 Defaults to 16	for partitions smaller than 1 GB, 64 for par-
		 titions 1GB or	larger.

     The remainder of the line is a comment and	shows the cylinder allocations
     based on the obsolete (but	possibly correct) geometry information about
     the drive.	 The asterisk (*) indicates that the partition does not	begin
     or	end exactly on a cylinder boundary.

EXAMPLES
	   disklabel da0

     Display the in-core label for da0s1 as obtained via /dev/da0s1.  When
     reading a label, FreeBSD will allow you to	specify	the base disk name
     even if the label resides on a slice.  However, to	be proper you should
     specify the base disk name	only if	you are	using a
     ``dangerously-dedicated'' label.  Normally	you specify the	slice.

	   disklabel da0s1 > savedlabel

     Save the in-core label for	da0s1 into the file savedlabel.	 This file can
     be	used with the -R flag to restore the label at a	later date.

	   disklabel -w	-r /dev/da0s1 da2212 foo

     Create a label for	da0s1 based on information for ``da2212'' found	in
     /etc/disktab.  Any	existing bootstrap code	will be	clobbered.

	   disklabel -e	-r da0s1

     Read the on-disk label for	da0s1, edit it and reinstall in-core as	well
     as	on-disk.  Existing bootstrap code is unaffected.

	   disklabel -e	-r -n da0s1

     Read the on-disk label for	da0s1, edit it,	and display what the new label
     would be (in sectors).  It	does NOT install the new label either in-core
     or	on-disk.

	   disklabel -r	-w da0s1 auto

     Try to auto-detect	the required information from da0s1, and write a new
     label to the disk.	 Use another disklabel -e command to edit the parti-
     tioning and file system information.

	   disklabel -R	da0s1 savedlabel

     Restore the on-disk and in-core label for da0s1 from information in
     savedlabel.  Existing bootstrap code is unaffected.

	   disklabel -R	-n da0s1 label_layout

     Display what the label would be for da0s1 using the partition layout in
     label_layout.  This is useful for determining how much space would	be
     alloted for various partitions with a labelling scheme using %-based or *
     partition sizes.

	   disklabel -B	da0s1

     Install a new bootstrap on	da0s1.	The boot code comes from /boot/boot1
     and possibly /boot/boot2.	On-disk	and in-core labels are unchanged.

	   disklabel -w	-B /dev/da0s1 -b newboot1 -s newboot2 da2212

     Install a new label and bootstrap.	 The label is derived from disktab
     information for ``da2212''	and installed both in-core and on-disk.	 The
     bootstrap code comes from the files /boot/newboot1	and /boot/newboot2.

	   dd if=/dev/zero of=/dev/da0 bs=512 count=32
	   fdisk -BI da0
	   dd if=/dev/zero of=/dev/da0s1 bs=512	count=32
	   disklabel -w	-B da0s1 auto
	   disklabel -e	da0s1

     Completely	wipe any prior information on the disk,	creating a new
     bootable disk with	a DOS partition	table containing one ``whole-disk''
     slice.  Then initialize the slice,	then edit it to	your needs.  The dd
     commands are optional, but	may be necessary for some BIOSes to properly
     recognize the disk.

     This is an	example	disklabel that uses some of the	new partition size
     types such	as %, M, G, and	*, which could be used as a source file	for

	   disklabel -R	ad0s1c new_label_file

	 # /dev/ad0s1c:
	 type: ESDI
	 disk: ad0s1
	 label:
	 flags:
	 bytes/sector: 512
	 sectors/track:	63
	 tracks/cylinder: 16
	 sectors/cylinder: 1008
	 cylinders: 40633
	 sectors/unit: 40959009
	 rpm: 3600
	 interleave: 1
	 trackskew: 0
	 cylinderskew: 0
	 headswitch: 0		 # milliseconds
	 track-to-track	seek: 0	 # milliseconds
	 drivedata: 0

	 8 partitions:
	 #	  size	 offset	   fstype   [fsize bsize bps/cpg]
	   a:	400M	    0	 4.2BSD	    4096 16384	  75	 # (Cyl.    0 -	812*)
	   b:	  1G	    *	   swap
	   c:	   *	    *	 unused
	   e: 204800	    *	 4.2BSD
	   f:	  5g	    *	 4.2BSD
	   g:	   *	    *	 4.2BSD

SEE ALSO
     ccd(4), disklabel(5), disktab(5), boot0cfg(8), fdisk(8), vinum(8)

DIAGNOSTICS
     The kernel	device drivers will not	allow the size of a disk partition to
     be	decreased or the offset	of a partition to be changed while it is open.
     Some device drivers create	a label	containing only	a single large parti-
     tion if a disk is unlabeled; thus,	the label must be written to the ``a''
     partition of the disk while it is open.  This sometimes requires the
     desired label to be set in	two steps, the first one creating at least one
     other partition, and the second setting the label on the new partition
     while shrinking the ``a'' partition.

     On	some machines the bootstrap code may not fit entirely in the area
     allocated for it by some file systems.  As	a result, it may not be	possi-
     ble to have file systems on some partitions of a ``bootable'' disk.  When
     installing	bootstrap code,	disklabel checks for these cases.  If the
     installed boot code would overlap a partition of type FS_UNUSED it	is
     marked as type FS_BOOT.  The newfs(8) utility will	disallow creation of
     file systems on FS_BOOT partitions.  Conversely, if a partition has a
     type other	than FS_UNUSED or FS_BOOT, disklabel will not install boot-
     strap code	that overlaps it.

BUGS
     When a disk name is given without a full pathname,	the constructed	device
     name uses the ``c'' partition.

     For the i386 architecture,	the primary bootstrap sector contains an
     embedded fdisk table.  The	disklabel utility takes	care to	not clobber it
     when installing a bootstrap only (-B), or when editing an existing	label
     (-e), but it unconditionally writes the primary bootstrap program onto
     the disk for -w or	-R, thus replacing the fdisk table by the dummy	one in
     the bootstrap program.  This is only of concern if	the disk is fully ded-
     icated, so	that the BSD disklabel starts at absolute block	0 on the disk.

     The disklabel utility does	not perform all	possible error checking.
     Warning *is* given	if partitions overlap; if an absolute offset does not
     match the expected	offset;	if the ``c'' partition does not	start at 0 or
     does not cover the	entire slice; if a partition runs past the end of the
     device; and a number of other errors; but no warning is given if space
     remains unused.

FreeBSD	9.3			 July 30, 1999			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | FILES | SAVED FILE FORMAT | EXAMPLES | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=disklabel&sektion=8&manpath=FreeBSD+4.8-RELEASE>

home | help