Replicant

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

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

h2. Automation scripts

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

h3. 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):

<pre>

#!/bin/sh

# Replicant USB Networking

# ========================                             

# 

# Copyright (C) 2011 Paul Kocialkowski, GPLv3+

# 

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

# 

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

IPTABLES_CLEAN_RULES=true

USB_IFACE="usb0"

INTERNET_IFACE="eth0"

USB_IFACE_IP="192.168.4.200"

# 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

}

# 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 

}

# 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

</pre>

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

h3. 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):

h4. For Replicant 4.0 (tested on the Nexus S).

<pre>

#!/system/bin/sh

# Replicant USB Networking

# ========================                             

# 

# Copyright (C) 2011 Paul Kocialkowski, GPLv3+

# 

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

# 

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

# Enable USB Networking

USB_IFACE="rndis0" 

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/android_usb/android0/enable

    ifconfig rndis0 up

}

usb_networking_configure () {

    ifconfig $USB_IFACE $USB_IFACE_IP

    route add default gw $GATEWAY_IP dev $USB_IFACE

    setprop net.dns1 $DNS1_IP

    # 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/android_usb/android0/enable

    ifconfig rndis0 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

</pre>

h4. For Replicant 2.3 

<pre>

#!/system/bin/sh

# Replicant USB Networking

# ========================                             

# 

# Copyright (C) 2011 Paul Kocialkowski, GPLv3+

# 

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

# 

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

# 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

	# 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

</pre>

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@ 

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

h4. 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@

h3. Customizing the scripts

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

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

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