gfwleak/zhangyang-libzt
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs and mac makefile

Browse Source
This commit is contained in:
Joseph Henry
2016-07-18 16:38:18 -07:00
parent 58c2ed2299
commit a9fe343158
11 changed files with 350 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -1,4 +1,4 @@
ZeroTier SDK (beta) ZeroTier SDK (alpha)
====== ======
ZeroTier-enabled apps. Virtual network access embedded directly into applications and games. ZeroTier-enabled apps. Virtual network access embedded directly into applications and games.
@@ -9,17 +9,17 @@ Imagine starting an instance of your application or game and having it automatic
## How is it used? ## How is it used?
There are generally two ways one might want to use this SDK/service. There are generally two ways one might want to use the service.
- The first approach is a *compile-time static linking* of our SDK/service directly into your application. With this option you can bundle our entire functionality right into your app with no need to communicate with a service externally, it'll all be handled automatically. - The first approach is a *compile-time static linking* of our service directly into your application. With this option you can bundle our entire functionality right into your app with no need to communicate with a service externally, it'll all be handled automatically. This is most typical for mobile applications, games, etc.
- The second is a service-oriented approach where our SDK is *dynamically-linked* into your applications upon startup and will communicate to a single ZeroTier service on the host. This can be useful if you've already compiled your applications and can't perform a static linking. - The second is a service-oriented approach where our network call "intercept" is *dynamically-linked* into your applications upon startup and will communicate to a single ZeroTier service on the host. This can be useful if you've already compiled your applications and can't perform a static linking.
![Image](docs/img/methods.png) ![Image](docs/img/methods.png)
## Build instructions ## Build instructions
Check out our [Integrations](integrations/) to learn how to build and integrate this into your particular application. Check out our [Integrations](integrations/) to learn how to integrate this into your application.
## How does it work? ## How does it work?

47
docs/integrations.md Normal file
View File

@@ -0,0 +1,47 @@
ZeroTier Integrations
====
If you want everything built at once, type `make all` and go play outside for a few minutes, we'll copy all of the targets into the `build` directory for you along with specific instructions contained in a `README.md` on how to use each binary. You can then use `make -s check` to check the build status of each binary target.
*NOTE for Apple platforms: In order to build iOS/OSX Frameworks and Bundles you will need XCode command line tools `xcode-select --install`*
*NOTE: For Android JNI libraries to build you'll need to install [Android Studio](https://developer.android.com/studio/index.html) the [Android NDK](https://developer.android.com/ndk/index.html). Currently only Android NDK r10e is supported and can be found [here for OSX](http://dl.google.com/android/repository/android-ndk-r10e-darwin-x86_64.zip) and [here for Linux](http://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip). You'll need to tell our project where you put it by putting the path in [this file](android/proj/local.properties), you'll need to install the Android Build-Tools (this can typically be done through the editor the first time you start it up), and finally you should probably upgrade your Gradle plugin if it asks you to. If you don't have these things installed and configured we will detect that and just skip those builds automatically. Additionally, you can specify the target architectures you wish to build for by editing [Application.mk](android/android_jni_lib/java/jni/Application.mk). By default it will build `arm64-v8a`, `armeabi`, `armeabi-v7a`, `mips`, `mips64`, `x86`, and `x86_64`*
Below are the specific instructions for each integration requiring *little to no modification to your code*. Remember, with a full build we'll put a copy of the appropriate integration instructions in the resultant binary's folder for you anyway.
For more support on these integrations, or if you'd like help creating a new integration, stop by our [community section](https://www.zerotier.com/community/)!
***
## Important Build flags
- `SDK_DEBUG` - Turns on SDK activity/warning/error output. Levels of verbosity can be adjusted in `src/SDK_Debug.h`
- `SDK_DEBUG_LOGFILE` - Used in conjunction with `SDK_DEBUG`, this will write all SDK debug chatter to a log file. To use this, set `make SDK_DEBUG_LOGFILE=1` then `export ZT_SDK_LOGFILE=debug.log`.
- `SDK_LWIP_DEBUG` - Turns on debug output for the lwIP library.
- `SDK_BUNDLED` - Builds the SDK as a single bundled target including a the RPC mechanism, the lwIP library, and the ZeroTier service.
- `SDK_SOCKS_PROXY` - Enables the SOCK5 Proxy. This flag is enabled by default on must builds, especially mobile.
***
## Current Integrations
### Apple `make apple`
##### iOS
- [Embedding within an app](../docs/ios_zt_sdk.md) `make ios_app_framework`
- [Unity3D plugin](../docs/unity3d_ios_zt_sdk.md) `make ios_unity3d_bundle`
##### OSX
- [Embedding within an app](../docs/osx_zt_sdk.md) `make osx_app_framework`
- [Dynamic-linking into an app/service at runtime](../docs/osx_zt_sdk.md) `make osx_shared_lib`
- [Unity3D plugin](../docs/unity3d_osx_zt_sdk.md) `make osx_unity3d_bundle`
***
### Linux
- [Dynamic-linking into an app/service at runtime](../docs/linux_zt_sdk.md) `make linux_shared_lib`
- [Using the SDK with Docker](../docs/docker_linux_zt_sdk.md) `make linux_shared_lib`
### Android `make android`
- [Embedding within an app](../docs/android_zt_sdk.md) `make android_jni_lib`
- [Unity 3D plugin](../docs/unity3d_android_zt_sdk.md) `make android_unity3d_plugin`
***
### Windows
- Not yet.

26
docs/zt_sdk_intro.md Normal file
View File

@@ -0,0 +1,26 @@
ZeroTier SDK (alpha)
======
ZeroTier-enabled apps. Virtual network access embedded directly into applications and games.
## What does it do?
Imagine starting an instance of your application or game and having it automatically be a member of your virtual network without having to rewrite your networking layer.
## How is it used?
There are generally two ways one might want to use the service.
- The first approach is a *compile-time static linking* of our service directly into your application. With this option you can bundle our entire functionality right into your app with no need to communicate with a service externally, it'll all be handled automatically. This is most typical for mobile applications, games, etc.
- The second is a service-oriented approach where our network call "intercept" is *dynamically-linked* into your applications upon startup and will communicate to a single ZeroTier service on the host. This can be useful if you've already compiled your applications and can't perform a static linking.
![Image](docs/img/methods.png)
## Build instructions
Check out our [Integrations](integrations/) to learn how to integrate this into your application.
## How does it work?
We've built a special background service that pairs the ZeroTier protocol with a user-space [Lightweight IP (lwIP) stack](http://savannah.nongnu.org/projects/lwip/) to create a new way for you to bring your applications onto your virtual network. For a more in-depth explanation of our technology take a look at our [SDK Primer](docs/zt_sdk.md)

0
docs/zt_sdk.md → docs/zt_sdk_primer.md
View File

9
integrations/Unity3D/Unity3D.userprefs
View File

@@ -2,12 +2,11 @@
<MonoDevelop.Ide.Workspace ActiveConfiguration="Debug" PreferredExecutionTarget="Unity.Instance.Unity Editor" /> <MonoDevelop.Ide.Workspace ActiveConfiguration="Debug" PreferredExecutionTarget="Unity.Instance.Unity Editor" />
<MonoDevelop.Ide.Workbench ActiveDocument="Assets/ZeroTierNetworkInterface.cs"> <MonoDevelop.Ide.Workbench ActiveDocument="Assets/ZeroTierNetworkInterface.cs">
<Files> <Files>
<File FileName="Assets/ZeroTierNetworkInterface.cs" Line="52" Column="1" />
<File FileName="Assets/ZeroTierSockets_Demo.cs" Line="213" Column="51" />
<File FileName="Assets/Demo.cs" Line="1" Column="1" />
<File FileName="Assets/MyZeroTier.cs" Line="1" Column="1" />
<File FileName="Assets/WorldMain.cs" Line="1" Column="1" /> <File FileName="Assets/WorldMain.cs" Line="1" Column="1" />
<File FileName="Assets/ZeroTier.cs" Line="1" Column="1" /> <File FileName="Assets/ZeroTierNetworkInterface.cs" Line="367" Column="1" />
<File FileName="Assets/ZeroTierSockets_Demo.cs" Line="237" Column="21" />
<File FileName="Assets/MyZeroTier.cs" Line="1" Column="1" />
<File FileName="Assets/ZeroTierUtils.cs" Line="1" Column="1" />
</Files> </Files>
</MonoDevelop.Ide.Workbench> </MonoDevelop.Ide.Workbench>
<MonoDevelop.Ide.DebuggingService.Breakpoints> <MonoDevelop.Ide.DebuggingService.Breakpoints>

69
integrations/android/README.md Normal file
View File

@@ -0,0 +1,69 @@
Android + ZeroTier SDK
====
Welcome!
Imagine a flat, encrypted, no-configuration LAN for all of the instances of your Android app.
This short tutorial will show you how to enable ZeroTier functionality for your Android app with little to no code modification. Check out our [ZeroTier SDK](https://www.zerotier.com/blog) page for more info on how the integration works and [Shim Techniques](https://www.zerotier.com/blog) for a discussion of shims available for your app/technology.
In this example we aim to set up a minimal [Android Studio](https://developer.android.com/studio/index.html) project which contains all of the components necessary to enable ZeroTier for your app. If you'd rather skip all of these steps and grab the code, look in the [sdk/android](https://github.com/zerotier/ZeroTierOne/tree/dev/sdk/integrations/android/example_app) folder in the source tree. Otherwise, let's get started!
*NOTE: For Android JNI libraries to build you'll need to install [Android Studio](https://developer.android.com/studio/index.html) the [Android NDK](https://developer.android.com/ndk/index.html). Currently only Android NDK r10e is supported and can be found [here for OSX](http://dl.google.com/android/repository/android-ndk-r10e-darwin-x86_64.zip) and [here for Linux](http://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip). You'll need to tell our project where you put it by putting the path in [this file](Android/proj/local.properties), you'll need to install the Android Build-Tools (this can typically be done through the editor the first time you start it up), and finally you should probably upgrade your Gradle plugin if it asks you to. If you don't have these things installed and configured we will detect that and just skip those builds automatically.*
**Step 1: Select build targets**
- Specify the target architectures you want to build in [Application.mk](android/java/jni/Application.mk). By default it will build `arm64-v8a`, `armeabi`, `armeabi-v7a`, `mips`, `mips64`, `x86`, and `x86_64`.
**Step 2: Build Shared Library**
- `make android_jni_lib`
- The resultant `build/android_jni_lib_YOUR_ARCH/libZeroTierOneJNI.so` is what you want to import into your own project to provide the API to your app. Select your architecture and copy the shared library into your project's JNI directory, possibly `/src/main/jniLibs/YOUR_ARCH/`. Selecting only the architectures you need will *significantly* reduce overall build time.
**Step 3: App Code Modifications**
- Create new package called `ZeroTierSDK` in your project and add a new file called `ZeroTierSDK.java` containing:
```
package ZeroTier;
public class ZeroTierSDK {
public native void startOneService(String homeDir);
public native void joinNetwork(String nwid);
public native void leaveNetwork(String nwid);
public native boolean isRunning();
static { System.loadLibrary("ZeroTierOneJNI"); } // Loads JNI code
}
```
- And now, start the service in your app with:
```
new Thread(new Runnable() {
public void run() {
ZeroTierSDK wrapper = new ZeroTierSDK();
wrapper.startOneService(); // Calls to JNI code
}
}).start();
```
**Step 4: App permissions**
- In order for your application to write the auth keys and network files to the internal storage you'll need to set a few permissions in your `AndroidManifest.xml` file at the same scope level as `<application>`:
```
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
```
**Step 5: Pick an API**
- If functional interposition isn't available for the API or library you've chosen to use, ZeroTier offers a SOCKS5 proxy server which can allow connectivity to your virtual network as long as your client API supports the SOCKS5 protocol. This proxy service will run alongside the tap service and can be turned on by compiling with the `-DUSE_SOCKS_PROXY` flag. By default, the proxy service is available at `0.0.0.0:1337`.
**Step 6: Join a network!**
- Simply call `wrapper.joinNetwork("XXXXXXXXXXXXXXXX")`
***
*Note for the curious on JNI naming conventions: In order to reference a symbol in the JNI library you need to structure the package and class in your Android Studio project in a very particular way. For example, in the ZeroTierSDK we define a function called `Java_ZeroTier_SDK_startOneService`, the name can be broken down as follows: `Java_PACKAGENAME_CLASSNAME_startOneService`, so as we've defined it, you must create a package called `ZeroTier` and add a class called `SDK`.*

10
integrations/android/android_jni_lib/java/jni/Application.mk
View File

@@ -7,10 +7,10 @@ APP_PLATFORM := android-14
# Architectures # Architectures
# APP_ABI := all # APP_ABI := all
#APP_ABI += arm64-v8a APP_ABI += arm64-v8a
APP_ABI += armeabi #APP_ABI += armeabi
#APP_ABI += armeabi-v7a APP_ABI += armeabi-v7a
#APP_ABI += mips #APP_ABI += mips
#APP_ABI += mips64 #APP_ABI += mips64
#APP_ABI += x86 APP_ABI += x86
#APP_ABI += x86_64 APP_ABI += x86_64

103
integrations/apple/example_app/OSX/README.md Normal file
View File

@@ -0,0 +1,103 @@
OSX + ZeroTier SDK
====
Welcome!
Imagine a flat, encrypted, no-configuration LAN for all of the instances of your OSX app.
This short tutorial will show you how to enable ZeroTier functionality for your OSX app with little to no code modification. Check out our [ZeroTier SDK](https://www.zerotier.com/blog) page for more info on how the integration works and [Shim Techniques](shims_zt_sdk.md) for a discussion of shims available for your app/technology.
In this example we aim to set up a minimal XCode project which contains all of the components necessary to enable ZeroTier for your app. If you'd rather skip all of these steps and grab the project code, look in the [sdk/integrations/apple](https://github.com/zerotier/ZeroTierSDK/tree/dev/sdk/integrations/apple) folder of the source tree. Otherwise, let's get started!
***
## Via Static-linking
Example:
gcc myapp.c -o myapp libztintercept.so
export ZT_NC_NETWORK=/tmp/sdk-test-home/nc_8056c2e21c000001
Start service
./zerotier-sdk-service -d -p8000 /tmp/sdk-test-home
Run application
./myapp
## Via Dynamic-linking at runtime with DYLD
## Via App Framework
*NOTE: a sample OSX desktop project using the ZeroTierSDK framework can be found [here](../integrations/apple/example_app/Example_OSX_App)*
***
**Step 1: Build iOS framework**
- `make ios_app_framework`
- This will output to `build/ios_app_framework/Release-iphoneos/ZeroTierSDK_iOS.framework`
**Step 2: Integrate SDK into project**
- Add the resultant framework package to your project
- Add `zerotiersdk/src` directory to `Build Settings -> Header Search Paths`
- Add `build/osx_app_framework/Release-iphoneos/` to *Build Settings -> Framework Search Paths*
- Add `ZeroTierSDK.frameworkiOS` to *General->Embedded Binaries*
- Add `src/SDK_XcodeWrapper.cpp` and `src/SDK_XcodeWrapper.hpp` to your project:
- Set `src/SDK_Apple-Bridging-Header.h` as your bridging-header in `Build Settings -> Objective-C Bridging-header`
**Step 3: Start the ZeroTier service**
Now find a place in your code to set up the ZeroTier service thread:
```
var service_thread : NSThread!
func zt_start_service() {
let path = NSSearchPathForDirectoriesInDomains(NSSearchPathDirectory.DocumentDirectory, NSSearchPathDomainMask.UserDomainMask, true)
start_service(path[0])
}
```
and then start it:
```
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0), {
self.service_thread = NSThread(target:self, selector:"zt_start_service", object:nil)
self.service_thread.start()
});
```
*NOTE: If you enabled the proxy service via `-DUSE_SOCKS_PROXY` it will start automatically and be reachable at `0.0.0.0:1337`*
**Step 4: Pick an API**
This integration allows for the following shim combinations:
- `Hook of BSD-like sockets`: Use BSD-like sockets as you normally would.
- `Proxy of NSStream`: Create NSStream. Configure stream for SOCKS5 Proxy. Use stream.
- `Changeling of BSD-like sockets`: Call `start_changeling()` and then use BSD-like sockets as you normally would.
- `Direct Call`: Consult [src/SDK_Apple-Bridging-Header.h](src/SDK_Apple-Bridging-Header.h).
If functional interposition isn't available for the API or library you've chosen to use, ZeroTier offers a SOCKS5 proxy server which can allow connectivity to your virtual network as long as your client API supports the SOCKS5 protocol. This proxy service will run alongside the tap service and can be turned on by compiling with the `-DUSE_SOCKS_PROXY` flag in *Build Settings->Other C Flags*. By default, the proxy service is available at `0.0.0.0:1337`.
**Step 5: Join a network!**
Simply call `zt_join_network("XXXXXXXXXXXXXXXX")`
***
**NSStream and SOCKS Proxy:**
As an example, here's how one would configure a NSStream object to redirect all network activity to the ZeroTier SOCKS proxy server:
```
// BEGIN proxy configuration
let myDict:NSDictionary = [NSStreamSOCKSProxyHostKey : "0.0.0.0",
NSStreamSOCKSProxyPortKey : 1337,
NSStreamSOCKSProxyVersionKey : NSStreamSOCKSProxyVersion5]
inputStream!.setProperty(myDict, forKey: NSStreamSOCKSProxyConfigurationKey)
outputStream!.setProperty(myDict, forKey: NSStreamSOCKSProxyConfigurationKey)
// END proxy configuration
```

79
integrations/apple/example_app/iOS/README.md Normal file
View File

@@ -0,0 +1,79 @@
iOS + ZeroTier SDK
====
Welcome!
Imagine a flat, encrypted, no-configuration LAN for all of the instances of your iOS app.
This short tutorial will show you how to enable ZeroTier functionality for your iOS app with little to no code modification. Check out our [ZeroTier SDK](https://www.zerotier.com/blog) page for more info on how the integration works and [Shim Techniques](shims_zt_sdk.md) for a discussion of shims available for your app/technology.
In this example we aim to set up a minimal XCode project which contains all of the components necessary to enable ZeroTier for your app. If you'd rather skip all of these steps and grab the project code, look in the [sdk/iOS](https://github.com/zerotier/ZeroTierSDK/tree/dev/sdk/integrations/apple) folder of the source tree. Otherwise, let's get started!
***
**Step 1: Build iOS framework**
- `make ios_app_framework`
- This will output to `build/ios_app_framework/Release-iphoneos/ZeroTierSDK_iOS.framework`
**Step 2: Integrate SDK into project**
- Add the resultant framework package to your project
- Add `zerotiersdk/src` directory to `Build Settings -> Header Search Paths`
- Add `build/ios_app_framework/Release-iphoneos/` to *Build Settings -> Framework Search Paths*
- Add `ZeroTierSDK.frameworkiOS` to *General->Embedded Binaries*
- Add `src/SDK_XcodeWrapper.cpp` and `src/SDK_XcodeWrapper.hpp` to your project:
- Set `src/SDK_Apple-Bridging-Header.h` as your bridging-header in `Build Settings -> Objective-C Bridging-header`
**Step 3: Start the ZeroTier service**
Now find a place in your code to set up the ZeroTier service thread:
```
var service_thread : NSThread!
func zt_start_service() {
let path = NSSearchPathForDirectoriesInDomains(NSSearchPathDirectory.DocumentDirectory, NSSearchPathDomainMask.UserDomainMask, true)
start_service(path[0])
}
```
and then start it:
```
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0), {
self.service_thread = NSThread(target:self, selector:"zt_start_service", object:nil)
self.service_thread.start()
});
```
*NOTE: If you enabled the proxy service via `-DUSE_SOCKS_PROXY` it will start automatically and be reachable at `0.0.0.0:1337`*
**Step 4: Pick an API**
This integration allows for the following shim combinations:
- `Hook of BSD-like sockets`: Use BSD-like sockets as you normally would.
- `Proxy of NSStream`: Create NSStream. Configure stream for SOCKS5 Proxy. Use stream.
- `Changeling of BSD-like sockets`: Call `start_changeling()` and then use BSD-like sockets as you normally would.
- `Direct Call`: Consult [src/SDK_Apple-Bridging-Header.h](src/SDK_Apple-Bridging-Header.h).
If functional interposition isn't available for the API or library you've chosen to use, ZeroTier offers a SOCKS5 proxy server which can allow connectivity to your virtual network as long as your client API supports the SOCKS5 protocol. This proxy service will run alongside the tap service and can be turned on by compiling with the `-DUSE_SOCKS_PROXY` flag in *Build Settings->Other C Flags*. By default, the proxy service is available at `0.0.0.0:1337`.
**Step 5: Join a network!**
Simply call `zt_join_network("XXXXXXXXXXXXXXXX")`
***
**NSStream and SOCKS Proxy:**
As an example, here's how one would configure a NSStream object to redirect all network activity to the ZeroTier SOCKS proxy server:
```
// BEGIN proxy configuration
let myDict:NSDictionary = [NSStreamSOCKSProxyHostKey : "0.0.0.0",
NSStreamSOCKSProxyPortKey : 1337,
NSStreamSOCKSProxyVersionKey : NSStreamSOCKSProxyVersion5]
inputStream!.setProperty(myDict, forKey: NSStreamSOCKSProxyConfigurationKey)
outputStream!.setProperty(myDict, forKey: NSStreamSOCKSProxyConfigurationKey)
// END proxy configuration
```

2
integrations/docker/README.md
View File

@@ -5,7 +5,7 @@ Welcome!
Imagine a flat, encrypted, no-configuration LAN for all of your Docker containers. Imagine a flat, encrypted, no-configuration LAN for all of your Docker containers.
This short tutorial will show you how to enable ZeroTier functionality for your Docker software container with little to no configuration. In this example we aim to build a Docker container with ZeroTier’s Network Container service bundled right in so that it’s effortless to hook any number of your services in the container up to your virtual network. Alternatively, you can check out a docker project directory [here](docker_demo). This short tutorial will show you how to enable ZeroTier functionality for your Docker software container with little to no configuration. In this example we aim to build a Docker container with ZeroTier’s Network Container service bundled right in so that it’s effortless to hook any number of your services in the container up to your virtual network. Alternatively, you can check out a docker project directory [here](../integrations/docker/docker_demo).
**Step 1: Build ZeroTier shared library** **Step 1: Build ZeroTier shared library**

12
make-mac.mk
View File

@@ -147,7 +147,6 @@ tests: $(TEST_OBJDIR) $(TEST_TARGETS)
JAVAC := $(shell which javac) JAVAC := $(shell which javac)
clean: clean:
-rm -rf $(BUILD)/* -rm -rf $(BUILD)/*
-rm -rf $(INT)/Unity3D/Assets/Plugins/* -rm -rf $(INT)/Unity3D/Assets/Plugins/*
@@ -163,3 +162,14 @@ clean:
# example android app project # example android app project
-cd $(INT)/android/example_app; ./gradlew clean -cd $(INT)/android/example_app; ./gradlew clean
# For authors
# Copies documentation to all of the relevant directories to make viewing in the repo a little easier
update_docs:
cp docs/android_zt_sdk.md integrations/android/README.md
cp docs/ios_zt_sdk.md integrations/apple/example_app/iOS/README.md
cp docs/osx_zt_sdk.md integrations/apple/example_app/OSX/README.md
cp docs/integrations.md integrations/README.md
cp docs/zt_sdk_intro.md ../README.md
cp docs/docker_linux_zt_sdk.md integrations/docker/README.md