diskutil(8) BSD System Manager's Manual diskutil(8) NAME diskutil -- Modify, verify and repair local disks. SYNOPSIS diskutil [quiet] verb [options] DESCRIPTION diskutil manipulates the volume-level structure of local disks. It provides information about, and allows the administration of, the partitioning scheme of disks, optical discs, and AppleRAID sets. VERBS Each verb is listed with its description and individual arguments. list [-plist | device] List disks. If no argument is given, then all disks and all of their partitions are listed. If -plist is specified, then a property list will be emitted instead of the normal user- readable output. If a device is specified, then instead of listing all families of whole disks and their partitions, only one such family is listed. In that case, specifying either the whole disk or any of its slices will work. The -plist and device arguments may not both be specified at the same time. A script could interpret the results of the diskutil list -plist output and use diskutil info -plist as well as diskutil listFilesystems -plist for more detailed information. See the DEVICES section below for the various forms that the device specification may take for this and all of the other diskutil verbs. The top-to-bottom appearance of partitions in diskutil list always indicates the on-disk ordering. BSD disk identifiers may, in certain circumstances, not appear in slice-numerical order when viewed this way. This is normal and is likely the result of a recent partition map editing operation in which volumes were kept mounted. info | information [-plist] device Get detailed information about a specific whole disk or partition. If -plist is specified, then a property list instead of the normal user-readable output will be emitted. listFilesystems [-plist] Show the file system personalities available for formatting in diskutil when using the eras- ing and partitioning verbs. This is a subset of the complete set of personalities exported by the various filesystem bundles that may be installed in the system. Also shown are some shortcut aliases for common personalities. See the FORMAT section below for more details. If -plist is specified, then a property list instead of the normal user-readable output will be emitted. unmount | umount [force] device Unmount a single volume. Force will force-unmount the volume (less kind to any open files; see also umount (8)). unmountDisk | umountDisk [force] device Unmount an entire disk (all volumes). Force will force-unmount the volumes (less kind to any open files; see also umount (8)). eject device Eject a disk. Media will become offline for the purposes of being a data store for file systems or being a member of constructs such as software RAID or direct data. Additionally, removable media will become eligible for safe manual removal; automatically-removable media will begin its physical (motorized) eject sequence. mount [readOnly] [-mountPoint path] device Mount a single volume. If readOnly is specified, then the file system is mounted read-only, even if the volume's underlying file system and/or device and/or media supports writing; even the super-user may not write to it; this is the same as the rdonly option to mount (8). If a -mountPoint is specified, then that path, rather than the standard path of /Vol- umes/VolumeName, will be used as the view into the volume file content; a directory at that path must already exist. mountDisk device Mount an entire disk (all mountable volumes). rename | renameVolume device name Rename a volume. Volume names are subject to file system-specific alphabet and length restrictions. enableJournal device Enable journaling on an HFS+ volume. This works whether or not the volume is currently mounted (the volume is temporarily mounted if necessary). Ownership of the affected disk is required. disableJournal [force] device Disable journaling on an HFS+ volume. This normally works whether or not the volume is cur- rently mounted (the volume is temporarily mounted if necessary). If the force option is specified, then journaling is disabled directly on disk; in this case, the volume must not be mounted. Ownership of the affected disk is required. moveJournal external|internal [journalDevice] device external will create a 512MB Apple_Journal partition out of journalDevice and an HFS+ parti- tion will be created out of the remaining space if available; journalDevice must be a parti- tion, not a whole-disk. The journal for device will then be moved externally onto the newly created Apple_Journal partition. internal will move the journal for device back locally. enableOwnership device Enable ownership of a volume. The on-root-disk Volume Database at /var/db/volinfo.database is manipulated such that the User and Group ID settings of files, directories, and links (file system objects, or "FSOs") on the target volume are taken into account. This setting for a particular volume is persistent across ejects and injects of that volume as seen by the current OS, even across reboots of that OS, because of the entries in this OS's Volume Database. Note thus that the setting is not kept on the target disk, nor is it in-memory. For some locations of devices (e.g. internal hard disks), consideration of ownership set- tings on FSOs is the default. For others (e.g. plug-in USB disks), it is not. When ownership is disabled, Owner and Group ID settings on FSOs appear to the user and pro- grams as the current user and group instead of their actual on-disk settings, in order to make it easy to use a plug-in disk of which the user has physical possession. When ownership is enabled, the Owner and Group ID settings that exist on the disk are taken into account for determining access, and exact settings are written to the disk as FSOs are created. A common reason for having to enable ownership is when a disk is to contain FSOs whose User and Group ID settings, and thus permissions behavior overall, is critically important, such as when the plug-in disk contains system files to be changed or added to. See also the vsdbutil command. Running as root is required. disableOwnership device Disable ownership of a volume. See enableOwnership above. Running as root is required. verifyVolume device Verify the data structure of a volume (e.g. fsck). Ownership of the affected disk is required. repairVolume device Repair the data structure of a volume (e.g. fsck). Ownership of the affected disk is required. verifyPermissions [-plist] device Verify the permissions of a Mac OS X boot volume. The data that guides the permissions ver- ification is written during the installation process. repairPermissions [-plist] device Repair the permissions of a Mac OS X boot volume. The data that guides the permissions repair is written during the installation process. Ownership of the affected disk is required. eraseDisk format name [[APM]Format | [MBR]Format | [GPT]Format] device Erase an existing disk, removing all volumes and writing out a new partitioning scheme con- taining one new empty filesystem volume. If the partitioning scheme is not specified, then an appropriate one for the current machine is chosen. Format is discussed below in the sec- tion for the partitionDisk verb. Ownership of the affected disk is required. eraseVolume format name device Erase an existing volume or write out a new empty filesystem if there was none. Format is discussed below in the section for the partitionDisk verb. Ownership of the affected disk is required. eraseOptical [quick] device Erase optical media (CD/RW, DVD/RW, etc.). Quick specifies whether the disc recording sys- tem software should do a full erase or a quick erase. Ownership of the affected disk is required. zeroDisk device Erase a device, writing zeros to the media. The device can be a whole-disk or a partition. In either case, in order to be useful again, zero'd whole-disks will need to be partitioned, or zero'd partitions will need to be erased (newfs'd), e.g. by using the partitionDisk or eraseDisk verbs. If you desire a more sophisticated erase algorithm or if you need to erase only free space not in use for files, use the secureErase verb. Ownership of the affected disk is required. randomDisk [times] device Erase a whole disk, writing random data to the media. Times is the optional (defaults to 1) number of times to write random information. The device can be a whole-disk or a partition. In either case, in order to be useful again, randomized whole-disks will need to be parti- tioned, or randomized partitions will need to be erased (newfs'd), e.g. by using the partitionDisk or eraseDisk verbs. If you desire a more sophisticated erase algorithm or if you need to erase only free space not in use for files, use the secureErase verb. Ownership of the affected disk is required. secureErase [freespace] level device Erase, using a secure method, either a whole-disk (including any and all partitions), or, only the free space (not in use for files) on a currently-mounted volume. Erasing a whole- disk will leave it useless until it is partitioned again. Erasing freespace on a volume will leave it exactly as it was from an end-user perspective, with the exception that it will not be possible to recover deleted files or data using utility software. If you need to erase all contents of a partition but not its hosting whole-disk, use the zeroDisk or randomDisk verbs. Ownership of the affected disk is required. Level should be one of the following: • 0 - Single-pass zero-fill erase. • 1 - Single-pass random-fill erase. • 2 - US DoD 7-pass secure erase. • 3 - Gutmann algorithm 35-pass secure erase. • 4 - US DoE algorithm 3-pass secure erase. partitionDisk device [numberOfPartitions] [[APM]Format | [MBR]Format | [GPT]Format] [part1Format part1Name part1Size part2Format part2Name part2Size part3Format part3Name part3Size ...] (re)Partition a disk, removing all volumes. All volumes on this disk will be destroyed. The device parameter specifies which whole disk is to be partitioned. The optional numberOfPartitions parameter specifies the number of partitions to create; if given then the number of parameter triplets (see below) is expected to match; else, the number of triplets alone given will determine the number of partitions created. The optional partitioning scheme parameter forces a particular partitioning scheme; if not specified, a suitable default is chosen. They are: • [APM]Format specifies that an Apple Partition Map scheme should be used. This is the traditional Apple partitioning scheme used to start up a PowerPC-based Macin- tosh computer, to use the disk as a non-startup disk with any Mac, or to create a multiplatform compatible startup disk. • [MBR]Format specifies that a Master Boot Record scheme should be used. This is the DOS/Windows-compatible partitioning scheme. • [GPT]Format specifies that a GUID Partitioning Table scheme should be used. This is the partitioning scheme used to start up an Intel-based Macintosh computer. For each partition, a triplet of the desired filesystem format, volume name, and size must be specified. Several other diskutil verbs allow these triplets as well (and for them, the numberOfPartitions parameter is also optional). The triplets must be as follows: • Format names are of the form HFS+, MS-DOS, etc.; a list of formatable filesystems and common aliases is available from the listFilesystems verb. You can specify Free Space to skip an area of the disk. Format guides diskutil both in what par- tition type to set for the partitions (slices) as well as what filesystem struc- tures to lay down therein, e.g. with the appropriate newfs_* (8). • Names are the initial volume names; they must conform to filesystem-specific restrictions. If a name of %noformat% is specified, then the partition is left blank such that the partition space is carved out, the partition type is set according to the filesystem format name, the partition space is partially erased, but a filesystem structure is not laid down; this is useful in certain cases e.g. when setting up ZFS pools. For Free Space triplets, names are ignored but dummy names must be present. • Sizes are floating point numbers followed by a letter or percent sign as described in the sizes section at the end of this page (e.g. 165536000B, 55.3T, 678M, 75%, R). The last partition may be lengthened to the end of the disk. You can specify an exact size for your last partition by specifying it as the penultimate triplet and specifying an addi- tional (last) triplet as Free Space. Ownership of the affected disk is required. resizeVolume device size [numberOfPartitions] [part1Format part1Name part1Size part2Format part2Name part2Size part3Format part3Name part3Size ...] Non-destructively resize a volume. You may increase or decrease its size. A size of limits will print the range of valid values for the current filesystem. When decreasing the size, new partitions may optionally be created to fill the newly-freed space. To do this, specify the numberOfPartitions, format, name, and size parameters in the same manner as the triplet description for the partitionDisk verb. Resizing a volume that is currently set as the computer's startup disk will invalidate that setting; use the Startup Disk System Preferences panel or bless (8) to reset the resized volume as the startup disk. Device refers to a volume; the volume's file system must be journaled HFS+. Valid sizes are a number followed by a capital letter multiplier or percent sign suffix as described in the sizes section at the end of this page (e.g. 1.5T, 128M, 50%). Ownership of the affected disk is required. splitPartition device [numberOfPartitions] [part1Format part1Name part1Size part2Format part2Name part2Size part3Format part3Name part3Size ...] Destructively split a volume into multiple partitions. You must supply a list of new parti- tions to create in the space of the old partition; specify these with the numberOfPartitions, format, name, and size parameters in the same manner as the triplet description for the partitionDisk verb. Device refers to a volume. Ownership of the affected disk is required. mergePartitions [force] format name fromDevice toDevice Merge two or more partitions on a disk. All data on merged partitions other than the first will be lost. The first will be erased if it doesn't have a resizable type (e.g. JHFS+) or if the force argument is given. Format and name apply only when the first partition is being erased. Merged partitions are required to be ordered sequentially on disk (see diskutil list for the actual on-disk ordering). Ownership of the affected disk is required. appleRAID raidVerb [...] AppleRAID verbs can be used to create, manipulate and destroy AppleRAID volumes (Software RAID). AppleRAID supports three basic types of RAID sets: • "stripe" - Striped Volume (RAID 0) • "mirror" - Mirrored Volume (RAID 1) • "concat" - Concatenated Volume (Spanning) Of these three basic types, only the "mirror" type increases fault-tolerance. Mirrors may have more than two disks to further increase their fault-tolerance. Striped and concaten- tated volumes are, in fact, more vulnerable to faults than single disk volumes. From these basic types, "stacked" or "nested" RAID volumes can be created. Stacked RAID sets that make use of mirrored RAID sets are fault-tolerant. For example, these are some of the more common combinations of stacked RAID sets: • RAID 50 - A striped RAID set of hardware RAID 5 disks. • RAID 10 - A striped RAID set of mirrored RAID sets. • RAID 0+1 - A mirrored RAID set of striped RAID sets. • Concatenated Mirror - A concatenation of mirrored RAID sets. When creating new RAID sets or adding disks, if possible, it is better to specify the entire disk instead of a partition on that disk. This allows the software to reformat the entire disk using the most current partition layouts. When using whole disks, the type of parti- tioning used is selected based on the platform type (PPC = APMFormat, Intel = GPTFormat). GPT and APM partition formats cannot be mixed in the same RAID set. In addition to whole disk and partition device names, AppleRAID uses UUIDs to refer to existing RAID sets and their members. Existing RAID sets may also be specified by mount point (e.g. /Volume/raidset). In many cases, using the UUID for the device argument is pre- ferred because disk device names may change over time when disks are added, disks are removed or when the system is rebooted. If RAID members have been physically disconnected from the system or are no longer responding, you must use the member's UUID as the command argument. Messages in the system log will refer to RAID sets and their member disks by UUID. For more information on specifying device arguments see the "DEVICES" section below. AppleRAID is not a replacement for backing up your data. Backups should be always be per- formed on a regular basis and before modifying any RAID set using these commands. The following is a list of raidVerb sub-verbs with their descriptions and individual argu- ments. list [UUID] Display AppleRAID volumes with current status and associated member disks. If UUID is specified, only list that RAID. diskutil listRAID is a deprecated syn- onym for diskutil appleRAID list. create mirror|stripe|concat setName format devices ... Create a new RAID set consisting of multiple disks and/or RAID sets. setName is used for both the name of the created RAID volume and the RAID set itself (as displayed in list). e.g. 'diskutil createRAID stripe MyArray JHFS+ disk1 disk2 disk3 disk4'. Ownership of the affected disks is required. diskutil createRAID is a deprecated synonym for diskutil appleRAID create. delete raidVolume Destroy an existing RAID set. If the RAID set is a mirror with a resizable filesystem, delete will attempt to convert each of the member partitions back into a non-RAID volume while retaining the contained filesystem. For concate- nated RAID sets with a resizable filesystem, delete will attempt to shrink the filesystem to fit on the first member partition and convert that to a non-RAID volume. Ownership of the affected disks is required. diskutil destroyRAID is a deprecated synonym for diskutil appleRAID delete. repairMirror raidVolume newDevice Repair a degraded mirror by replacing a broken or missing member. Broken devices in the mirrored set can also be rebuilt by specifying newDevice. When replacing members of a mirrored set, the new disk must be the same size or larger than the existing disks in the RAID set. Ownership of the affected disk is required. diskutil repairMirror is a deprecated synonym for diskutil appleRAID repairMirror. add type newDevice raidVolume Add a new member or hot spare to an existing RAID set. Type can be either member or spare. New disks are added live, the RAID volume does not need to be unmounted. Mirrored volumes support adding both members and hot spares, concate- nated volumes only support adding members. When adding to a mirrored RAID set, the new disk must be the same size or larger than the existing disks in the RAID set. Adding a hot spare to a mirror will enable autorebuilding for that mirror. Adding a new member to a concatenated RAID set appends the member and expands the RAID volume. Ownership of the affected disk is required. diskutil addToRAID is a deprecated synonym for diskutil appleRAID add. remove oldDevice raidVolume Remove a member or spare from an existing RAID set. Old disks are removed live, the RAID volume does not need to be unmounted. For missing devices, oldDevice must be the device's UUID. Online mirror members with a resizable filesystem will be converted to non-RAID volumes, spare and offline members will be marked free. For concatenated RAID sets, only the last member can be removed. For resizable filesystems remove will first attempt to shrink the concatenated RAID set so that the filesystem fits on the remaining disks. Ownership of the affected disk is required. diskutil removeFromRAID is a deprecated synonym for diskutil appleRAID remove. enable mirror|concat device Convert a non-RAID disk partition containing a resizable filesystem (like JHFS+) into an unpaired mirror or single disk concatenated RAID set. Disks that were originally partitioned on Mac OS X 10.2 Jaguar or earlier or were partitioned to be Mac OS 9 compatible may not be resizable. Ownership of the affected disk is required. diskutil enableRAID is a deprecated synonym for diskutil appleRAID enable. update key value raidVolume Update the key value parameters of an existing RAID set. Valid keys are: • AutoRebuild - If true, the system attempts to rebuild degraded mirrored volumes automatically. When looking for devices for rebuild, AppleRAID first looks for hot spares and then degraded members. Use a value of "1" for true and "0" for false. • SetTimeout - Controls how long the system waits (in seconds) for a missing device before degrading a mirrored raid set. Also controls the amount of time you have to disconnect all devices from an unmounted mirror without degrading it. Ownership of the affected disk is required. diskutil updateRAID is a deprecated synonym for diskutil appleRAID update. DEVICES A device parameter to any of the above commands (except where explicitly required otherwise) is usually any of the following: • The disk identifier (see below). Any entry of the form of disk*, e.g. disk1s9. • The device node entry containing the disk identifier. Any entry of the form of /dev/disk*, e.g. /dev/disk2. • The volume mount point. Any entry of the form of /Volumes/*, e.g. /Volumes/Untitled. • The Universally Unique Identifier or UUID. Any entry of the form of e.g. 11111111-2222-3333-4444-555555555555. DISK IDENTIFIER The disk identifier string variously identifies a device unit, a session upon that device, or a parti- tion (slice) upon that session. It may take the form of diskU, diskUsS, diskUsQ, or diskUsQsS, where U, S, and Q are decimal integers (possibly multi-digit), and where: • U is the device unit. It may refer to hardware (e.g. a hard drive, optical drive, or memory card) or a "drive" constructed by software (e.g. an AppleRAID set or a disk image). • Q is the session and is only included for optical media; it refers to the number of times recording has taken place on the currently-inserted medium (disc). • S is the slice; it refers to a partition. Upon this partition, the raw data that underlies a user-visible file system is usually present, but it may also contain specialized data for certain 3rd-party database programs, or data required for the system software (e.g. EFI or booter partitions, or APM partition map data). Some units (e.g. floppy disks, RAID sets) contain filesystem data upon their "whole" device instead of containing a partitioning scheme with partitions. Note that the forms diskUsQ and diskUsS appear the same and must be distinguished by context. For non- optical media, this two-part form identifies a slice upon which (filesystem) data is stored. For opti- cal media, it identifies a session upon which a partitioning scheme (with its slices with filesystems) is stored. SIZES Wherever a size is to be specified, you can specify absolute values as a decimal number, possibly fol- lowed by a period and a decimal fraction, followed without whitespace with a letter as follows: • B is bytes (not blocks) where the multiplier is 1. • S is 512-byte blocks (device-independent) where the multiplier is 512. • K is power of 10 kilobytes where the multiplier is 1000 (1 x 10^3). • M is power of 10 megabytes where the multiplier is 1000000 (1 x 10^6). • G is power of 10 gigabytes where the multiplier is 1000000000 (1 x 10^9). • T is power of 10 terabytes where the multiplier is 1000000000000 (1 x 10^12). • P is power of 10 petabytes where the multiplier is 1000000000000000 (1 x 10^15). Additionally, in certain contexts, such as when specifying partition triplets, the following relative forms may also be used: • % (with a preceding number) is a percentage of the whole-disk size. • R (with no preceding number) specifies the remainder of the whole-disk size after all other triplets in the group are taken into account. It need not be in the last triplet. It must only appear in at most one triplet in the group of triplets. Note again that B refers to bytes and S refers to 512-byte-blocks; the latter is useful when working with tools such as gpt (8) or df (1). Note also that these 512-byte-blocks are BSD software blocks and not necessarily the same size as the block size actually implemented by the underlying hardware. Examples: 10G (10 gigabytes), 4.23T (4.23 terabytes), 5M (5 megabytes), 25.4% (25.4 percent of whole disk size). FORMAT The format parameter for the erasing and partitioning verbs is the filesystem personality name. You can determine this name by looking in a filesystem bundle's /System/Library/Filesystems/<fs>.fs/Contents/Info.plist or by using the listFilesystems verb, which also lists shortcut aliases for common personalities (these shortcuts are defined by diskutil for use with it only). Common examples include JHFS+, MS-DOS, etc. EXAMPLES Erase a disk diskutil eraseDisk UFS UntitledUFS disk3 Erase a volume diskutil eraseVolume HFS+ UntitledHFS /Volumes/SomeDisk Partition a disk with three partitions diskutil partitionDisk disk3 3 HFS+ Untitled 10G UFS UntitledUFS 10G MS-DOS DOS 10G Partition a disk with the APM partitioning scheme diskutil partitionDisk disk3 APM HFS+ vol1 25% Journaled HFS+ vol2 25% Journaled HFS+ vol3 50% Free Space volX 0% Partition a disk with the GPT partitioning scheme diskutil partitionDisk disk3 GPT HFS+ vol1 25% MS-DOS vol2 25% HFS+ vol3 50% Free Space volX 0% Resize a volume and create a volume after it, using all remaining space diskutil resizeVolume /Volumes/SomeDisk 50g MS-DOS DOS 0b Resize a volume and leave all remaining space as unused diskutil resizeVolume /Volumes/SomeDisk 12g Merge two partitions into a new partition diskutil mergePartitions JHFS+ not disk1s3 disk1s5 Split a partition into three new ones diskutil splitPartition /Volumes/SomeDisk JHFS+ vol1 12g MS-DOS vol2 8g JHFS+ vol3 0b Create a RAID diskutil createRAID mirror MirroredVolume JHFS+ disk1 disk2 Destroy a RAID diskutil destroyRAID /Volumes/MirroredVolume Repair a damaged RAID diskutil repairMirror /Volumes/MirroredVolume disk3 Convert volume into RAID volume diskutil enableRAID mirror /Volumes/ExistingVolume SEE ALSO authopen(1), hdid(8), hdiutil(1), ufs.util(8), msdos.util(8), hfs.util(8), drutil(1), diskarbitrationd(8), mount(8), umount(8), newfs(8), vsdbutil(8), fsck(8) HISTORY The eraseDisk and partitionDisk verbs had an option to add Mac OS 9 drivers (in partitions designated for that purpose); there was also a repairOS9Permissions verb. These have been removed. Starting with Mac OS X 10.6, the input and output notation of disk and partition sizes use power-of-10 suffixes. In the past this has been power-of-2, regardless of the suffix (e.g. G, Gi, GiB) used for display or accepted as input.