macOS: Avoid deviceinterfaced races during DFU reconnect

During Port DFU-to-DFU re-enumeration, macOS deviceinterfaced daemon can
acquire the USB interface first, making idevicerestore time out waiting
for DFU reconnection.

Add experimental flag: --exclusive-usb that keeps deviceinterfaced from
claiming the USB device for the duration of the restore, by booting it
out or repeatedly terminating it when bootout is denied (SIP on), then
reloading and starting it again on exit.

idevicerestore itself does not need to run as root for this. Only the
launchctl subcommands that manage the system-domain deviceinterfaced
daemon (bootout, bootstrap, kickstart, kill) are elevated individually
via sudo, which may prompt for a password on the controlling terminal.
Read-only queries (print) are run unprivileged. Document how to allow
these specific commands via a scoped sudoers(5) NOPASSWD rule for
unattended use.

Co-authored-by: Nikias Bassen <nikias@gmx.li>

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/idevicerestore.1 b/docs/idevicerestore.1
index 633469a..df46dcb 100644
--- a/docs/idevicerestore.1
+++ b/docs/idevicerestore.1
@@ -110,6 +110,46 @@ Use given VARIANT to match the build identity to use, e.g. 'Customer Erase Insta
 Try to continue the restore process after certain errors (like a failed baseband update).
 
 \f[B]WARNING\f[]: This might render the device unable to boot or only partially functioning. \f[B]Use with caution\f[].
+.TP
+.B \-\-exclusive\-usb
+\f[B](macOS only)\f[] Keep the \f[B]deviceinterfaced\f[] system daemon from claiming the
+USB device during Port DFU-to-DFU re-enumeration, which can otherwise cause
+idevicerestore to time out waiting for the device to reconnect.
+
+idevicerestore itself does not need to run as root for this option. The few
+\f[B]launchctl\f[](1) subcommands that manage the system-domain
+\f[B]com.apple.deviceinterfaced\f[] daemon (\f[B]bootout\f[], \f[B]bootstrap\f[],
+\f[B]kickstart\f[], \f[B]kill\f[]) are elevated individually via \f[B]sudo\f[](8), which
+may prompt for your password (or Touch ID, if configured) on the controlling
+terminal. See the \f[B]NOTES\f[] section below for unattended use.
+
+\f[B]EXPERIMENTAL\f[]: only use if you are hitting DFU reconnection timeouts.
+
+.SH NOTES
+.SS Passwordless \-\-exclusive\-usb
+By default, using \f[B]\-\-exclusive\-usb\f[] will prompt for your
+password via \f[B]sudo\f[](8) whenever idevicerestore needs to boot out,
+kickstart, or forcibly terminate the \f[B]com.apple.deviceinterfaced\f[]
+daemon. For unattended/scripted use, you can allow just those specific
+commands to run without a password by adding a narrowly-scoped rule to
+\f[B]sudoers\f[](5), e.g. via \f[B]visudo \-f /etc/sudoers.d/idevicerestore\f[]:
+
+.nf
+.RS
+Cmnd_Alias DEVICEINTERFACED_CTL = \\
+    /bin/launchctl bootout system/com.apple.deviceinterfaced, \\
+    /bin/launchctl bootstrap system /Library/Apple/System/Library/PrivateFrameworks/DeviceInterface.framework/Support/com.apple.deviceinterfaced.plist, \\
+    /bin/launchctl kickstart system/com.apple.deviceinterfaced, \\
+    /bin/launchctl kill SIGKILL system/com.apple.deviceinterfaced
+
+%admin ALL=(root) NOPASSWD: DEVICEINTERFACED_CTL
+.RE
+.fi
+
+Replace \f[B]%admin\f[] with the specific user or group that should be
+allowed to run these commands without a password. This grants no broader
+privileges: only these exact \f[B]launchctl\f[] invocations, against this
+one system daemon, may be run as root without authentication.
 
 .SH AUTHORS
 Martin Szulecki