Skip to content

Instantly share code, notes, and snippets.

@applch

applch/diskutil man on macOS 10.13.1 High Sierra

Created November 1, 2017 04:54
Show Gist options
  • Save applch/e949a0135e99ff2154543ea22799de8e to your computer and use it in GitHub Desktop.
Save applch/e949a0135e99ff2154543ea22799de8e to your computer and use it in GitHub Desktop.
Download ZIP
diskutil man
Raw
diskutil man on macOS 10.13.1 High Sierra
DISKUTIL(8) BSD System Manager's Manual DISKUTIL(8)
NNAAMMEE
ddiisskkuuttiill -- modify, verify and repair local disks
SSYYNNOOPPSSIISS
ddiisskkuuttiill [qquuiieett] _v_e_r_b [_o_p_t_i_o_n_s]
DDEESSCCRRIIPPTTIIOONN
ddiisskkuuttiill manipulates the structure of local disks. It provides informa-
tion about, and allows the administration of, the partitioning schemes,
layouts, and formats of disks. This includes hard disks, solid state
disks, optical discs, APFS volumes, CoreStorage volumes, and AppleRAID
sets. It generally manipulates whole volumes instead of individual files
and directories.
VVEERRBBSS
Each verb is listed with its description and individual arguments.
lliisstt [--pplliisstt] [iinntteerrnnaall | eexxtteerrnnaall] [pphhyyssiiccaall | vviirrttuuaall] [_d_e_v_i_c_e]
List disks, including internal and external disks, whole disks
and partitions, and various kinds of virtual or offline disks.
If no argument is given, then all whole disks and their parti-
tions are listed.
You can limit the number of disks shown by specifying filter-
ing arguments such as iinntteerrnnaall above, and/or a _d_e_v_i_c_e disk.
When limiting by a disk, you can specify either a whole disk,
e.g. disk0, or any of its slices, e.g. disk0s3, but filtering
is only done at the whole disk level (disk0s3 is a synonym for
disk0 in this case).
If --pplliisstt is specified, then a property list will be emitted
instead of the normal user-readable output.
A script could interpret the results of ddiisskkuuttiill lliisstt --pplliisstt
and use ddiisskkuuttiill iinnffoo --pplliisstt as well as ddiisskkuuttiill
lliissttFFiilleessyysstteemmss --pplliisstt for more detailed information.
The top-to-bottom appearance of all whole disks is sorted in
numerical order by unit (whole disk) number. However, within
each whole disk's "sublist" of partitions, the ordering indi-
cates actual on-disk location. The first disk item listed rep-
resents the partition which is located most near the beginning
of its encompassing whole disk, and so on.
When viewed this way, the slice (partition) parts of the BSD
disk identifiers may, in certain circumstances, not appear in
numerical order. This is normal and is likely the result of a
recent partition map editing operation in which volumes were
kept mounted.
Note that both human-readable and plist output are sorted as
described above.
See the DDEEVVIICCEESS section below for the various forms that the
_d_e_v_i_c_e specification may take for this and all of the other
ddiisskkuuttiill verbs.
iinnffoo | iinnffoorrmmaattiioonn [--pplliisstt] _d_e_v_i_c_e | --aallll
Get detailed information about a specific whole disk or parti-
tion. If --pplliisstt is specified, then a property list instead of
the normal user-readable output will be emitted. If --aallll is
specified, then all disks (whole disks and their partitions)
are processed.
aaccttiivviittyy
Continuously display system-wide disk manipulation activity as
reported by the Disk Arbitration framework until interrupted
with a signal (e.g. by typing Control-C).
This can be useful to watch system-wide activity of disks com-
ing on-line or being ejected, volumes on disks being mounted
or unmounted, volumes being renamed, etc. However, this out-
put must never be parsed; programs should become Disk Arbitra-
tion clients instead.
For debugging information, such as the monitoring of applica-
tions dissenting (attempting to deny) activities for disks for
which they have registered an interest, you must use the log-
ging features of the ddiisskkaarrbbiittrraattiioonndd daemon. Programs needing
this information must become Disk Arbitration clients.
lliissttFFiilleessyysstteemmss [--pplliisstt]
Show the file system personalities available for formatting in
ddiisskkuuttiill when using the erasing and partitioning verbs. This
is a subset of the complete set of personalities exported by
the various file system bundles that may be installed in the
system. Also shown are some shortcut aliases for common per-
sonalities. See the FFOORRMMAATT section below for more details.
If --pplliisstt is specified, then a property list instead of the
normal user-readable output will be emitted.
uunnmmoouunntt | uummoouunntt [ffoorrccee] _d_e_v_i_c_e
Unmount a single volume. FFoorrccee will force-unmount the volume
(less kind to any open files; see also uummoouunntt (8)).
uunnmmoouunnttDDiisskk | uummoouunnttDDiisskk [ffoorrccee] _d_e_v_i_c_e
Given a disk containing a partition map, unmount all of its
volumes. That is, unmounts are attempted for the map's parti-
tions containing file system volumes, as well as for "virtual"
volumes exported by storage systems which import data from the
map's partitions. Storage systems supported include APFS,
AppleRAID, and CoreStorage.
FFoorrccee will force-unmount the volumes (less kind to any open
files; see also uummoouunntt (8)).
You should specify a whole disk, but all volumes of the whole
disk are attempted to be unmounted even if you specify a par-
tition.
eejjeecctt _d_e_v_i_c_e
Eject a disk. Media will become offline for the purposes of
being a data store for file systems or being a member of con-
structs such as software RAID or direct data. Additionally,
removable media will become eligible for safe manual removal;
automatically-removable media will begin its physical (motor-
ized) eject sequence.
mmoouunntt [rreeaaddOOnnllyy] [--mmoouunnttPPooiinntt _p_a_t_h] _d_e_v_i_c_e
Mount a single volume. If rreeaaddOOnnllyy is specified, then the
file system is mounted read-only, even if the volume's under-
lying 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 rrddoonnllyy option to mmoouunntt (8). If a --mmoouunnttPPooiinntt is speci-
fied, 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.
mmoouunnttDDiisskk _d_e_v_i_c_e
Mount all mountable and UI-browsable volumes on the given par-
tition map; that is, a mount is attempted on the directly-
mountable volume, if any, on each of the whole disk's parti-
tions. However, "virtual" volumes, such as those are implied
by e.g. Core Storage Physical Volumes, AppleRAID Members,
etc., are not handled. You should specify a whole disk, but
all volumes of the whole disk are attempted to be mounted even
if you specify a partition.
rreennaammee | rreennaammeeVVoolluummee _d_e_v_i_c_e _n_a_m_e
Rename a volume. Volume names are subject to file system-spe-
cific alphabet and length restrictions.
eennaabblleeJJoouurrnnaall _d_e_v_i_c_e
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.
ddiissaabblleeJJoouurrnnaall [ffoorrccee] _d_e_v_i_c_e
Disable journaling on an HFS+ volume. This normally works
whether or not the volume is currently mounted (the volume is
temporarily mounted if necessary). If the ffoorrccee 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.
mmoovveeJJoouurrnnaall eexxtteerrnnaall _j_o_u_r_n_a_l_D_e_v_i_c_e _d_e_v_i_c_e
Create a 512MB Apple_Journal partition using the _j_o_u_r_n_a_l_D_e_v_i_c_e
partition to serve as a journal for the volume _d_e_v_i_c_e_. For
best results, _j_o_u_r_n_a_l_D_e_v_i_c_e should be a partition on a differ-
ent whole-disk than the volume itself.
The journal for _d_e_v_i_c_e will be moved externally onto the newly
created Apple_Journal partition.
Since the _j_o_u_r_n_a_l_D_e_v_i_c_e you specify will invariably be larger
than 512MB, a new HFS+ partition will be created following the
Apple_Journal partition to fill the remaining space.
Moving the journal works whether or not the volume is mounted,
provided journaling is enabled on that volume. No errors are
currently supported to flag attempts to move journals on vol-
umes that do not have journaling enabled. If you have multi-
ple volumes for which you want external journals, each must
have its own external Apple_Journal partition. Ownership of
the affected disks is required.
mmoovveeJJoouurrnnaall iinntteerrnnaall _d_e_v_i_c_e
Move the journal for _d_e_v_i_c_e back locally (onto that same
device). Ownership of the affected disk is required.
eennaabblleeOOwwnneerrsshhiipp _d_e_v_i_c_e
Enable ownership of a volume. The on-root-disk Volume Data-
base 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), con-
sideration of ownership settings 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 programs 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 phys-
ical 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 set-
tings, 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(8) command. Running as root is
required.
ddiissaabblleeOOwwnneerrsshhiipp _d_e_v_i_c_e
Disable ownership of a volume. See eennaabblleeOOwwnneerrsshhiipp above.
Running as root is required.
vveerriiffyyVVoolluummee _d_e_v_i_c_e
Verify the file system data structures of a volume. The
appropriate fsck program is executed and the volume is left
mounted or unmounted as it was before the command. Ownership
of the disk to be verified is required.
rreeppaaiirrVVoolluummee _d_e_v_i_c_e
Repair the file system data structures of a volume. The
appropriate fsck program is executed and the volume is left
mounted or unmounted as it was before the command. Ownership
of the affected disk is required.
vveerriiffyyDDiisskk _d_e_v_i_c_e
Verify the partition map layout of a whole disk intended for
booting or data use on a Macintosh. The checks further
include, but are not limited to, the integrity of the EFI Sys-
tem Partition, the integrity of any Core Storage Physical Vol-
ume partitions, and provisioning of space for boot loaders.
Ownership of the disk to be verified is required; it must be a
whole disk and must have a partition map.
rreeppaaiirrDDiisskk _d_e_v_i_c_e
Repair the partition map layout of a whole disk intended for
booting or data use on a Macintosh. The repairs further
include, but are not limited to, the repair or creation of an
EFI System Partition, the integrity of any Core Storage Physi-
cal Volume partitions, and the provisioning of space for boot
loaders. Ownership of the affected disk is required; it must
be a whole disk and must have a partition map.
eerraasseeDDiisskk _f_o_r_m_a_t _n_a_m_e [AAPPMM[[FFoorrmmaatt]] | MMBBRR[[FFoorrmmaatt]] | GGPPTT[[FFoorrmmaatt]]] _d_e_v_i_c_e
Erase an existing disk, removing all volumes and writing out a
new partitioning scheme containing one new empty file system
volume. If the partitioning scheme is not specified, then an
appropriate one for the current machine is chosen. _F_o_r_m_a_t is
discussed below in the section for the ppaarrttiittiioonnDDiisskk verb.
Ownership of the affected disk is required.
eerraasseeVVoolluummee _f_o_r_m_a_t _n_a_m_e _d_e_v_i_c_e
Write out a new empty file system volume (erasing any current
file system volume) on an existing partition. The partition
remains but its data is lost. _F_o_r_m_a_t is discussed below in
the section for the ppaarrttiittiioonnDDiisskk verb.
If you specify FFrreeee SSppaaccee for _f_o_r_m_a_t, the partition itself is
deleted (removed entirely) from the partition map instead of
merely being erased. Ownership of the affected disk is
required.
rreeffoorrmmaatt _d_e_v_i_c_e
Erase an existing volume by writing out a new empty file sys-
tem of the same personality (type) and with the same volume
name. Ownership of the affected disk is required.
eerraasseeOOppttiiccaall [qquuiicckk] _d_e_v_i_c_e
Erase optical media (CD/RW, DVD/RW, etc.). QQuuiicckk specifies
whether the disc recording system software should do a full
erase or a quick erase. Ownership of the affected disk is
required.
zzeerrooDDiisskk [ffoorrccee] _d_e_v_i_c_e
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, zeroed whole-disks will need to be (re)parti-
tioned, or zeroed partitions will need to be (re)formatted
with a file system, e.g. by using the ppaarrttiittiioonnDDiisskk,,
eerraasseeDDiisskk,, or eerraasseeVVoolluummee verbs. If you desire a more sophis-
ticated erase algorithm or if you need to erase only free
space not in use for files, use the sseeccuurreeEErraassee verb. The
ffoorrccee parameter causes best-effort, non-error-terminating,
forced unmounts and shared-mode writes to be attempted; how-
ever, this is still no guarantee against drivers which claim
the disk exclusively. In such cases, you may have to first
unmount all overlying logical volumes (e.g. CoreStorage or
AppleRAID). If a disk is partially damaged in just a certain
unlucky way, you might even have to un-install a kext or erase
the disk elsewhere. Ownership of the affected disk is
required.
rraannddoommDDiisskk [_t_i_m_e_s] _d_e_v_i_c_e
Erase a whole disk, writing random data to the media. _T_i_m_e_s
is the optional (defaults to 1) number of times to write ran-
dom information. The device can be a whole-disk or a parti-
tion. In either case, in order to be useful again, randomized
whole-disks will need to be (re)partitioned, or randomized
partitions will need to be (re)formatted with a file system,
e.g. by using the ppaarrttiittiioonnDDiisskk,, eerraasseeDDiisskk,, or eerraasseeVVoolluummee
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 sseeccuurreeEErraassee verb. Ownership of the affected disk is
required.
sseeccuurreeEErraassee [ffrreeeessppaaccee] _l_e_v_e_l _d_e_v_i_c_e
Erase, using a "secure" (but see the NOTE below) method,
either a whole-disk (including all of its partitions if parti-
tioned), or, only the free space (not in use for files) on a
currently-mounted volume. Secure erasing makes it harder to
recover data using "file recovery" software.
Erasing a whole-disk will leave it useless until it is parti-
tioned again. Erasing freespace on a volume will leave your
files intact, indeed, from an end-user perspective, it will
appear unchanged, with the exception that it will have
attempted to make it impossible to recover deleted files.
If you need to erase all contents of a partition but not its
hosting whole-disk, use the zzeerrooDDiisskk or rraannddoommDDiisskk verbs.
Ownership of the affected disk is required.
_L_e_v_e_l should be one of the following:
++oo 0 - Single-pass zero-fill erase.
++oo 1 - Single-pass random-fill erase.
++oo 2 - US DoD 7-pass secure erase.
++oo 3 - Gutmann algorithm 35-pass secure erase.
++oo 4 - US DoE algorithm 3-pass secure erase.
NOTE: This kind of secure erase is no longer considered safe
because modern devices have wear-leveling, block-sparing, and
possibly-persistent cache hardware. The modern solution for
quickly and securely erasing your data is strong encryption,
with which mere destruction of the key more or less instantly
renders your data irretrievable in practical terms.
ppaarrttiittiioonnDDiisskk _d_e_v_i_c_e [_n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s] [AAPPMM[[FFoorrmmaatt]] | MMBBRR[[FFoorrmmaatt]] |
GGPPTT[[FFoorrmmaatt]]] [_p_a_r_t_1_F_o_r_m_a_t _p_a_r_t_1_N_a_m_e _p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t
_p_a_r_t_2_N_a_m_e _p_a_r_t_2_S_i_z_e _p_a_r_t_3_F_o_r_m_a_t _p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e _._._.]
(re)Partition a disk, removing all volumes. All volumes on
this disk will be destroyed. The _d_e_v_i_c_e parameter specifies
which whole disk is to be partitioned. The optional
_n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s parameter specifies the number of parti-
tions 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:
++oo AAPPMM[[FFoorrmmaatt]] specifies that an Apple Partition Map
scheme should be used. This is the traditional
Apple partitioning scheme used to start up a Pow-
erPC-based Macintosh computer, to use the disk as a
non-startup disk with any Mac, or to create a multi-
platform compatible startup disk.
++oo MMBBRR[[FFoorrmmaatt]] specifies that a Master Boot Record
scheme should be used. This is the DOS/Windows-com-
patible partitioning scheme.
++oo GGPPTT[[FFoorrmmaatt]] 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 file system for-
mat, volume name, and size must be specified. Several other
ddiisskkuuttiill verbs allow these triplets as well (and for them, the
_n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s parameter is also optional). The triplets
must be as follows:
++oo _F_o_r_m_a_t names are of the form jhfs+, HFS+, MS-DOS,
etc.; a list of formattable file systems (more pre-
cisely, specific file system personalities exported
by the installed file system bundles) and common
aliases is available from the lliissttFFiilleessyysstteemmss verb.
_F_o_r_m_a_t guides ddiisskkuuttiill both in what partition type
to set for the partitions (slices) as well as what
file system structures to initialize therein, using
the file system bundle's plist's FormatExecutable
setting which usually points to the appropriate for-
matter program such as newfs_hfs(8).
You can specify a _f_o_r_m_a_t of FFrreeee SSppaaccee to skip an
area of the disk.
You can specify the partition type manually and
directly with a _f_o_r_m_a_t of %<human-readable partition
type>% such as %%AAppppllee__HHFFSS%% or %<GPT partition type
UUID constant>% such as
%%4488446655330000--00000000--1111AAAA--AAAA1111--0000330066554433EECCAACC%%;; these imply
a _n_a_m_e of %%nnooffoorrmmaatt%% (below). Human-readable types
must be known to the system but UUID types (GPT
scheme only) can be arbitrary.
++oo _N_a_m_e_s are the initial volume names; they must con-
form to file system specific restrictions.
If a name of %%nnooffoorrmmaatt%% is specified, then the par-
tition is left blank such that the partition space
is carved out, the partition type is set according
to the file system format name or explicit type, the
partition space is partially erased ("wiped"), but a
file system structure is not initialized with any
file system's formatter program (e.g. newfs_hfs(8);
this is useful for setting up partitions that will
contain user-defined (not necessarily file system)
data.
For a triplet whose _f_o_r_m_a_t is FFrreeee SSppaaccee or a
directly-specified partition type, its _n_a_m_e is
ignored but a dummy name must nevertheless be
present.
++oo _S_i_z_e_s are floating point numbers followed by a let-
ter or percent sign as described in the SSIIZZEESS sec-
tion at the end of this page (e.g. 165536000, 55.3T,
678M, 75%, R).
In addition to explicitly-requested partitions, space (gaps)
might be allocated to satisfy certain filesystems' position
and length alignment requirements; space might be allocated
for possible future booter partition insertion; and indeed,
actual booter partitions might be implicitly created.
In particular, there is a rule that unrecognized partitions
1GiB or larger automatically acquire booters. Thus, if you
create an arbitrary partition with e.g. ddiisskkuuttiill
ppaarrttiittiioonnDDiisskk ddiisskk00 ggpptt %%1111111122222222--11111111--22222222--11111111--111111112222222211111111%%
%%nnooffoorrmmaatt%% 33ggiibb jjhhffss++ UUnnttiittlleedd rr, then a booter partition will
also be created. You can always delete that booter with
ddiisskkuuttiill eerraasseeVVoolluummee ""FFrreeee SSppaaccee"" dduummmmyy ddiisskk00ss33.
The last partition is usually automatically lengthened to the
end of the partition map (disk). You can specify an exact
size for your last partition by specifying it as the penulti-
mate triplet and specifying an additional (last) triplet as
FFrreeee SSppaaccee. Or you can use the RR (remainder) size specifier
for one of your middle partitions while specifying an exact
size for your last partition.
Ownership of the affected disk is required.
rreessiizzeeVVoolluummee _d_e_v_i_c_e [ lliimmiittss | mmaappssiizzee | RR | _s_i_z_e [_n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s]
[_p_a_r_t_1_F_o_r_m_a_t _p_a_r_t_1_N_a_m_e _p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t _p_a_r_t_2_N_a_m_e
_p_a_r_t_2_S_i_z_e _p_a_r_t_3_F_o_r_m_a_t _p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e _._._.] ]
Non-destructively resize a volume (partition); you may
increase or decrease its size. Alternatively, takes no action
and prints some info.
A _s_i_z_e of lliimmiittss takes no action, but instead will print the
range of valid values for the target partition, taking into
account current file system and partition map conditions such
as files in use and other (immovable) partitions following the
target.
A _s_i_z_e of mmaappssiizzee takes no action, but instead will print the
size of the encompassing whole-disk device, as well as the
size of the entire partition map (all partitions less map
overhead). The whole-disk device might be larger than the par-
tition map if the whole-disk device has grown since the parti-
tion map was created. Growing a whole-disk device is possible
with certain enterprise disk (RAID) systems.
You can grow a volume (partition) (back) to its maximum size
possible, provided no new partitions have been created that
are in the way, by specifying RR for the new volume size. You
should use RR instead of attempting an absolute value such as
110000%% because the latter cannot count partition map overhead.
When decreasing the size, new partitions may optionally be
created to fill the newly-freed space. To do this, specify
the _n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s_, _f_o_r_m_a_t_, _n_a_m_e_, and _s_i_z_e parameters in
the same manner as the triplet description for the
ppaarrttiittiioonnDDiisskk verb.
Resizing a volume that is currently set as the computer's
startup disk will invalidate that setting; use the SSttaarrttuupp
DDiisskk System Preferences panel or bblleessss (8) to reset the
resized volume as the startup disk.
_D_e_v_i_c_e refers to a volume; the volume's file system must be
journaled HFS+. Valid ssiizzeess are a number followed by a capi-
tal letter multiplier or percent sign suffix as described in
the SSIIZZEESS section at the end of this page (e.g. 1.5T, 128M,
50%). Ownership of the affected disk is required.
sspplliittPPaarrttiittiioonn _d_e_v_i_c_e [_n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s] [_p_a_r_t_1_F_o_r_m_a_t _p_a_r_t_1_N_a_m_e
_p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t _p_a_r_t_2_N_a_m_e _p_a_r_t_2_S_i_z_e _p_a_r_t_3_F_o_r_m_a_t
_p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e _._._.]
Destructively split a volume into multiple partitions. You
must supply a list of new partitions to create in the space of
the old partition; specify these with the _n_u_m_b_e_r_O_f_P_a_r_t_i_t_i_o_n_s_,
_f_o_r_m_a_t_, _n_a_m_e_, and _s_i_z_e parameters in the same manner as the
triplet description for the ppaarrttiittiioonnDDiisskk verb.
For one of your triplets, you can optionally specify the RR
meta-size in lieu of a constant number value for the _s_i_z_e
parameter: the substituted value will be exactly the amount of
space necessary to complete the re-filling of the original
partition with all of your triplets.
_D_e_v_i_c_e refers to a volume. Ownership of the affected disk is
required.
mmeerrggeePPaarrttiittiioonnss [ffoorrccee] _f_o_r_m_a_t _n_a_m_e _f_r_o_m_D_e_v_i_c_e _t_o_D_e_v_i_c_e
Merge two or more partitions on a disk. All data on merged
partitions other than the first will be lost. Data on the
first partition will be lost as well if the ffoorrccee argument is
given.
If ffoorrccee is not given, and the first partition has a resizable
file system (e.g. JHFS+), the file system will be preserved
and grown in a data-preserving manner; your _f_o_r_m_a_t and _n_a_m_e
parameters are ignored in this case. If ffoorrccee is not given,
and the first partition is not resizable, you are prompted if
you want to format. You will also be prompted to format if
the first partition has an (HFS) Allocation Block Size which
is too small to support the required growth of the first par-
tition; see the --bb option for nneewwffss__hhffss (8).
If ffoorrccee is given, the final resulting partition is always
(re)formatted. You should do this if you wish to (re)format to
a new file system type. You will be prompted to confirm.
_F_o_r_m_a_t and _n_a_m_e must always be given, but they have an effect
only when ffoorrccee is given.
Merged partitions are required to be ordered sequentially on
disk (see ddiisskkuuttiill lliisstt for the actual on-disk ordering). All
partitions in the range, except for the first one, must be
unmountable. Ownership of the affected disk is required.
AAPPFFSS | aapp _a_p_f_s_V_e_r_b [...]
Apple APFS is a system of virtual volumes. APFS verbs can be
used to create, manipulate and destroy APFS Containers and
their APFS Volumes. Apple APFS defines these types of
objects:
++oo Container - An APFS Container imports one or more
APFS Physical Store disks and exports zero or more
APFS Volume disks. Zero or more APFS Containers can
exist in (might be attached to) the system at any
one time.
While attached, the "handle" by which an APFS Con-
tainer is identified is by its APFS CCoonnttaaiinneerr
RReeffeerreennccee disk (device). You should treat this as an
opaque reference token.
The CCoonnttaaiinneerr RReeffeerreennccee disk is a synthesized whole-
disk which is exported by APFS for identification
purposes only; it has no storage. It is associated
with the AppleAPFSContainerScheme node in the IO
Registry. While APFS Volume device identifiers
appear to be of a related form, you should never use
the Container Reference as a basis to create device
identifiers yourself; use the listing verbs with
their plist options instead.
++oo Physical Store - An APFS Physical Store is a disk
which is imported into (that is, which backs, indeed
defines) an APFS Container. An APFS Container can
import more than one Physical Store, e.g. for
Fusion-style Containers.
An APFS Physical Store disk is not necessarily a
disk from a partition map; it could be e.g. an
AppleRAID Set disk. Therefore, you must never assume
that an APFS Physical Store's disk identifier is a
2-part form such as disk0s2.
++oo Volume - An APFS Volume is an [un]mountable file
system volume which is exported from an APFS Con-
tainer. Zero or more APFS Volumes may be exported
out of an APFS Container.
APFS Volumes have no specified "size" (capacity).
Instead, all APFS Volumes consume capacity out of
the remaining free space of their parent APFS Con-
tainer, consuming or returning such capacity as user
file data is added or deleted. Note that this means
that all Volumes within a Container compete for the
Container's remaining capacity. However, you can
manage Volume allocation with the optional rreesseerrvvee
and qquuoottaa size values.
The optional rreesseerrvvee size requests an assured mini-
mum capacity for an APFS Volume. If successfully
created, the Volume is guaranteed to be able to
store at least this many bytes of user file data.
Note that beyond this, the Volume might be able to
store even more until constrained by reaching zero
free space in its parent Container or by reaching a
quota, if any. You can use a rreesseerrvvee to prevent run-
ning out of capacity due to competition from other
Volumes or from a Container shrink attempt.
The optional qquuoottaa size applies a maximum capacity
to an APFS Volume, placing a limit on the number of
bytes of user file data which can be stored on the
Volume. Note that you might not be able to reach
this limit if its parent Container becomes full
first. You can use a qquuoottaa to enforce accounting or
to manage against "unfair" premature filling-up of
the parent Container due solely to this Volume at
the expense of sibling Volumes.
Efficient file copy cloning (copy-on-write) is sup-
ported (see ccooppyyffiillee (3)'s COPYFILE_CLONE).
Optional file-level encryption is supported.
The format of an APFS Volume's device identifier is
that of a slice disk of a special whole-disk; both
disks are synthesized by APFS. The "whole" identi-
fier number (a positive possibly-multi-digit inte-
ger) is arbitrary, and the "slice" numbers (positive
possibly-multi-digit integers) count up from 1 with
each new Volume. Deleting Volumes may cause gaps in
the numbering until the next eject/attach cycle.
This form appears the same as a partition (map)
scheme and partitions, but it is completely unre-
lated. For example: If "disk3s2" is a Physical
Store defining a Container, then "disk5s1",
"disk5s2", and "disk5s3" might be the Container's
Volumes; "disk5" exists but is never used directly.
Although it has a device node, an APFS Volume's data
may only be accessed through its files; you cannot
open an APFS Volume device node to "directly" access
its on-disk bytes.
++oo Snapshot - An APFS Volume can have zero or more
associated APFS Snapshots. An APFS Snapshot appears
as a read-only copy of its parent APFS Volume at a
frozen moment in time. Snapshots are neither listed
nor discoverable when their Volume is not mounted.
APFS itself has no provision for backing up your data. Back-
ups should be always be performed on a regular basis and
before modifying any APFS Container using these commands.
The following is a list of AAPPFFSS sub-verbs with their descrip-
tions and individual arguments.
lliisstt [--pplliisstt] [_c_o_n_t_a_i_n_e_r_R_e_f_e_r_e_n_c_e_D_e_v_i_c_e]
Display APFS objects as a tree. AFPS Container(s)
are shown with their imported Physical Store(s) and
exported Volume(s).
All currently-attached APFS Containers in the sys-
tem are listed unless you specify a
_c_o_n_t_a_i_n_e_r_R_e_f_e_r_e_n_c_e_D_e_v_i_c_e, which limits the output
to that specific APFS Container family.
If --pplliisstt is specified, then a property list will
be emitted instead of the normal user-readable out-
put.
ccoonnvveerrtt _d_e_v_i_c_e [--ddrryyrruunn]
Non-destructively convert an HFS volume to an APFS
Container with a single APFS Volume. The APFS Con-
tainer can then be manipulated (e.g. adding and
deleting APFS Volumes) as usual. The source HFS
volume can be located on a partition or on a
CoreStorage logical volume (LV); in the latter
case, the CoreStorage logical volume group (LVG) is
dismantled.
Ownership of the affected disks is required.
ccrreeaattee _d_e_v_i_c_e [_d_e_v_i_c_e] _n_a_m_e
Convenience verb which creates an empty APFS Con-
tainer and then adds one APFS Volume with the given
name. The APFS Volume will have default attributes
such as no encryption, no capacity reserve nor
quota, etc. This is a combination of the ddiisskkuuttiill
aappffss ccrreeaatteeCCoonnttaaiinneerr and ddiisskkuuttiill aappffss aaddddVVoolluummee
verbs.
Ownership of the affected disks is required.
ccrreeaatteeCCoonnttaaiinneerr [--mmaaiinn] _d_e_v_i_c_e [--sseeccoonnddaarryy] [_d_e_v_i_c_e]
Create an empty APFS Container. The device(s)
specified become APFS Physical Stores.
If you specify more than one device, a Fusion Con-
tainer is created, with the performance roles
assigned automatically (preferred) unless you use
the --mmaaiinn and --sseeccoonnddaarryy options, in which case,
the secondary disk is assumed by APFS's performance
algorithms to be on "slower" hardware. The sec-
ondary disk is usually not solid solid state, is
usually larger, and is used to store associated
"auxiliary" data such as any Windows partition(s)
for Boot Camp Assistant.
You may then add APFS Volumes with the ddiisskkuuttiill
aappffss aaddddVVoolluummee verb.
Ownership of the affected disks is required.
ddeelleetteeCCoonnttaaiinneerr _c_o_n_t_a_i_n_e_r_R_e_f_e_r_e_n_c_e_D_e_v_i_c_e | _p_h_y_s_i_c_a_l_S_t_o_r_e_D_e_v_i_c_e
[_n_a_m_e]
Destroy an existing APFS Container, including all
of its APFS Volumes. The APFS Volumes are
unmounted first; this process may not succeed if
one or more is busy. If this happens, the operation
is aborted and everything is left intact. Other-
wise, all APFS Volumes are deleted as well as its
APFS Container, and the APFS Container's former
Physical Store disks will be reformatted as HFS;
data on all APFS Volumes will be lost.
You can optionally specify a new _n_a_m_e, or else
"Untitled" will be chosen. If there were multiple
Physical Stores, a space and a number suffix is
added for each.
Specifying an APFS Physical Store activates an
alternate last-resort mode which tries to reclaim
your disk(s) even though they may be unusable due
to being damaged yet un-deletable due to being
busy.
Ownership of the affected disks is required.
rreessiizzeeCCoonnttaaiinneerr _c_o_n_t_a_i_n_e_r_R_e_f_e_r_e_n_c_e_D_e_v_i_c_e | _p_h_y_s_i_c_a_l_S_t_o_r_e_D_e_v_i_c_e
_s_i_z_e [_p_a_r_t_1_F_o_r_m_a_t _p_a_r_t_1_N_a_m_e _p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t
_p_a_r_t_2_N_a_m_e _p_a_r_t_2_S_i_z_e _p_a_r_t_3_F_o_r_m_a_t _p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e
_._._.]
Resize an existing APFS Container by specifying
either an APFS Container Reference (preferred) or
an APFS Physical Store partition, and a proposed
new size. The operation is live, non-destructive,
and does not mount or unmount any APFS Volumes.
If you specify a Container Reference and that Con-
tainer imports more than one Physical Store (e.g.
Fusion), the appropriate Physical Store will be
chosen automatically.
Shrinks are constrained by the amount of data usage
by all APFS Volumes on the APFS Container. Grows
are constrained by the amount of partition map free
space trailing the targeted Physical Store parti-
tion.
When shrinking, new partitions may optionally be
created to fill the newly-freed space. To do this,
specify the _f_o_r_m_a_t_, _n_a_m_e_, and _s_i_z_e parameters in
the same manner as the triplet description for the
ppaarrttiittiioonnDDiisskk verb.
You can specify a _s_i_z_e of zero ((00)) to grow the tar-
geted APFS Physical Store such that all remaining
space is filled to the next partition or the end of
the partition map.
Ownership of the affected disks is required.
aaddddVVoolluummee _c_o_n_t_a_i_n_e_r_R_e_f_e_r_e_n_c_e_D_e_v_i_c_e _f_i_l_e_s_y_s_t_e_m _n_a_m_e
[--ppaasssspprroommpptt] | [--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e] |
[--ssttddiinnppaasssspphhrraassee] [--ppaasssspphhrraasseeHHiinntt _p_a_s_s_p_h_r_a_s_e_H_i_n_t]
[--rreesseerrvvee _r_e_s_e_r_v_e] [--qquuoottaa _q_u_o_t_a] [--rroollee _r_o_l_e_s]
[--nnoommoouunntt] [--mmoouunnttppooiinntt _m_o_u_n_t_p_o_i_n_t]
Add a new APFS Volume to an existing APFS Con-
tainer. Files can then be stored on this newly-cre-
ated APFS Volume.
The _f_i_l_e_s_y_s_t_e_m parameter sets the permanent APFS
personality for this new APFS Volume; you should
specify AAPPFFSS or CCaassee--sseennssiittiivvee AAPPFFSS..
The new APFS Volume will be unencrypted unless you
specify one of the passphrase options, in which
case the volume will be encrypted from the begin-
ning of its existence (as opposed to having encryp-
tion applied later); the user which is added will
be the "Disk User". The optional _p_a_s_s_p_h_r_a_s_e_H_i_n_t is
a user-defined string that can be displayed even
while an encrypted APFS Volume is locked.
APFS Volumes have no fixed size; they allocate
backing store on an as-needed basis. You can spec-
ify the _r_e_s_e_r_v_e parameter to guarantee a minimum
amount of space for your volume; at least that many
bytes will be available for file data. You can
also specify the _q_u_o_t_a parameter to limit your vol-
ume's file usage to a maximum amount; no more than
that many bytes will be available for file data,
even if there is otherwise enough space in the par-
ent APFS Container. You can specify both _r_e_s_e_r_v_e
and _q_u_o_t_a simultaneously; however, the reserve is
not allowed to be larger than the quota.
APFS Volumes can carry certain metadata hint flags;
you can supply the _r_o_l_e parameter with any combina-
tion of one or more of the characters BBRRVV,, or 00 as
a no-op for scripting convenience.
The new APFS Volume is explicitly mounted after
creation; you can specify --nnoommoouunntt to leave it
unmounted or supply a _m_o_u_n_t_p_o_i_n_t for a "custom"
mountpoint path, in which case the directory must
already exist and you must delete the directory
yourself when you unmount.
Ownership of the affected disks is required.
ddeelleetteeVVoolluummee _v_o_l_u_m_e_D_e_v_i_c_e
Remove the given APFS Volume from its APFS Con-
tainer. All of the Volume's data will be lost.
Ownership of the affected disks is required.
eerraasseeVVoolluummee _v_o_l_u_m_e_D_e_v_i_c_e --nnaammee _n_e_w_N_a_m_e [--ppaasssspprroommpptt] |
[--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e] | [--ssttddiinnppaasssspphhrraassee]
[--ppaasssspphhrraasseeHHiinntt _p_a_s_s_p_h_r_a_s_e_H_i_n_t]
Erase the contents of an existing APFS Volume; all
of its data will be lost. Unlike ddiisskkuuttiill aappffss
ddeelleetteeVVoolluummee, the APFS Volume is not removed from
its APFS Container.
The "new" APFS Volume will inherit the APFS file
system type (Case-sensitive or not) but will not
inherit attributes such as name, reserve, quota, or
encryption status.
The "new" APFS Volume be unencrypted, unless you
supply passphrase options in the same manner as
ddiisskkuuttiill aappffss aaddddVVoolluummee in which case it will be
encrypted and initially accessible by the "Disk
User".
If you need more control, you should delete and
(re-)add the Volume instead.
Ownership of the affected disks is required.
cchhaannggeeVVoolluummeeRRoollee | cchhrroollee _v_o_l_u_m_e_D_e_v_i_c_e _r_o_l_e_s
Change the role metadata flag bits of an existing
APFS Volume.
The _r_o_l_e_s should be any combination of one or more
of the characters bbrrvvBBRRVV in much the same manner as
ddiisskkuuttiill aappffss aaddddVVoolluummee above, in which unspecified
flags are left alone, use of lower-case causes
flags to be cleared, and use of upper-case causes
flags to be set. Alternatively, cclleeaarr will remove
all flags, or 00 can be used as a no-op for script-
ing convenience. You should not make any assump-
tions about the usage or legal combinations of role
bits.
Ownership of the affected disks is required.
uunnlloocckkVVoolluummee | uunnlloocckk _v_o_l_u_m_e_D_e_v_i_c_e [--uusseerr ddiisskk | --uusseerr
_c_r_y_p_t_o_U_s_e_r_U_U_I_D | --rreeccoovveerryykkeeyycchhaaiinn _f_i_l_e]
[--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e] | [--ssttddiinnppaasssspphhrraassee]
[--nnoommoouunntt | --mmoouunnttppooiinntt _m_o_u_n_t_p_o_i_n_t] [--vveerriiffyy]
Unlock and mount an encrypted and locked APFS Vol-
ume or verify a passphrase.
If you do not supply the --uusseerr option, then all
cryptographic users on that APFS Volume are
searched for a match; if you supply --uusseerr ddiisskk then
the Disk UUID (which equals the APFS Volume UUID)
user is assumed; if you supply --uusseerr with a UUID
then that specific user is assumed; if you instead
supply --rreeccoovveerryykkeeyycchhaaiinn then the Institutional
Recovery user (see below) is assumed.
You will be prompted interactively for a passphrase
unless you specify a passphrase parameter with
--ppaasssspphhrraassee or pipe your passphrase into stdin and
use --ssttddiinnppaasssspphhrraassee..
As an alternative to a passphrase, you can specify
--rreeccoovveerryykkeeyycchhaaiinn with a full path to a keychain
file if an Institutional Recovery Key has been pre-
viously set up on the APFS Volume. The keychain
must be unlocked; see security(1) and fdesetup(8)
for more information.
You can skip the explicit mounting step or specify
a "custom" mountpoint with the --nnoommoouunntt or
--mmoouunnttppooiinntt options. If you specify your own mount-
point path, it must exist and you must have write
privileges on it.
Specifying --vveerriiffyy will test passphrase correctness
without affecting the locked or unlocked state.
To re-lock the volume, unmount it, e.g. with
ddiisskkuuttiill uunnmmoouunntt or ddiisskkuuttiill aappffss lloocckkVVoolluummee..
Ownership of the affected disks is required.
lloocckkVVoolluummee | lloocckk _v_o_l_u_m_e_D_e_v_i_c_e
Unmount and lock an encrypted unlocked APFS Volume.
This is mostly a synonym for ddiisskkuuttiill uunnmmoouunntt..
Ownership of the affected disks is required.
lliissttCCrryyppttooUUsseerrss | lliissttUUsseerrss [--pplliisstt] _v_o_l_u_m_e_D_e_v_i_c_e
Show all cryptographic users (by their Crypto-
graphic User UUID) that are associated with the
given APFS Volume.
If --pplliisstt is specified, then a property list will
be emitted instead of the normal user-readable out-
put.
cchhaannggeePPaasssspphhrraassee | cchhaannggeeCCrryyppttooUUsseerrPPaasssspphhrraassee | ppaasssswwdd
_v_o_l_u_m_e_D_e_v_i_c_e --uusseerr ddiisskk | _c_r_y_p_t_o_U_s_e_r_U_U_I_D
[--oollddPPaasssspphhrraassee _o_l_d_P_a_s_s_p_h_r_a_s_e |
--oollddSSttddiinnppaasssspphhrraassee] [--nneewwPPaasssspphhrraassee _n_e_w_P_a_s_s_p_h_r_a_s_e
| --nneewwSSttddiinnppaasssspphhrraassee]
Change the passphrase of the given cryptographic
user associated with the given APFS Volume.
The old and new passphrases are specified in the
same manner as ddiisskkuuttiill aappffss aaddddVVoolluummee..
Ownership of the affected disks is required.
sseettPPaasssspphhrraasseeHHiinntt | sseettCCrryyppttooUUsseerrPPaasssspphhrraasseeHHiinntt | hhiinntt
_v_o_l_u_m_e_D_e_v_i_c_e --uusseerr ddiisskk | _c_r_y_p_t_o_U_s_e_r_U_U_I_D --hhiinntt
_h_i_n_t_M_e_s_s_a_g_e | --cclleeaarr
Set or clear an arbitrary hint string to aid recall
of a passphrase for the given cryptographic user
associated with the given APFS Volume.
Ownership of the affected disks is required.
eennccrryyppttVVoolluummee _v_o_l_u_m_e_D_e_v_i_c_e --uusseerr ddiisskk | _e_x_i_s_t_i_n_g_C_r_y_p_t_o_U_s_e_r_U_U_I_D
[--ppaasssspphhrraassee _e_x_i_s_t_i_n_g_O_r_N_e_w_P_a_s_s_p_h_r_a_s_e |
--ssttddiinnppaasssspphhrraassee]
Start "background" encryption of a currently-unen-
crypted APFS Volume.
You can supply an existing cryptographic user UUID,
in which case you must supply its corresponding
passphrase, or you can supply ddiisskk (or the
Disk/Volume UUID) and the corresponding passphrase
of the "Disk User", provided the "Disk User"
already exists.
Alternatively, if no users exist yet on this APFS
Volume, you can still supply ddiisskk (or the Disk/Vol-
ume UUID), and a "Disk User" will be created with a
new passphrase which you supply.
The passphrase, interactive or not, is specified in
the same manner as ddiisskkuuttiill aappffss aaddddVVoolluummee..
Ownership of the affected disks is required.
ddeeccrryyppttVVoolluummee _v_o_l_u_m_e_D_e_v_i_c_e
Start "background" decryption of a currently-
encrypted APFS Volume. No crypto credentials are
required, but the APFS Volume must be unlocked.
Ownership of the affected disks is required.
aapppplleeRRAAIIDD | aarr _r_a_i_d_V_e_r_b [...]
AppleRAID verbs can be used to create, manipulate and destroy
AppleRAID volumes (Software RAID). AppleRAID supports three
basic types of RAID sets:
++oo "stripe" - Striped Volume (RAID 0)
++oo "mirror" - Mirrored Volume (RAID 1)
++oo "concat" - Concatenated Volume (Spanning)
Of these three basic types, only the "mirror" type increases
fault-tolerance. Mirrors may have more than two disks to fur-
ther 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:
++oo RAID 50 - A striped RAID set of hardware RAID 5
disks.
++oo RAID 10 - A striped RAID set of mirrored RAID sets.
++oo RAID 0+1 - A mirrored RAID set of striped RAID sets.
++oo 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 partitioning 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. _/_V_o_l_u_m_e_/_r_a_i_d_s_e_t). In many cases, using the UUID
for the device argument is preferred 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 spec-
ifying device arguments, see the DDEEVVIICCEESS section below.
AppleRAID is not a replacement for backing up your data.
Backups should be always be performed on a regular basis and
before modifying any RAID set using these commands.
The following is a list of aapppplleeRRAAIIDD sub-verbs with their
descriptions and individual arguments.
lliisstt [--pplliisstt | _U_U_I_D]
Display AppleRAID volumes with current status and
associated member disks. If _U_U_I_D is specified,
only list the RAID set with that AppleRAID Set
UUID. If --pplliisstt is specified, then a property list
will be emitted instead of user-formatted output.
The --pplliisstt and _U_U_I_D arguments may not both be spec-
ified. ddiisskkuuttiill lliissttRRAAIIDD and ddiisskkuuttiill cchheecckkRRAAIIDD
are deprecated synonyms for ddiisskkuuttiill aapppplleeRRAAIIDD
lliisstt..
ccrreeaattee mmiirrrroorr | ssttrriippee | ccoonnccaatt _s_e_t_N_a_m_e _f_o_r_m_a_t _d_e_v_i_c_e_s _._._.
Create a new RAID set consisting of multiple disks
and/or RAID sets. _s_e_t_N_a_m_e is used for both the
name of the created RAID volume and the RAID set
itself (as displayed in lliisstt). e.g. 'diskutil cre-
ateRAID stripe MyArray JHFS+ disk1 disk2 disk3
disk4'. Ownership of the affected disks is
required. ddiisskkuuttiill ccrreeaatteeRRAAIIDD is a deprecated syn-
onym for ddiisskkuuttiill aapppplleeRRAAIIDD ccrreeaattee..
ddeelleettee _r_a_i_d_V_o_l_u_m_e
Destroy an existing RAID set. If the RAID set is a
mirror with a resizable file system, ddeelleettee will
attempt to convert each of the member partitions
back into a non-RAID volume while retaining the
contained file system. For concatenated RAID sets
with a resizable file system, ddeelleettee will attempt
to shrink the file system to fit on the first mem-
ber partition and convert that to a non-RAID vol-
ume. Ownership of the affected disks is required.
ddiisskkuuttiill ddeessttrrooyyRRAAIIDD is a deprecated synonym for
ddiisskkuuttiill aapppplleeRRAAIIDD ddeelleettee..
rreeppaaiirrMMiirrrroorr _r_a_i_d_V_o_l_u_m_e _n_e_w_D_e_v_i_c_e
Repair a degraded mirror by adding a "new" disk
given as _n_e_w_D_e_v_i_c_e to the RAID mirror set whose
exported disk device or set UUID is given as
_r_a_i_d_V_o_l_u_m_e_. The new disk must be the same size or
larger than the existing disks in the RAID set.
After running this command, you should manually
remove the old (orphaned, failed) member(s) with
ddiisskkuuttiill aapppplleeRRAAIIDD rreemmoovvee.. Ownership of the
affected disk is required. ddiisskkuuttiill rreeppaaiirrMMiirrrroorr
is a deprecated synonym for ddiisskkuuttiill aapppplleeRRAAIIDD
rreeppaaiirrMMiirrrroorr..
aadddd _t_y_p_e _n_e_w_D_e_v_i_c_e _r_a_i_d_V_o_l_u_m_e
Add a new member or hot spare to an existing RAID
set. _T_y_p_e can be either _m_e_m_b_e_r or _s_p_a_r_e. New
disks are added live, the RAID volume does not need
to be unmounted. Mirrored volumes support adding
both members and hot spares, concatenated volumes
only support adding members. When adding to a mir-
rored 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 autore-
building 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. ddiisskkuuttiill aaddddTTooRRAAIIDD is a depre-
cated synonym for ddiisskkuuttiill aapppplleeRRAAIIDD aadddd..
rreemmoovvee _o_l_d_D_e_v_i_c_e _r_a_i_d_V_o_l_u_m_e
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,
_o_l_d_D_e_v_i_c_e must be the device's UUID. Online mirror
members with a resizable file system will be con-
verted to non-RAID volumes, spare and offline mem-
bers will be marked free. For concatenated RAID
sets, only the last member can be removed. For
resizable file systems rreemmoovvee will first attempt to
shrink the concatenated RAID set so that the file
system fits on the remaining disks. Ownership of
the affected disk is required. ddiisskkuuttiill
rreemmoovveeFFrroommRRAAIIDD is a deprecated synonym for ddiisskkuuttiill
aapppplleeRRAAIIDD rreemmoovvee..
eennaabbllee mmiirrrroorr | ccoonnccaatt _d_e_v_i_c_e
Convert a non-RAID disk partition containing a
resizable file system (such as 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. Own-
ership of the affected disk is required. ddiisskkuuttiill
eennaabblleeRRAAIIDD is a deprecated synonym for ddiisskkuuttiill
aapppplleeRRAAIIDD eennaabbllee..
uuppddaattee _k_e_y _v_a_l_u_e _r_a_i_d_V_o_l_u_m_e
Update the _k_e_y _v_a_l_u_e parameters of an existing RAID
set. Valid keys are:
++oo AAuuttooRReebbuuiilldd - 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 _v_a_l_u_e of "1" for true and
"0" for false.
++oo SSeettTTiimmeeoouutt - 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.
ddiisskkuuttiill uuppddaatteeRRAAIIDD is a deprecated synonym for
ddiisskkuuttiill aapppplleeRRAAIIDD uuppddaattee..
ccoorreeSSttoorraaggee | ccss _c_o_r_e_S_t_o_r_a_g_e_V_e_r_b [...]
CoreStorage verbs can be used to create, manipulate and
destroy CoreStorage volumes.
CoreStorage maintains a world of virtual disks, somewhat like
RAID, in which one can easily add or remove imported backing
store disks, as well as exported usable volumes, to or from a
pool (or several pools). This provides the user with flexibil-
ity in allocating their hardware; user or operating system
data can span multiple physical disks seamlessly, for example.
Apple CoreStorage defines four types of objects, instances of
which are uniquely represented by a UUID:
++oo Logical Volume Group (LVG)
++oo Physical Volume (PV)
++oo Logical Volume Family (LVF)
++oo Logical Volume (LV)
The Logical Volume Group (LVG) is the top or "pool" level;
zero or more may exist during any OS boot time session.
An LVG imports one or more Physical Volumes (PVs). A PV repre-
sents a device that feeds the LVG storage space; a PV is nor-
mally real media but it can be a disk image or even an
AppleRAID Set. A disk offered to be a PV must be a partition
and the encompassing scheme must be GPT.
An LVG exports zero or more Logical Volume Families (LVFs). An
LVF contains properties which govern and bind together all of
its descendant Logical Volumes (LVs). These properties provide
settings for Full Disk Encryption (FDE) (such as whether the
LVG is encrypted, which users have access, etc) and other ser-
vices. However, at the present time, for new LVF creation,
only zero or one LVF per LVG is supported.
A Logical Volume Family (LVF) exports one or more Logical Vol-
umes (LVs). However, at the present time, only and exactly
one LV per LVF is supported.
A Logical Volume (LV) exports a dev node, upon which a file
system (such as Journaled HFS+) resides.
For more information on specifying device arguments, see the
DDEEVVIICCEESS section below.
CoreStorage is not a replacement for backing up your data.
Backups should be always be performed on a regular basis and
before modifying any CoreStorage volumes using these commands.
The following is a list of ccoorreeSSttoorraaggee sub-verbs with their
descriptions and individual arguments.
lliisstt [--pplliisstt | _U_U_I_D]
Display a tree view of the CoreStorage world for
all current logical volume groups (LVGs) with mem-
ber disks (PVs) and exported volumes (LVFs and
LVs), with properties and status for each level.
If --pplliisstt is specified then a property list will be
emitted instead of the formatted tree output; the
UUIDs can be used with the ddiisskkuuttiill ccoorreeSSttoorraaggee
iinnffoorrmmaattiioonn verb to get properties for the object
represented by that UUID. If _U_U_I_D is specified
then an attempt is made to list only that UUID
(whatever type of CoreStorage object it may repre-
sent). The --pplliisstt and _U_U_I_D arguments may not both
be specified.
iinnffoo | iinnffoorrmmaattiioonn [--pplliisstt] _U_U_I_D | _d_e_v_i_c_e
Display properties of the CoreStorage object (LVG,
PV, LVF, or LV) associated with the given CoreStor-
age UUID or disk.
ccoonnvveerrtt _d_e_v_i_c_e [--ssttddiinnppaasssspphhrraassee | --ppaasssspphhrraassee [_p_a_s_s_p_h_r_a_s_e]]
Convert a regular Journaled HFS+ or Case-sensitive
Journaled HFS+ volume (must be on a partition and
within a GPT partitioning scheme) into a CoreStor-
age logical volume.
If --ppaasssspphhrraassee is specified, the on-disk bytes will
be encrypted. You will be prompted for a new
passphrase interactively, or you can specify the
_p_a_s_s_p_h_r_a_s_e on the command line. Alternatively, if
you specify --ssttddiinnppaasssspphhrraassee the standard input is
read for the passphrase so that a program could
execute ddiisskkuuttiill and send the passphrase through a
pipe without having to expose it as a command-line
parameter.
The volume is encrypted with an FDE "Disk"
passphrase, which is distinct from the "User" ID
and passphrase combination which FileVault asso-
ciates with a volume. Therefore, if you want to
encrypt a macOS "OS-bearing" volume (with its user
accounts), you must use FileVault in Security Pref-
erences or the contextual menu in the Finder.
The volume must be resizable (the above types are)
and also mounted. Conversion is done live and in-
place; targeting the boot volume is supported; as
much of the conversion as possible is done before
an eject or reboot is necessary.
After slightly shrinking the source volume to make
room for CoreStorage data structures at the end,
its partition type is changed to Apple_CoreStorage
and it becomes a CoreStorage Physical Volume. A
new CoreStorage Logical Volume Group is then cre-
ated with this Physical Volume as the backing
store, followed by the creation of a Logical Volume
Family and Logical Volume pair.
At this point, the new CoreStorage PV/LVG/LVF/LV
stack is ready for use, although the "old" mount-
point must first be unmounted; yet it might not be
unmountable. This will occur if the target (now the
PV) is the current boot volume.
Just before exiting, ddiisskkuuttiill ccoorreeSSttoorraaggee ccoonnvveerrtt
will try to unmount the target disk (which is now
the "old" mount point and the new PV). If success-
ful (target is not the boot disk), the volume now
becomes mounted from the LV. If unsuccessful (tar-
get is the boot disk), a reboot is necessary.
At this point, if no encryption was specified, all
is done. Otherwise, the bytes-on-disk will begin to
be encrypted in-place by CoreStorage automatically
"in the background" while the PV/LVG/LVF/LV stack
continues to be usable. Encryption progress may be
monitored with ddiisskkuuttiill ccoorreeSSttoorraaggee lliisstt..
When encryption is finished, a Disk passphrase will
be required the next time the LV is ejected and re-
attached. If the LV is hosting the boot volume,
this passphrase requirement will thus occur at the
next reboot.
Note that all on-disk data is not secured immedi-
ately; it is a deliberate process of encrypting all
on-disk bytes while the CoreStorage driver keeps
publishing the (usable) LVG/LV.
Ownership of the affected disk is required.
rreevveerrtt _d_e_v_i_c_e | _l_v_U_U_I_D [--ssttddiinnppaasssspphhrraassee] | [--ppaasssspphhrraassee
_p_a_s_s_p_h_r_a_s_e] | [--rreeccoovveerryykkeeyycchhaaiinn _f_i_l_e]
Convert a CoreStorage logical volume back to its
native type. The volume must have been created by
means of conversion, e.g. with ddiisskkuuttiill ccoorreeSSttoorraaggee
ccoonnvveerrtt..
If the volume was not created with a passphrase,
then simple ownership of the affected disk is
required; otherwise, a Disk passphrase must be sup-
plied, either interactively or via one of the
parameters or a keychain file in the same manner as
ddiisskkuuttiill ccoorreeSSttoorraaggee uunnlloocckkVVoolluummee..
ccrreeaattee | ccrreeaatteeLLVVGG _l_v_g_N_a_m_e _d_e_v_i_c_e_s _._._.
Create a CoreStorage logical volume group. The
disks specified will become the (initial) set of
physical volumes; more than one may be specified.
You can specify partitions (which will be re-typed
to be Apple_CoreStorage) or whole-disks (which will
be partitioned as GPT and will contain an
Apple_CoreStorage partition). The resulting LVG
UUID can then be used with createVolume below. All
existing data on the drive(s) will be lost. Owner-
ship of the affected disk is required.
ddeelleettee | ddeelleetteeLLVVGG _l_v_g_U_U_I_D | _l_v_g_N_a_m_e
Delete a CoreStorage logical volume group. All log-
ical volume families with their logical volumes are
removed, the logical volume group is destroyed, and
the now-orphaned physical volumes are erased and
partition-typed as Journaled HFS+.
rreennaammee | rreennaammeeLLVVGG _l_v_g_U_U_I_D | _l_v_g_N_a_m_e _n_e_w_N_a_m_e
Rename a CoreStorage logical volume group. Do not
confuse this name with the LV name or the volume
name of the file system volume on the LV.
ccrreeaatteeVVoolluummee | ccrreeaatteeLLVV _l_v_g_U_U_I_D | _l_v_g_N_a_m_e _t_y_p_e _n_a_m_e _s_i_z_e
[--ssttddiinnppaasssspphhrraassee | --ppaasssspphhrraassee [_p_a_s_s_p_h_r_a_s_e]]
Export a new logical volume family, with a new log-
ical volume under it, out of a CoreStorage logical
volume group. _T_y_p_e is the file system personality
to initialize on the new logical volume. Valid
types are Journaled HFS+ or Case-sensitive Jour-
naled HFS+ or their aliases. _S_i_z_e is the amount of
space to allocate from the parent LVG. It is given
in the same manner as the triplet description for
the ppaarrttiittiioonnDDiisskk verb, and you can also specify
with %% a percentage of the currently remaining
unallocated space in the LVG.
If --ppaasssspphhrraassee or --ssttddiinnppaasssspphhrraassee is specified, in
the same manner as with ddiisskkuuttiill ccoorreeSSttoorraaggee
ccoonnvveerrtt above, on-disk data will be stored in an
encrypted form as the Logical Volume is filled;
otherwise, the data will remain plain.
ddeelleetteeVVoolluummee | ddeelleetteeLLVV _l_v_U_U_I_D | _d_e_v_i_c_e
Remove an exported logical volume (and its logical
volume family as appropriate) from a CoreStorage
logical volume group. Any data on that logical vol-
ume will be lost. This operation will thus result
in an increase in free space in the logical volume
group.
It is assumed that the logical volume is used as a
backing store for a file system; therefore, an
unmount attempt is made which must succeed before
the removal of the logical volume is done.
eennccrryyppttVVoolluummee | eennccrryyppttLLVV _l_v_U_U_I_D | _d_e_v_i_c_e [--ssttddiinnppaasssspphhrraassee] |
[--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e]
Begin a live background process of encrypting the
on-disk backing bytes of an existing plain
CoreStorage logical volume (LV).
That is, the on-disk bytes that are backing the
user data are all visited, read, and re-written in
an encrypted form; this process can take a long
time (minutes to hours). This process continues
seamlessly across reboots. The logical volume
remains usable at all times. When this command
returns, the operation will be ongoing; you can
check progress with ddiisskkuuttiill ccoorreeSSttoorraaggee lliisstt..
The entire logical volume family (LVF) is affected
since all LVs in an LVF share the same encryption
settings.
Any new user data written while this background
operation is in progress will be in encrypted form.
Specifying --ppaasssspphhrraassee or --ssttddiinnppaasssspphhrraassee or
interactively entering a passphrase is mandatory;
you do so in the same manner as with ddiisskkuuttiill
ccoorreeSSttoorraaggee ccoonnvveerrtt above.
The volume is encrypted with an FDE "Disk"
passphrase, which is distinct from the "User" ID
and passphrase combination which FileVault asso-
ciates with a volume. Therefore, if you want to
encrypt a macOS "OS-bearing" volume (with its user
accounts), you must use FileVault in Security Pref-
erences or the contextual menu in the Finder.
ddeeccrryyppttVVoolluummee | ddeeccrryyppttLLVV _l_v_U_U_I_D | _d_e_v_i_c_e [--ssttddiinnppaasssspphhrraassee] |
[--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e]
Begin a live background process of decrypting the
on-disk backing bytes of an existing encrypted
CoreStorage logical volume (LV). Bytes are read,
decrypted, and written back to disk in plain form.
The LV must be unlocked before beginning this oper-
ation.
Like as in ddiisskkuuttiill ccoorreeSSttoorraaggee eennccrryyppttVVoolluummee
above, all on-disk bytes are visited and converted,
the process is seamless across reboots, the logical
volume remains usable at all times, the entire log-
ical volume family (LVF) is affected, any new user
data written will be in plain form, and the opera-
tion will be ongoing when this command returns.
Credentials must be supplied; you can use
--ppaasssspphhrraassee or --ssttddiinnppaasssspphhrraassee to supply a Disk
passphrase, or you can specify that a recovery key-
chain file be used, in the same manner as ddiisskkuuttiill
ccoorreeSSttoorraaggee uunnlloocckkVVoolluummee..
uunnlloocckkVVoolluummee | uunnlloocckkLLVV [--nnoommoouunntt] _l_v_U_U_I_D [--ssttddiinnppaasssspphhrraassee] |
[--ppaasssspphhrraassee _p_a_s_s_p_h_r_a_s_e] | [--rreeccoovveerryykkeeyycchhaaiinn _f_i_l_e]
Unlock a logical volume and file system, causing it
to be attached and mounted.
Data is then accessible in plain form to the file
system and applications, while the on-physical-disk
backing bytes remain in encrypted form.
The locked state means that the CoreStorage driver
has not been given authentication information (a
passphrase) to interpret the encrypted bytes on
disk and thus export a dev node. This verb unlocks
a logical volume family (LVF) and its logical vol-
umes (LVs) by providing that authentication; as the
LVs thus appear as dev nodes, any file systems upon
them are automatically mounted unless the --nnoommoouunntt
option is given.
To re-lock the volume, make it offline again by
ejecting it, e.g. with ddiisskkuuttiill eejjeecctt..
Credentials must be supplied. You must either sup-
ply a Disk passphrase interactively, with one of
the --ppaasssspphhrraassee or --ssttddiinnppaasssspphhrraassee parameters in
the same manner as with ddiisskkuuttiill ccoorreeSSttoorraaggee
ccoonnvveerrtt above, or you must specify that a recovery
keychain file be used.
You can specify --rreeccoovveerryykkeeyycchhaaiinn with a path to a
keychain file. The keychain must be unlocked; see
security(1) for more information.
cchhaannggeeVVoolluummeePPaasssspphhrraassee | ppaasssswwdd _l_v_U_U_I_D [--rreeccoovveerryykkeeyycchhaaiinn
_f_i_l_e] [--oollddppaasssspphhrraassee _o_l_d_p_a_s_s_p_h_r_a_s_e]
[--nneewwppaasssspphhrraassee _n_e_w_p_a_s_s_p_h_r_a_s_e] [--ssttddiinnppaasssspphhrraassee]
Change the Disk passphrase of an existing encrypted
volume. It need not be unlocked nor mounted. The
parameters, while variously optional, must be given
in the above order.
You must authenticate either via the --oollddppaasssspphhrraassee
parameter, via the --ssttddiinnppaasssspphhrraassee parameter (with
newline or eof-terminated data given to stdin), or
via an interactive prompt (if no parameters are
given), in the same manner as ddiisskkuuttiill ccoorreeSSttoorraaggee
ccoonnvveerrtt above. Alternatively, you can authenticate
by specifying --rreeccoovveerryykkeeyycchhaaiinn with a path to a
keychain file.
A new passphrase must then be supplied, again via
one of the three methods above (interactive,
--nneewwppaasssspphhrraassee,, or --ssttddiinnppaasssspphhrraassee))..
If you are supplying both the old and new
passphrases via stdin, they must be separated with
a newline character.
Only the Disk passphrase is supported; you cannot
change credentials for various users that were set
up with FileVault or the Finder; to edit creden-
tials for such users, you should use ffddeesseettuupp (8).
rreessiizzeeVVoolluummee | rreessiizzeeLLVV _l_v_U_U_I_D | _d_e_v_i_c_e _s_i_z_e
Resize a logical volume (LV). If you shrink an LV,
more space becomes available in its logical volume
group (LVG); if you grow an LV, less space becomes
available. You can check the free space with
ddiisskkuuttiill ccoorreeSSttoorraaggee lliisstt.. The file system volume
which resides inside the LV is grown or shrunk as
needed.
You can specify a _s_i_z_e of zero ((00)) to fill up all
remaining space in the parent LVG with the given
LV.
rreessiizzeeDDiisskk | rreessiizzeePPVV _p_v_U_U_I_D _s_i_z_e [_p_a_r_t_1_F_o_r_m_a_t _p_a_r_t_1_N_a_m_e
_p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t _p_a_r_t_2_N_a_m_e _p_a_r_t_2_S_i_z_e
_p_a_r_t_3_F_o_r_m_a_t _p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e _._._.]
Resize a physical volume (PV). If you shrink a PV,
less space becomes available in its logical volume
group (LVG); if you grow a PV, more space becomes
available. The partition in which the PV resides is
changed to accommodate, and the associated booter
partition, if present, is automatically moved.
Note that you cannot ordinarily grow a PV unless
there is free space in the partition map beyond it;
note also that you cannot ordinarily shrink a PV
unless the LVG has some free space in it (e.g. by
shrinking an overlying LV first).
When decreasing the size (shrinking), new parti-
tions may optionally be created to fill the newly-
freed space. To do this, specify the _f_o_r_m_a_t_, _n_a_m_e_,
and _s_i_z_e parameters in the same manner as the
triplet description for the ppaarrttiittiioonnDDiisskk verb.
You can specify a _s_i_z_e of zero ((00)) to fill up all
remaining space to the next partition or the end of
the partition map, if possible.
rreessiizzeeSSttaacckk _l_v_U_U_I_D | _d_e_v_i_c_e [_p_v_U_U_I_D] _s_i_z_e [_p_a_r_t_1_F_o_r_m_a_t
_p_a_r_t_1_N_a_m_e _p_a_r_t_1_S_i_z_e _p_a_r_t_2_F_o_r_m_a_t _p_a_r_t_2_N_a_m_e _p_a_r_t_2_S_i_z_e
_p_a_r_t_3_F_o_r_m_a_t _p_a_r_t_3_N_a_m_e _p_a_r_t_3_S_i_z_e _._._.]
Combine the actions of ddiisskkuuttiill ccoorreeSSttoorraaggee
rreessiizzeePPVV and ddiisskkuuttiill ccoorreeSSttoorraaggee rreessiizzeeLLVV in the
correct sequence in order to effect a shrink or a
grow in an entire LVG setup.
This is done by making a change to the size of a
logical volume (LV), after or before which (one of
its) physical volume(s) (PV) also changes its size
accordingly. The (HFS) file system "on top of" the
LV and the disk partition "below" the PV, as well
as the location of the PV's associated booter par-
tition, are automatically adjusted.
When decreasing the size (shrinking), new parti-
tions may optionally be created to fill the newly-
freed space. To do this, specify the _f_o_r_m_a_t_, _n_a_m_e_,
and _s_i_z_e parameters in the same manner as the
triplet description for the ppaarrttiittiioonnDDiisskk verb.
Since an LVG might have one (e.g. Full Disk Encryp-
tion (FDE), aka FileVault), two (e.g. Fusion), or
even three (certain Boot Camp configurations) PVs,
a specific PV must be chosen. You can have this
command choose one for you, or you can specify the
PV UUID directly. If you do not specify a PV, the
one which has previously been marked for this pur-
pose is used; if no mark, a policy algorithm is
applied.
If your new LV size represents a grow of the exist-
ing LV size, then the PV size will take up more
space on disk, thus creating a larger LVG for the
larger LV to live in. If your new LV size repre-
sents a shrink, then the PV size will take up less
space on disk, thus creating a smaller LVG, which
is enough for the smaller LV to live in. The magni-
tude of the size change you specify (which is for
the LV) causes an exact size change in the PV if
you conform to partition rounding (alignment)
restrictions; the corresponding LV change may be
greater because it is under additional alignment
restrictions imposed by CoreStorage and HFS.
The "spilling over" of size change effects from one
PV onto another is not supported; only and exactly
one PV is affected by this operation. Grows or
shrinks whose effects don't "fit" the designated PV
will result in an error message and no effect. For
example, you can't do a shrink on a multi-PV setup
such that the designated PV should shrink to zero
size and so effectively should disappear. Nor can
you do a grow which would necessitate the growth of
some other PV or the addition of new PVs.
As in ddiisskkuuttiill ccoorreeSSttoorraaggee rreessiizzeePPVV, note that you
cannot grow unless there is free space in the par-
tition map beyond the designated PV, which is not
normally the case because you usually don't leave
gaps of free space on your disk.
You can specify a _s_i_z_e of zero ((00)) to fill up all
remaining space to the partition following the des-
ignated PV's booter or to the end of the partition
map, if possible.
DDEEVVIICCEESS
A device parameter for any of the above commands (except where explicitly
required otherwise) can usually be any of the following:
++oo The ddiisskk iiddeennttiiffiieerr (see below). Any entry of the form of
_d_i_s_k_*, e.g. _d_i_s_k_1_s_9.
++oo The device node entry containing the ddiisskk iiddeennttiiffiieerr. Any
entry of the form of _/_d_e_v_/_[_r_]_d_i_s_k_*, e.g. _/_d_e_v_/_d_i_s_k_2.
++oo The volume mount point. Any entry of the form of _/_V_o_l_u_m_e_s_/_*,
e.g. _/_V_o_l_u_m_e_s_/_U_n_t_i_t_l_e_d. In most cases, a "custom" mount point
e.g. _/_y_o_u_r_/_c_u_s_t_o_m_/_m_o_u_n_t_p_o_i_n_t_/_h_e_r_e is also accepted.
++oo The URL form of any of the volume mount point forms described
above. E.g. _f_i_l_e_:_/_/_/_V_o_l_u_m_e_s_/_U_n_t_i_t_l_e_d or _f_i_l_e_:_/_/_/.
++oo A UUID. Any entry of the form of e.g.
_1_1_1_1_1_1_1_1_-_2_2_2_2_-_3_3_3_3_-_4_4_4_4_-_5_5_5_5_5_5_5_5_5_5_5_5. The UUID can be a
"media" UUID which IOKit places in an IOMedia node as derived
from e.g. a GPT map's partition UUID, or it can be an AppleRAID
(or CoreStorage) set (LV) or member (PV) UUID.
++oo A volume name, e.g. _U_n_t_i_t_l_e_d. This match is only attempted if
the given device is not of the form _[_/_d_e_v_/_]_[_r_]_d_i_s_k_*, nor
_[_/_V_o_l_u_m_e_s_/_]_*. The match attempt is against the intrinsic vol-
ume label, not against the terminal component, if mounted, of
its mount point.
DDIISSKK IIDDEENNTTIIFFIIEERR
The (BSD) ddiisskk iiddeennttiiffiieerr string variously identifies a physical or logi-
cal device unit, a session (if any) upon that device, a partition (slice)
upon that session (if any), or a virtual logical volume. It may take the
form of _d_i_s_k_U, _d_i_s_k_U_s_S, _d_i_s_k_U_s_Q, or _d_i_s_k_U_s_V, where U, S, Q and V are pos-
itive decimal integers (possibly multi-digit), and where:
++oo _U is the device unit. It may refer to hardware (e.g. a hard
drive, optical drive, or memory card) or a virtual "drive" con-
structed by software (e.g. an AppleRAID Set, disk image,
CoreStorage LV, etc).
++oo _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).
++oo _S is the "slice"; it refers to a partition. Upon this parti-
tion, 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 partitions, booter partitions, APM
partition map data, etc), or, notably, it might contain back-
ing-store physical volumes for AppleRAID, CoreStorage, APFS, or
3rd-party Storage Systems.
++oo _V is an APFS "Volume"; it refers to a virtual logical volume
that is shared out of an APFS Container. For example, if an
Apple_APFS-typed partition is on disk5s2, then disk5s2 is
termed the APFS Physical Store which is imported into an APFS
Container. The APFS Container might then export e.g. disk8s1,
which is termed an APFS Volume, which is mountable as a file
system. Multiple APFS Volumes can be exported from a single
APFS Container.
Some units (e.g. floppy disks, RAID sets) contain file system data upon
their "whole" device instead of containing a partitioning scheme with
partitions.
Note that some of the forms appear the same and must be distinguished by
context. For example, _d_i_s_k_U_s_Q, _d_i_s_k_U_s_S, and _d_i_s_k_U_s_V are all 2-part forms
that can mean different things: For non-optical media, it identifies a
partition (on a partition map) upon which (file system) data is stored;
for optical media, it identifies a session upon which an entire partition
map (with its partitions with file systems) is stored; for an APFS setup,
it identifies an APFS Volume. As another example, in "stacked" cases
(CoreStorage on AppleRAID or APFS on AppleRAID), the 1-part _d_i_s_k_U form
becomes a CoreStorage PV or APFS PhysicalStore, in contrast with the
more-common 2-part form.
It is important for software to avoid relying on numerical ordering of
any of the parts. Activities including but not limited to partition
deletions and insertions, partition resizing, virtual volume deletions
and additions, device ejects and attachments due to media insertion
cycles, plug cycles, authentication lock cycles or reboots, can all cause
(temporary) gaps and non-increments in the numerical ordering of any of
the parts. You must rely on more persistent means of identification, such
as the various UUIDs.
SSIIZZEESS
Wherever a size is emitted as an output, it is presented as a base-ten
approximation to the precision of one fractional decimal digit and a
base-ten SI multiplier, often accompanied by a precise count in bytes.
Scripts should refrain from parsing this human-readable output and use
the --pplliisstt option instead.
Wherever a _s_i_z_e is to be supplied by you as an input, you can provide
values in several different ways, some absolute and some context-sensi-
tive. All suffixes described below are interpreted in a case-insensitive
manner. The BB is optional.
The most common way is to specify absolute values as a decimal number,
possibly followed by a period and a decimal fraction, followed without
whitespace with a suffix as follows:
++oo BB is bbyytteess (not blocks) where the multiplier is 1. This suffix
may be omitted.
++oo KK[[BB]] is power of ten kkiilloobbyytteess where the multiplier is 1000 (1
x 10^3).
++oo MM[[BB]] is power of ten mmeeggaabbyytteess where the multiplier is 1000000
(1 x 10^6).
++oo GG[[BB]] is power of ten ggiiggaabbyytteess where the multiplier is
1000000000 (1 x 10^9).
++oo TT[[BB]] is power of ten tteerraabbyytteess where the multiplier is
1000000000000 (1 x 10^12).
++oo PP[[BB]] is power of ten ppeettaabbyytteess where the multiplier is
1000000000000000 (1 x 10^15).
++oo EE[[BB]] is power of ten eexxaabbyytteess where the multiplier is
1000000000000000000 (1 x 10^18).
You can also use the following suffixes:
++oo SS | UUAAMM ("sectors") is 551122--bbyyttee uunniittss (device-independent)
where the multiplier is always 512.
++oo DDBBSS ("device block size") is the ddeevviiccee--ddeeppeennddeenntt native block
size of the encompassing whole disk, if applicable, where the
multiplier is often 512, but not always; indeed it might not be
a power of two.
++oo KKii[[BB]] is power of two kkiibbiibbyytteess where the multiplier is 1024 (1
x 2^10).
++oo MMii[[BB]] is power of two mmeebbiibbyytteess where the multiplier is 1048576
(1 x 2^20).
++oo GGii[[BB]] is power of two ggiibbiibbyytteess where the multiplier is
1073741824 (1 x 2^30).
++oo TTii[[BB]] is power of two tteebbiibbyytteess where the multiplier is
1099511627776 (1 x 2^40).
++oo PPii[[BB]] is power of two ppeebbiibbyytteess where the multiplier is
1125899906842624 (1 x 2^50).
++oo EEii[[BB]] is power of two eexxbbiibbyytteess where the multiplier is
1152921504606846976 (1 x 2^60).
In certain contexts (e.g. when specifying partition triplets) you can
provide a relative value as follows:
++oo %% (with a preceding number) is a ppeerrcceennttaaggee of the whole-disk
size, the partition map size, or other allocatable size, as
appropriate by context. Use of %% is not supported in all situ-
ations.
++oo RR (with no preceding number) specifies the rreemmaaiinnddeerr of the
whole-disk size or other allocatable 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 among all triplets. Use of RR is not supported in all
situations.
You can provide an operating system-defined constant value as follows:
++oo %%rreeccoovveerryy%% (with no preceding number) is the customary size of
macOS Recovery Partitions.
Note again that BB refers to bytes and SS and UUAAMM refer to a constant mul-
tiplier of 512; the latter are useful when working with tools such as ggpptt
(8) or ddff (1). Note also that this multiplier is not a "block" size as
actually implemented by the underlying device driver and/or hardware, nor
is it an "allocation block", which is a file system's minimum unit of
backing store usage, often formatting-option-dependent.
Examples: 10G (10 gigabytes), 4.23tb (4.23 terabytes), 5M (5 megabytes),
4GiB (exactly 2^32 bytes), 126000 (exactly 126000 bytes), 25.4% (25.4
percent of whole disk size).
FFOORRMMAATT
The _f_o_r_m_a_t parameter for the erasing and partitioning verbs is the file
system personality name. You can determine this name by looking in a
file system bundle's
_/_S_y_s_t_e_m_/_L_i_b_r_a_r_y_/_F_i_l_e_s_y_s_t_e_m_s_/_<_f_s_>_._f_s_/_C_o_n_t_e_n_t_s_/_I_n_f_o_._p_l_i_s_t and looking at
the keys for the FFSSPPeerrssoonnaalliittiieess dictionary, or by using the
lliissttFFiilleessyysstteemmss verb, which also lists shortcut aliases for common per-
sonalities (these shortcuts are defined by ddiisskkuuttiill for use with it
only).
Common examples include JHFS+, JHFSX, MS-DOS, etc, as nicknames for the
canonical forms from the file system bundles such as "Case-sensitive
HFS+".
EEXXAAMMPPLLEESS
Erase a disk
diskutil eraseDisk JHFS+ Untitled disk3
Erase a volume
diskutil eraseVolume HFS+ UntitledHFS /Volumes/SomeDisk
Partition a disk with three partitions
diskutil partitionDisk disk3 3 HFSX Name1 10G JHFS+ Name2 10G MS-DOS
NAME3 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
Convert a disk to Core Storage and encrypt it
diskutil coreStorage convert disk3s2 -passphrase
Shrink your Core Storage PV in order to make space for a Boot Camp volume
subtract desired Windows size from LV size, to be new LV size, i.e. 150g
diskutil coreStorage list
diskutil coreStorage resizeStack _L_V_U_U_I_D _P_V_U_U_I_D 150g ms-dos BOOTCAMP 0
Revert a disk from Core Storage back to plain HFS, possibly decrypting
diskutil coreStorage revert disk5
Create a Core Storage setup "manually"
diskutil coreStorage createLVG LVG1 disk0s2 disk1s2
diskutil cs list
diskutil cs createLV _L_V_G_U_U_I_D jhfs+ LVG1-Vol1 100%
Remove a partition
diskutil eraseVolume Free\ Space not disk0s4
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
Erase a partition and shrink to add an associated Recovery Partition
diskutil splitPartition disk8s2 JHFS+ MacHD R %Apple_Boot% %noformat%
%recovery%
SSEEEE AALLSSOO
hdiutil(1), mount(8), umount(8), diskmanagementd(8),
diskmanagementstartup(8), diskarbitrationd(8), corestoraged(8),
fdesetup(8), ioreg(8), newfs_hfs(8), fsck_hfs(8), authopen(1),
hfs.util(8), msdos.util(8), ufs.util(8), drutil(1), vsdbutil(8)
EERRRROORRSS
ddiisskkuuttiill will exit with status 0 if successful or 1 if it cannot complete
the requested operation; this includes cases in which usage text is
printed. Before ddiisskkuuttiill returns with status 1, it prints a message
which might include an explanation local to diskutil, an error string
from the DiskManagement or MediaKit frameworks, an underlying POSIX
error, or some combination.
HHIISSTTOORRYY
The eraseDisk and partitionDisk verbs had an option to add Mac OS 9 driv-
ers (in partitions designated for that purpose); there was also a
repairOS9Permissions verb. These have been removed.
Starting with Mac OS X 10.11, the verify- and repairPermissions verbs
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. Starting with Mac OS X 10.11, the BB suffix is
optional even for "bare" numeric values.
Starting with macOS 10.12, the plist output of partitions from ddiisskkuuttiill
lliisstt --pplliisstt is presented in on-disk (not BSD slice) order, as the human-
readable output always has been. This mimics the order of outputs from
programs such as ggpptt (1).
macOS 5 October 2017 macOS
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment