Estimated reading time: 9 minutes
Table of contents
The Search for the perfect SSH client
For years, I’ve searched for the perfect SSH client for my iPhone. I’ve tried both free and paid versions, but something was always missing. Worse, I’ve paid for apps that became incompatible after an iOS update, abandoned by their developers. I’m not going down that road anymore. This experience led me to a much better solution: running Linux on my iPhone.
But why?!
So, why would I want an iOS Linux environment? First, it’s a superior SSH client than the apps I used before. Its real power, however, lies in troubleshooting. It’s an (almost) complete linux terminal in my pocket, always with me. For instance, I can troubleshoot from an external network by simply turning off Wi-Fi on my iPhone. This provides a different perspective than my laptop on the local network (if I brought the laptop with me…).
A primary reason I use this, is to connect via my Alpine Linux Jump Box, in this previous blog post, I explained how to set up a lightweight VPN alternative. From my iPhone, I can SSH via this jump box to other hosts, giving me secure access to all my containers and VMs (at home). It’s the perfect solution for when I don’t have my laptop with me but want to check on a service, do some quick maintenance or even script a bit (which is challenging, but doable).
Getting Linux on my iPhone: Setting Up iSH
First, we need the right application. The magic behind this is an app called iSH . It’s important to understand that iSH doesn’t run a native Linux kernel. Instead, it cleverly uses a user-mode x86 emulator. This means it simulates a traditional PC processor right inside the app. On top of this emulation layer, it runs a standard, unmodified version of Alpine Linux.
This approach is what makes it possible to have a nearly complete Linux experience without jailbreaking my iPhone. It operates within Apple’s security rules while giving me linux power. You can easily find and download iSH Shell from the App Store. Once installed, opening it will greet with a command-line interface — the gateway to Alpine Linux on iOS.
Step 1: Upgrading Alpine Linux to the “Latest” Version
The default version of Alpine Linux in iSH is quite dated. Therefore, for better security, performance and compatibility, we should upgrade it. For some reason, the latest Alpine Linux version that works reliably with iSH is 3.18.9, which is EOL. Normally I really would like to go for the latest available stable version (which is 3.22 at time of writing), maybe I can later, when the iSH app gets an update. However, this version is perfectly fine for my needs, it’s not like I’m going to host any service, like a website on my iPhone or something… not yet anyway. I haven’t dived deep into why later versions are unstable, but my bet is it has to do with the emulator/custom kernel that iSH uses. Newer versions of Alpine Linux likely use system calls that the iSH emulator doesn’t fully support yet, leading to errors.
- First, open the browser and navigate to
alpinelinux.org/downloads/. - Next, scroll down and find the link for “Previous Releases”.
- From there, navigate through the folders:
v3.18→releases→x86. - After that, scroll to the bottom of the list. Download the file named
alpine-minirootfs-3.18.9-x86.tar.gz - Now, return to the iSH app. Tap the settings gear icon in the top left.
- Go to File Systems and select Import. Choose the file that was just downloaded.
- Finally, tap on the new file system and select “Boot from this Filesystem”.
The app will stop. When you reopen it, iSH will be using a newer version of Alpine Linux.
Step 2: Installing Essential Packages
With the environment ready, it’s time to install some essential tools. The apk command is Alpine’s package manager. We can install multiple packages with a single command.
apk add openssh python3 py3-requests nano git curl neofetch
This command installs the software I need, well, for this guide anyway. For instance, OpenSSH enables remote access. Python3 and py3-requests are for scripting. Nano is a simple text editor. In addition, Git is for version control, Curl for web requests, and Neofetch for system information.
Step 3: Exploring The Mobile Linux Shell
Now let’s put the new tools to use. These examples show the practical power of having Linux on an iPhone.
A Practical Python Script
Let’s write a Python script to fetch a random fact from the internet. This is more engaging than a simple math problem.
First, create a new file with nano:
nano fact.py
Next, type or paste the following code into the editor:
import requests
import json
try:
# Fetch data from the API
response = requests.get("https://uselessfacts.jsph.pl/random.json?language=en")
response.raise_for_status() # Raise an exception for bad status codes
# Parse the JSON and print the fact
fact_data = response.json()
print("\nHere's a random fact for you:")
print(f"-> {fact_data['text']}\n")
except requests.exceptions.RequestException as e:
print(f"Error fetching data: {e}")
Press Ctrl + O and Enter to save, then Ctrl + X to exit. Finally, run the script:
python3 fact.py
Now I have a fun script that connects to an online API:
System Information with Neofetch
Instead of a simple animation, let’s use a tool that is both visually appealing and useful. Fastfetch* Neofetch displays system information alongside cool ASCII art. It’s a great way to confirm everything is working correctly. *(Fastfetch isn’t available as package in the v3.18 community repo)
Simply run the command in the iSH terminal:
neofetch
This provides a neat summary of the iOS Linux environment:
Network Troubleshooting with Curl
While traditional tools like dig and nslookup can be unreliable do not work in the iSH emulator, curl provides an alternative for DNS queries using DNS-over-HTTPS (DoH). This method uses standard web requests, which iSH handles perfectly.
To look up the IP address (A record) for a domain, I can query Google’s public DoH service:
curl "https://dns.google/resolve?name=ramon.vanraaij.eu&type=A"
This will return a JSON object. The IP address will be in the data field of one of the answers. This is an useful and reliable way to perform network diagnostics on the go.
Making the Output Readable with Python
To make the JSON output from the curl command easier to read, I’ve created a simple Python script, it can be downloaded it directly from my GitHub repository using curl.
1. Download the script using the following command:
curl -o dns-lookup.py \
https://raw.githubusercontent.com/ramonvanraaij/Scripts/main/linux/iSH/dns-lookup.py2. Now, run the script with a domain name: python3 dns-lookup.py ramon.vanraaij.eu
This gives a clean, human-readable list of IP addresses:
But obviously, it is much easier to just SSH in to an other machine and do the troubleshooting from there with dig and nslookup. But as dig and nslookup were not working, I looked for an alternative… and this is what I have come up with.
Step 5: Temporarily Enabling SSH for Easy Setup
Typing complex commands on a phone can be tedious. To make setup easier, we can temporarily enable SSH. This allows me to connect from my computer and use its keyboard to install packages and configure files. I’ll disable it once I’m done to ensure security.
- First, generate the required SSH host keys:
ssh-keygen -A - Next, we need to edit the SSH server configuration file.
nano /etc/ssh/sshd_config - Inside nano, find the line
#PermitRootLogin prohibit-password. Uncomment it by removing the#. Then, changeprohibit-passwordtoyes. The final line should be:PermitRootLogin yes. - Press Ctrl + O to save and Ctrl + X to exit.
- After that, set a password for the root user. This is the password I will use to log in remotely.
passwd - Finally, start the SSH server daemon for this session:
/usr/sbin/sshd
The iPhone is now listening for connections. I need to remember to keep the iSH app open.
Step 6: Connecting and Disabling the SSH Server
Now, I’m connecting from my computer to perform setup tasks. First, I need my iPhone’s local IP address. I can find this manually in Settings > Wi-Fi by tapping the “i” icon, or I can use a script right inside iSH.
Finding the iPhone’s IP Address with a Script
As a convenient alternative, I’ve written a Python script that finds both the Local (LAN) and Wide Area Network (WAN) IP addresses. It can be downloaded directly from my GitHub repository using curl.
1. Download the script using the following command:
curl -o get-my-ip.py \
https://raw.githubusercontent.com/ramonvanraaij/Scripts/main/linux/iSH/get-my-ip.py2. Run the script:
python3 get-my-ip.pyThe LAN IP is the address I need for the SSH connection.
Making the Connection
Now I open a terminal on my computer. Using the following command, and replacing the placeholder with my iPhone’s LAN IP address:
ssh root@[My_iPhone_IP_Address]
Accept the security fingerprint if prompted, then enter the password I created. I can now conveniently manage my iSH environment from my computer.
Important: When I’m finished, I must stop the SSH server. The most reliable way to do this is to reboot the filesystem.
- Go to the iSH app’s settings (gear icon).
- Tap on File Systems.
- Tap on the active filesystem (e.g.,
alpine-minirootfs-3.18.9-x86) and select “Boot from this Filesystem”.
The app will restart, and the SSH server will no longer be running. This ensures the iOS Linux environment remains secure.
Step 7: (Bonus) Setting Hostname and Colorized Shell
Some of you might have noticed that my prompt doesn’t show “localhost” and is in colors. To fix the hostname, I followed the instructions here. I also installed the fish shell to get a better user experience. You can see my configuration for a colorized shell and the correct hostname here. I also created a sudo user account and adapted the fish config to login to it at “boot”, instead of root (That is not included in the config on my GitHub).
Mission Accomplished: A Persistent Linux Shell on My iPhone
And there it is! I now have a powerful, persistent mobile Linux shell right on my iPhone. I’ve updated the environment for stability, installed essential tools, and explored practical uses from network troubleshooting to running Python scripts. Most importantly, I’ve set up a secure way to connect remotely for easier configuration.
Looking ahead, I might explore an app called UTM SE at some point. It offers the ability to run a full virtual machine on an iPhone, which is a step beyond iSH’s emulation. However, I assume that running a full VM would be significantly more resource-heavy than the lightweight iSH app, likely impacting battery life and performance more. For now, iSH provides the perfect balance of power and efficiency for my needs.
Buy me a coffee 🙂
If you found this post helpful, informative, or if it saved or made you some money, consider buying me a coffee. Your support means a lot and motivates me to keep writing.
You can do so via bunq.me (bunq, iDeal, Bankcontact and Credit- or Debit cards) or PayPal (PayPal and Credit- or Debit cards). Thank you!
Disclaimer
The blog posts, guides, and scripts provided on this website are for informational and educational purposes only. They are provided “as is” and without any warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement.
By using the information or scripts from this blog, you agree that I am not liable for any direct, indirect, incidental, consequential, or any other damages or losses arising from the use of or inability to use the information, scripts, or instructions contained herein. You assume full responsibility for any and all risks associated with the use of this content.
The blog posts, guides, and pages may contain referral/affiliate links. If you make a purchase through these links, I may receive a commission at no additional cost to you.
Ⅴery nice post. I just stumbled upon your blog and wished to say that I’ve trᥙly enjoyed surfing around үour blog posts.
In any case I will be subscribing on your feed and I hope you write again very soon!
Thanks for the compliment!