George Zhu’s BLOG

Before Apple officially releases its SDK, Installer is a de-facto standard 3rd party software installation tool nowadays, but there may have some issues during your daily use, especially when network is not stable (not only on your side, but on both sides). This article introduces some tips on efficiently use Installer and tries to troubleshoot some well-known issues.

Make Installation Faster

My local ISP has bad route to North America and Europe, so it has been painful to install big applications (e.g. BSD Subsystem). A workaround is to tell Installer to download packages from local sites.

If you have a web site, regardless it’s on LAN or Internet, you have two choices to speed up the installation.

Method One

One way is to spoof the DNS:

Make DNS resolves the original site to your local site IP address
Modify your local site to listen on the same port as the original site
Create the same directory structure as the original site
Put the manually downloaded package into the same directory as the original site

For example, suppose we want to install OpenSSH from our local site http://localsite.com, IP address 192.168.0.10, we need to take the following steps:

1. Download the package from the original site:

http://ste-repo.natetrue.com:15842/iphone-apps/zips/openssh-4.6p1-1.zip

2. Modify local site configuration, make it listen on the same port, 15842 in our example.

3. Put the package onto local site at the same directory as the original site:

http://localsite.com:15842/iphone-apps/zips/openssh-4.6p1-1.zip

4. Change your local DNS server configuration, make it resolve host ste-repo.natetrue.com to 192.168.0.10.

5. Change iPhone’s DNS server to your local DNS server,

6. Fire up Installer and install it.

If you don’t wanna bother spoofing DNS, you have another choice, this is what I will explain in-depth in this article.

Method Two

This method involves modifying the Installer data file. In the following contents I’ll use BSD Subsystem as an example, and I’ll use iPHUC to upload/download files to/from iPhone, you may choose other tools (iBrickr, SCP, etc).

Before you start, please make sure Installer has refreshed the sources, then quit. Installer may stay in background if there’re tasks in queue, if you are not sure about the queue status, press and hold Home button for 8 seconds until it returns to SpringBoard, this will force an exit (similar like ‘kill -9′ on Unix). BTW, this also generates a crash report in /var/logs/CrashReporter

1. Put the downloaded package on your website, say, it’s at http://yousite.com/iphone/BSD_Subsystem.zip

2. Start iPHUC, then enter the following commands to fetch the current RemotePackages.plist from iPhone:

setafc com.apple.afc2
cd /var/mobile/Library/Installer
getfile RemotePackages.plist RemotePackages.plist
exit

NOTE: Only the latest Installer stores data in mobile account, for earlier versions, please use /var/root/Library/Installer in the above commands.

3. Now edit RemotePackages.plist, if you’re on Windows, make sure you use a good text editor that preserves the Unix text file format after edit (Notepad and Wordpad are definitely not your choice). Look for BSD Subsystem in RemotePackages.plist, it’s like this (I’ve removed some items to make it shorter, your data will be longer):

<dict>
   <key>name</key>
   <string>BSD Subsystem</string>
   <key>description</key>
   <string>Unix tools for the iPhone.</string>
   <key>location</key>
   <string>http://home.cogeco.ca/~nullriver/BSD_Subsystem.zip</string>
   <key>size</key>
   <string>6877861</string>
</dict>

Change the <string>…</string> under <key>location</key> to your local site, in our example:

<string>http://yoursite.com/iphone/BSD_Subsystem.zip</string>

Then get BSD_Subsystem.zip file size (in bytes), and fill in the <string>…</string> under <key>size</size>, this ensures you won’t have download failure, and also allows you to install a different version if your package version doesn’t match the one in Installer.

Now check whether there’s a <key>hash</key> item, if so, remove it and a <string>…</string> line right below it.

4. Upload your modified file to iPhone with iPHUC:

setafc com.apple.afc2
cd /var/mobile/Library/Installer
putfile RemotePackages.plist
exit

NOTE: You may need to use /var/root/Library/Installer in the above commands, refer to the earlier note.

5. Now start Installer, install BSD Subsystem, it’ll download from yoursite and install the package without problem.

NOTE: Your modified RemotePackages.plist will be overwritten once Installer refreshes the sources and updates the file (if it needs to).

TIP: I often restore to do some tests, so I keep all my must-have packages on site, and keep a copy of my modified RemotePackages.plistfile, this way I can quickly install applications for a new jailbreak given your phone has afc2 support. That’s why I patched Zibri’s jailbreak.

UPDATE: You may use other methods to download/upload files, I use iPHUC because I need to install BSD Subsystem and there’s no SSH access yet.

Cons and Pros

In Method One, you don’t have to worry about the Installer data file changes, because the method only spoofs the DNS records. However, just like every good thing has its bad side, it also has disadvantages, the problem is:

1. You must configure your local site to listen on the same port as the original site
2. You must keep the same directory structure as the original site

Since original sites may have different listening ports, you may have to configure your local site to listen on multiple ports. If the original site changes directory structure, you’ll have to make the same changes on your local site.

The Method Two doesn’t have the listening port problem, and you don’t need to care about the original sites’ directory structures, but the disadvantage is obvious:

Your modifications to the Installer data files will be reverted once Installer refreshes and updates its data files

Since I feel convenient to upload the data files through iPHUC, I prefer the Method Two.

Troubleshoot Download Failure

This issue often happens when download is incomplete and the downloaded size does not match the expected size. Sometimes, source site has updated the package but your RemotePackages.plist has not been refreshed, this also causes size mismatch.

UPDATE: Check the following:

1. Is your WiFi network working fine?
Try browsing some sites to make sure your WiFi is working.

2. Does your Installer have the latest sources ?
Try refresh sources in Installer.

After checking the above steps, try install the package again. If this doesn’t solve your problem, you may have to Turn On Log to File and search for the Installer error message.

Troubleshoot Main Script Execution Failure

This issue mostly happens when Installer is extracting the package but fails for some reason. For example, in Dev Team’s Jailbreak 1.1.3-1, a symbolic link is created in /usr/share:

/usr/share/terminfo -> /var/root/terminfo

When installing BSD Subsystem, Installer will fail because it can’t create a terminfo folder.

There’s no turn-key solution to this issue, you have to find out where Installer fails, the only guaranteed method is to Turn On Log to File and check the log, Installer logs all installation steps so you’ll have no problem figuring out the failure.