Advertisement
Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- CFGUTIL(1) BSD General Commands Manual CFGUTIL(1)
- NAME
- cfgutil -- Command-line iOS device management
- SYNOPSIS
- cfgutil [-C ] [-K ]
- [-e | -f | --foreach]
- [--format JSON | plist | text] [-v] command [ ...]
- DESCRIPTION
- cfgutil performs various management tasks on one or more attached iOS
- devices. It can be used manually and as part of automated workflows.
- TERMS
- These terms are used throughout the manual and are useful for understand-
- ing the design of cfgutil.
- activation
- The first step of setting up a device after iOS is installed;
- requires an Internet connection. Some devices require a SIM card
- inserted to activate. If used, Activation Lock must be disabled.
- bundle identifier
- A unique name identifying an iOS app, generally in reverse DNS
- format.
- Example: `com.apple.Camera'
- ECID
- A unique identifier of a device which is available even in recov-
- ery mode. Used to select devices.
- configuration profile
- A file containing settings for a device. The extension is
- .mobileconfig.
- IPA
- A file containing an iOS app. The extension is .ipa.
- IPSW
- A file containing an iOS restore image. The extension is .ipsw.
- MobileSync directory
- The directory where backups are stored by iTunes and Apple Con-
- figurator 2:
- ~/Library/Application Support/MobileSync/Backup
- pairing
- Pairing a device requests it to trust the host Mac. Most commands
- require a paired device.
- provisioning profile
- A profile which allows development and enterprise apps to run on
- a device. The extension is .mobileprovision.
- recovery mode/DFU
- A device showing the "connect to iTunes" screen or a black screen
- is in recovery mode. It can be repaired with revive or restore.
- supervision
- A supervised device allows management of additional features
- which can otherwise only be modified on the device itself. Super-
- vised devices recognize host Mac computers through their supervi-
- sion identities. Unlike iOS devices, Apple TV devices always
- accept supervised-only commands, but don't use supervision iden-
- tities.
- supervision identity
- A signing identity (X.509 certificate and private key) used to
- authenticate a host Mac to a supervised device. See EXAMPLES for
- steps to generate an identity.
- tags
- A key-value store on the device which can be used to save identi-
- fying information.
- UDID
- Similar to ECID, a unique identifier for a device which is only
- available when booted into iOS.
- unlock token
- On supervised devices, a key which can be saved and later used to
- clear a passcode. This token must be saved before the device is
- locked, and may be invalidated if the device is erased or the iOS
- software is updated.
- OPTIONS
- Some options take a path to a file as a parameter for input or output.
- For these options, you may pass `-' to read the file from standard input,
- or write the results to standard output.
- IMPORTANT: If you use this for multiple options, the behavior is unde-
- fined.
- Some options take passwords as parameters. Although the password can be
- entered directly, you can pass the name of a file by prefixing it with
- `@':
- --password @password.txt
- You can also pass `-' and a password prompt will be shown. This avoids
- sensitive passwords being shown to other users.
- -C
- The certificate part of the supervision identity. Must be in DER
- format.
- -K
- The private key part of the supervision identity. Must be in DER
- format.
- -e | --ecid
- Selects the device with that ECID on which to apply the given
- command. May be passed more than once to select multiple devices,
- although not all commands support this.
- -f | --foreach
- Selects all attached devices. If neither -e nor -f is passed, the
- first detected device will be selected.
- A few commands always operate on all attached devices, and a few
- commands will error if multiple devices are selected.
- --format JSON | plist | text
- Sets the output format of cfgutil.
- JSON and plist formats output dictionaries with results of each
- command; see JSON OUTPUT.
- Plaintext output format is the default.
- --progress
- Output progress messages in JSON and plist format mode; other-
- wise, they will only ever print one message.
- -v Increases the verbosity.
- COMMANDS
- More information on command options is available from `cfgutil help
- '.
- activate
- Activates devices which are unactivated and displaying the first
- page of Setup Assistant. Fails if the activation server requires
- user interaction, for example if the device is activation locked.
- This step runs as part of prepare.
- add-tags [-u -n ]...
- Add a new tag to the device. UUID and name can be any string.
- The name will be displayed in Apple Configurator 2, while the
- UUID will be used to uniquely identify the tag.
- backup
- Take a backup of a prepared iOS device and stores it under the
- device's UDID in the MobileSync directory. Backups may be taken
- from booted iOS devices which have completed Setup Assistant.
- clear-passcode
- Send an unlock token to a supervised device; the passcode will be
- removed from the device. If there is a passcode policy set on
- the device, you may be required to immediately enter a new one.
- The unlock token path may be - to read from stdin.
- This command only runs on one device at a tine.
- erase | erase-content
- Causes a device to perform Erase All Content and Settings. All
- user data is removed and unrecoverable. The device must first be
- signed out of Find my iPhone. Although devices can also be erased
- by restoring new iOS firmware onto them, this method is much
- faster and does not require updating the OS.
- Devices running iOS 8 or earlier must be supervised to perform
- this action.
- exec [-a | --on-attach <shell command>] [-d | --on-detach <shell
- command>]
- Run a custom command each time a device attaches or detaches.
- There is no filtering on device attach or detach events; for
- example, restoring a device will cause it to detach and attach
- several times in a row. Complex "on attach" scripts should be
- written to exit if a previous attach script is still running for
- the device.
- Script execution is not serialized. A detach script may start as
- an attach is still running and vice versa.
- The --ecid and --foreach global options aren't respected by this
- command.
- When the attach/detach scripts are running, these environment
- variables are set:
- ECID Target device's ECID.
- PATH The path is changed to include cfgutil.
- UDID Target device's UDID, if available.
- deviceName Target device's name, if available. ("iPhone
- 1")
- deviceType Target device's type, if available.
- ("iPhone7,2")
- buildVersion Installed iOS build number, if available.
- ("12B466")
- firmwareVersion
- Installed iOS version, if available.
- ("8.1.3")
- locationID Location ID of the device's USB port.
- ("0x00000001")
- get | get-property
- Fetch various properties of a device.
- To see the possible names of properties, use `cfgutil get
- supportedPropertyNames'.
- To fetch all properties, use `cfgutil get all'.
- In JSON or plist mode, properties are printed as a dictionary
- under Output with ECIDs as keys and properties as values. Addi-
- tionally, if any errors occurred, Output will contain a dictio-
- nary under Error with ECIDs as keys and error descriptions as
- values.
- Some properties will be printed as dictionaries with specific
- keys. These include:
- configurationProfiles
- provisioningProfiles
- apps
- tags
- get-app-icon [--raw] ...
- Save app icons from a single device.
- You can find the bundle identifier for an app with `cfgutil get
- apps'.
- get-icon-layout
- Fetch the home screen layout of a single device and print it as a
- JSON object.
- The entries can be rearranged and used with set-icon-layout. The
- first top-level entry represents the dock, while each later entry
- is one home screen page. Each page contains items that are either
- folders, web clip URLs, or app bundle identifiers. A folder is an
- array where the first entry is the name of the folder.
- get-unlock-token
- Get unlock tokens from supervised devices, for later use by
- clear-passcode. This command can't be used while the device is
- locked, so if you wish to clear passcodes from devices you must
- save the unlock token ahead of time. Unlock tokens may change,
- such as when the device is erased or updated.
- In plaintext mode, these are printed directly to Terminal. JSON
- and plist mode print them per device under the Output key.
- help | usage
- Show the help and options for a command.
- install-app
- Installs the given app (IPA file or enterprise app) on devices.
- Users may need to sign into the App Store on the device with the
- appropriate account for the app to run.
- install-doc | install-document [-s | --sync]
- ...
- Installs the given document(s) in the named app's storage on
- devices. Use the --sync option to sync the document(s) on the
- device using the given document(s) as a sync source. This will
- remove any documents on the device that are not included in the
- passed in documents. Any new source documents will be installed
- and any updated documents will also be updated on the device. Not
- passing this flag will reinstall non-iBooks documents even if an
- identical copy already exists on the device.
- You can find the bundle identifier for an app with `cfgutil get
- apps'.
- install-profile | ...
- Install the given configuration or provisioning profiles on
- devices. Profiles will be installed silently if a supervision
- identity is passed in the general options. On devices running
- iOS 8 or later, profiles are installed silently if the device is
- in Setup Assistant.
- Otherwise, profiles require confirmation on the device before
- installing. When this occurs, cfgutil raises an issue and halts
- any further processes. In this situation, it isn't possible to
- install multiple profiles in one cfgutil command.
- MDM enrollment profiles and profiles with SCEP payloads cannot be
- installed unless the device has already joined a network.
- cfgutil will automatically wait after installing configuration
- profiles containing networks to allow the device to auto-join.
- Some profiles can't be installed silently, such as profiles for
- email accounts if the password is missing. Some profiles can only
- be installed on supervised devices.
- list | list-devices
- List attached devices. In plaintext output, the device type,
- ECID, UDID, USB location ID and name are printed in column format
- and can be parsed with a tool such as awk(1). The --ecid and
- --foreach global options are not respected by this command. It
- always lists all devices.
- list-backups
- List backups available to be restored using restore-backup.
- These backups are stored in the MobileSync directory.
- pair
- Begin pairing with devices.
- If no supervision identity is passed, it is necessary to confirm
- pairing on the device itself by tapping Trust on the pairing dia-
- log.
- prepare
- Applies initial configuration to freshly erased or unconfigured
- devices in Setup Assistant. The devices are activated, have Set-
- up Assistant panes configured, and supervised, depending on the
- options passed.
- To supervise a device, use the --supervised , --name and
- --host-cert options. If supervised, to never pair with another
- host Mac, use the --forbid-pairing option. To use setup-time MDM
- enrollment on the device, use the --mdm-url and --anchor-cert
- options.
- Devices can also automatically skip some Setup Assistant panes.
- For specific skipping options, use `cfgutil help prepare'.
- In order to redo preparation on a device, it must be erased
- beforehand with erase (available with supervised devices),
- restore, or by using Erase All Content and Settings on the
- device.
- Devices enrolled in Apple School Manager or the Device Enrollment
- Program may be automatically configured using --dep. In this
- mode, all non-ASM or non-DEP options have no effect, except for
- --skip-language and --skip-region. Before preparing with ASM or
- DEP, the device must be able to reach your MDM server over a net-
- work connection. To cause devices to join a WLAN network, use
- install-profile before prepare to install a profile with a Wi-Fi
- payload set to auto-join. In this case, the "interactive install
- required" error from install-profile should be ignored.
- remove-app
- Removes the app with the given bundle identifier from attached
- devices.
- remove-profile
- Removes the passed-in configuration and provisioning profiles
- from devices. Parameters may either be the original files, by
- path, or the identifiers of the profiles.
- remove-tags ...
- Remove the tags with the given UUIDs from attached devices.
- rename | set-name
- Set the name on attached devices to the given string.
- restart
- Immediately reboot attached devices. If a passcode is set on a
- device, it will not rejoin Wi-Fi networks or respond to commands,
- including clear-passcode until the passcode is entered.
- restore | update [-I ...]
- Install the latest iOS on attached devices. If a device is
- attached in recovery mode, both restore and update will erase it.
- If you want to install a beta build of iOS onto eligible devices,
- use one -I option for each IPSW file and the appropriate build
- will be used for each device.
- When using this option and targeting all devices, be sure only
- the intended devices are attached to the host Mac to avoid data
- loss. If a device signed into Find my iPhone is restored, you
- will have to clear its activation lock after restoring.
- restore-backup
- Restore a backup of data and settings taken from a device.
- Some private data such as passwords will only be restored if the
- backup was encrypted with a password, or if the device targeted
- is the one who was the original source of the backup. Similarly,
- supervision state and configuration profiles are only restored to
- the original device. Note that using prepare to re-supervise
- devices will not work on the original device in this case, as it
- is already supervised.
- If --source is passed, each device will restore from the backup
- of that name in the MobileSync directory. Otherwise, each device
- will try to restore from the backup named with that device's
- UDID.
- Devices must be erased before a backup can be restored to them.
- revive
- Attempt to rescue a device which is in recovery mode. This com-
- mand attempts to install the latest iOS version on the devices
- without erasing user data. If the command fails, use restore to
- erase the device and make it usable again.
- set-backup-password
- Set or remove a password on the device which will be used to
- encrypt backups. When backups are passworded, more private infor-
- mation including account passwords can be restored onto any other
- device. Otherwise, private information will only be restored onto
- the original device from the backup.
- Removing the backup password requires the original password to be
- entered again, even if the device is supervised.
- shut-down
- Immediately power off attached iOS devices. This command does not
- support Apple TV.
- set-icon-layout
- Set the home screen icon layout on devices, using the JSON format
- from get-icon-layout.
- Unexpected behavior may occur if the given layout does not con-
- tain every icon on the device or contains too many icons for one
- screen.
- syslog
- Display a single device's syslog output. This command runs until
- canceled with ctrl-C. If the device is detached, syslog waits for
- it to reattach.
- unpair
- Remove the pairing to the host Mac from devices. After unpairing,
- most commands won't work on the device until its Trust pairing
- dialog is accepted.
- version
- Show the currently installed version of cfgutil.
- wallpaper [--sourceRect ] [--screen lock | home | both] [--text
- ]
- Set wallpaper on supervised devices. You can use the options to
- crop the original image and overlay text on it.
- GENERATING SUPERVISION IDENTITIES
- A new supervision identity can be generated using the openssl(1) command
- as follows:
- openssl genrsa -out tmp-privkey.pem 2048
- openssl req -new -x509 -key tmp-privkey.pem -out tmp-cert.pem -days
- 3600
- openssl rsa -outform DER -out identity-key.der -in tmp-privkey.pem
- openssl x509 -outform DER -out identity-cert.crt -in tmp-cert.pem
- rm tmp-cert.pem tmp-privkey.pem
- You can export existing signing identities from Apple Configurator 2
- using Preferences > Organizations > Export Identity....
- JSON OUTPUT
- In JSON and plist output modes, cfgutil's output is a dictionary similar
- to the following:
- {"Command":"add-tags","Type":"CommandOut-
- put","Devices":["0x9118908BB6027"]]}
- All dictionaries have a key called Type, which can be used to determine
- the format of the message. Types are:
- CommandOutput The command has succeeded and produced output.
- Command Name of the command.
- Devices List of ECIDs against which the command was run.
- Output A dictionary with ECIDs as keys and command-spe-
- cific output as values. See COMMANDS for spe-
- cific formats.
- Error The command encountered an issue. See DIAGNOSTICS.
- AffectedDevices Devices which encountered this issue.
- UnaffectedDevices Devices which the command was running
- against, but were not affected by this
- issue. Their state is not known.
- Message High level description of the error.
- Detail Detailed description of the error.
- FailureReason Detailed failure reason of the error.
- Domain / Code Specific error code. Support documents
- will refer to errors using these.
- Syslog Output from the syslog command.
- Message A line of text.
- DIAGNOSTICS
- When cfgutil encounters an issue, it stops the command immediately and
- reports which devices were affected by the issue. The state of unaffected
- devices is not guaranteed. After resolving the issue, check their state
- or repeat the command.
- In plaintext mode, error output looks like:
- $ cfgutil install-profile profile.mobileconfig
- cfgutil: error: A profile with the same identifier is already
- installed.
- (Domain: ConfigurationUtilityKit.error Code: 118)
- "install-profile" failed on iPhone (ECID: 0x9118908BB6027).
- --- Summary ---
- Operation "install-profile" failed on 2 devices.
- In JSON or plist mode, cfgutil will output a message of type Error.
- EXIT STATUS
- The cfgutil utility exits 0 on success, and >0 if an error occurs.
- HISTORY
- cfgutil was introduced with Apple Configurator 2.0.
- CAVEATS
- cfgutil doesn't support recovering from issues, while the GUI does.
- Apple Configurator 2 11 August, 2015 Apple Configurator 2
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement