Ish - Linux shell for iOS

iSH

Last update: Jan 4, 2023

Overview

iSH

A project to get a Linux shell running on iOS, using usermode x86 emulation and syscall translation.

For the current status of the project, check the issues tab, and the commit logs.

App Store page
TestFlight beta
Discord server
Wiki with help and tutorials
README中文 (如若未能保持最新，请提交PR以更新)

Hacking

This project has a git submodule, make sure to clone with --recurse-submodules or run git submodule update --init after cloning.

You'll need these things to build the project:

Python 3
- Meson (pip3 install meson)
Ninja
Clang and LLD (on mac, brew install llvm, on linux, sudo apt install clang lld or sudo pacman -S clang lld or whatever)
sqlite3 (this is so common it may already be installed on linux and is definitely already installed on mac. if not, do something like sudo apt install libsqlite3-dev)
libarchive (brew install libarchive, sudo port install libarchive, sudo apt install libarchive-dev) TODO: bundle this dependency

Build for iOS

Open the project in Xcode, open iSH.xcconfig, and change ROOT_BUNDLE_IDENTIFIER to something unique. You'll also need to update the development team ID in the project (not target!) build settings. Then click Run. There are scripts that should do everything else automatically. If you run into any problems, open an issue and I'll try to help.

Build command line tool for testing

To set up your environment, cd to the project and run meson build to create a build directory in build. Then cd to the build directory and run ninja.

To set up a self-contained Alpine linux filesystem, download the Alpine minirootfs tarball for i386 from the Alpine website and run ./tools/fakefsify, with the minirootfs tarball as the first argument and the name of the output directory as the second argument. Then you can run things inside the Alpine filesystem with ./ish -f alpine /bin/login -f root, assuming the output directory is called alpine. If tools/fakefsify doesn't exist for you in your build directory, that might be because it couldn't find libarchive on your system (see above for ways to install it.)

You can replace ish with tools/ptraceomatic to run the program in a real process and single step and compare the registers at each step. I use it for debugging. Requires 64-bit Linux 4.11 or later.

Logging

iSH has several logging channels which can be enabled at build time. By default, all of them are disabled. To enable them:

In Xcode: Set the ISH_LOG setting in iSH.xcconfig to a space-separated list of log channels.
With Meson (command line tool for testing): Run meson configure -Dlog="<space-separated list of log channels>".

Available channels:

strace: The most useful channel, logs the parameters and return value of almost every system call.
instr: Logs every instruction executed by the emulator. This slows things down a lot.
verbose: Debug logs that don't fit into another category.
Grep for DEFAULT_CHANNEL to see if more log channels have been added since this list was updated.

A note on the JIT

Possibly the most interesting thing I wrote as part of iSH is the JIT. It's not actually a JIT since it doesn't target machine code. Instead it generates an array of pointers to functions called gadgets, and each gadget ends with a tailcall to the next function; like the threaded code technique used by some Forth interpreters. The result is a speedup of roughly 3-5x compared to pure emulation.

Unfortunately, I made the decision to write nearly all of the gadgets in assembly language. This was probably a good decision with regards to performance (though I'll never know for sure), but a horrible decision with regards to readability, maintainability, and my sanity. The amount of bullshit I've had to put up with from the compiler/assembler/linker is insane. It's like there's a demon in there that makes sure my code is sufficiently deformed, and if not, makes up stupid reasons why it shouldn't compile. In order to stay sane while writing this code, I've had to ignore best practices in code structure and naming. You'll find macros and variables with such descriptive names as ss and s and a. Assembler macros nested beyond belief. And to top it off, there are almost no comments.

So a warning: Long-term exposure to this code may cause loss of sanity, nightmares about GAS macros and linker errors, or any number of other debilitating side effects. This code is known to the State of California to cause cancer, birth defects, and reproductive harm.

Comments

Selecting text will copy it into the pasteboard
In the latest TestFlight build 35, when I just long press text to select it on iSH, it will be copied into the pasteboard even if I don’t tap the “Copy” item.

How to reproduce it: https://youtu.be/OoDOArAkhSg

Select text

Tap “Paste” item

I reproduced the issue on

3rd generation 12.9” iPad Pro with iOS 12.1.1

iPad Air 2 with iOS 12.1

iPhone XS with iOS 12.1.1

Related to #25
opened by kkk669 31
wget issue

a random bad bug (at least with commit fd48ae6, f802873, maybe also with c846847, will try with old commit when I have some time)

sometime wget issue with "wget: read error: Invalid argument" and the same url with curl work fine. seem to be related to network.

you can try with following url: https://dl.i4th.me/a, this one should retrieve a 41KB file https://dl.i4th.me/b, this one should retrieve a 5KB file sometime only wget for b work, sometime both work, sometime none work no failure at this time with curl
no repro

opened by francoisvignon 25
Oh-my-zsh compatibility

I'm experiencing OMZ compatibility issue on my 2018 iPad Pro with iPadOS 14.5 beta, which doesn’t happen on my iPhone with iOS 14.4.2.

Situation: The prompt label doesn’t display, no matter it’s local or remote. Syntax highlighting is also buggy. zsh itself and other shells seem all fine.

unconfirmed

opened by stevapple 22
I/O ERROR during apk install

We're trying to collect diagnostics for an Apple bug report. If this happens to you, please immediately capture a sysdiagnose (press both volume buttons and the power button simultaneously for a few seconds) and send this to me, along with the approximate date and time the issue occurred and the output of dmesg. Thanks! ~@tbodt

i get following error . Any idea ?

opened by F3000 22
Race between execve and proc_pid_cmdline_show

See attached image for some context. This is the script I'm running that causes the crash...

#!/bin/bash tmux new-session -s "My iPad" -d tmux split-window -h tmux split-window -v tmux -2 attach-session -d

Note that I can manually create the same layout after running tmux manually.

opened by emkey1 22
Friendly-shell 'fish' cannot process a local example, but unknown or corrupted style, of file linking/also originated by unknown tool, which ash/bash, et.al. could use uninhibited.

fish seems to work now.

Originally posted by @tbodt in https://github.com/ish-app/ish/issues/122#issuecomment-449228241

fetch http://dl-cdn.alpinelinux.org/alpine/v3.12/community/x86/APKINDEX.tar.gz (1/3) Installing bc (1.07.1-r1) (2/3) Installing libpcre2-32 (10.35-r0) (3/3) Installing fish (3.1.2-r0) Executing fish-3.1.2-r0.post-install Executing busybox-1.31.1-r19.trigger 3 errors; 3025 MiB in 687 packages iPhone0 user root@Thu 26_ 4:00PM~(/root)-zsh:which fish /usr/bin/fish iPhone0 user root@Thu 26_ 4:00PM~(/root)-zsh:ldd /usr/bin/fish /lib/ld-musl-i386.so.1 (0xf7f6e000) libncursesw.so.6 => /usr/lib/libncursesw.so.6 (0xf7d99000) libpcre2-32.so.0 => /usr/lib/libpcre2-32.so.0 (0xf7d09000) libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xf7b74000) libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0xf7b5b000) libc.musl-x86.so.1 => /lib/ld-musl-i386.so.1 (0xf7f6e000) iPhone0 user root@Thu 26_ 4:01PM~(/root)-zsh:

iPhone0 user root@Thu 26_ 4:06PM~(/root)-zsh:history 1 apk search go 2 apk list go 3 go --help 4 go packages 5 go list 6 go env 7 go get -u github.com/ramya-rao-a/go-outline 8 dmesg 9 apk list fish 10 apk add fish 11 which fish 12 ldd /usr/bin/fish 13 fish iPhone0 user root@Thu 26_ 4:06PM~(/root)-zsh:fish Welcome to fish, the friendly interactive shell Type help for instructions on how to use fish root@iPhone ~# history Failed to execute process '/usr/bin/less'. Reason: exec: unknown error (errno was 13) root@iPhone ~ [125]# dmesg [ 0.000000] 496 stub syscall 375

root@iPhone ~ [1]# ls -la /usr/bin/less -rw-rw-rw- 1 root root 12 Jul 20 00:59 /usr/bin/less root@iPhone ~# chmod +x /usr/bin/less root@iPhone ~# history Failed to execute process '/usr/bin/less'. Reason: exec: unknown error (errno was 8) The file '/usr/bin/less' is marked as an executable but could not be run by the operating system.
unconfirmed

opened by 62f 21
kerberos commands return “Bad file descriptor”
HI - I’m really looking forward to use ish to access computing resources from my iPad. We use kerberos for security. I did

apk add krb5

and copied my krb5.conf file to /etc/krb5.conf.

I get a Kerberos ticket with kinit. The communication with our kerberos server seems to work, but it ends with an error...

ipad-132427:~# kinit <removed> Password for <removed> kinit: Failed to store credentials: Bad file descriptor (filename: /tmp/krb5cc_0) while getting initial credentials

There’s an option to kinit that saves credentials to any file, and when I do a file in /root it fails the same way.

Furthermore, the klist command, which tells me what tickets I have (maybe none) also fails with a similar Bad file descriptor error.

I imagine the kerberos executables were built in some incompatible way. Any ideas? Let me know how I can help! Thanks, Adam
opened by lyon-fnal 21
Support ngrok error illegal instruction

opened by professorUnknown 20
Feature Request: Allow the Ish app to run in the background.

The Ish app should be allowed to run in the background if you leave the app. Sometimes I have to leave the app, and then the in-app processes would stop so allowing the app to run in the background would be great.

opened by VincentCCandela 20
Inform 7 (interactive fiction)

Can someone tell me if Inform 7 works on iSH? I tried to install it with script but obviously it didn't work. I manually unzipped the right files, but when I try to compile a sample file, it doesn't work.

http://inform7.com/download/content/6M62/I7_6M62_Linux_all.tar.gz

opened by ecstaticax 19
network not use

liuende:~# cat /etc/resolv.conf nameserver 192.168.1.1 liuende:~# ping 192.168.1.1 PING 192.168.1.1 (192.168.1.1): 56 data bytes ping: sendto: Host is unreachable liuende:~# apk add openssh fetch http://dl-cdn.alpinelinux.org/alpine/v3.8/main/x 86/APKINDEX.tar.gz ERROR: http://dl-cdn.alpinelinux.org/alpine/v3.8/main: temporary error (try again later) WARNING: Ignoring APKINDEX.adfa7ceb.tar.gz: No such fi le or directory fetch http://dl-cdn.alpinelinux.org/alpine/v3.8/commun ity/x86/APKINDEX.tar.gz ERROR: http://dl-cdn.alpinelinux.org/alpine/v3.8/commu nity: temporary error (try again later) WARNING: Ignoring APKINDEX.efaa1f73.tar.gz: No such fi le or directory ERROR: unsatisfiable constraints: openssh (missing): required by: world[openssh]

opened by DHCMediWay 18
Invalid API call. Please retry or visit the documentation (https://www.alphavantage.co/documentation/) for TIME_SERIES_DAILY_ADJUSTED.

Invalid API call. Please retry or visit the documentation (https://www.alphavantage.co/documentation/) for TIME_SERIES_DAILY_ADJUSTED.
unconfirmed

opened by xxccy668 0
New App Store release with 2022 improvements?

Looking at the Git history, there have been many valuable improvements to the emulator in 2022, many of which fix tools like Git and Node.js that don't work well in the last App Store release from November 2021. Is it planned to update the App Store version of iSH soon to make these improvements easily available to all?
unconfirmed

opened by denisw 1
Crashes during installation in background

I have consistently had iSH crash when I am installing something with apk add and then I leave the app even for a short time in the background. The installation gets canceled and I have to start again. It only works if I stay in the app during installation.

does anyone know why this is or experience this too?
unconfirmed

opened by hmltn-2 0
iPadOS: vim status bar

I am really liking ish app. There’s a small issue when using vim that makes it hard to know what’s happening. The options bar overlays the bottom of vim status bar.

Edit: I use external keyword.
unconfirmed

opened by MTraveller 0

Trying to run Dwarf Fortress, illegal instruction at 0x8b9f8be: 0f 13 83 60 5a 00 00 89

Heyo! I'm trying to run Dwarf Fortress inside a Debian chroot, since it isn't musl compatible and gcompat gives me other errors. Managed to make it work on docker with econcz/x86-alpine-glibc:ish-import as the base. Compressed the chroot folder, transferred it into my iPad and I'm getting this error running the exact same instructions as in Docker (where it does indeed work):

Mateos-iPad:~# chroot /root/chroot/ /bin/bash
root@Mateos-iPad:~/chroot# LD_PRELOAD=/root/libgraphics.so /root/df_linux/libs/Dwarf_Fortress
Illegal instruction
root@Mateos-iPad:~/chroot# dmesg
[    0.000000] 4 stub syscall 383
               4 stub syscall 383
               8 stub syscall 383
               8 stub syscall 383
               8 stub syscall 383
               13 stub syscall 383
               13 stub syscall 383
               13 stub syscall 383
               13 stub syscall 383
               13 stub syscall 439
               14 illegal instruction at 0x8b9f8be: 0f 13 83 60 5a 00 00 89 
root@Mateos-iPad:~/chroot# uname -a
Linux Mateos-iPad 4.20.69-ish iSH 1.2.3 (298) Dec 17 2021 06:08:24 i686 GNU/Linux

the chroot is uploaded at dfChroot.tar.gz

unconfirmed

opened by PibePlayer 0