Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@consuelita
consuelita authored Nov 16, 2023
1 parent f09ac95 commit 680bcf1
Showing 1 changed file with 54 additions and 12 deletions.
66 changes: 54 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,77 @@ Moonbounce is a VPN Service library for Android devices written in Kotlin. This

The server side companion to this library is [Persona](https://github.com/OperatorFoundation/Persona.git).

## Split Proxy Usages
## Starting the VPN Service

You must make sure that you have requested (and have been granted) the correct permissions in order to start a VPN service. See the demo app for an example of how to do this.

To start the Moonbounce VPNService:

1) Create an intent with the MBAKVpnService class.
2) Set the intent action to START_VPN_ACTION.
3) Provide the server IP as an extra using the Moonbounce key words SERVER_IP.
4) Provide the port as an extra using the Moonbounce key word SERVER_PORT.
5) Call startService() with your intent.

```
// 1. Create the Intent
var moonbounceVPNIntent = Intent(this, MBAKVpnService::class.java)
// 2. Set the action (start not stop)
moonbounceVPNIntent.action = START_VPN_ACTION
Note: A minimum Android API of 26 is required to use the Proxy feature of this library.
// 3. Set the IP address of the vpn server (transport server if a transport is being used)
moonbounceVPNIntent.putExtra(SERVER_IP, "127.0.0.1") // Use your actual Persona server IP here
// 4. Set the port of the vpn server (transport server if a transport is being used)
moonbounceVPNIntent.putExtra(SERVER_PORT, 1111) // Use your actual Persona server port here
// 5. Start the VPN Service
startService(moonbounceVPNIntent)
```


## Split Proxy Usages

The Moonbounce library can be used to create two different split tunneling options. One that allows one or more applications to be disallowed from tunneling, and one that allows one or more routes (IP Addresses) to be excluded from tunneling. Split tunneling allows users to use two different network connections simultaneously. Users can determine which applications and/or routes they would like to exclude. Excluded apps and routes will connect to the internet in the usual way while all other traffic will be sent through the VPN tunnel.

### Disallowed App
### Disallow Applications from Using the VPN

Note: A minimum Android API of 26 is required to use this feature.

Moonbounce for Android allows users to enter a specific application to exclude from the VPN tunnel. This allows internet traffic for that application to be routed directly to the open network without passing through the VPN tunnel.
Moonbounce for Android allows users to enter applications to exclude from the VPN tunnel. This allows internet traffic for that application to be routed directly to the open network without passing through the VPN tunnel.

To disallow an application from using the VPN tunnel, provide the package name of the application (e.g. ‘com.android.chrome’) to be disallowed, to the VPN library. This is done by adding it as an “extra” to the Moonbounce VPN Service intent before calling startService() with that intent. The demo application shows an example of how to do this correctly (please note that you must use the keys such as “DISALLOWED_APP” that are shown in the demo application for the service to be able to find the values that you provide):
To disallow applications from using the VPN tunnel, provide an array containing the application ID's (e.g. ‘com.android.chrome’) of the apps you wish to disallow, to the VPN library. This is done by adding it as an “extra” to the Moonbounce VPN Service intent before calling startService() with that intent. The demo application shows an example of how to do this correctly (please note that you must use the keys such as “DISALLOWED_APPS” that are shown in the demo application for the service to be able to find the values that you provide):

`moonbounceVPNIntent.putExtra(DISALLOWED_APP, disallowedApp)`
```
var disallowedApps: Array<String> = arrayOf("com.android.chrome")
var moonbounceVPNIntent = Intent(this, MBAKVpnService::class.java)
...
moonbounceVPNIntent.putExtra(DISALLOWED_APPS, disallowedApp)
startService(moonbounceVPNIntent)
```

The demo application has a button that prints the package names of all applications installed on the device. This can be used to find the package name of the application you wish to disallow. Use this in lieu of the “disallowedApp” in the example above.

### Exclude Route
### Exclude Routes

Note: A minimum Android API of 33 is required to use this feature.

Moonbounce for Android allows users to enter a specific IP address to exclude from the VPN tunnel. This allows internet traffic destined for the specific IP address to be routed directly to the open network without passing through the VPN tunnel.

To exclude a route from the VPN tunnel, provide the IP address that should be excluded to the Moonbounce VPN library. This is done by adding it as an “extra” to the Moonbounce VPN Service intent before calling startService() with that intent. This is the same way that you would provide the vpn server’s IP address, or any application that you wish to also exclude. The demo application shows an example of how to do this correctly (please note that you must use the keys such as “EXCLUDE_ROUTE” that are shown in the demo application for the service to be able to find the values that you provide):
To exclude a route from the VPN tunnel, provide an array of the IP addresses that should be excluded to the Moonbounce VPN library. This is done by adding it as an “extra” to the Moonbounce VPN Service intent before calling startService() with that intent. This is the same way that you would provide the vpn server’s IP address and port, as well as any applications that you wish to exclude. The demo application shows an example of how to do this correctly (please note that you must use the keys such as “EXCLUDE_ROUTES” that are shown in the demo application for the service to be able to find the values that you provide):

`moonbounceVPNIntent.putExtra(EXCLUDE_ROUTE, excludeRoute)`
```
var excludeRoutes: Array<String> = arrayOf("8.8.8.8")
var moonbounceVPNIntent = Intent(this, MBAKVpnService::class.java)
...
moonbounceVPNIntent.putExtra(EXCLUDE_ROUTES, excludeRoutes)
startService(moonbounceVPNIntent)
```

## Demo Application

A rudimentory demo application is included in this repository as an example of how to use this library. Install it on any Android device with platforms between 7.0 (API 24) through 12.0 (API 34). This is experimental software and is still under development.
A rudimentory demo application is included in this repository as an example of how to use this library. Install it on any Android device with minimum API 33. This is experimental software and is still under development. The demo is meant only to show an example of how to use the library API and is not intended to be used as a standalone application.

- Moonbounce requires a [Persona](https://github.com/OperatorFoundation/Persona.git) server to be listening on an IP address and Port of your choosing. See the repository for instructions on how to run this server.

Expand All @@ -45,8 +87,8 @@ A rudimentory demo application is included in this repository as an example of h

#### Disallow App (Demo)

Should you prefer to disallow a certain app from being opened via your VPN service, enter that app name in the space provided. You must enter the canonical name of the application as the OS understands it. For example: com.android.chrome. To determine the correct name of the application you want to disallow, the PRINT INSTALLED APPS button will print a list of the names of all the apps downloaded on the device you’re running to your IDE.
Should you prefer to disallow certain apps from using the VPN tunnel, enter the app IDs in the text field provided seperated by spaces. To determine the correct name of the application you want to disallow, the PRINT INSTALLED APPS button will print a list of the names and IDs of all the apps installed on the device you’re running to your IDE.

#### Exclude Route (Demo)

Additionally, Moonbounce can exclude a website's route if you can provide Moonbounce with the IP Address of the website. For example: 142.250.217.78 is a valid IP address for Google.com try entering this IP Address in the exclude route area, turn the VPN on, and Google will be accessed through your normal ISP.
Additionally, Moonbounce can exclude specific routes, enter the IP addresses you wish to exclude, seperated by spaces, in the text field provided.

0 comments on commit 680bcf1

Please sign in to comment.