Skip to content

docs: add README #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
webbrain-one wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add README #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@


# LightVPN

LightVPN is a lightweight PPTP VPN client for Android. It provides a simple interface to manage multiple VPN profiles, configure server credentials, DNS settings, and toggle connections on or off. Under the hood, it leverages standard Linux networking utilities (`mtpd`, `pppd`, `iptables`) to establish and route PPTP tunnels directly through the device's network interfaces.

## Features
- 📱 Lightweight PPTP client optimized for older Android versions
- 📂 Multi-profile management with persistent local storage
- 🔐 MPPE encryption toggle for secure tunnels
- 🌐 Custom DNS configuration (Primary & Secondary)
- 🇨🇳 Bilingual support (English & Simplified Chinese)
- 🛡️ Full root-privilege network routing & firewall management

## Requirements
- Android 4.0 Ice Cream Sandwich (API 14) or higher
- Rooted Android device or emulator (mandatory for `mtpd`/`pppd` execution and `iptables` routing)
- Android Studio or legacy ADT/Eclipse for building

## Installation
1. Clone the repository:
```bash
git clone https://github.com/zodsoft/LightVPN.git
cd LightVPN
```
2. Open the project in Android Studio. If using a newer version, you may need to update the build tools or SDK platform to `android-19` to match the `targetSdkVersion`.
3. Sync dependencies and build the project (`Build > Build APK(s)`).
4. Install the generated `.apk` on your rooted Android device.

## Usage
1. **Add a Profile:** Tap the `+` icon at the bottom of the left drawer to create a new profile.
2. **Configure Details:** Enter the PPTP server address, username, password, and optional DNS servers. Enable the MPPE checkbox if your server requires encrypted payloads.
3. **Save:** Tap the floppy disk/save icon in the action bar to persist your configuration.
4. **Connect/Disconnect:** Use the `On`/`Off` switch in the action bar to establish or terminate the VPN tunnel.
5. **Manage Profiles:** Long-press any profile in the drawer to delete it. Tap a profile to switch the active configuration.

## Technical Details
- **Networking Stack:** Relies on `mtpd` (PPTP daemon) and `pppd` for tunnel creation.
- **Routing & Firewall:** Uses `su` to execute `ip route`, `ip rule`, and `iptables` DNAT rules to ensure all traffic and DNS queries are routed through the `ppp100` interface.
- **Persistence:** Profile data is stored in Android SharedPreferences under the `vpns` application data.
- **Legacy Compatibility:** Targets `android-19` and uses older Android Support Library v4 components (`ActionBarDrawerToggle`, `DrawerLayout`). May require legacy SDK tools for compilation.