Jump to content

Installing packages on a running phone: Difference between revisions

From postmarketOS Wiki
Fix packages directory after adding stable branch to pmaports
Knuxify (talk | contribs)
m fix syntax highlighting error
 
(30 intermediate revisions by 10 users not shown)
Line 1: Line 1:
1. Go to the pmbootstrap packages dir and start a web server:
{{warning|Do not install suspicious apk packages from unknown sources!}}
 
This article explains how to install packages that were built with [[pmbootstrap]] on your phone via Wi-Fi or USB network.
 
== pmbootstrap sideload ==
{{note|If you want to sideload an application to test a pmaports or aports merge request, [[Mrtest]] is probably more convenient.}}
 
This method copies a package via SSH to your phone and installs it. It makes installing a single package relatively easy. If you need to install multiple packages with dependencies on each other, hosting a repository locally (see below) is recommended instead.
 
Connect your phone using [[USB Network]] (or Wi-Fi) and make sure you can login into it with SSH. Then excecute the following:
<syntaxhighlight lang="shell-session">
pc:~$ pmbootstrap sideload --host 172.16.42.1 --user user --arch <arch> package-name
</syntaxhighlight>
replace ''arch''  with actual architecture (for example, aarch64).
 
Add <code>--install-key</code> argument if you see the error about untrusted signature.
 
Add <code>--port NUM</code> if your device's SSH server is running on a non-standard port (not 22). This may be needed for example, for an image that is running using '''pmbootstrap qemu''' (see [[QEMU]]).
 
For Wi-Fi use your device's Wi-Fi IP address.
 
== Host repository locally using a web server ==
This method is easier when you need to install multiple dependent packages at once, or simulate the regular upgrade process from repositories. For single packages, <code>pmbootstrap sideload</code> is probably easier, see above.
 
==== Start the webserver ====
 
===== Python http.server =====
Go to the pmbootstrap packages dir and start a web server:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ cd ~/.local/var/pmbootstrap/packages/edge
pc:~$ cd ~/.local/var/pmbootstrap/packages/edge && python3 -m http.server
$ python3 -m http.server
</syntaxhighlight>
</syntaxhighlight>


2. Add your own repository on top of your <code>/etc/apk/repositories</code> file on the phone (remember to adjust the IP):
===== Nginx =====
See [[Host a reverse_proxy to postmarketOS and Alpine_Repositories#Local repository server]]
 
==== Add the repository ====
Install your favorite editor and open <code>/etc/apk/repositories</code> on your phone via [[SSH]]:
 
<syntaxhighlight lang="shell-session">
phone:~$ sudo apk add neovim
phone:~$ sudo nvim /etc/apk/repositories
</syntaxhighlight>


<source lang="shell">
Add your own repository on top:
# Add your host machine address
<syntaxhighlight lang="text">
http://172.16.42.2:8000
http://172.16.42.2:8000
   
https://nl.alpinelinux.org/alpine/edge/main
https://nl.alpinelinux.org/alpine/edge/community
https://nl.alpinelinux.org/alpine/edge/testing
</source>


3. Upgrade the package you have built with <code>apk upgrade [package name]</code>
http://mirror.postmarketos.org/postmarketos/v20.05
http://dl-cdn.alpinelinux.org/alpine/v3.12/main
http://dl-cdn.alpinelinux.org/alpine/v3.12/community
</syntaxhighlight>
 
==== Copy the package signing keys ====
If you did not generate the postmarketOS installation from the same PC, which is now running pmbootstrap to build the packages you want to install, then you need to copy the package signing keys. Otherwise, apk will refuse to install the packages ("UNTRUSTED signature").
 
On your PC (replace <code>172.16.42.1</code> with the IP of your phone, <code>user</code> with your ssh username, mind the <code>:</code> at the end of the <code>scp</code> command):
<syntaxhighlight lang="shell-session">
pc:~$ scp ~/.local/var/pmbootstrap/config_apk_keys/pmos*.rsa.pub user@172.16.42.1:
pc:~$ ssh user@172.16.42.1
</syntaxhighlight>


If you get <code>UNTRUSTED signature</code> and you trust your LAN, then you may consider <code>apk upgrade --allow-untrusted [package name]</code>. Beware of the security implications that <code>--allow-untrusted</code> has.
Run on your phone via SSH:
<syntaxhighlight lang="shell-session">
phone:~$ sudo mv pmos*.rsa.pub /etc/apk/keys/
</syntaxhighlight>


4. '''Optional:''' If you are upgrading a kernel package, the new Android boot image is not automatically flashed to the boot partition at the moment. If you are booting the flashed image (i.e. not using <code>pmbootstrap flasher boot</code>) you'll need to call <code>pmos-update-kernel</code>.
==== Use your repository ====
Now <code>apk</code> should recognize your repository, and you should be able to install or upgrade packages built on your PC:


The apk hosting this command is called <code>postmarketos-update-kernel</code>. Then you need to figure out the name of your kernel flavor. Run <code>ls /boot/boot.img-*</code>. Whatever is after the dash, that is your kernel flavor. So
<syntaxhighlight lang="shell-session">
phone:~$ sudo apk update
fetch http://172.16.42.2:8000/aarch64/APKINDEX.tar.gz
fetch http://postmarketos1.brixit.nl/postmarketos/v20.05/aarch64/APKINDEX.tar.gz                                                                 
fetch http://dl-cdn.alpinelinux.org/alpine/v3.12/main/aarch64/APKINDEX.tar.gz                                                                   
fetch http://dl-cdn.alpinelinux.org/alpine/v3.12/community/aarch64/APKINDEX.tar.gz                                                               
postmarketOS [http://172.16.42.2:8000]
2020-09-01 17:02:31.099145 [http://postmarketos1.brixit.nl/postmarketos/v20.05]                                                                 
v3.12.0-283-g612cd12ab6 [http://dl-cdn.alpinelinux.org/alpine/v3.12/main]                                                                       
v3.12.0-276-gbdd3966958 [http://dl-cdn.alpinelinux.org/alpine/v3.12/community]                                                                   
OK: 12967 distinct packages available
phone:~$ sudo apk upgrade hello-world
</syntaxhighlight>


<source lang="shell">
== pmos-update-kernel ==
$ ls /boot/boot.img-*
{{warning|Do not use pmos-update-kernel on '''lk2nd''' devices, such as '''MSM8916''' devices. lk2nd in boot partition will be replaced and the booting will be broken!}}
/boot/boot.img-postmarketos-qcom-msm8974
While devices in main and community categories are expected to update the kernel fully automatically, many Android devices currently need to run <code>pmos-update-kernel</code> after a kernel upgrade, to actually write the new kernel to the partition expected by the bootloader (see [[Boot_process#LK_.28Android.29|boot process]]). You should check the page for your device or it's platform to know if you need this extra step.
# your kernel flavor is postmarketos-qcom-msm8974
$ sudo pmos-update-kernel postmarketos-qcom-msm8974
</source>


==== Run it manually ====
Install <code>postmarketos-update-kernel</code>, figure out the kernel flavor (in the example below: <code>postmarketos-qcom-msm8974</code>) and update the kernel:


== Updating your kernel from a running phone ==
<syntaxhighlight lang="shell-session">
phone:~$ sudo apk add postmarketos-update-kernel
phone:~$ ls /boot/boot.img-*
/boot/boot.img-postmarketos-qcom-msm8974
phone:~$ sudo pmos-update-kernel postmarketos-qcom-msm8974
</syntaxhighlight>


==== Automate with a script ====
If you're experimenting with mainline kernel and adding new features you might end up wanting to update your kernel and restart your phone very often. On the kernel building end you can use [[envkernel.sh]] + <code>pmbootstrap build --envkernel MAINLINE_LINUX_PACKAGE_NAME</code>. That will produce a fresh new kernel package with the changes you made. Then you need to install that package to the phone.
If you're experimenting with mainline kernel and adding new features you might end up wanting to update your kernel and restart your phone very often. On the kernel building end you can use [[envkernel.sh]] + <code>pmbootstrap build --envkernel MAINLINE_LINUX_PACKAGE_NAME</code>. That will produce a fresh new kernel package with the changes you made. Then you need to install that package to the phone.


After you execute steps 1 and 2 above, install postmarketos-update-kernel, and find your kernel flavor, you can run the following script:
Use this script to automate the steps above (adjust <code>postmarketos-qcom-msm8974</code>!):
<syntaxhighlight lang="shell">
#!/bin/sh -ex
# Upgrade all packages (should have your kernel upgrade)
sudo apk update
sudo apk add postmarketos-update-kernel
sudo apk upgrade


<source lang="shell">
# Write kernel to location expected by LK
#!/bin/sh
sudo pmos-update-kernel postmarketos-qcom-msm8974


set -e # errors are critical -- will end script immediately
# Prompt for restart
set -x # echo executed commands
sudo apk --allow-untrusted update                    # update package info
sudo apk --allow-untrusted upgrade                  # upgrade all new packages (most likely kernel)
sudo pmos-update-kernel postmarketos-qcom-msm8974    # make sure new kernel is selected after reboot
set +x
set +x
 
echo -n 'reboot [yN]? '
echo -n 'reboot [yN]? '                             # prompt for restart
read ans
read ans
test "$ans" = 'y' && sudo reboot
test "$ans" = 'y' && sudo reboot
</source>
</syntaxhighlight>
 
== See also ==
* [[Host a reverse proxy to postmarketOS and Alpine Repositories]]


[[Category:Guide]]
[[Category:Guide]]

Latest revision as of 12:55, 4 June 2024

Warning WARNING: Do not install suspicious apk packages from unknown sources!

This article explains how to install packages that were built with pmbootstrap on your phone via Wi-Fi or USB network.

pmbootstrap sideload

Note If you want to sideload an application to test a pmaports or aports merge request, Mrtest is probably more convenient.

This method copies a package via SSH to your phone and installs it. It makes installing a single package relatively easy. If you need to install multiple packages with dependencies on each other, hosting a repository locally (see below) is recommended instead.

Connect your phone using USB Network (or Wi-Fi) and make sure you can login into it with SSH. Then excecute the following:

pc:~$ pmbootstrap sideload --host 172.16.42.1 --user user --arch <arch> package-name

replace arch with actual architecture (for example, aarch64).

Add --install-key argument if you see the error about untrusted signature.

Add --port NUM if your device's SSH server is running on a non-standard port (not 22). This may be needed for example, for an image that is running using pmbootstrap qemu (see QEMU).

For Wi-Fi use your device's Wi-Fi IP address.

Host repository locally using a web server

This method is easier when you need to install multiple dependent packages at once, or simulate the regular upgrade process from repositories. For single packages, pmbootstrap sideload is probably easier, see above.

Start the webserver

Python http.server

Go to the pmbootstrap packages dir and start a web server:

pc:~$ cd ~/.local/var/pmbootstrap/packages/edge && python3 -m http.server
Nginx

See Host a reverse_proxy to postmarketOS and Alpine_Repositories#Local repository server

Add the repository

Install your favorite editor and open /etc/apk/repositories on your phone via SSH:

phone:~$ sudo apk add neovim
phone:~$ sudo nvim /etc/apk/repositories

Add your own repository on top:

http://172.16.42.2:8000

http://mirror.postmarketos.org/postmarketos/v20.05
http://dl-cdn.alpinelinux.org/alpine/v3.12/main
http://dl-cdn.alpinelinux.org/alpine/v3.12/community

Copy the package signing keys

If you did not generate the postmarketOS installation from the same PC, which is now running pmbootstrap to build the packages you want to install, then you need to copy the package signing keys. Otherwise, apk will refuse to install the packages ("UNTRUSTED signature").

On your PC (replace 172.16.42.1 with the IP of your phone, user with your ssh username, mind the : at the end of the scp command):

pc:~$ scp ~/.local/var/pmbootstrap/config_apk_keys/pmos*.rsa.pub user@172.16.42.1:
pc:~$ ssh user@172.16.42.1

Run on your phone via SSH:

phone:~$ sudo mv pmos*.rsa.pub /etc/apk/keys/

Use your repository

Now apk should recognize your repository, and you should be able to install or upgrade packages built on your PC:

phone:~$ sudo apk update
fetch http://172.16.42.2:8000/aarch64/APKINDEX.tar.gz
fetch http://postmarketos1.brixit.nl/postmarketos/v20.05/aarch64/APKINDEX.tar.gz                                                                  
fetch http://dl-cdn.alpinelinux.org/alpine/v3.12/main/aarch64/APKINDEX.tar.gz                                                                     
fetch http://dl-cdn.alpinelinux.org/alpine/v3.12/community/aarch64/APKINDEX.tar.gz                                                                
postmarketOS [http://172.16.42.2:8000]
2020-09-01 17:02:31.099145 [http://postmarketos1.brixit.nl/postmarketos/v20.05]                                                                   
v3.12.0-283-g612cd12ab6 [http://dl-cdn.alpinelinux.org/alpine/v3.12/main]                                                                         
v3.12.0-276-gbdd3966958 [http://dl-cdn.alpinelinux.org/alpine/v3.12/community]                                                                    
OK: 12967 distinct packages available
phone:~$ sudo apk upgrade hello-world

pmos-update-kernel

Warning WARNING: Do not use pmos-update-kernel on lk2nd devices, such as MSM8916 devices. lk2nd in boot partition will be replaced and the booting will be broken!

While devices in main and community categories are expected to update the kernel fully automatically, many Android devices currently need to run pmos-update-kernel after a kernel upgrade, to actually write the new kernel to the partition expected by the bootloader (see boot process). You should check the page for your device or it's platform to know if you need this extra step.

Run it manually

Install postmarketos-update-kernel, figure out the kernel flavor (in the example below: postmarketos-qcom-msm8974) and update the kernel:

phone:~$ sudo apk add postmarketos-update-kernel
phone:~$ ls /boot/boot.img-*
/boot/boot.img-postmarketos-qcom-msm8974
phone:~$ sudo pmos-update-kernel postmarketos-qcom-msm8974

Automate with a script

If you're experimenting with mainline kernel and adding new features you might end up wanting to update your kernel and restart your phone very often. On the kernel building end you can use envkernel.sh + pmbootstrap build --envkernel MAINLINE_LINUX_PACKAGE_NAME. That will produce a fresh new kernel package with the changes you made. Then you need to install that package to the phone.

Use this script to automate the steps above (adjust postmarketos-qcom-msm8974!):

#!/bin/sh -ex
# Upgrade all packages (should have your kernel upgrade)
sudo apk update
sudo apk add postmarketos-update-kernel
sudo apk upgrade

# Write kernel to location expected by LK
sudo pmos-update-kernel postmarketos-qcom-msm8974

# Prompt for restart
set +x
echo -n 'reboot [yN]? '
read ans
test "$ans" = 'y' && sudo reboot

See also