In this guide you will learn how to turn you Raspberry Pi or any other linux device into a log capture tool for iPhones and iPads.
The guide simply brings together the hard work from the following sources which are really responsible for all the hard work and clever development. The first thing to do is acknowledge all the clever contributions which makes this possible
In their words...
"A cross-platform FOSS library written in C to communicate with iOS devices natively."
In my words... "The magic needed to connect to the iDevice and make this all possible."
Untether iOS (from new image)
Turn your Raspberry Pi into a remote and fully wireless iPhone log capture device.
With this guide, you can setup a brand new SD Card to turn your Pi into a remote log capture tool.
Get a nice new SD Card (Suggest 8GB to ensure you have space for log captures)
Follow the steps below
Power your Pi from a battery pack
Insert the SD card into your Mac and load the logs into nOversight
An easy way to start fresh is download the Raspberry pi imager from raspberrypi.org/software/
You can follow the tutorial in the video if you need help. Be sure to setup your device for ssh access and give it a name (such as "mydevice.local") and a password.
Once the SD card is flashed, access it via SSH
Once connected to your Pi, get the nMirror script and run it as below
git clone https://github.com/bentumbler/nMirror_iOS.git cd nMirror_iOS chmod +x nMirror.sh ./nmirror.sh
You will be asked some things along the way so just answer them as needed.
Important: Once everything is installed you must initially connect your device via USB first and get a log stream coming in.
/usr/local/bin/idevice_id /usr/local/bin/idevicesyslog -u [ID from previous command]
After that, you should be able to connect to the device via the bluetooth PAN.
Re-run the idevice_id command and if working, you will see the ID of the connected device with (network) at the end. If not, try rebooting the Pi and the device and then reconnect the PAN and try again.
It normally works but has sometimes taken a while to register - we think it is something to do with getting trust for the PI on the device but haven't quite sussed it yet.
Once it works, use the -n switch to access a networked log stream.
/usr/local/bin/idevicesyslog -u [ID from previous command] -n
And to save the logs to a file
/usr/local/bin/idevicesyslog -u [ID from previous command] -n > mylog.log
Untether iOS – Step by Step
Access your rPi (or other linux device) via SSH
ssh pi@[name of pi]
This tutorial assumes you will build everything from source in ~/nMirror
mkdir ~/nMirror cd ~/nMirror
If you need to update the build tools, now is the time
sudo apt-get update sudo apt-get install \ build-essential \ checkinstall \ git \ autoconf \ automake \ libtool-bin \ python-dev
You will need to install the following dependencies
sudo apt-get install \ libplist-dev \ libusbmuxd-dev \ libimobiledevice-dev \ libusb-1.0-0-dev \ libplist++-dev \ libssl-dev \ usbmuxd \ udev \ libavahi-client-dev \ avahi-utils
Clone these repos
libplist is needed at version 2.2.1 (by usbmuxd2 later) which is not tagged so you will have to get the HEAD for now
git clone https://github.com/libimobiledevice/libplist.git cd libplist ./autogen.sh make sudo make install cd ~/nMirror
libusbmuxd is the underlying magic for accessing the iDevice. We've tested it with 2.0.2 (HEAD breaks things at the time of writing)
git clone https://github.com/libimobiledevice/libusbmuxd.git cd libusbmuxd git checkout 2.0.2 ./autogen.sh make sudo make install cd ~/nMirror
libimobiledevice is the amazing library we depend on. Checkout version 1.3.0 as HEAD breaks things at the time of writing.
Please visit and support the amazing team behind this here: https://libimobiledevice.org/
git clone https://github.com/libimobiledevice/libimobiledevice.git cd libimobiledevice git checkout 1.3.0 ./autogen.sh make sudo make install cd ~/nMirror
To make this work over a network connection on Linux, we need the re-implementation of usbmuxd from tihmstar. Please support him too as we would be nowhere without this great work.
He has a general library for all his projects so you will need this first. Checkout 55 as HEAD breaks things at the time of writing
git clone https://github.com/tihmstar/libgeneral.git cd libgeneral git checkout 55 cd ~/nMirror
Now for the reimplementation. No tags so just use HEAD
git clone https://github.com/tihmstar/usbmuxd2.git cd usbmuxd2 git submodule init git submodule update cd ~/nMirror
Make sure all the new links and cache is updated to pickup the latest libs we have been building
Usbmuxd2 needs Avahi running and we used this tutorial Zeroconf mDNS
It works but you may be able to come to a different configuration.
To stick with our approach, ensure the following flags are set in /etc/avahi/avahi-daemon.conf
domain-name=local publish-hinfo=yes publish-workstation=yes
Check the avahi-daemon service is available
systemctl list-unit-files avahi-daemon.service
As per the zeroconf mDNS tutorial, activate the following services
sudo systemctl enable avahi-daemon.service sudo systemctl start avahi-daemon.service
Do the same for ssh although it is likely it is already running (as you are ssh'd into your device)
sudo systemctl enable ssh.service sudo systemctl start ssh.service
We had a ton of trouble getting usbmuxd2 to build and came up with the following approach to install libatomic and put it in the LDFLAGS
sudo apt-get install libatomic-ops-dev libatomic1
Build it with the following flags!
cd /libgeneral ./autogen.sh make CFLAGS="-g -O2 -std=c11 -latomic" LDFLAGS=-latomic sudo make install cd ~/nMirror sudo ldconfig
Now for usbmuxd2
With g++ 8.3.0 on the rPi it does not link the atomic libs. We got around this by patching LDFLAGS in [configure.ac] as below. You can also use clang 9 if you want (authors test are with a clang build).
Note: The order is important -latomic has to be first
huh- it works...
cd usbmuxd2[edit configure.ac]
Now build usbmuxd2 (no need for command line flags as configure.ac has been updated instead)
./autogen.sh make sudo make install sudo ldconfig
Because we want to connect persistently to the iPhone/iPad even when Wi-Fi drops out, we use a BT PAN
This is one way to get is going and (although insecure) avoids the needs for a PIN on your potentially headless rPi
sudo apt-get install bluez-tools
Some BT config stuff to change. You may need to create these files if they do not exist.
[NetDev] Name=pan0 Kind=bridge
[Match] Name=pan0 [Network] Address=172.20.1.1/24 DHCPServer=yes
[Unit] Description=Bluetooth Auth Agent [Service] #ExecStart=/usr/bin/bt-agent -c NoInputNoOutput ExecStart=/bin/sh -c '/usr/bin/yes | /usr/bin/bt-agent --capability=NoInputNoOutput' #autoaccept Type=simple [Install] WantedBy=multi-user.target
[Unit] Description=Bluetooth NEP PAN After=pan0.network [Service] ExecStart=/usr/bin/bt-network -s nap pan0 Type=simple [Install] WantedBy=multi-user.target
Get alll the BT stuff going
sudo systemctl enable systemd-networkd sudo systemctl enable bt-agent sudo systemctl enable bt-network sudo systemctl start systemd-networkd sudo systemctl start bt-agent sudo systemctl start bt-network
And now make it discoverable so you can connect on your i device (you may need to reboot at this point)
sudo bt-adapter --set Discoverable 1
Scan for connected devices with this command:
Now, you are ready to connect and see the logs. You can do this by running this: (for network version you must connect via USB first - its a quirk, go with it)
/usr/local/bin/idevicesyslog -u [number from prev. command] [add -n for network version]
And to save the logs to a file,
/usr/local/bin/idevicesyslog -u [number from prev. command] -n > mylog.log
Check out nOversight
So you are capturing iPhone logs remotely. Now what?
To analyse these logs and see how your iDevice has been making it's network choices, import them into nOversight.