From 6a7f910468e9e1ca34004e8496fc729549f19cde Mon Sep 17 00:00:00 2001 From: Jess Sullivan Date: Tue, 14 Jul 2026 05:02:51 -0400 Subject: [PATCH 1/4] feat(blog): restore SSH/KVM HID post with allowUSBRestrictedMode polarity fix --- ...23-ssh-macos-kvm-hid-accessory-approval.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md diff --git a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md new file mode 100644 index 0000000..f9d6dd5 --- /dev/null +++ b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md @@ -0,0 +1,73 @@ +--- +title: "The tiny SSH trick for letting a USB KVM talk to a locked Mac" +date: "2026-06-23" +description: "A quick macOS tip for allowing a NanoKVM-style USB HID accessory from an SSH session when Screen Sharing is unavailable and the Mac is stuck at the login window." +tags: ["macOS", "hardware", "homelab", "usb-protocol", "kvm", "ssh"] +published: true +slug: "ssh-macos-kvm-hid-accessory-approval" +category: "hardware" +author_slug: "jesssullivan" +--- + +Tiny discovery. + +I was decommissioning a Mac and needed a USB KVM HID device to enumerate before I wiped the machine. The fun part was that the Mac was sitting at the login window, Screen Sharing was not getting me into a usable session, and SSH worked perfectly. + +So naturally the accessory prompt was somewhere I could not click. + +On Apple silicon Mac laptops, macOS can block data for new USB, Thunderbolt, and similar accessories until a console user approves them. That is the right default! It is also a lil awkward when the whole point of the KVM is "please let me reach the console from over here." + +The SSH-side workaround that got me moving was flipping the local accessory restriction preference off. The key name is inverted from the thing you want: `allowUSBRestrictedMode` set to `false` is what disables the restriction and lets the accessory talk without a console click: + +```bash +TARGET="user@mac-on-your-network" + +read -rsp "sudo password for remote Mac: " SUDO_PASS +echo + +printf '%s\n' "$SUDO_PASS" | ssh -tt "$TARGET" \ + "sudo -S -p '' /bin/sh -c ' + /usr/bin/defaults write /Library/Preferences/com.apple.applicationaccess allowUSBRestrictedMode -bool false + /usr/bin/killall cfprefsd 2>/dev/null || true + '" + +unset SUDO_PASS +``` + +Then I rechecked the USB tree: + +```bash +ssh "$TARGET" \ + "/usr/sbin/ioreg -p IOUSB -w0 -l | /usr/bin/grep -E 'USB Product Name|USB Vendor Name|idVendor|idProduct|\\+-o '" +``` + +And the HID side: + +```bash +ssh "$TARGET" \ + "/usr/sbin/ioreg -r -c IOHIDDevice -l -w0 | /usr/bin/grep -E '^\\+-o |\"Product\"|\"Manufacturer\"|\"Transport\"|\"VendorID\"|\"ProductID\"|\"Built-In\"'" +``` + +After that, the NanoKVM showed up as both a USB device and USB HID device. + +Huzzah. + +Two caveats. First, do not put the sudo password in the SSH command line; process listings and shell history are boring places to leak secrets. Second, if this is a managed Mac, the cleaner durable fix is an MDM/Jamf restrictions payload for `allowUSBRestrictedMode`, scoped only as long as you need it. For a one-off decommissioning session, the local preference was enough. + +The flip side: on a Mac whose USB is load-bearing — external SSD scratch for nix and bazel, YubiKeys, darwin artifact builds that have to keep enumerating even when nobody is at the console — you probably want this off *durably*, declared in your MDM payload or nix-managed defaults rather than poked in ad hoc. Same knob, opposite lifetime. + +When done, either wipe the Mac as planned or undo the local override (deleting the key restores the default, so approval prompts come back): + +```bash +read -rsp "sudo password for remote Mac: " SUDO_PASS +echo + +printf '%s\n' "$SUDO_PASS" | ssh -tt "$TARGET" \ + "sudo -S -p '' /usr/bin/defaults delete /Library/Preferences/com.apple.applicationaccess allowUSBRestrictedMode" + +unset SUDO_PASS +``` + +Tiny gate. Useful escape hatch. + +-Jess From 5df09478c48c16c46ed15e3cc794d441210583c8 Mon Sep 17 00:00:00 2001 From: Jess Sullivan Date: Tue, 14 Jul 2026 05:09:23 -0400 Subject: [PATCH 2/4] docs(blog): clarify managed USB restriction path --- src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md index f9d6dd5..cad0961 100644 --- a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md +++ b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md @@ -52,9 +52,9 @@ After that, the NanoKVM showed up as both a USB device and USB HID device. Huzzah. -Two caveats. First, do not put the sudo password in the SSH command line; process listings and shell history are boring places to leak secrets. Second, if this is a managed Mac, the cleaner durable fix is an MDM/Jamf restrictions payload for `allowUSBRestrictedMode`, scoped only as long as you need it. For a one-off decommissioning session, the local preference was enough. +Two caveats. First, do not put the sudo password in the SSH command line; process listings and shell history are boring places to leak secrets. Second, Apple documents the durable control as a device-level `com.apple.applicationaccess` restrictions profile, normally delivered by MDM. The local preference was enough for this one-off decommissioning session, but it is an escape hatch rather than a fleet-enforcement mechanism. -The flip side: on a Mac whose USB is load-bearing — external SSD scratch for nix and bazel, YubiKeys, darwin artifact builds that have to keep enumerating even when nobody is at the console — you probably want this off *durably*, declared in your MDM payload or nix-managed defaults rather than poked in ad hoc. Same knob, opposite lifetime. +The flip side: on a Mac whose USB is load-bearing — external SSD scratch for nix and bazel, YubiKeys, darwin artifact builds that have to keep enumerating even when nobody is at the console — you probably want this off *durably* through that device-level profile rather than poked in ad hoc. Same knob, opposite lifetime. When done, either wipe the Mac as planned or undo the local override (deleting the key restores the default, so approval prompts come back): From 4b316f4e8eed805ac3c42d2d0fa9be0cb262c6c9 Mon Sep 17 00:00:00 2001 From: Jess Sullivan Date: Wed, 15 Jul 2026 07:20:52 -0400 Subject: [PATCH 3/4] blog: reduce KVM post to gist register (operator prose ruling) --- ...23-ssh-macos-kvm-hid-accessory-approval.md | 28 ++++++------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md index cad0961..6a27d1a 100644 --- a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md +++ b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md @@ -9,15 +9,9 @@ category: "hardware" author_slug: "jesssullivan" --- -Tiny discovery. +Quick reference for letting a USB KVM HID device enumerate on a Mac that is sitting at the login window, when Screen Sharing is not usable and SSH is. -I was decommissioning a Mac and needed a USB KVM HID device to enumerate before I wiped the machine. The fun part was that the Mac was sitting at the login window, Screen Sharing was not getting me into a usable session, and SSH worked perfectly. - -So naturally the accessory prompt was somewhere I could not click. - -On Apple silicon Mac laptops, macOS can block data for new USB, Thunderbolt, and similar accessories until a console user approves them. That is the right default! It is also a lil awkward when the whole point of the KVM is "please let me reach the console from over here." - -The SSH-side workaround that got me moving was flipping the local accessory restriction preference off. The key name is inverted from the thing you want: `allowUSBRestrictedMode` set to `false` is what disables the restriction and lets the accessory talk without a console click: +On Apple silicon Mac laptops, macOS blocks data for new USB, Thunderbolt, and similar accessories until a console user approves them. From SSH, the local escape hatch is the `com.apple.applicationaccess` restriction preference. The key name is inverted from the thing you want: `allowUSBRestrictedMode` set to `false` is what disables the restriction and lets the accessory talk without a console click: ```bash TARGET="user@mac-on-your-network" @@ -34,7 +28,7 @@ printf '%s\n' "$SUDO_PASS" | ssh -tt "$TARGET" \ unset SUDO_PASS ``` -Then I rechecked the USB tree: +Recheck the USB tree: ```bash ssh "$TARGET" \ @@ -48,15 +42,15 @@ ssh "$TARGET" \ "/usr/sbin/ioreg -r -c IOHIDDevice -l -w0 | /usr/bin/grep -E '^\\+-o |\"Product\"|\"Manufacturer\"|\"Transport\"|\"VendorID\"|\"ProductID\"|\"Built-In\"'" ``` -After that, the NanoKVM showed up as both a USB device and USB HID device. +The KVM should now enumerate as both a USB device and a USB HID device. -Huzzah. +Notes: -Two caveats. First, do not put the sudo password in the SSH command line; process listings and shell history are boring places to leak secrets. Second, Apple documents the durable control as a device-level `com.apple.applicationaccess` restrictions profile, normally delivered by MDM. The local preference was enough for this one-off decommissioning session, but it is an escape hatch rather than a fleet-enforcement mechanism. +- Do not put the sudo password in the SSH command line; process listings and shell history are boring places to leak secrets. +- Apple documents the durable control as a device-level `com.apple.applicationaccess` restrictions profile, normally delivered by MDM. The local preference is a one-off escape hatch, not fleet enforcement. +- On a Mac whose USB is load-bearing — external SSD scratch for nix and bazel, YubiKeys, darwin artifact builds that have to keep enumerating with nobody at the console — you want this off durably through that device-level profile rather than poked in ad hoc. Same knob, opposite lifetime. -The flip side: on a Mac whose USB is load-bearing — external SSD scratch for nix and bazel, YubiKeys, darwin artifact builds that have to keep enumerating even when nobody is at the console — you probably want this off *durably* through that device-level profile rather than poked in ad hoc. Same knob, opposite lifetime. - -When done, either wipe the Mac as planned or undo the local override (deleting the key restores the default, so approval prompts come back): +When done, either wipe the Mac as planned or undo the local override; deleting the key restores the default, so approval prompts come back: ```bash read -rsp "sudo password for remote Mac: " SUDO_PASS @@ -67,7 +61,3 @@ printf '%s\n' "$SUDO_PASS" | ssh -tt "$TARGET" \ unset SUDO_PASS ``` - -Tiny gate. Useful escape hatch. - --Jess From e5fdc35173a0790c9e2c24673a548905d1217f33 Mon Sep 17 00:00:00 2001 From: Jess Sullivan Date: Wed, 15 Jul 2026 07:24:14 -0400 Subject: [PATCH 4/4] blog: down-tier KVM post to less-noteworthy (operator ruling) --- src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md index 6a27d1a..3a708fa 100644 --- a/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md +++ b/src/posts/2026-06-23-ssh-macos-kvm-hid-accessory-approval.md @@ -7,6 +7,7 @@ published: true slug: "ssh-macos-kvm-hid-accessory-approval" category: "hardware" author_slug: "jesssullivan" +editorial_tier: "less-noteworthy" --- Quick reference for letting a USB KVM HID device enumerate on a Mac that is sitting at the login window, when Screen Sharing is not usable and SSH is.