SSH

This article provides an overview of how to use the SSH server after postmarketOS was installed. It is aimed at beginners, who have possibly installed postmarketOS for the first time.

Start the SSH Daemon

If you are running postmarketOS from a pre-built image, the SSH daemon is disabled. Open a terminal on your phone and type the following to start it. Your sudo password is your PIN (147147 in pre-built images):

$ sudo service sshd start

Enable the service on every boot:

$ sudo rc-update add sshd

Config

For developers connecting regularly over USB, an SSH config entry like the following will reduce a lot of headache:

Host 172.16.42.1 pmos
    HostName 172.16.42.1
    User user
    StrictHostKeyChecking no
    UserKnownHostsFile=/dev/null
    ConnectTimeout 5
    ServerAliveInterval 1
    ServerAliveCountMax 5

This will fairly quickly time out when the device is rebooted or unplugged, avoid saving into UserKnownHosts (mostly helpful if you reflash often or work on multiple devices), and avoid other annoying prompts.

Find the IP of your phone

When connecting your phone via USB Network, then the IP of the phone is 172.16.42.1.

Wi-Fi

In Phosh, you can find the IP in the "Settings" app, by clicking on the cogwheel next to the Wi-Fi network you are connected to, then "More details".

In any user interface, you can open a terminal and type ip a to display the Wi-Fi IP.

First login

Password authentication with a short password is unsafe! Leave it in this state not longer than necessary by following replace password with SSH key below.

Make sure your phone is on the same Wi-Fi network as your PC, or connect your phone via USB to your PC. Then type:

$ ssh username@172.16.42.1

In pre-built images, username defaults to user and your user's password or PIN is 147147. Adjust the IP as necessary.

If you cannot login as user, see the troubleshooting instructions below.

If that doesn't help it either, see USB Network for a more detailed guide and more troubleshooting instructions.

Improving security

Using an SSH key instead of a password

If the SSH server is enabled in postmarketOS, it listens to USB networking, Wi-Fi and cellular network. This provides a big attack surface, so it's highly recommended to install an SSH key and disable password login.

In order to do so, you need to generate a keypair on your client machine. If that is still connected to the phone, quit the connection: $ exit. Then generate the keypair:

$ ssh-keygen -t rsa

Now you will be asked a few questions. You can hit 'Enter' to chose the default location for the keys. Set a passphrase you can remember. After the successful generation of the keys, the public key is now located in /home/user/.ssh/id_rsa.pub. The public key needs to be transferred to the phone.

$ ssh-copy-id username@172.16.42.1

You will have to enter your phones password. Now make sure everything worked by using ssh with your passphrase:

$ ssh username@172.16.42.1

If you were asked for the passphrase and successfully logged in, everything worked as expected.

When generating your own image with pmbootstrap, your SSH public key should be copied automatically if you had one. If you have multiple keys, you can customize which are copied by changing pmbootstrap config ssh_key_glob

The next step is to only allow logging in via the ssh keys. To do so, edit the file /etc/ssh/sshd_config. If you have nano installed the command is:

$ sudo nano /etc/ssh/sshd_config

In this file, set:

PasswordAuthentication no
KbdInteractiveAuthentication no

Save and close the file. Then restart the ssh server for the changes to take effect.

Enable specific network interfaces only

New installations have a nftables as firewall configured that limits incoming SSH connections to Wi-Fi and USB (only on some devices?). As mentioned in the linked article, you can add your own rules too if you want to lock it down even more.

Troubleshooting

Login with username "user" fails

In postmarketOS v21.03 and earlier, as well as postmarketOS edge before 2021-06, the on-device installer asked if a dedicated SSH user should be created. While the original idea was to ensure that the SSH user always has a stronger password than just a numeric PIN that would be used for the main user at the time, this made the installation process more complicated and it's more complex to use the dedicated user to access files from / start applications for the regular user. So this was removed in favor of having SSH always disabled and following the (relatively simple) steps to enable and secure it on this wiki page. So if you are currently running a postmarketOS installation that was set up like this, do the following to make it possible to login as the regular user. And then make sure that you copy over your SSH key and disable password authentication again, as described above in this article.

Open the file /etc/ssh/sshd_config with a text editor, for example vi:

$ sudo vi /etc/ssh/sshd_config

Then enable password authentication for your user by removing the following section from the end of the file (in vi: arrow keys or j/k to navigate up/down, press d twice to delete a line, :w to write, :q to quit).

Match User user
    PasswordAuthentication no
Match all

Save and close the file and restart (or start if not running) the SSH service:

$ sudo service sshd restart

Login with username "root" fails

After having put a good /root/.ssh/authorized_keys file into the root account (maybe just by copying the user account's one), if it still fails to get in, it is because the root account is disabled (no password is set). To enable public key SSH login with the root account you have to set a password for the root user first.

Enable SSH in downloaded image

In some hopefully rare cases, when using images downloaded from bpo, you may have no easy way to gain access to the running system to enable SSH (e.g. broken touch sensor). You can get around this limitation by enabling SSH in the image before you write it to the device. Proceed as follows:

# Decompress the image
$ xz -d _image.img.xz

# Find the start of the root partition inside image
$ sudo fdisk -l _image.img

# The output is as follows:
#    ...
#    Units: sectors of 1 * 512 = 512 bytes
#    ...
#    Device         Boot  Start     End Sectors  Size Id Type
#    _image.img1    *      2048  499711  497664  243M 83 Linux
#    _image.img2         499712 2437119 1937408  946M 83 Linux

# The important values are: the sector size = 512 in this case, and
# the start sector of the rootfs (2nd partition in this case) = 499712

# Mount the root partition stored inside image. The numbers are from previous command
$ sudo mkdir /mnt/image/
$ sudo mount -o loop,offset=$((512*499712))  _image.img  /mnt/image

# Create symlink to sshd in default runlevel
$ cd /mnt/image/etc/runlevels/default
$ sudo ln -s /etc/init.d/sshd

# Unmount the image
$ sudo unmount /mnt/image

SSH will be active in the image when you flash/burn it

Cool things to do with SSH