Configure the Mac mini host for network payload capture

Learn how to configure your local Cloud or Standalone Kobiton Mac mini host so you and your team can use network payload capture (NPC) during a manual session or automation session.

Before you start

You’ll need to:

  • Access the Mac mini host as the deviceconnect user for all the operations below.

  • For iOS devices, decide which option to use for setting up the iOS devices, as each option requires different setup steps for the Mac mini host.

  • Make sure that the current deviceConnect version on the Mac mini hosting the device is at least 4.19.5. Update deviceConnect if the version is lower.

  • Make sure the Mac mini is connected to a network that satisfies the network requirements for Network Payload Capture before proceeding.

Select an option to set up iOS devices for NPC

Network payload traffic from iOS devices is captured by a proxy server. For secure (SSL) traffic, the proxy server’s certificate must be trusted by the devices. On iOS devices, you can establish trust using one of the following options:

Option 1 (default): Supervise devices to install the certificate automatically

This option is recommended for organizations that want an automated solution to import and trust the proxy server certificate. To use this option, the following requirements must be met:

  • A single supervision identity exported into two files: organization.crt and organization.der. Copy both files to the Mac mini host at /usr/local/deviceconnect.

  • Supervise iOS devices either:

    • Automatically through Automated Device Enrollment (requires Apple School Manager or Apple Business Manager).

    • Manually using Apple Configurator.

  • Ensure all devices connected to one Mac mini host are supervised by the same supervision identity. If devices are supervised with an identity that doesn’t match the organization.crt and organization.der files on the Mac mini host, NPC can’t be enabled on those devices.

  • If you supervise devices using Apple Configurator, you must use a Mac that isn’t running Kobiton software (including deviceConnect or deviceShare).

Option 2: Manually import and trust the certificate

  • This option is recommended for organizations that don’t want to supervise devices or that already supervise devices using multiple supervision identities. To use this option, the following requirements must be met:

  • Manually import the proxy server’s SSL certificate to the device and trust it.

  • Install and configure additional software on the Mac mini host:

    • Apple Configurator and its Automation Tools.

    • A trusted SSH connection to localhost.

    • Update the dc.ini file to use option 2.

Comparison: Option 1 vs. Option 2

Feature Option 1: Supervised (default) Option 2: Manual

Certificate deployment

Automatic

Manual, device by device

Recommended for

Organizations wanting automation

Organizations with multiple supervision identities or that don’t want supervision

Setup complexity

Higher (requires supervision setup)

Lower for small groups, but manual per device

Mac mini requirements

organization.crt and organization.der in /usr/local/deviceconnect

Apple Configurator, Automation Tools, SSH to localhost, dc.ini update

Device enrollment

Supervision required via either Automated Device Enrollment (automated) or Apple Configurator (manual)

No supervision required

NPC compatibility

Works only if all devices share the same supervision identity

Works even with multiple supervision identities

Required setup steps

This section applies to both hosting Android and iOS devices.

Mac mini with Apple Silicon: Install Rosetta

Open Terminal on the Mac mini host.

Run the below command to install Rosetta:

softwareupdate --install-rosetta --agree-to-license

Enable NPC in dc.ini file

Edit the dc.ini file from the location /usr/local/deviceconnect/ using any text editor (Create a backup of the dc.ini file prior to making updates).

Check if the below content exists in the file. Otherwise, append the content to the end of the file.

Make sure the below is under the [set] tag, not [config].
# Payload Capture
DeviceNetworkCapture.NetworkCaptureProxyHost=[deviceConnect IP address]
DeviceNetworkCapture.NetworkCaptureProxyIsLocal=true
DeviceNetworkCapture.NetworkCaptureProxyControlPort=8225
DeviceNetworkCapture.NetworkCaptureProxyHttpListenPort=8080
DeviceNetworkCapture.TimeoutConnectSeconds=10
DeviceNetworkCapture.Trace=true
DeviceNetworkCapture.ExternalDebugLog=false

Replace [deviceConnect IP address] with the local IP address of the Mac mini host.

If the Mac mini is connected to more than one network at the same time (for example, both Ethernet and Wi-Fi), make sure [deviceconnect IP address] is the IP address obtained from the interface that is connected to the same network as the mobile devices.

You can retrieve the local IP address(es) of the Mac mini by either:

  • Navigating to Settings > Network > Ethernet or Wi-Fi and copying the IP address value. For Wi-Fi, click the Details… button next to the connected network to view the IP.

  • Opening Terminal, then entering the ifconfig command. The IP address is usually under the en0 entry (for Ethernet) or en1 entry (for Wi-Fi), next to inet.

    example of ifconfig command
    en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
    	options=50b<RXCSUM,TXCSUM,VLAN_HWTAGGING,AV,CHANNEL_IO>
    	ether **:**:**:**:ad:a1
    	inet6 fe80::140b:b7b:e8a0:c90f%en0 prefixlen 64 secured scopeid 0x4
    	inet 192.168.50.86 netmask 0xffffff00 broadcast 192.168.50.255
    
    en1: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
    	options=6460<TSO4,TSO6,CHANNEL_IO,PARTIAL_CSUM,ZEROINVERT_CSUM>
    	ether **:**:**:**:**:19
    	inet6 fe80::1834:8865:82ea:2b5c%en1 prefixlen 64 secured scopeid 0x7
    	inet 192.168.50.118 netmask 0xffffff00 broadcast 192.168.50.255

Save the file, then restart services on the Mac mini host to apply the changes.

If you are only hosting Android devices, you can move on to configure your Android device. The next sections are only required for hosting iOS devices.

Additional setup for hosting iOS devices

Configure the Mac mini host based on the selected option.

Option 1: Verify supervision identity and dc.ini configuration

Access the Mac mini host and open Finder.

Press Shift + Command + G, enter /usr/local/deviceconnect, and press Enter.

  • If the files organization.crt and organization.der are present, the supervision identity already exists.

  • If the files are not present, follow this guide to create and export the supervision identity files on a Mac that is not running Kobiton software, then transfer the files to the Mac mini host.

Open the dc.ini file from /usr/local/deviceconnect/ using a text editor. Create a backup before making changes.

Locate the line IOSDeviceController.WifiCaptureProxyAutomation=ui.

  • If the line does not exist, add IOSDeviceController.WifiCaptureProxyAutomation=profile.

  • If the line exists, change it to IOSDeviceController.WifiCaptureProxyAutomation=profile

Restart deviceConnect services to apply the changes.

Option 2: Establish a trusted SSH connection and install Automation Tools

Access the Mac mini host.

Check for an existing SSH key

In the terminal, ensure the .ssh directory exists, then list its contents.

mkdir -p ~/.ssh
cd ~/.ssh && ls -a

If the file id_rsa is present, proceed to modifying the SSH key. If not, continue to generate a new key.

Generate a new SSH key

In the .ssh directory, enter the following command:

ssh-keygen -t rsa

Leave the passphrase empty and press Enter when prompted.

> Enter passphrase (empty for no passphrase): [Leave empty]
> Enter same passphrase again: [Leave empty]

Modify the SSH key

Copy the contents of the id_rsa.pub file into the authorized_keys file:

cat id_rsa.pub >> ./authorized_keys
If authorized_keys does not exist, the command creates it automatically.

Log in using the SSH key. If prompted to trust the connection, type yes and press Enter.

ssh 127.0.0.1

After successfully logging in, exit the session and restart the Mac mini host:

exit && sudo shutdown -r now

Install Automation Tools from Apple Configurator

After the restart, access the Mac mini host.

Open the App Store, search for Apple Configurator, and install it. An Apple ID is required.

Apple Configurator in the Mac App Store

Open Apple Configurator. From the menu bar, select Apple Configurator > Install Automation Tools.

The Install Automation Tools option under the Apple Configurator menu bar

When prompted, select Install and provide the administrator password.

The Install Automation Tools confirmation pop-up

After installation, close Apple Configurator. It does not need to remain open for network payload capture.

Add dc.ini configuration

Open the dc.ini file from /usr/local/deviceconnect/ using a text editor. Create a backup before making changes.

Locate the line that begins with IOSDeviceController.WifiCaptureProxyAutomation.

  • If the line does not exist, add the following to the end of the file:

    IOSDeviceController.WifiCaptureProxyAutomation=ui
  • If the line exists, confirm that it matches exactly the above. Update it if necessary.

Restart deviceConnect services to apply the changes.

Next steps

Configure the Android and iOS devices for network payload capture.