From iPhone Development Wiki

debugserver is a console app that as server for remote gdb debugging. It is installed when a device is marked for development. It can be found in /Developer/usr/bin/debugserver. This is also the process invoked by Xcode to debug applications on the device.

Command line options

debugserver can be invoked with

debugserver [<options>] host:<port> [<prog-name> <arg1> <arg2> ...]

Where options can be:

Option Effect
-a process Attach debugserver to process. The process can be a pid or executable name.
-d integer Assign the waitfor-duration.
-f ? ?
-g Turn on debugging.
-i integer Assign the waitfor-interval.
-l filename Log to file. Set filename to stdout to log to standard output.
-t Use task ID instead of process ID.
-v Verbose.
-w ? ?
-x method
How to launch the program. Can be one of:
  • auto: Auto-detect the best launch method to use.
  • fork: Launch program using fork(2) and exec(3).
  • posix: Launch program using posix_spawn(2).
  • spring: Launch program via SpringBoard.
--lockdown Obtain parameters from lockdown (?)

Patching for process attaching

The vanilla debugserver cannot attach to any processes due to lack of entitlement to allow task_for_pid(). An entitlement must be inserted to the binary to allow this.

  • 0. cd ~
  • 1. Thin the binary because ldid does not support fat binaries:
lipo -thin armv6 /Developer/usr/bin/debugserver -output ~/debugserver
  • 2. Save for following as ent.xml:
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
  • 3. Apply the entitlement with ldid:
ldid -Sent.xml debugserver

Alternative Instructions (64bit compatible)

Alternatively if you are on a mac with xcode installed you can follow Peter Steinberger's instructions to add entitlement's to the debugserver that comes with xcode. This will allow you to keep it as a fat binary, which will work on all devices including 64bit iPhone 5S.

You can find Peter's full slides here: and which contain more useful tips. Instructions for getting the debugserver to work start on slide 45.

I am not sure if you need an Apple developer membership and certificate to add the entitlements. If this fails for you, try the first method above.

  • 1. Mount xcode's developer disk image on your Mac and copy the debugserver binary to your working directory:
hdiutil attach /Applications/ DeviceSupport/7.0.3\ \(11B508\)/DeveloperDiskImage.dmg
cp /Volumes/DeveloperDiskImage/usr/bin/debugserver .
  • 2. Save for following as entitlements.plist:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" " PropertyList-1.0.dtd">
<plist version="1.0">
	<key></key> <true/>
	<key>get-task-allow</key> <true/> <key>task_for_pid-allow</key> <true/>
  • 3. Apply the entitlement with codesign:
codesign -s - --entitlements entitlements.plist -f debugserver

Example session

  • 1. Copy MobileNotes to your Mac, e.g. to /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS3.1.sdk/Applications/
  • 2. On the device, type:
~/debugserver -x spring host:6789 /Applications/

This will launch MobileNotes and wait for the remote debugger.

  • 3. Launch the debugger and attach it to the remote process:

If using GDB:

  • On your Mac, launch /Developer/Platforms/iPhoneOS.platform/Developer/usr/libexec/gdb/gdb-arm-apple-darwin.
  • Type the following in gdb:
set shlib-path-substitutions / /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS3.1.sdk/
file /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS3.1.sdk/Applications/
target remote-macosx

where should be replaced by the actual IP address of your device. The remote debug connection is now complete.

If using LLDB:

  • On your Mac, launch lldb.
  • Type the following in lldb:
platform select remote-ios
process connect connect://
  • 4. Enter c to continue and do whatever you want.