USB Network

After plugging a cable between your phone and PC, you should be able to do:

This article provides details in case this does not work out of the box (no IP assigned, doing a new port etc.).

= Connecting =

Power on your device and connect it to your USB port. A new network interface should appear, run  to list all of them. The new entry should look something like

If you instead get something like

then you need to give the interface a proper MAC address to be able to get an ip address, run. Make sure you specify the right interface name.

You should now have been assigned the IP  address (verify with   or  ). If it still does not work automatically, you might need to run a DHCP client on your PC ( or  ).

SSH
When you are past the initramfs, you should be able to connect via  and the username and password you set during the install phase:

Use  to run commands as , it is configured.

Prevent host key verification clashes when connecting to different devices
If you have multiple devices you want to SSH into, you will get issues with host key verification as your system will realize it's talking to different devices on the same IP address. To prevent this, disable host key verification entirely for the IP address used by postmarketOS devices when connected by USB.

Add the following to : Host pmos HostName 172.16.42.1 UserKnownHostsFile /dev/null StrictHostKeyChecking=no

Afterwards you can connect to your device by running. Replace  with the proper username on your device.

= Troubleshooting =

Try IPv4 only
Especially while mainlining, getting an IP oftentimes only works with the following command:

Making sure the USB is detected
In case you don't get an IP address directly, make sure that your PC recognizes the phone after it booted into postmarketOS at all. It should show the following in.

It should also show up on  (the name doesn't necessarily match the model):

And  should show an additional entry as well (the last one, in the following list):

If that's the case and you can't connect, your computer probably just doesn't have an IP address on its side of the link.

If however, nothing shows up (even when Inspecting the initramfs), the most likely reason is a wrong Kernel_configuration. This is highly device-specific, but some hints can be found in

No IP assigned or MAC address is 00:00:00:00:00:00
If USB gets detected, then you probably don't have a network manager that automatically requests IP addresses from new ethernet interfaces, so you'll have to set the interface up manually.

If there's no MAC address assigned(00:00:00:00:00:00), you need to assign one.

Use the following command to start a DHCP client. Replace the interface name with the one on your machine (see  before and after connecting the device via USB). Some Linux distributions have  installed instead of.

Some distribution use other tools that might interfere with  and. In most cases, you should be able to set an IP address with

If after assigning an IP address and  shows your device status as "DOWN" instead of "UNKNOWN", bring it up with

P.S. If your device is Samsung with old kernel and, something like usb_gadget-set-random-rndis-host-MAC-address.patch can help with preventing zero MAC.

After the interface is brought up you can SSH to the phone at the phone's ip address

Kernel configuration parameters
If you think that the kernel configuration may be at fault, first double check with  that the required parameters are all set. The postmarketOS initramfs is able to configure two different USB systems in the kernel in order to let your PC talk to your phone via networking. One of them has to be enabled (exclusively?):
 * CONFIG_USB_ETH
 * CONFIG_USB_ETH_RNDIS is usually needed as well, it enables a compatibility interface for microsoft hosts.
 * Usually used in mainline kernels (see also: Mainlining FAQ)
 * CONFIG_USB_G_ANDROID
 * This option is usually enabled in Android kernel forks

You can use  on your kernel config to check which of these options are enabled or not (  means it is enabled). If you want to change the options, don't modify the file directly, but use  (usage instructions). Otherwise the dependencies in that configuration file will not get resolved properly and cause other issues.

Related: linux-postmarketos-qcom: Remove composite usb gadget for networking

SSH issues
If SSH doesn't work for one reason or another, you can try enabling telnetd on your installation. For that, add the debug-shell initfs hook and connect to it. Then run the following commands to mount your root partition (writable): source /etc/deviceinfo source init_functions.sh mount_root_partition mount -o rw,remount /sysroot

Put the following content into
 * 1) !/sbin/openrc-run

command="/usr/sbin/telnetd" command_args="-F" pidfile="/run/${RC_SVCNAME}.pid" command_background="yes"

depend { need net localmount after firewall } Then make the file executable and enable the service so telnet gets launched by openrc: chmod +x /sysroot/etc/init.d/telnetd && chroot /sysroot rc-update add telnetd default

Then resume boot by typing. Telnetd should be started once the device boots and you should be able to connect to it.

Using Dropbear
Alternatively you can try to use  SSH server instead of default. For this you can avoid messing with debug-shell hook and modifying system on running phone, you can tweak rootfs before flashing it in this sequence:

1. pmbootstrap init 2. pmbootstrap install 3. pmbootstrap chroot -r   # go inside you phone's future rootfs 4. # make modifications to rootfs # in this case, to workaround an SSH issue: apk add dropbear rc-update del sshd default rc-update add dropbear default 5. exit 6. pmbootstrap install     # again, to recreate image # flash images as usual 7. pmbootstrap flasher flash_kernel 8. pmbootstrap flasher flash_rootfs

Note about HTC devices

 * HTC devices seem to be tricky in general, we have a few open issues with HTC devices that seem to be not booting
 * The HTC desire does work, and it required this line in the initfs-hook to get USB network
 * It was hard to discover: drebrez used the tuning sysfs instructions, but he had to write it as a initfs hook and save it in the  partition of the device, then reboot in TWRP to get that file.
 * Without a working display, no USB network and no serial output, you can use the LEDs for debugging and the other partitions to store files.

Windows driver
Normally Windows should already have / should be able to assign the right drivers. If it's not the case and before going further first check if you can assign Microsoft RNDIS USB driver to the device. If no RNDIS driver is showing up, follow what's next.

If your device is listed as an ADB device you'll have to uninstall it (with the driver) first.

if you can't find the RNDIS driver you'll have to create an inf file that match your computer OS version.

Take the file in the guide from microsoft.

Once you have the file, go into device manager. Follow the dialogs up to the 'choose a driver', point it to your .inf, accept the security warnings and you're done, using a ssh client you should be able to login.

= See also =
 * USB Internet: Let your phone access the Internet by sharing your PC's Internet connection via USB.
 * Osk-sdl
 * Troubleshooting:boot