Openmoko Networking Setup

In order to communicate via TCP/IP to your FreeRunner, a basic understanding of the networking expectations is required. Each end of the USB connection forms a LAN (local area network) segment, with the FreeRunner's USB networking device at one end (default 192.168.0.202) and your laptop or desktop at the other end (192.168.0.200 in this guide).

Normally, your desktop machine will know how to reach the Internet, having had its gateway (the IP address of the machine or device which knows how to send packets to machines beyond your subnet) configured via DHCP or statically (probably via a router). For the FreeRunner to reach the Internet, your desktop will have to be configured to route and masquerade (NAT) packets from it.

Normally, none of this is an issue, but problems can arise when the subnet between the FreeRunner and your desktop overlap with the desktop to the router (which forms a second LAN), since your desktop might not know how to route traffic properly.

In other words: if your existing router and desktop have addresses 192.168.0.(something) changing them to e.g. 192.168.1.(something) might save you a lot of troubleshooting later. A discussion of this is here.

Simple Manual Linux Configuration

Try this first (as root on your desktop, with FreeRunner attached via USB cable and booted properly, not at the Boot Menu). If it works, then you can add permanent configuration or use more sophisticated setups below.

The shortest way

This simple way has been tested with many Linux distributions and network configurations. It was even successfully applied to connect another Linux based handhelds like TDS Nomad and surely can be recommended as the first attempt.

If your Internet connection is also in the range 192.168.0.x then instead you might want to use only:

ip addr add 192.168.0.200/28 dev usb0

(This will just map the net from 192.168.0.192 to 192.168.0.207 onto usb0. If you get the error 'Cannot find device "usb0"', double-check that your FreeRunner is turned on and connected by USB. If that doesn't work, try unplugging and replugging the USB cable.)

And in this case you should enable ARP proxy on internet facing interface INSTEAD of using iptables:

sysctl net.ipv4.conf.eth2.proxy_arp=1

This assuming that eth2 is connected to ISP.

Then

ifconfig usb0 up

Then (ideally, not as root):

ssh root@192.168.0.202

The default password is blank.

Due to the fact that in most cases your Neo will use the same dns servers as your computer uses, you can automate the process of writing dns servers to your phone:

Again if your net already is 192.168.0.0, replace the POSTROUTING statement with

iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/28

This simple script will set up routing for your Freerunner and than copy resolv.conf with dns addresses straight to the phone.
All you have to do is connect phone to the computer, run the script and enjoy internet connection from your phone.

Linux Kernel Support

Your Linux desktop/laptop needs to have suitable support, in particular, you will need to have enabled full masquerading in the kernel and USB networking options enabled. For default kernels in many Linux distributions, this will already be the case. If not, you will need to enable:

Firewall Issues

On some systems, you may have firewall rules which prevent this working - such as added by the iptables service on Fedora. You may care to stop these, and/or review any rules or policies you think might cause issues.

The most relevant table is the nat table, which controls translation of addresses:

iptables -L -t nat -v -n

Unless you have a special setup, you'll want to see only the MASQUERADE rule that you apply below, and ACCEPT as the default policy. Also look at the filter table:

iptables -L -t filter -v -n

If this contains anything in the FORWARD chain, then this may prevent passing packets. It can be flushed with:

iptables -t filter -F FORWARD

DNS

In addition to routing issues, to be practical, DNS will need to work. In some cases, you might already be running a DNS server on your desktop such as dnsmasq or bind9, which is the default assumption the FreeRunner makes. In other cases, you'll need to configure DNS to that of your router, or a DNS server further out on the internet such as that provided by your ISP.

Configure Default Neo DNS

DNS is configured in /etc/resolv.conf on your FreeRunner.

You should add the IP address of the DNS servers as provided by your ISP. Check your router's or PC's network status for the nameserver IP addresses.

These settings will be lost on reboot. You can set the DNS for the next connect, by adding the following to the end of the usb0 setting in /etc/network/interfaces, right above the bluetooth networking section:

Proxying DNS from Desktop/Laptop

If you move about, making assumptions about the network may not be convenient, and it is possible to proxy DNS requests via your host laptop (which you are also taking with you), without running or installing a DNS server. There are a number of ways to do this:

If so, then this is sufficient for most internet access. But manual changes to resolv.conf are usually lost later if for example one uses DHCP, especially for WiFi, and so may not be convenient to configure manually.

Testing Your Connection

You should be able to connect to your Neo! Make sure you can ping your Neo to be sure.
ping 192.168.0.202

Then log into your Neo using ssh:
ssh root@192.168.0.202
The default password is blank (press enter).

You can also scp files back and forth. You can telnet, SSH, SMB or do whatever you want if you install software that enables you to set up TCP/IP network over your USB connection.

Now, make sure you can ping back to your desktop
ping 192.168.0.200
(Note that some systems like Vista, don't respond to ICMP ping by default)

Try pinging the outside world (a Google IP address)
ping 74.125.19.147
This demonstrates that masquerading is working - your desktop is sending/receiving packets to the wider internet.

OS or Distro Specific & Automatic Configuration

Based on Hotplugging usbnet by Marcin 'Hrw' Juszkiewicz.
These instructions should keep you from having to run the Simple Manual Linux Configuration every time you plug in and want to connect to an Openmoko device. One run and then you're done!

If the Simple Manual Linux Configuration does not work for your OS or Distro (MacOS X, MS Windows, etc) there may be instructions here that work for you.

MacOS X

Windows

There is also a very helpful tutorial for connecting with Vista at [1].

FreeBSD

You need to load the cdce kernel module (if it is not already linked into your kernel). As root do:

kldload cdce

The Neo should then show up as cdce0 interface and you can handle the cdce0 interface just like the usb0 device under Linux. For more information see the cdce manpage. An easy way to assign the IP address to the cdce0 interface is using the devd(8) daemon. Create the following two files,

This is more sophisticated than the manual setup. The 'auto usb' stanza ties into the Linux hotplug system so that when the device appears and vanishes, as happens when the FreeRunner is connected via USB, this is run.

In addition, the desktop-side netmask is limited to a much smaller range, so that overlapping subnets are less of a problem - Linux will use more specific routes first when deciding where to send packets.

Another possible configuration that adds DNS forward and removes
the iptables changes after unplugging:

It is possible to use network-manager to automatically connect to the Freerunner using udev. The process uses udev to run a script when the Frerunner is plugged in. The script uses the ip command to set the mac address of the usb network interface. To begin, create /etc/udev/rules.d/80-freerunner.rules :

# This file causes programs to be run on device insertion.
# See udev(7) for syntax.
# rule to assign a fixed mac address specified in /
KERNEL=="usb[0-9]*", DRIVERS=="cdc_ether", ACTION=="add", RUN+="/usr/local/sbin/freerunner-usb-add.sh %k"

Finally run "chmod +x /usr/local/sbin/freerunner-usb-add.sh" to make it executable. Now you can use network-manager with mac-address specific settings and get it to automatically connect.

Ubuntu Issues

Ubuntu 8.10 doesn't work as expected if you used /etc/network/interfaces to automate the connection. Network manager likes to latch onto the network device and add a default route through 192.168.0.202, breaking your network connection. Network manager also says you can't edit or remove this connection from its list. I'm going back to making the connection manually.

The bug is that the DRIVERS variable isn't set at all when the device is unplugged.

This appears to be fixed in Ubuntu 8.04 Mattt 11:38, 30 July 2008 (UTC)

Actually it appears that it's not fixed, but patching that file and disconnecting and reconnecting the phone works perfectly. --Johndoesacc 18:37, 20 August 2008 (UTC)

Well, yes, it must be fixed because it worked for me out-of-the-box without tweaking the udev rule on 8.04 --EtienneG November 26th, 2008

Ubuntu Workaround

Use wicd instead of networkmanager:
It is much further in development than networkmanager yet and doesn't make any problems with USB networking. You can use the "normal" settings in /network/interfaces.
Note: Because of it's dependencies it deinstalls networkmanager.

Mandriva

This first file configures the network system for the usb0 interface. Any time you plug in the FreeRunner the interface will be configured.

This next file configures the static routes that we need to communicate to the subnet. Since it has "usb0" in the name, the system will automatically apply these static routes any time that the usb0 interface is configured. (i.e. when you connect the FreeRunner)

/etc/sysconfig/network-scripts/usb0-routes:

ADDRESS0=192.168.0.200
NETMASK0=255.255.255.0

Now we need to restart the network system to pick up the changes.

service network restart

This didn't work for me (Mandriva 2008.1), giving errors from Shorewall. However, simply using MCC, Network->Sharing Internet Access worked fine. You need to connect Neo when starting it. --Alih 18:50, 22 September 2008 (UTC)

Automatic Configuration

One way to automate all this is to create /etc/conf.d/net.usb0 as follows. It sets IP forwarding and the iptables rules all in one go. It removes the iptables rules and disables ip forwarding when the FreeRunner is unplugged.

Archlinux

SSH Extras

Reportedly, the ssh daemon (dropbear 0.49) on the FreeRunner appears to have a bug when sending the exit status back to the client. From time to time you receive an exit status of 255.

To avoid ssh adding a new line for every ssh host-key to your known_hosts you can add the following to the phone section in ~/.ssh/config (or see the snippet at : USB Networking#Changing_host_keys bellow)

UserKnownHostsFile /dev/null

You might want to use keys to bypass the login prompt too.

SSH Keys

From desktop to FreeRunner

To generate ssh keys for use as a login mechanism type:

user@host$ ssh-keygen -t rsa

When prompted for a password either hit enter for no password (not really a good idea) or enter a password for this key. ssh into the phone and create ~/.ssh:

root@phone# mkdir ~/.ssh

Then from your desktop copy the .pub file to the phone.

user@host$ scp ~/.ssh/id_rsa.pub root@phone:~/.ssh/authorized_keys

You should now be able to ssh directly into the phone without a password prompt using a command like 'ssh root@phone' from the account user@host because the public key in the file user@host:~/.ssh/id_rsa.pub is contained in the list of keys which have access in the file root@phone:~/.ssh/authorized_keys (since scp is used, only one key exists, but you can grant access to the phone from more than one account, for example user@host, user@laptop).

To make ssh login as root by default, add the following lines to ~/.ssh/config:

Host phone
User root

Replace phone with the hostname or ip of your phone. You should now be able to ssh into the phone without having to type root@ every time.

To disable password logins (after setting up key access) edit /etc/init.d/dropbear and change the following line:

Changing host keys

This is suggested because ssh on your desktop may complain if the key matching a certain IP changes (stored in .ssh/known_hosts). Now you have set this, you can issue the following command to connect to your moko :

ssh root@moko

GUI on desktop through SSH

To get the GUI on the FreeRunner onto the desktop via USB, you can use ssh as follows:

ssh -l root -X -v 192.168.0.202

Using this, run openmoko-finger-demo for example, and it will open up on the desktop. To get landscape view, just resize the GUI window on the desktop.

If you get an error like this:
dbus.exceptions.DBusException: org.freedesktop.DBus.Error.Spawn.ExecFailed: dbus-launch failed to
autolaunch D-Bus session: Autolaunch requested, but X11 support not compiled in.
you need to set the DBUS_SESSION_BUS_ADDRESS environment variable to the value on the FreeRunner before launching the process from your desktop. You can find the value of this variable by using a command such as
ps auxwwwwe | grep -m 1 DBUS_SESSION_BUS_ADDRESS
Note that you must run that command on the FreeRunner. Back on your desktop, run the process you want with the env command like this:
env DBUS_SESSION_BUS_ADDRESS=dbus_addressprocess #(isn't the "env" redundant here?)

Display Remote Applications on FreeRunner

To get desktop apps to show up on your FreeRunner, first log in:

ssh -l root 192.168.0.202

Then run:

DISPLAY=:0 xhost +192.168.0.200

After this you can close the ssh session. Back on the desktop computer, run:

DISPLAY=openmoko:0 xclock

Note that the xhost command will allow remote applications on 192.168.0.200 to access the X server. It will allow anyone on the desktop machine to access the X server of the neo, including snooping anything you type on it. To disallow remote applications again, run this in the neo:

DISPLAY=:0 xhost -192.168.0.200

sftp

After you get the SSH connection working, it is possible to use Konqueror, Nautilus or another sftp - enabled tool to browse the phone filesystem and deploy the test applications. Just enter sftp://root@192.168.0.202 into address bar.

Views

Personal tools

Openmoko Networking Setup

In order to communicate via TCP/IP to your FreeRunner, a basic understanding of the networking expectations is required. Each end of the USB connection forms a LAN (local area network) segment, with the FreeRunner's USB networking device at one end (default 192.168.0.202) and your laptop or desktop at the other end (192.168.0.200 in this guide).

Normally, your desktop machine will know how to reach the Internet, having had its gateway (the IP address of the machine or device which knows how to send packets to machines beyond your subnet) configured via DHCP or statically (probably via a router). For the FreeRunner to reach the Internet, your desktop will have to be configured to route and masquerade (NAT) packets from it.

Normally, none of this is an issue, but problems can arise when the subnet between the FreeRunner and your desktop overlap with the desktop to the router (which forms a second LAN), since your desktop might not know how to route traffic properly.

In other words: if your existing router and desktop have addresses 192.168.0.(something) changing them to e.g. 192.168.1.(something) might save you a lot of troubleshooting later. A discussion of this is here.

Simple Manual Linux Configuration

Try this first (as root on your desktop, with FreeRunner attached via USB cable and booted properly, not at the Boot Menu). If it works, then you can add permanent configuration or use more sophisticated setups below.

The shortest way

This simple way has been tested with many Linux distributions and network configurations. It was even successfully applied to connect another Linux based handhelds like TDS Nomad and surely can be recommended as the first attempt.

If your Internet connection is also in the range 192.168.0.x then instead you might want to use only:

ip addr add 192.168.0.200/28 dev usb0

(This will just map the net from 192.168.0.192 to 192.168.0.207 onto usb0. If you get the error 'Cannot find device "usb0"', double-check that your FreeRunner is turned on and connected by USB. If that doesn't work, try unplugging and replugging the USB cable.)

And in this case you should enable ARP proxy on internet facing interface INSTEAD of using iptables:

sysctl net.ipv4.conf.eth2.proxy_arp=1

This assuming that eth2 is connected to ISP.

Then

ifconfig usb0 up

Then (ideally, not as root):

ssh root@192.168.0.202

The default password is blank.

Due to the fact that in most cases your Neo will use the same dns servers as your computer uses, you can automate the process of writing dns servers to your phone:

Again if your net already is 192.168.0.0, replace the POSTROUTING statement with

iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/28

This simple script will set up routing for your Freerunner and than copy resolv.conf with dns addresses straight to the phone.
All you have to do is connect phone to the computer, run the script and enjoy internet connection from your phone.

Linux Kernel Support

Your Linux desktop/laptop needs to have suitable support, in particular, you will need to have enabled full masquerading in the kernel and USB networking options enabled. For default kernels in many Linux distributions, this will already be the case. If not, you will need to enable:

Firewall Issues

On some systems, you may have firewall rules which prevent this working - such as added by the iptables service on Fedora. You may care to stop these, and/or review any rules or policies you think might cause issues.

The most relevant table is the nat table, which controls translation of addresses:

iptables -L -t nat -v -n

Unless you have a special setup, you'll want to see only the MASQUERADE rule that you apply below, and ACCEPT as the default policy. Also look at the filter table:

iptables -L -t filter -v -n

If this contains anything in the FORWARD chain, then this may prevent passing packets. It can be flushed with:

iptables -t filter -F FORWARD

DNS

In addition to routing issues, to be practical, DNS will need to work. In some cases, you might already be running a DNS server on your desktop such as dnsmasq or bind9, which is the default assumption the FreeRunner makes. In other cases, you'll need to configure DNS to that of your router, or a DNS server further out on the internet such as that provided by your ISP.

Configure Default Neo DNS

DNS is configured in /etc/resolv.conf on your FreeRunner.

You should add the IP address of the DNS servers as provided by your ISP. Check your router's or PC's network status for the nameserver IP addresses.

These settings will be lost on reboot. You can set the DNS for the next connect, by adding the following to the end of the usb0 setting in /etc/network/interfaces, right above the bluetooth networking section:

Proxying DNS from Desktop/Laptop

If you move about, making assumptions about the network may not be convenient, and it is possible to proxy DNS requests via your host laptop (which you are also taking with you), without running or installing a DNS server. There are a number of ways to do this:

If so, then this is sufficient for most internet access. But manual changes to resolv.conf are usually lost later if for example one uses DHCP, especially for WiFi, and so may not be convenient to configure manually.

Testing Your Connection

You should be able to connect to your Neo! Make sure you can ping your Neo to be sure.
ping 192.168.0.202

Then log into your Neo using ssh:
ssh root@192.168.0.202
The default password is blank (press enter).

You can also scp files back and forth. You can telnet, SSH, SMB or do whatever you want if you install software that enables you to set up TCP/IP network over your USB connection.

Now, make sure you can ping back to your desktop
ping 192.168.0.200
(Note that some systems like Vista, don't respond to ICMP ping by default)

Try pinging the outside world (a Google IP address)
ping 74.125.19.147
This demonstrates that masquerading is working - your desktop is sending/receiving packets to the wider internet.

OS or Distro Specific & Automatic Configuration

Based on Hotplugging usbnet by Marcin 'Hrw' Juszkiewicz.
These instructions should keep you from having to run the Simple Manual Linux Configuration every time you plug in and want to connect to an Openmoko device. One run and then you're done!

If the Simple Manual Linux Configuration does not work for your OS or Distro (MacOS X, MS Windows, etc) there may be instructions here that work for you.

MacOS X

Windows

There is also a very helpful tutorial for connecting with Vista at [1].

FreeBSD

You need to load the cdce kernel module (if it is not already linked into your kernel). As root do:

kldload cdce

The Neo should then show up as cdce0 interface and you can handle the cdce0 interface just like the usb0 device under Linux. For more information see the cdce manpage. An easy way to assign the IP address to the cdce0 interface is using the devd(8) daemon. Create the following two files,

This is more sophisticated than the manual setup. The 'auto usb' stanza ties into the Linux hotplug system so that when the device appears and vanishes, as happens when the FreeRunner is connected via USB, this is run.

In addition, the desktop-side netmask is limited to a much smaller range, so that overlapping subnets are less of a problem - Linux will use more specific routes first when deciding where to send packets.

Another possible configuration that adds DNS forward and removes
the iptables changes after unplugging:

It is possible to use network-manager to automatically connect to the Freerunner using udev. The process uses udev to run a script when the Frerunner is plugged in. The script uses the ip command to set the mac address of the usb network interface. To begin, create /etc/udev/rules.d/80-freerunner.rules :

# This file causes programs to be run on device insertion.
# See udev(7) for syntax.
# rule to assign a fixed mac address specified in /
KERNEL=="usb[0-9]*", DRIVERS=="cdc_ether", ACTION=="add", RUN+="/usr/local/sbin/freerunner-usb-add.sh %k"

Finally run "chmod +x /usr/local/sbin/freerunner-usb-add.sh" to make it executable. Now you can use network-manager with mac-address specific settings and get it to automatically connect.

Ubuntu Issues

Ubuntu 8.10 doesn't work as expected if you used /etc/network/interfaces to automate the connection. Network manager likes to latch onto the network device and add a default route through 192.168.0.202, breaking your network connection. Network manager also says you can't edit or remove this connection from its list. I'm going back to making the connection manually.

The bug is that the DRIVERS variable isn't set at all when the device is unplugged.

This appears to be fixed in Ubuntu 8.04 Mattt 11:38, 30 July 2008 (UTC)

Actually it appears that it's not fixed, but patching that file and disconnecting and reconnecting the phone works perfectly. --Johndoesacc 18:37, 20 August 2008 (UTC)

Well, yes, it must be fixed because it worked for me out-of-the-box without tweaking the udev rule on 8.04 --EtienneG November 26th, 2008

Ubuntu Workaround

Use wicd instead of networkmanager:
It is much further in development than networkmanager yet and doesn't make any problems with USB networking. You can use the "normal" settings in /network/interfaces.
Note: Because of it's dependencies it deinstalls networkmanager.

Mandriva

This first file configures the network system for the usb0 interface. Any time you plug in the FreeRunner the interface will be configured.

This next file configures the static routes that we need to communicate to the subnet. Since it has "usb0" in the name, the system will automatically apply these static routes any time that the usb0 interface is configured. (i.e. when you connect the FreeRunner)

/etc/sysconfig/network-scripts/usb0-routes:

ADDRESS0=192.168.0.200
NETMASK0=255.255.255.0

Now we need to restart the network system to pick up the changes.

service network restart

This didn't work for me (Mandriva 2008.1), giving errors from Shorewall. However, simply using MCC, Network->Sharing Internet Access worked fine. You need to connect Neo when starting it. --Alih 18:50, 22 September 2008 (UTC)

Automatic Configuration

One way to automate all this is to create /etc/conf.d/net.usb0 as follows. It sets IP forwarding and the iptables rules all in one go. It removes the iptables rules and disables ip forwarding when the FreeRunner is unplugged.

Archlinux

SSH Extras

Reportedly, the ssh daemon (dropbear 0.49) on the FreeRunner appears to have a bug when sending the exit status back to the client. From time to time you receive an exit status of 255.

To avoid ssh adding a new line for every ssh host-key to your known_hosts you can add the following to the phone section in ~/.ssh/config (or see the snippet at : USB Networking#Changing_host_keys bellow)

UserKnownHostsFile /dev/null

You might want to use keys to bypass the login prompt too.

SSH Keys

From desktop to FreeRunner

To generate ssh keys for use as a login mechanism type:

user@host$ ssh-keygen -t rsa

When prompted for a password either hit enter for no password (not really a good idea) or enter a password for this key. ssh into the phone and create ~/.ssh:

root@phone# mkdir ~/.ssh

Then from your desktop copy the .pub file to the phone.

user@host$ scp ~/.ssh/id_rsa.pub root@phone:~/.ssh/authorized_keys

You should now be able to ssh directly into the phone without a password prompt using a command like 'ssh root@phone' from the account user@host because the public key in the file user@host:~/.ssh/id_rsa.pub is contained in the list of keys which have access in the file root@phone:~/.ssh/authorized_keys (since scp is used, only one key exists, but you can grant access to the phone from more than one account, for example user@host, user@laptop).

To make ssh login as root by default, add the following lines to ~/.ssh/config:

Host phone
User root

Replace phone with the hostname or ip of your phone. You should now be able to ssh into the phone without having to type root@ every time.

To disable password logins (after setting up key access) edit /etc/init.d/dropbear and change the following line:

Changing host keys

This is suggested because ssh on your desktop may complain if the key matching a certain IP changes (stored in .ssh/known_hosts). Now you have set this, you can issue the following command to connect to your moko :

ssh root@moko

GUI on desktop through SSH

To get the GUI on the FreeRunner onto the desktop via USB, you can use ssh as follows:

ssh -l root -X -v 192.168.0.202

Using this, run openmoko-finger-demo for example, and it will open up on the desktop. To get landscape view, just resize the GUI window on the desktop.

If you get an error like this:
dbus.exceptions.DBusException: org.freedesktop.DBus.Error.Spawn.ExecFailed: dbus-launch failed to
autolaunch D-Bus session: Autolaunch requested, but X11 support not compiled in.
you need to set the DBUS_SESSION_BUS_ADDRESS environment variable to the value on the FreeRunner before launching the process from your desktop. You can find the value of this variable by using a command such as
ps auxwwwwe | grep -m 1 DBUS_SESSION_BUS_ADDRESS
Note that you must run that command on the FreeRunner. Back on your desktop, run the process you want with the env command like this:
env DBUS_SESSION_BUS_ADDRESS=dbus_addressprocess #(isn't the "env" redundant here?)

Display Remote Applications on FreeRunner

To get desktop apps to show up on your FreeRunner, first log in:

ssh -l root 192.168.0.202

Then run:

DISPLAY=:0 xhost +192.168.0.200

After this you can close the ssh session. Back on the desktop computer, run:

DISPLAY=openmoko:0 xclock

Note that the xhost command will allow remote applications on 192.168.0.200 to access the X server. It will allow anyone on the desktop machine to access the X server of the neo, including snooping anything you type on it. To disallow remote applications again, run this in the neo:

DISPLAY=:0 xhost -192.168.0.200

sftp

After you get the SSH connection working, it is possible to use Konqueror, Nautilus or another sftp - enabled tool to browse the phone filesystem and deploy the test applications. Just enter sftp://root@192.168.0.202 into address bar.