nMirror

Turn your Raspberry Pi into a wireless iPhone log capture tool

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

libimobiledevice

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

usbmuxd2 by tihmstar

A reimplementation of the original usbmuxd daemon by the libimobiledevice project.

The missing piece needed to make a (wireless) network connection between the iDevice and Raspberry Pi.

Networking Tutorials

Setup of Avahi for zeroconf, headless mDNS in order to make usbmuxd2 work neatly. 

Setup of the BT PAN without the need of a PIN to make the pairing between a headless Raspberry Pi and an iDevice easy.

Untether iOS (from new image)

Posted: August 19, 2021

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

    • Collect logs

    • 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

ssh pi@[name_of_pi.local]

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

Posted: August 26, 2021

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

sudo ldconfig

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]
LDFLAGS+="-latomic -lstdc++fs"

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.

[/etc/systemd/network/pan0.netdev]
[NetDev]
Name=pan0
Kind=bridge
[/etc/systemd/network/pan0.network]
[Match]
Name=pan0

[Network]
Address=172.20.1.1/24
DHCPServer=yes
[/etc/systemd/system/bt-agent.service]
[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
[/etc/systemd/system/bt-network.service]
[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:

/usr/local/bin/idevice_id

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.

Click Here