gistfile1.txt

     coreStorage | cs coreStorageVerb [...]
                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:

                      o   Logical Volume Group (LVG)

                      o   Physical Volume (PV)

                      o   Logical Volume Family (LVF)

                      o   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.

                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) and other services.

                A Logical Volume Family (LVF) exports one or more Logical Vol-
                umes (LVs).

                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
                DEVICES 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 coreStorage sub-verbs with their
                descriptions and individual arguments.

                list [-plist | UUID]
                           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 -plist is specified then a property list will be
                           emitted instead of the formatted tree output; the
                           UUIDs can be used with the diskutil coreStorage
                           information verb to get properties for the object
                           represented by that UUID.  If UUID is specified
                           then an attempt is made to list only that UUID
                           (whatever type of CoreStorage object it may repre-
                           sent).  The -plist and UUID arguments may not both
                           be specified.

                info | information [-plist] UUID | device
                           Display properties of the CoreStorage object (LVG,
                           PV, LVF, or LV) associated with the given CoreStor-
                           age UUID or disk.

                convert device [-stdinpassphrase | -passphrase [passphrase]]
                           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 -passphrase is specified, the on-disk bytes will
                           be encrypted. You will be prompted for a new
                           passphrase interactively, or you can specify the
                           passphrase on the command line. Alternatively, if
                           you specify -stdinpassphrase the standard input is
                           read for the passphrase so that a program could
                           execute diskutil and send the passphrase through a
                           pipe without having to expose it as a command-line
                           parameter.

                           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, diskutil coreStorage convert
                           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 diskutil coreStorage list.

                           When encryption is finished, a 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.

                revert device | lvUUID [-stdinpassphrase] | [-passphrase
                           passphrase] | [-recoverykeychain file]
                           Convert a CoreStorage logical volume back to its
                           native type.  The volume must have been created by
                           means of conversion, e.g. with diskutil coreStorage
                           convert.

                           If the volume was not created with a passphrase,
                           then simple ownership of the affected disk is
                           required; otherwise, a passphrase must be supplied,
                           either interactively or via one of the parameters.

                create lvgName devices ...
                           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.

                delete lvgUUID
                           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+.

                createVolume lvgUUID type name size [-stdinpassphrase |
                           -passphrase [passphrase]]
                           Export a new logical volume family, with a new log-
                           ical volume under it, out of a CoreStorage logical
                           volume group.  Type 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.  Size is the amount of
                           space to allocate from the parent LVG. It is given
                           in the same manner as the triplet description for
                           the partitionDisk verb, and you can also specify
                           with % a percentage of the current size of the LVG.

                           If -passphrase or -stdinpassphrase is specified, in
                           the same manner as with diskutil coreStorage
                           convert above, on-disk data will be stored in an
                           encrypted form as the Logical Volume is filled.

                unlockVolume lvUUID [-stdinpassphrase] | [-passphrase
                           passphrase] | [-recoverykeychain file]
                           Unlock a logical volume and file system, causing it
                           to be attached and mounted.

                           A CoreStorage logical volume family (LVF) contains
                           one or more logical volumes (LVs), grouping the LVs
                           together by security and other future relation-
                           ships.  An LVF can be unencrypted or encrypted (see
                           diskutil coreStorage convert and diskutil
                           coreStorage createVolume above).

                           When encrypted, an LVF can be locked or unlocked.
                           It is locked if a passphrase was specified upon
                           creation, either with diskutil coreStorage
                           createVolume or after conversion has finished in
                           the background as a result of diskutil coreStorage
                           convert.

                           The locked state means that the CoreStorage driver
                           has not been given authentication information (a
                           passphrase) to interpet the encrypted bytes on disk
                           and thus export a dev node.  This verb unlocks an
                           LVF by providing that authentication; as the LVs
                           thus appear as dev nodes, any file systems upon
                           them are automatically mounted. To "re-lock" the
                           volume, make it offline again by ejecting it, e.g.
                           with diskutil eject.

                           Credentials must be supplied. You must either enter
                           a passphrase interactively, specify one of the
                           -passphrase or -stdinpassphrase parameters in the
                           same manner as with diskutil coreStorage convert
                           above, or specify that a recovery keychain file be
                           used.

                           You can specify -recoverykeychain with a path to a
                           keychain file.  The keychain must be unlocked (see
                           security (1)).

                changeVolumePassphrase | passwd lvUUID [-recoverykeychain
                           file] [-oldpassphrase oldpassphrase]
                           [-newpassphrase newpassphrase] [-stdinpassphrase]
                           Change the passphrase of an existing encrypted vol-
                           ume. 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 -oldpassphrase
                           parameter, via the -stdinpassphrase 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 diskutil coreStorage
                           convert above.  Alternatively, you can authenticate
                           by specifying -recoverykeychain with a path to a
                           keychain file.

                           A new passphrase must be supplied, again via one of
                           the three methods above (interactive,
                           -newpassphrase, or -stdinpassphrase).

                           If you are supplying both the old and new
                           passphrases via stdin, they must be separated with
                           a newline character.