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] [-f] disk
     disklabel -w [-r] [-n] [-f] disk disktype/auto [packid]
     disklabel -e [-r] [-n] [-f] disk
     disklabel -R [-r] [-n] [-f] disk protofile
     disklabel [-NW] [-f] disk

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

DESCRIPTION
     The disklabel utility installs, examines or modifies the label on a disk
     drive or pack, or a regular file representing a disk image.  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	sev-
     eral forms	of the command that read (display), 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.  Note that -r is implicit when	disklabel operates on
     a regular file ( -f) option.

   Disk	device name
     Unless the	-f option is used, all disklabel forms require a disk device
     name, which should	always be the raw device name representing the disk or
     slice.  For example da0 represents	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.  If the -f option is used, disklabel will interpret the disk name
     (which must be an absolute	pathname) as the name of a regular file	repre-
     senting a disk image, and will work on it instead of a device.  Note that
     when it operates on a regular file, the -r	option becomes implicit	as the
     kernel will not cache disklabel info.

   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, vnode devices, and regular
     files.  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 (full pathnames are	still required when operating with
     regular files and the -f option).

     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.

     2.	  Use disklabel	to define partitions on	FreeBSD	slices created in the
	  previous step.

     3.	  Finally use newfs(8) to create file systems on new partitions.

     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' partition for
     /var/tmp (usually 128MB), an `f' partition	for /usr (usually around 2GB),
     and finally a `g' partition for /home (usually all	remaining space).
     Your mileage may vary.

     fdisk -BI da0

     disklabel -w -B da0s1 auto

     disklabel -e da0s1

FILES
     /boot/boot	   Default boot	image.
     /etc/disktab  Disk	description file.

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 specifi-
     cations 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 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 is the	UNIX partition table, not the DOS partition
     table described in	fdisk(8).

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

     #	     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    The size of the partition in sectors, K (kilobytes	- 1024), M
	     (megabytes	- 1024*1024), G	(gigabytes - 1024*1024*1024), %	(per-
	     centage 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 spa-
	     ces between them.

	     Example: 2097152, 1G, 1024M and 1048576K are all the same size
	     (assuming 512-byte	sectors).

     offset  The offset	of the start of	the partition from the beginning of
	     the drive in sectors, or *	to have	disklabel calculate the	cor-
	     rect offset to use	(the end of the	previous partition 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(4)
	     partitions, use type 4.2BSD.  For Vinum drives, use type vinum.
	     Other common types	are swap and unused.  By convention, 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 <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 1GB, 4096 for	parti-
	     tions 1GB or larger.

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

     bps/cpg
	     For 4.2BSD	file systems, the number of cylinders in a cylinder
	     group.  For LFS file systems, the segment shift value.  Defaults
	     to	16 for partitions smaller than 1GB, 64 for partitions 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 da0s1

     Display the in-core label for the first slice of the da0 disk, as
     obtained via /dev/da0s1.  (If the disk is ``dangerously-dedicated'', the
     base disk name should be specified, such as da0.)

	   disklabel da0s1 > savedlabel

     Save the in-core label for	da0s1 into the file savedlabel.	 This file can
     be	used with the -R option	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 and the disk
     rendered unbootable.

	   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.11-RELEASE>

home | help