Replicant

= Replicant USB Networking =

This page explains how to connect your Replciant phone to the Internet via an USB connection to a computer connected to the Internet.

What you need * A phone running Replicant (but it should also work on CyanogenMod or Android) * A computer with USB connectivity and network access running GNU/Linux Automation scripts

Two scripts are necessary: one to run on the host computer and one to run on the device.

=== Replicant USB Networking - PC ===

Here's the script to run on the computer. Copy the following text to a file named "run_pc.sh" (or any other name, you just need to keep the same name along the process):

{{{
#!/bin/sh

1. Replicant USB Networking
2. ========================
4. Copyright (C) 2011 Paul Kocialkowski, GPLv3+
6. This program is free software: you can redistribute it and/or modify
7. it under the terms of the GNU General Public License as published by
8. the Free Software Foundation, either version 3 of the License, or
9. (at your option) any later version.
11. You should have received a copy of the GNU General Public License
12. along with this program. If not, see <http://www.gnu.org/licenses/&gt;.

IPTABLES_CLEAN_RULES=true

USB_IFACE="usb0"
INTERNET_IFACE="eth0"

USB_IFACE_IP="192.168.4.200"

1. Clean iptables rules

iptables_rules_clean () {
if [ $IPTABLES_CLEAN_RULES = false ]
then
return
fi

iptables --flush
    iptables --table nat --flush
    iptables --delete-chain
    iptables --table nat --delete-chain
}

1. Inject iptables forwarding rules

iptables_forward_rules_apply () {
iptables --table nat --append POSTROUTING --out-interface $INTERNET_IFACE -j MASQUERADE
iptables --append FORWARD --in-interface $USB_IFACE -j ACCEPT
echo 1 > /proc/sys/net/ipv4/ip_forward
}

1. Configure network link

usb_networking_configure () {
ifconfig $USB_IFACE up
ifconfig $USB_IFACE $USB_IFACE_IP
}

usb_networking_disable () {
ifconfig $USB_IFACE down
echo 0 > /proc/sys/net/ipv4/ip_forward
}

case $1 in
"start")
echo "Starting Replicant USB Networking"
iptables_rules_clean
usb_networking_configure
iptables_forward_rules_apply
;;
"stop")
echo "Stopping Replicant USB Networking"
usb_networking_disable
iptables_rules_clean
;;
*)
echo "Usage: sh $0 {start|stop}"
;;
esac
}}}

Then, set this file executable: {{{ chmod a+x run_pc.sh }}}

=== Replicant USB Networking - Device ===

Here's the script to run on the device. Copy the following text to a file named "run_dev.sh" (or any other name, you just need to keep the same name along the process):

{{{
#!/system/bin/sh

1. Replicant USB Networking
2. ========================
4. Copyright (C) 2011 Paul Kocialkowski, GPLv3+
6. This program is free software: you can redistribute it and/or modify
7. it under the terms of the GNU General Public License as published by
8. the Free Software Foundation, either version 3 of the License, or
9. (at your option) any later version.
11. You should have received a copy of the GNU General Public License
12. along with this program. If not, see <http://www.gnu.org/licenses/&gt;.

1. Enable USB Networking

USB_IFACE="usb0"

USB_IFACE_IP="192.168.4.202"
GATEWAY_IP="192.168.4.200"
DNS1_IP="8.8.8.8"

usb_networking_enable () {
echo 1 > /sys/class/usb_composite/rndis/enable
ifconfig usb0 up
}

usb_networking_configure () {
ifconfig $USB_IFACE $USB_IFACE_IP
route add default gw $GATEWAY_IP dev $USB_IFACE
setprop net.dns1 $DNS1_IP

1. setprop net.dns1 $( cat /system/etc/resolv.conf | sed -e "s|.*#.*||" -e "s|^.*nameserver \(.*\)$|\1|g" | grep -v "^$" | head -n 1 )
   }

usb_networking_disable () {
echo 0 > /sys/class/usb_composite/rndis/enable
ifconfig usb0 down
}

case $1 in
"start")
echo "Starting Replicant USB Networking"
usb_networking_enable
usb_networking_configure
;;
"stop")
echo "Stopping Replicant USB Networking"
usb_networking_disable
;;
*)
echo "Usage: sh $0 {start|stop}"
;;
esac
}}}

Now you need to copy it to your phone. Start adb server as root: {{{ # adb start-server }}} and copy the file (as regular user): {{{ adb push run_dev.sh /data/ }}}
Get a shell on your device ({{{ adb shell }}}) and set this file executable: {{{ # chmod a+x /data/run_dev.sh }}}.

=== Using the scripts ===

Now both scripts are in place. You should now: * Start "run_dev.sh" on the device: {{{ adb shell "sh /data/run_dev.sh start" }}} * Start "run_pc.sh" '''as root''' on the host pc (you must be in the directory where you created the script): {{{ # ./run_pc.sh start }}}

Note that if you use NetworkManager, it could notice a new network interface and try to configure it: you should disconnect this interface on NetworkManager before you run the second script.

Now everything is in place. If no error is shown, it should now be working. You can try to ping some website on the device.
If It doesn't work, try to run again each script, running the configuration one more time can't do any worse.

==== Getting back to normal ====

If you want to disable Replicant USB Networking, you have to: * Stop the script on the device: {{{ adb shell "sh /data/run_dev.sh stop" }}} * Stop the script on the host computer: {{{ # ./run_pc.sh stop }}}

=== Customizing the scripts ===

The variables at the beginning of each script can be customized for your usage:

==== run_pc.sh ====

• {{{IPTABLES_CLEAN_RULES}}} can be set to true or false, depending if you want the iptables rules to be cleaned before the configuration.
• {{{USB_IFACE}}} contains the usb network interface name to the device. You can find out this name by launching "ifconfig" before and after you run the first script: the usb interface will appear after the first script completed.
• {{{INTERNET_IFACE}}} defines the name of the network interface connected to the internet. This should be the one configured with an IP address on ifconfig (and which is not called lo). If you use an Ethernet connection, it's probably "eth0" and if you use a WiFi connection, it's probably "wlan0".
• {{{USB_IFACE_IP}}} configures the IP address to give to the computer on the network between the device and the computer. Note that this must be the same address in {{{GATEWAY_IP}}} on the device script.

==== run_dev.sh ====

• {{{USB_IFACE}}} contains the usb network interface name to the computer. This should normally not be changed.
• {{{USB_IFACE_IP}}} configures the IP address to give to the device on the network between the device and the computer.
• {{{GATEWAY_IP}}} configures the gateway's IP address. Note that this must be the same address in {{{USB_IFACE_IP}}} on the computer script.
• {{{DNS1_IP}}} defines which DNS server to use for name resolution. This is set by default to the Google DNS server but you can change it as you want to any other DNS server.