This project is no longer maintained, see lantern-client instead.
Lantern Android is an App that uses the Android VpnService API to route all device traffic through a packet interception service and subsequently the Lantern circumvention tool.
Before building make sure you've compiled the Lantern proxy for Android:
cd $GOPATH/src/github.com/getlantern/lantern
make android-lib
Download the most recent copy of the Lantern Android source code using git:
mkdir -p ~/AndroidstudioProjects
cd ~/AndroidstudioProjects
git clone https://github.com/getlantern/lantern-mobile.git
In the welcome screen choose the "Open an existing Android Studio" option and
select the lantern folder you just checked out with git.
- Java Development Kit 1.7
- Git
- Android NDK
- Android SDK Tools (if not using Android Studio)
- Go (1.6 tip is best as it eliminates text-relocations and provides the best performance)
Replace the paths based on wherever you've installed the Android SDK and NDK
export ANDROID_HOME=/opt/adt-bundle-mac-x86_64-20130917/sdk
export PATH=$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$ANDROID_HOME/build-tools/23.0.2/:$PATH
export NDK_HOME=/opt/android-ndk-r10e
export PATH=$NDK_HOME:$PATHUsing the sdk-manager ($ANDROID_HOME/tools/android), install Android 6.0 API
23 and also the Android SDK Build Tools rev. 23.0.1.
Lantern Android uses tun2socks to route intercepted VPN traffic through a local SOCKS server.
make build-tun2socks
Build the Debug target:
make build-debug
Install it:
make install
Run the app on the device from the command line:
make run
By default, all three tasks will be run in order with:
make
Note - if you want to test with an emulator, run android and then choose
Tools -> Manage AVDs. Create an AVD (e.g. Nexus_4) and then run the emulator
from the command line like so:
emulator -avd Nexus_4
The following settings seem to work well enough performance wise:
Device: 3.4" WQVGA 240x432
Target: Android 5.1.1 - API Level 22
CPU/ABI: ARM (armeabi-v7a)
Keyboard: x Hardware keyboard present
Skin: Skin with dynamic hardware controls
Front Camera: None
Back Camera: None
Memory RAM: 2048
VM Heap: 128
Internal Storage: 200
SD Card: 4GiB (probably more than necessary)
Emulation Options: x Use Host GPU
With Lantern Android running, to filter Logcat messages:
make logcat
This is very useful when you can to check each moving part separately.
Within Android, the VpnService creates a TUN device and configures the network to route all traffic to this virtual device, an app is listening on this device and has the ability to inspect, modify and reinject packets back to the device. Some special packets can ignore the tun device and pass to the Internet directly (protected packages).
We are going to use a Linux virtual machine to simulate the device <-> tun <-> tun2sock <-> lantern <-> Internet dance, on a normal Linux we don't have the
VpnService API but we have the ability to create tun devices and route
traffic at will.
The main idea is to create a tun device, run a vanilla tun2socks and route all outgoing traffic to this device, everything but DNS server requests and a special route that goes directly to the virtual machine's host, which will be running a Lantern-SOCKs server.
Let's create and configure this virtual machine:
cd /path/to/lantern-mobile
vagrant up
While you're waiting for the vm to build up go back to the local machine (the vm's host) and compile the socks-server:
cd ~/go/src/github.com/getlantern/lantern
source setenv.bash
go build github.com/getlantern/lantern-mobile/lantern/socks-server
Run the server you've just compiled:
./socks-server
# ...
# DEBUG lantern-android.interceptor: interceptor.go:90 SOCKS proxy now listening on port: 8788
# 2015/09/15 08:47:40 Go and play for 10 minutes.
Run a simple test with cURL and watch the sock-server output.
curl --socks5 127.0.0.1:8788 https://www.google.com/humans.txt
# Google is built by a large team of engineers, designers, researchers, robots, and others in many different sites across the globe. It is updated continuously, and built with more tools and technologies than we can shake a stick at. If you'd like to help us out, see google.com/careers.
The SOCKs server will run for 10 minutes and then it will exit, you can also
stop it anytime with ^C.
You can also cross-compile the tests we're going to run within the vm:
cd ~/go/src/github.com/getlantern/lantern
make mobile-test-linux-amd64
# ...
# ok github.com/getlantern/lantern-mobile/lantern 0.082s
Once the build has finished log in into the new box:
vagrant ssh
And run the script that is going to setup
chmod +x /vagrant/vagrant-tun-up.sh
/vagrant/vagrant-tun-up.sh
The script will ask you for a HOST_IP, this is the IP of the host machine
which in my case is 10.0.0.101:
HOST_IP=10.0.0.101 /vagrant/vagrant-tun-up.sh
# NOTICE(tun2socks): initializing BadVPN tun2socks 1.999.130
# NOTICE(tun2socks): entering event loop
Go back to your host and restart the socks-server.
./socks-server
# ^C
./socks-server
# ...
Open another terminal without stopping the tun2socks process and we'll be ready to test everything.
vagrant ssh
curl https://www.google.com/humans.txt
# Google is built by a large team of engineers, designers, researchers, robots, and others in many different sites across the globe. It is updated continuously, and built with more tools and technologies than we can shake a stick at. If you'd like to help us out, see google.com/careers.
Make sure the request is catched by tun2socks and by the socks-server by watching each program's output.
Finally, run the transparent test, which will basically do the same as a normal cURL through tun2socks and the socks-server:
/vagrant/lantern/lantern_mobile_test -test.v -test.run TestTransparentRequestPassingThroughTun0
# ...
# --- PASS: TestTransparentRequestPassingThroughTun0 (1.36s)
# PASS
