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

 * 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

# 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

}}}

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

# 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

}}}

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 /sdcard/ }}} (you can change /sdcard/ to any other writable disk place, just remind where you put it).

Get a shell on your device ({{{ adb shell }}}) and set this file executable: {{{ # chmod a+x /sdcard/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 /sdcard/run_dev.sh start" }}}

and then "run_pc.sh" '''as root''' on the host pc:

{{{ # ./run_pc.sh start }}}

assuming that you are on the directory where you created the script.

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.

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

If you want to disable Replicant USB Networking, you have to :

 * Stop the script on the device: {{{ adb shell "sh /sdcard/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.