Jump to content

USB Network: Difference between revisions

From postmarketOS Wiki
m USB Network: Change header sizes
Line 2: Line 2:
postmarketOS uses [[USB Network]]ing for every communication between the device and computer.
postmarketOS uses [[USB Network]]ing for every communication between the device and computer.


=== Connecting ===
= Connecting =
Power on your device and connect it to your USB port. You should get the IP <code>172.16.42.2</code> assigned to your PC, check it with <code>ip a</code> or <code>ifconfig</code>.
Power on your device and connect it to your USB port. You should get the IP <code>172.16.42.2</code> assigned to your PC, check it with <code>ip a</code> or <code>ifconfig</code>.


Line 15: Line 15:
</source>
</source>


=== SSH ===
== SSH ==
{{note|There is a dedicated article for [[Inspecting_the_initramfs|inspecting the initramfs]] via telnet.}}
{{note|There is a dedicated article for [[Inspecting_the_initramfs|inspecting the initramfs]] via telnet.}}


Line 37: Line 37:
Use <code>sudo</code> to run commands as <code>root</code>, it is configured.
Use <code>sudo</code> to run commands as <code>root</code>, it is configured.


=== Troubleshooting ===
= Troubleshooting =


==== Try IPv4 only ====
== Try IPv4 only ==
Especially while mainlining, getting an IP oftentimes only works with the following command:
Especially while mainlining, getting an IP oftentimes only works with the following command:
<source lang="shell-session">
<source lang="shell-session">
Line 45: Line 45:
</source>
</source>


==== Making sure the USB is detected ====
== 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 <code>dmesg</code>.
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 <code>dmesg</code>.


Line 83: Line 83:
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 [[#Kernel configuration parameters]]
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 [[#Kernel configuration parameters]]


==== No IP assigned or MAC address is 00:00:00:00:00:00 ====
== 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 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.


Line 109: Line 109:
P.S. If your device is Samsung with old kernel and <code>CONFIG_USB_ANDROID_SAMSUNG_COMPOSITE</code>, something like [https://gitlab.com/postmarketOS/pmaports/blob/master/device/linux-samsung-klte/0007-usb_gadget-set-random-rndis-host-MAC-address-to-prev.patch this patch] can help with preventing zero MAC.
P.S. If your device is Samsung with old kernel and <code>CONFIG_USB_ANDROID_SAMSUNG_COMPOSITE</code>, something like [https://gitlab.com/postmarketOS/pmaports/blob/master/device/linux-samsung-klte/0007-usb_gadget-set-random-rndis-host-MAC-address-to-prev.patch this patch] can help with preventing zero MAC.


==== Kernel configuration parameters ====
== Kernel configuration parameters ==
If you think that the kernel configuration may be at fault, first double check with <code>pmbootstrap kconfig check</code> that the required parameters are all set.
If you think that the kernel configuration may be at fault, first double check with <code>pmbootstrap kconfig check</code> 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?):
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?):
Line 122: Line 122:
Related: {{github|1462}} linux-postmarketos-qcom: Remove composite usb gadget for networking
Related: {{github|1462}} linux-postmarketos-qcom: Remove composite usb gadget for networking


==== SSH issues ====
== 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):
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):
Line 169: Line 169:
  8. pmbootstrap flasher flash_rootfs
  8. pmbootstrap flasher flash_rootfs


=== Note about HTC devices ===
== Note about HTC devices ==
* HTC devices seem to be tricky in general, we have a [[Troubleshooting:boot#See_also|few open issues]] with HTC devices that seem to be not booting
* HTC devices seem to be tricky in general, we have a [[Troubleshooting:boot#See_also|few open issues]] with HTC devices that seem to be not booting
* The [[HTC_Desire_(htc-bravo)|HTC desire]] does work, and it required [https://github.com/postmarketOS/pmbootstrap/blob/bd4ebb3473764108daa92b308511be7e0a1b6948/aports/device/device-htc-bravo/initfs-hook.sh#L8 this line in the initfs-hook] to get USB network
* The [[HTC_Desire_(htc-bravo)|HTC desire]] does work, and it required [https://github.com/postmarketOS/pmbootstrap/blob/bd4ebb3473764108daa92b308511be7e0a1b6948/aports/device/device-htc-bravo/initfs-hook.sh#L8 this line in the initfs-hook] to get USB network
Line 175: Line 175:
* 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.
* 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.


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

Revision as of 09:02, 14 October 2019

USB connectivity is generally one of the first things you want up and running on your phone when porting to a new device. postmarketOS uses USB Networking for every communication between the device and computer.

Connecting

Power on your device and connect it to your USB port. You should get the IP 172.16.42.2 assigned to your PC, check it with ip a or ifconfig.

$ ip a
1: enp0s19f2u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UNKNOWN group default qlen 1000
    link/ether aa:bb:cc:dd:ee:ff brd ff:ff:ff:ff:ff:ff
    inet 172.16.42.2/24 brd 172.16.42.255 scope global dynamic noprefixroute enp0s19f2u1
       valid_lft 861920sec preferred_lft 861920sec
    inet6 fe80::aabb:ccdd:eeff:00aa/64 scope link noprefixroute
       valid_lft forever preferred_lft forever

SSH

Note There is a dedicated article for inspecting the initramfs via telnet.

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

$ ssh user@172.16.42.1
user@172.16.42.1's password: 
Welcome to postmarketOS!

This distribution is based on Alpine Linux.
Read both our wikis to find a large amount of how-to guides and
general information about administrating and development.
See <https://wiki.postmarketos.org> and <https://wiki.alpinelinux.org>.

You may change this message by editing /etc/motd.

localhost:~$

Use sudo to run commands as root, it is configured.

Troubleshooting

Try IPv4 only

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

$ dhcpcd interface --nohook ipv6

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 dmesg.

[ 6284.442088] usb 1-1: new high-speed USB device number 36 using xhci_hcd
[ 6284.627106] usb 1-1: New USB device found, idVendor=18d1, idProduct=d001
[ 6284.627123] usb 1-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 6284.627134] usb 1-1: Product: Android
[ 6284.627143] usb 1-1: Manufacturer: Android
[ 6284.627151] usb 1-1: SerialNumber: 0123456789ABCDEF
[ 6284.632322] rndis_host 1-1:1.0 usb0: register 'rndis_host' at usb-0000:00:14.0-1, RNDIS device, b2:c4:1e:03:64:b9
[ 6285.239048] rndis_host 1-1:1.0 enp0s20f0u1: renamed from usb0
[ 6285.287058] IPv6: ADDRCONF(NETDEV_UP): enp0s20f0u1: link is not ready

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

Bus 001 Device 023: ID 18d1:d001 Google Inc. Nexus 4 (fastboot)
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

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

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether e2:88:85:58:0f:99 brd ff:ff:ff:ff:ff:ff
3: wlp2s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DORMANT group default qlen 1000
    link/ether e2:08:85:58:0f:99 brd ff:ff:ff:ff:ff:ff
14: enp0s29f7u3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UNKNOWN mode DEFAULT group default qlen 1000
    link/ether 86:11:85:5e:df:fa brd ff:ff:ff:ff:ff:ff

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 #Kernel configuration parameters

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.

# ip link set dev enp0s20f0u1 address 12:12:12:12:12:12

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

$ dhclient -v enp0s20f0u1

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

# ip address add dev enp0s20f0u1 172.16.42.2/24

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

# ip link set enp0s20f0u1 up


P.S. If your device is Samsung with old kernel and CONFIG_USB_ANDROID_SAMSUNG_COMPOSITE, something like this patch can help with preventing zero MAC.

Kernel configuration parameters

If you think that the kernel configuration may be at fault, first double check with pmbootstrap kconfig check 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?):

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

Related: #1462 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 /sysroot/etc/init.d/telnetd

#!/sbin/openrc-run

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

depend() {
        need net localmount
        after firewall
}

Afterwards enable the service so telnet gets launched by openrc:

chroot /sysroot rc-update add telnetd default

Then telnetd should be started once the device boots and you should be able to connect to it.

Alternatively you can try to use dropbear SSH server instead of default openssh. 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 cache 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.

See also