Skip to content

Instantly share code, notes, and snippets.

@jschiefner
Last active December 1, 2024 03:05
Show Gist options
  • Save jschiefner/95a22d7f4803e7ad32a95b0f3aa655dc to your computer and use it in GitHub Desktop.
Save jschiefner/95a22d7f4803e7ad32a95b0f3aa655dc to your computer and use it in GitHub Desktop.

Setup Altserver Linux on Raspberry Pi with Wifi Refresh

This is a rough outline on how to setup altserver-linux on the 🍓🍰. Wifi refreshing is enabled through the use of netmuxd, which acts as a proxy from AltServer to the iDevice (replaces/enhances usbmuxd).

Tutorials used

Prerequisites

Create a dedicated folder for the setup, e.g. ~/Developer/alt-server to hold binaries and other things.

sudo apt install -y \
  libavahi-compat-libdnssd-dev \
  usbmuxd \
  ninja-build \
  ldc \
  libplist-dev \
  libimobiledevice-dev \
  libgtk-3-0 \
  dub \
  openssl

Install libimobiledevice-glue from source by following the instructions on https://github.com/libimobiledevice/libimobiledevice-glue#debian--ubuntu-linux. As well, install libimobiledevice from source, by following the instructions on https://github.com/libimobiledevice/libimobiledevice#debian--ubuntu-linux. This installs executables such as idevicepair and ideviceinfo. We can use those later to verify if our wireless connection to the idevice is working properly.

Install rustup from https://rustup.rs/ and setup up the toolchain:

rustup toolchain install stable
rustup default stable

Then enable some systemd services. Before you do that however, you need to edit the usbmuxd service file, which is located at /lib/systemd/system/usbmuxd.service. Add the following to it:

# Taken from https://bugs.archlinux.org/task/31056
[Install]
WantedBy=multi-user.target

so that it can enabled with systemctl. Then run:

sudo systemctl enable --now avahi-daemon.service
sudo systemctl enable --now usbmuxd

Now you can download the AltServer-aarch64 binary from https://github.com/NyaMisty/AltServer-Linux/releases and place it in the folder you created earlier. As well, download the netmuxd binary aarch64-linux-netmuxd from https://github.com/jkcoxson/netmuxd/releases and also place it in the your folder. Don't forget to make them executable with chmod +x ....

Install Docker by following the instructions on https://pimylifeup.com/raspberry-pi-docker/. If the docker install script fails at some point because it's trying to startup a service that won't start, just do a sudo reboot and run the script again. Ignore the warning that running the script again might cause problems, this is just to warn that it could cause problems if docker has been installed in another way.

Make sure everything works as expected

With docker installed, you can now run the following command to start the anisette container:

docker run -d -v lib_cache:/opt/lib/ --restart=always -p 6969:6969 --name anisette dadoum/anisette-server:latest

This will keep the container running even if you reboot the pi. No cron job necessary for that.

Everything should now be set up. First, connect your iDevice to your Mac/PC with USB, enable "Wifi Sync" in the Finder or in iTunes and hit Sync/Apply. This is important so the iDevice will also be recognized over the network by the pi. After syncing disconnect the iDevice from USB make sure it is broadcasting itself on the network by running avahi-browse -a on the pi. Or run dns-sd -B _apple-mobdev2._tcp local on the mac. On linux you need to do sudo apt-get install avahi-utils first. If the device does not show up, there is no chance it will be recognized by netmuxd.

Once your iDevice is broadcasting itself, connect it to the pi via USB and tap trust on the iDevice to trust the pi. Verify that the pairing was successful by running idevicepair validate. Now, disconnect your iDevice from the pi. Run sudo ./aarch64-linux-netmuxd to start the netmuxd proxy. Ensure that no errors or warnings are issued by netmuxd, it won't quit the program but it will also most likely not work. It should say:

Starting netmuxd
Starting mDNS discovery for _apple-mobdev2._tcp.local with mdns
Listening on /var/run/usbmuxd
Adding device 00008110-0123A456B789D012 # or similar, this should appear after a few seconds

If the device is not added it is not properly paired with the pi or it is not broadcasting itself to the network via bonjour. Troubleshoot this problem and continue only when the device is shown here.

When the device shows up (without heartbeat errors), you can now run sudo ALTSERVER_ANISETTE_SERVER=http://127.0.0.1:6969 ./AltServer-aarch64 to start the AltServer app. If the ALTSERVER_ANISETTE_SERVER env variable is set in your current environment, you could also do a sudo -E to make all env variables available in the root user process. This is not happening automatically! Verify that the env variable is set for the process by running:

ps aux | grep AltServer # copy pid
sudo cat /proc/<pid>/environ | tr '\0' '\n'

If the ALTSERVER_ANISETTE_SERVER env variable is not present in the output here, make sure you ran AltServer with the ALTSERVER_ANISETTE_SERVER env variable specified correctly! If this is not set AltServer will not complain, but App refreshing will most likely not work, because AltServer is not using your own anisette server!

Quit the AltServer for now and install AltStore on the iDevice. Check the latest version number for AltStore here: https://cdn.altstore.io/file/altstore/apps.json

curl -L https://cdn.altstore.io/file/altstore/apps/altstore/1_6_1.ipa > AltStore.ipa # replace 1_6_1 with the most recent version
sudo ALTSERVER_ANISETTE_SERVER=http://127.0.0.1:6969 ./AltServer-aarch64 -u 00008110-0123A456B789D012 -a <apple-id-email> -p <apple-id-password> AltStore.ipa

AltStore should now be successfully installed on your iDevice. You can now just start AltServer without any arguments (but with the env variable!) and use it for app refreshingn and installing apps through AltStore directly. Try Delta in the AltStore App for example.

If anything fails, always make sure it works through USB (disable netmuxd first) to make sure it's not a wireless connection issue. Always make sure sudo systemctl status usbmuxd and sudo systemctl status avahi-daemon.service are running at all times, especially after a system reboot.

Autostart

Use crontab to start netmuxd and AltServer on boot. Run sudo crontab -e and add the following lines:

@reboot sleep 20 && /.../alt-server/aarch64-linux-netmuxd > /.../alt-server/log/netmuxd.log 2>&1
@reboot sleep 20 && ALTSERVER_ANISETTE_SERVER=http://127.0.0.1:6969 /.../alt-server/AltServer-aarch64 > /.../alt-server/log/altserver.log 2>&1

replace ... with the whole path to the executables. Also create your log folder so the processes can write their logs in the background with mkdir /.../alt-server/log. The 2>&1 part is important to redirect stderr to stdout so it is written to the log file as well.

After a sudo reboot make sure AltServer and netmuxd processes run (with ps aux | grep ...) and write to their log files. Also make sure the anisette container is running with docker ps. Inspect it's logs with docker logs anisette to make sure it is running properly. Finally make sure the AltServer process has the ALTSERVER_ANISETTE_SERVER env variable set.

Alternative startup for netmuxd

You can also start netmuxd like this:

sudo ./aarch64-linux-netmuxd --disable-unix --host 127.0.0.1

You then need to set the USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 for AltServer so it can connect to netmuxd. The second tutorial from reddit mentions that for this to work usbmuxd has to be disabled (sudo systemctl stop usbmuxd. For me however it worked without these extra steps, so i'll leave this step out.

Building netmuxd from source

If you want to build netmuxd from source, it uses an mdns fork which you would need to clone first from https://github.com/jkcoxson/mdns and place on the same level as your clone from https://github.com/jkcoxson/netmuxd/. Then just edit the zeroconf = { version = "0.10.5", path = "../zeroconf-rs/zeroconf", optional = true } to zeroconf = { version = "*" } in the Cargo.toml of netmuxd. Make sure you have sudo apt-get -y install libclang-dev cmake installed and then follow the build instructions from the netmuxd README.

Other useful resources

Don't forget

  • install altstore through altserver on linux, but install all other apps through altstore, if you install stuf with altserver directly it will not show up in altstore
  • iDevice needs to have wifi sync enabled in finder on macos (or itunes on windows)
  • you can see environment variables of any process by running sudo cat /proc/<pid>/environ | tr '\0' '\n' (replace <pid> with the process id of the process you want to see the environment variables of)
  • You can reset the anisette docker container by docker stop anisette, docker rm anisette and docker volume rm lib_cache
  • When asked for the 2 Factor Auth Code in AltStore it sometimes happens for me that it first reports "invalid code". Then, when refreshing the desired App again it works the second time without issues.
@Samk19
Copy link

Samk19 commented Sep 22, 2023

How to bypass the two step verification that apple has implemented now. Unable to install altstore app due to it on linux

@jschiefner
Copy link
Author

@Samk19 can you let me know which step exactly you are having trouble with? When I had 2FA problems, the solution was to install the app I wanted in AltStore again and the second time it worked.

When asked for the 2 Factor Auth Code in AltStore it sometimes happens for me that it first reports "invalid code". Then, when refreshing the desired App again it works the second time without issues.

@Flamini90
Copy link

Flamini90 commented Sep 23, 2023

Hello,
thank you for the guide!
I have successfully installed Altstore in my iphone throught the altserver in my ubuntu server with Wi-Fi, but inside the AltStore app, in my iphone, im having issues to log in (after typed my user and pass and clicked on Sign in, i see the loading is infinity) and without login with my apple ID, i cannot download nothing :/

I've checked who netmuxd and Altserver are running & creats logs and the last one is setted correctly (env).

Could you help me please? :)

P.S i've installed the last one version for the Altstore (v.1.07), im on ios 17 with my 14 pro max if this can help....

(3 hours later) I tried to uninstall Altstore from my iphone and if i try to install Alstore again i have that error:

image

and now, from logs when i try to test my wireless connection i have that:

image

I guess have the heartbeat error right now....

@jschiefner
Copy link
Author

@Flamini90 With the heartbeat error there is no point in trying to continue, it has to be solved first. Did you try the alternative usage for netmuxd I mentioned (https://gist.github.com/jschiefner/95a22d7f4803e7ad32a95b0f3aa655dc#alternative-startup-for-netmuxd)? Maybe that serves you better.

@wangguangyou
Copy link

So, do I need to run my Pi on Wi-Fi or would it work fine with Ethernet?

@jschiefner
Copy link
Author

jschiefner commented Sep 27, 2023

@wangguangyou i dont think there's anything stopping you from connecting the PI via Ethernet (make sure to disable wifi in that case on the pi, otherwise it will prefer Wifi over Ethernet i think https://raspberrytips.com/disable-wifi-raspberry-pi/ -> 4: Config.txt) local networking should work just the same, no matter the connection type.

@Flamini90
Copy link

Flamini90 commented Sep 28, 2023

@Flamini90 With the heartbeat error there is no point in trying to continue, it has to be solved first. Did you try the alternative usage for netmuxd I mentioned (https://gist.github.com/jschiefner/95a22d7f4803e7ad32a95b0f3aa655dc#alternative-startup-for-netmuxd)? Maybe that serves you better.

thank you for the suggestion and the patience, I've not so much experience in linux :/
By the way, now I've resolved the heartbeat error (i had to do the extra step ''sudo systemctl stop usbmuxd'' too) but still the main problem is there, when I open the Altstore app on my iphone I could not log with my apple Id and im in an infinite loading (look below):

image

fast recap: resolved heartbeat, downloaded & installed altstore from altserver linux through wifi, started altserver, then opened Altstore from iphone, try to login, infinite loading.....

Could be a chance that there is a conflict from the old Altstore (previously i had an Altstore from a windows altserver that I've deleted before I installed this one) and this one?

For more info, when I start Altserver, in the output I've this:

No argument supplied, if you want for help, please use -h or --help
Not supplying ipa, running in server mode!
Running python3 command to advertise AltServer: from ctypes import *; dll = CDLL('libdns_sd.so'); sdRef = c_int(); flags = 0; interfaceIndex = 0; name = None; regtype = br'_altserver._tcp'; domain = None; host = None; port = 33243; txtLen = 17; txtRecord = b'\x10\x73\x65\x72\x76\x65\x72\x49\x44\x3D\x31\x32\x33\x34\x35\x36\x37'; ret = dll.DNSServiceRegister(byref(sdRef), flags, interfaceIndex, name, regtype, domain, host, port, txtLen, txtRecord, None, None); print('DNSServiceRegister result: %d' % ret); from threading import Event; Event().wait();
*** WARNING *** The program 'python3.10' uses the Apple Bonjour compatibility layer of Avahi.
*** WARNING *** Please fix your application to use the native API of Avahi!
*** WARNING *** For more information see http://0pointer.de/blog/projects/avahi-compat.html
DNSServiceRegister result: -65548

Those Warnings are something that should I care about or could I ignore them?

@jschiefner
Copy link
Author

jschiefner commented Sep 28, 2023

@Flamini90 you're welcome! Do you set the USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 when starting AltServer? you should start it like this, in your case

sudo ALTSERVER_ANISETTE_SERVER="http://127.0.0.1:6969" USBMUXD_SOCKET_ADDRESS="127.0.0.1:27015" ./AltServer-aarch64

I'm not sure about the warnings, i think i had them too and it didnt matter (i dont use the setup anymore so i can't really verify right now). Maybe also try to do the login via USB and hope that it works with USB and then maybe you can rely on wifi just for refreshing the apps.

@Flamini90
Copy link

@Flamini90 you're welcome! Do you set the USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 when starting AltServer? you should start it like this, in your case

sudo ALTSERVER_ANISETTE_SERVER="http://127.0.0.1:6969" USBMUXD_SOCKET_ADDRESS="127.0.0.1:27015" ./AltServer-aarch64

I'm not sure about the warnings, i think i had them too and it didnt matter (i dont use the setup anymore so i can't really verify right now). Maybe also try to do the login via USB and hope that it works with USB and then maybe you can rely on wifi just for refreshing the apps.

Now I have again the heartbeat error... XD

That could be resolve it? (https://gist.github.com/jschiefner/95a22d7f4803e7ad32a95b0f3aa655dc#building-netmuxd-from-source)

root@Server:/home/flamini90/Developer/alt-server# ps aux | grep netmuxd
root 580 0.0 0.0 2888 1536 ? Ss 20:01 0:00 /bin/sh -c sleep 20 && export USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 && /home/flamini90/Developer/alt-server/x86_64-linux-netmuxd > /home/flamini90/Developer/alt-server/log/netmuxd.log 2>&1
root 1883 0.0 0.0 1766468 3712 ? Sl 20:01 0:00 /home/flamini90/Developer/alt-server/x86_64-linux-netmuxd
root 2995 0.0 0.0 14872 6016 pts/1 T 20:06 0:00 sudo USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 ./x86_64-linux-netmuxd
root 2996 0.0 0.0 14872 2544 pts/2 Ss 20:06 0:00 sudo USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015 ./x86_64-linux-netmuxd
root 2997 0.0 0.0 1764416 3712 pts/2 Tl+ 20:06 0:00 ./x86_64-linux-netmuxd
root 3048 0.0 0.0 14876 6016 pts/1 T 20:08 0:00 sudo ./x86_64-linux-netmuxd
root 3049 0.0 0.0 14876 2656 pts/5 Ss 20:08 0:00 sudo ./x86_64-linux-netmuxd
root 3050 0.0 0.0 1764428 5120 pts/5 Tl+ 20:08 0:00 ./x86_64-linux-netmuxd
root 3088 0.0 0.0 9236 2560 pts/4 S+ 20:11 0:00 grep --color=auto netmuxd

@jschiefner
Copy link
Author

@Flamini90 if that is all the output of ps aux | grep netmuxd then you sure do have a lot of netmuxd processes running, i can see how that could cause issues! try killing them (kill -9 <processid>) and having just one running at the same time. i dont know if building from source helps, i managed to build it but it didnt behave any differently for me.

@Flamini90
Copy link

Flamini90 commented Sep 28, 2023

@Flamini90 if that is all the output of ps aux | grep netmuxd then you sure do have a lot of netmuxd processes running, i can see how that could cause issues! try killing them (kill -9 <processid>) and having just one running at the same time. i dont know if building from source helps, i managed to build it but it didnt behave any differently for me.

I rebooted the machine, I had a lot of netmuxd processes because i was doing various tries .
Now I have this output:

root@Server:/home/flamini90/Developer/alt-server# ps aux | grep netmuxd
root 571 0.0 0.0 2888 1536 ? Ss 21:39 0:00 /bin/sh -c sleep 20 && /home/flamini90/Developer/alt-server/x86_64-linux-netmuxd > /home/flamini90/Developer/alt-server/log/netmuxd.log 2>&1
root 1873 0.0 0.0 1764428 5504 ? Sl 21:39 0:00 /home/flamini90/Developer/alt-server/x86_64-linux-netmuxd
root 3057 0.0 0.0 9236 2560 pts/1 S+ 21:41 0:00 grep --color=auto netmuxd

I have to kill some processes here?

@jschiefner
Copy link
Author

Try killing the first (it is probably from your cronjob, then the second should also disappear), and try again by just starting netmuxd as before. If you have the heartbeat error still then the previous method of using netmuxd was maybe better after all. Take a look at the other useful resources, maybe there is something that can help you or look at the reddit links at the top and see if you find a solution there. Thats all i can recommend ✌️

@clementmoine
Copy link

Awesome ! Thank you a lot ! I followed the steps and had issues with the libimobiledevice and libimobiledevice-glue but after multiple tries with the source and released versions that worked and I had no problem to fulfill the install until the end !

Now I have a RPI running armv7 netmuxd and alterserver perfectly ! I am trying to manage to get access to this through my Wireguard setup on my PI, it is not working out of the box but maybe there is a config trick in Wireguard to ensure this to work on LTE + home Wireguard setup

@Flamini90
Copy link

Flamini90 commented Mar 20, 2024

Try killing the first (it is probably from your cronjob, then the second should also disappear), and try again by just starting netmuxd as before. If you have the heartbeat error still then the previous method of using netmuxd was maybe better after all. Take a look at the other useful resources, maybe there is something that can help you or look at the reddit links at the top and see if you find a solution there. Thats all i can recommend ✌️

Hello Dear,
I picked up the problem again a few weeks ago and was able to solve my issue. I had to port forward my device to the machine where I hosted altserver :)

Thanks anyway for the help!

@jadc
Copy link

jadc commented May 8, 2024

When trying to install AltStore, I'm getting this error. Any ideas?

Installing app...
parse anisette data ret
Alert: Could not install 1_6_3.ipa to unknown.
    Failed to read HTTP status line
Press any key to continue...

@TaroKid
Copy link

TaroKid commented Oct 19, 2024

Every time I trie to deactivate an app, it always fail to deactivate it and untrust the developer so that I have to go back to setting and trust my self again. Installing new apps untrusts the app developer too. I cannot find which part I did is wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment