.\"- .\" Copyright (c) 2026 Nick Chan .\" SPDX-License-Identifier: MIT .\" .Dd "23 December 2024" .Dt palera1n 1 .Sh NAME .Nm palera1n .Nd arm64 iOS/iPadOS/tvOS 15-26, bridgeOS 5-10 jailbreaking tool .Sh SYNOPSIS .Nm .Op Fl hvlfcBsTVpPednq .Op Fl e Ar Boot arguments .Op Fl k Ar Pongo image .Op Fl o Ar overlay file .Op Fl r Ar ramdisk file .Op Fl K Ar KPF file .Op Fl -cli .Op Fl -gui .Op Fl -tui .Op Fl -force-revert .Op Fl -dark-blockchain .Op Fl -force-enable-ssv .Sh DESCRIPTION .Nm jailbreaks an arm64 (arm64e excluded) iOS/iPadOS/tvOS 15-26, bridgeOS 5-10 device, utilizing the .Em checkm8 bootROM exploit. .Pp .Nm provides rootful and rootless jailbreak modes. On iOS/iPadOS 15.0 and later, .Nm is able to jailbreak the device in fakefs-rootful mode, where / is writable, as well as rootless mode, where / cannot be written to. On tvOS and bridgeOS, only rootful is supported. On versions where fakefs-rootful is not applicable, palera1n modifies the actual root filesystem instead of making a fakefs. .Pp Due to the nature of the .Em checkm8 exploit, .Nm is semi-tethered. That is, you must run the .Nm tool after the device reboot in order to enter the jailbroken state. However, it is not required for the device to boot. .Pp On A11 devices, that is, iPhone 8, iPhone 8 Plus and iPhone X, the passcode cannot be used. .Pp On iOS 15, the passcode must be off while jailbroken. .Pp On iOS 16, the passcode must be off since restore, and .Sy Reset All Contents and Settings from settings app counts as a restore. A backup may be used in this case. .Pp In the remainder of this document, the term "iOS" and "iPadOS" will be used interchangably as the difference is negligible as far as the jailbreak is concerened. .Pp .Sh SUPPORTED DEVICES As described above, arm64 iOS 15.0-26.0 devices are supported, here is an explicit list of supported devicecs: .Bl -tag -compact .It iPhone 6s .It iPhone 6s Plus .It iPhone SE (2016) .It iPhone 7 .It iPhone 7 Plus .It iPhone 8 .It iPhone 8 Plus .It iPhone X .El .Bl -tag -compact .It iPad mini 4 .It iPad Air 2 .It iPad (5th generation) .It iPad (6th generation) .It iPad (7th generation) .It iPad Pro (9.7") .It iPad Pro (12.9") (1st generation) .It iPad Pro (10.5") .It iPad Pro (12.9") (2nd generation) .El .Bl -tag -compact .It iPod Touch (7th generation) .El .Bl -tag -compact .It Apple TV HD .It Apple TV 4K (1st generation) .El .Bl -tag -compact .It Apple T2 iMacPro1,1 .It Apple T2 MacBookPro15,1 .It Apple T2 MacBookPro15,2 .It Apple T2 Macmini8,1 .It Apple T2 MacPro7,1 .It Apple T2 MacBookPro15,3 .It Apple T2 MacBookAir8,1 .It Apple T2 MacBookPro15,4 .It Apple T2 MacBookAir8,2 .It Apple T2 MacBookPro16,1 .It Apple T2 MacBookAir9,1 .It Apple T2 MacBookPro16,2 .It Apple T2 iMac20,1 .It Apple T2 iMac20,2 .It Apple T2 MacBookPro16,3 .It Apple T2 MacBookPro16,4 .El Support for the A8 HomePod on Darwin 21 and above could be added, but it is currently unsupported. arm64e devices will NEVER be supported. .Sh OPTIONS .Bl -tag -width -indent .It Fl h , -help Prints usage information. .It Fl v , -version Prints the program version and exit. .It Fl -cli Run in command line interface mode. .It Fl -gui Run in graphical user interface mode. .Pp This argument is available only in builds compiled with .Cm WITH_GUI support enabled. .It Fl -tui Run in text user interface mode. .Pp This argument is available only in builds compiled with .Cm WITH_TUI support enabled. .It Fl -dark-blockchain Runs the jailbreak in hacker mode. .It Fl -force-revert Remove the jailbreak while keeping user data. Some jailbreak files may remain after running this command. Additionally, jailbreak apps may remain on the home screen on for a while even when the files are deleted as the icon cache still has their icons. When used with .Fl f , -rootful , this will actually boot the device in rootless mode then delete the jailbreak files. As a result, using the loader app to install the jailbreak environment is not supported when this option is used together with .Fl f , -rootful \[char46] .It Fl -force-enable-ssv Force the jailbreak to detect Signed System Volume (SSV) as being required on the system. This option provides compatibility with previous version of palera1n that incorrectly detect SSV as being required on tvOS 18.2 and above. When using this option with .Fl f , -fakefs , the jailbreak will behave as if fakefs is required, which allows the user to boot into fakefs possibly created by previous versions of palera1n, or remove it if the .Fl -force-revert option is specified as well. (It is technically possible to setup fakefs using this option as well, but this is not a supported scenario) .It Fl l , -rootless Proceed in rootless mode. This option is only supported on iOS/iPadOS. .It Fl f , -rootful Proceed in rootful mode. Despite its name, this applies to both full, partial fakefs, as well as realfs, and it still applies even when trying to force revert. .It Fl c , -setup-fakefs When used with .Fl f , -rootful , creates the new APFS volume required for rootful. Will fail if one already exists. This flag is supported on iOS/iPadOS 15.0 or later and tvOS 18.2 or later, as they require fakefs for rootful. .It Fl B , -setup-fakefs-partial Like .Fl c , -setup-fakefs but the size of the created fakefs is smaller at the expense of having unwritable parts in rarely-written paths. When jailbreaking 16 GB devices, this option must be used when setting up fakefs for rootful, as they do not have enough storage for full fakefs. This flag is supported on iOS/iPadOS 15.0 or later and tvOS 18.2 or later, as they require fakefs for rootful. .It Fl s , -safe-mode Enter safe mode. An alert will be displayed on iOS/iPadOS/tvOS. Jailbreak daemons nor early boot executable files specified (see .Sy FILES section below) will be executed. The loader app and the built in SSH server can still be used, as well as any jailbreak-specific apps you have installed. .It Fl T , -telnetd Enable the TELNET daemon on port 46, all interfaces. Please note that there is no authentication and is therefore insecure. .It Fl V , -verbose-boot Boots the device in verbose mode, allowing boot logs to be seen. .It Fl p , -early-exit Exit after booting into a clean PongoOS shell. .It Fl P , -late-exit Exit after uploading existing images into the PongoOS shell. .It Fl e , -extra-bootargs Ar boot arguments Specify custom XNU kernel command line. Additionally, the .Em wdt=-1 argument is used during fakefs setup. .It Fl k , -override-pongo Ar pongo file Override PongoOS image. The raw image, named .Em Pongo.bin when built, should be used. PongoOS 2.6.0 or later is required. .It Fl K , -override-kpf Ar KPF file Override the kernel patchfinder PongoOS module. The module is required to support setting root filesystem in paleinfo with .Em rootfs command. If in doubt, use .Sy https://github.com/palera1n/PongoOS iOS15 branch or your own fork of it. .It Fl o , -override-overlay Ar overlay file Specify the path to a custom overlay file, which is then mounted onto /cores/binpack during boot, if the default ramdisk is used. The default ramdisk expects the overlay to contain a folder named .Em Applications at the root of it, as well as a dmg named .Em loader.dmg at the root of it. Otherwise, the device will not boot. It is also expected that it contains a shell, a ssh server, and various command line utilities. .It Fl r , -override-ramdisk Ar ramdisk file Override the ramdisk. At a very minimum, it should contain .Em /cores/ploosh as well as a fake dyld .Em /usr/lib/dyld where the logic is expected to be in. .It Fl d , -debug-logging Enable debug logging. Supports up to 5 levels of verbosity, with 5 being the most verbose. .It Fl n , -no-colors Disable colors on the command line. .It Fl q , -quick When used with .Fl -tui , or .Fl -gui , the interfaces will automate the process of entering DFU mode, without needing to press the interface buttons for every step of the process. .Pp This variable is available only in builds compiled with .Cm WITH_GUI or .Cm WITH_TUI support enabled. .El .Sh ENVIRONMENTAL VARIABLES .Bl -tag -width -indent .It Ev RA1N_ABORT_TIMEOUT Set a custom timeout value (0 to 999999999) for the exploit abort timer. While the default value is sufficient for standard platforms (Intel or Apple Silicon), this variable allows timing adjustments on specific environments such as Linux (AMD) or Raspberry Pi (ARM64), where the exploit may fail due to platform-specific USB stack behavior. .Pp E.g. Raspberry Pi 5: .Em RA1N_ABORT_TIMEOUT=1000000 .Pp This variable is available only in builds compiled with .Cm WITH_CIDERRAIN support enabled. .It Ev RA1N_CLI Equivalent to using the .Fl -cli option. .It Ev RA1N_GUI Equivalent to using the .Fl -gui option. .Pp This variable is available only in builds compiled with .Cm WITH_GUI support enabled. .It Ev RA1N_TUI Equivalent to using the .Fl -tui option. .Pp This variable is available only in builds compiled with .Cm WITH_TUI support enabled. .It Ev RA1N_DARK_BLOCKCHAIN Equivalent to using the .Fl -dark-blockchain option. .It Ev RA1N_FORCE_REVERT Equivalent to using the .Fl -force-revert option. .It Ev RA1N_FORCE_ENABLE_SSV Equivalent to using the .Fl -force-enable-ssv option. .It Ev RA1N_ROOTLESS Equivalent to using the .Fl l , -rootless option. .It Ev RA1N_ROOTFUL Equivalent to using the .Fl f , -rootful option. .It Ev RA1N_SETUP_FAKEFS Equivalent to using the .Fl c , -setup-fakefs option. .It Ev RA1N_SETUP_FAKEFS_PARTIAL Equivalent to using the .Fl B , -setup-fakefs-partial option. .It Ev RA1N_SAFE_MODE Equivalent to using the .Fl s , -safe-mode option. .It Ev RA1N_TELNETD Equivalent to using the .Fl T , -telnetd option. .It Ev RA1N_VERBOSE_BOOT Equivalent to using the .Fl V , -verbose-boot option. .It Ev RA1N_EARLY_EXIT Equivalent to using the .Fl p , -early-exit option. .It Ev RA1N_LATE_EXIT Equivalent to using the .Fl P , -late-exit option. .It Ev RA1N_EXTRA_BOOTARGS Equivalent to using the .Fl e , -extra-bootargs option. .It Ev RA1N_OVERRIDE_PONGO Equivalent to using the .Fl k , -override-pongo option. .It Ev RA1N_OVERRIDE_KPF Equivalent to using the .Fl K , -override-kpf option. .It Ev RA1N_OVERRIDE_OVERLAY Equivalent to using the .Fl o , -override-overlay option. .It Ev RA1N_OVERRIDE_RAMDISK Equivalent to using the .Fl r , -override-ramdisk option. .It Ev RA1N_DEBUG_LOGGING Equivalent to using the .Fl d , -debug-logging option. Supports up to 5 levels of verbosity, with 5 being the most verbose. e.g. to enable level 3 debug logging, use .Em RA1N_DEBUG_LOGGING=3 .It Ev RA1N_NO_COLORS Equivalent to using the .Fl n , -no-colors option. .It Ev RA1N_QUICK Equivalent to using the .Fl q , -quick option. .Pp This variable is available only in builds compiled with .Cm WITH_GUI or .Cm WITH_TUI support enabled. .El .Sh EXAMPLES To (re-)jailbreak in rootless mode: .Pp .Dl "palera1n -l" .Pp To setup fakefs for rootful mode: .Pp .Dl "palera1n -fc" .Pp After the device has rebooted into recovery mode, follow the following example. .Pp To re-jailbreak in rootful mode: .Pp .Dl "palera1n -f" .Pp To remove the jailbreak in rootful mode: .Pp .Dl "palera1n --force-revert -f" .Pp To remove the jailbreak in rootless mode: .Pp .Dl "palera1n --force-revert" .Pp To verbose boot in rootful mode: .Pp .Dl "palera1n -Vf" .Pp To create a partial fakefs with bind mounts: .Pp .Dl "palera1n -Bf" .Pp .El .Sh CAVEATS .Pp .Em -v is not a real XNU boot argument. It is interpreted by iBoot. However, since XNU boot arguments are set in PongoOS, which is ran after iBoot has ran, it does nothing. To verbose boot, use the .Fl V , -verbose-boot option when jailbreaking. .Pp Fakefs takes up around 5-10 GB of storage, and takes up to 10 minutes to setup. .Pp iOS 15.0 requires DER entitlements, and iOS 15.1 requires hash agility in code signatures. As a result, binaries with the old code signature format need to be resigned with a recent version of the Procursus fork of .Xr ldid 1 before they can be ran on a device jailbroken with .Nm \[char46] .Pp When using rootful mode, the .Fl f , -rootful flag must be specified at all times. It does not matter whether you want to create fakefs, create partial fakefs, rejailbreak or remove jailbreak. .Pp Due to a stock bug, using the .Fl V , -verbose-boot option might cause some versions for tvOS to crash and not boot. .Pp Offical Apple USB-C cables as well as some other USB-C cables cannot be used to enter DFU mode. USB-A cable with male USB-C to female USB-A adapter works fine. .Sh POST INSTALLATION (iOS/iPadOS) The palera1n loader app will take up to 1 minute to appear on the homescreen after the device has booted. If it does not appear, you can try using the shortcut: .Pp .Lk https://www.icloud.com/shortcuts/8cd5f489c8854ee0ab9ee38f2e62f87d .Pp to open it. After opening the loader app, select a package manager to install. This will also bootstrap your device. .Pp A built-in SSH server runs on port 44 on loopback interfaces. .Sh POST INSTALLATION (tvOS) .Pp The palera1n loader app will appear on homescreen. Open the loader and select a package manager to install. This will also bootstrap your device. .Pp A built-in SSH server runs on port 44 on all interfaces. .Sh POST INSTALLATION (bridgeOS) .Pp A built-in SSH server runs on port 44 on all interfaces. .Pp Bootstrapping is currently not supported on this device. .Sh FILES During the jailbreak process, a temporary filesystem is mounted on /cores as a place to stash jailbreak files needed during the boot process. No files are ever written onto the actual disk if you do not use the SSH server to write files or using the loader app to install additional jailbreak files. .Bl -tag -width "/var/jb/Library/LaunchDaemons" .It Pa /cores The location of the temporary filesystem where jailbreak files are stashed during boot. .It Pa /Library/LaunchDaemons The directory where jailbreak-specific .Xr launchd.plist 5 property list files should be placed on rootful. .It Pa /var/jb/Library/LaunchDaemons The directory where jailbreak-specific .Xr launchd.plist 5 property list files should be placed on rootless. .It Pa /etc/rc.d The directory where executable files that needs to be executed during boot, before daemons are launched, are placed on rootful. They are executed after all filesystems has been mounted. .It Pa /var/jb/etc/rc.d The directory where executable files that needs to be executed during boot, before daemons are launched, are placed on rootless. They are executed after all filesystems has been mounted. .El .Sh BUGS .Nm may crash if the machine it is running on has non-compliant USB devices plugged in. .Pp .Nm will fail to initialize on Linux when there are no USB devices plugged in. Usually this is not a problem on PCs since the built-in root hubs are also USB devices. However, on platforms such as Apple Silicon Macs in Linux, since there are no built-in USB hubs, at least one USB device needs to be manually plugged in for palera1n to be initialized. .Pp The exploit may also work less reliably on some hosts, like AMD desktops, or some MediaTek devices. .Pp The built-in SSH server might be not accessible with password after bootstrapping rootful, since the bootstrap uses a custom crypt() function that is not supported by the built-in SSH server. .Pp There are no DFU instructions for iBridge T2 as there are no known ways to connect to the T2's USB interface when macOS has been booted. .Sh DEPRECATED AND REMOVED FUNCTIONALITY There was an option in .Nm to force create the fakefs even when one already exists (which would overwrite the existing fakefs), by setting the palerain_option_setup_rootful_forced flag in palera1n flags. This option was removed because using .Fl -force-revert and .Fl c at the same time has exactly the same effect. .Pp The hook that enabled .Sy launchctl runstats has been removed, since it leaks memory in launchd. .Pp .Fl f, -fakefs has been renamed to .Fl f, -rootful due to its ambiguity. As it supports both fakefs and realfs on certain platforms. .Fl P, -pongo-full has been renamed to .Fl P, -late-exit due to its ambiguity. .Sh SEE ALSO .Xr launchd 8 .Xr launchd.plist 5 .Xr ldid 1 .Xr p1ctl 8 .Sh HISTORY The .Nm jailbreak was first written by Nebula and Mineek on September 26, 2022, as a shell script. Tweak support with DEVELOPMENT kernels are added on October 2, 2022. RELEASE kernel support is added on November 14, 2022. iOS 16 Support is added on December 13, 2022. Later, the first attempt to rewrite palera1n into C begins on January 01 2023. The .Nm utility described here is the second attempt, which first started on January 16, 2023, using checkra1n 1337 and a custom KPF. Something happened on August 15, 2023.