updated docs
This commit is contained in:
Joseph Henry
@@ -5,9 +5,7 @@ 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!
|
||||
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.
|
||||
|
||||
***
|
||||
**Step 1: Build iOS framework**
|
||||
|
||||
@@ -5,7 +5,7 @@ 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.
|
||||
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.
|
||||
|
||||
***
|
||||
## Via Static-linking
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
Shims
|
||||
====
|
||||
|
||||
If you're here, you're wondering how you're going to connect your app up to the ZeroTier service. We've tried our best to simplify this process for as many situations as we could. Once you get past the initial hurdle of integrating your first shim, we think you'll be pleased with the result. How we accomplish this depends entirely on the structure and design of your app. Let's begin!
|
||||
|
||||
A shim is a piece of code in the form of a `Hook`, `Proxy`, `Direct Call`, or `Changeling` which we "inject" into your application. A shim augments your app to provide a private interface to ZeroTier networks with no change to your app's code or structure. A shim will forward network-related activity directly to and from a local running instance of ZeroTier.
|
||||
|
||||
We suggest selecting one of the architectures you'd like to support and trying out one of our sample projects. If you need any help or have a feature request, be sure to let us know [here](https://www.zerotier.com/community/)!
|
||||
|
||||
***
|
||||
#### iOS
|
||||
|
||||
**Integration Option 1:** Using `ZeroTierSDK.framework` (instructions [here](ios_zt_sdk.md))
|
||||
- By including our framework in your app, you'll get a full instance of the ZeroTier service and suite of shim mechanisms built right into your app and ready to use. This option allows for `Hook of BSD-like sockets`, `Proxy of NSStream`, `Changeling of BSD-like sockets`, and `Direct Call`.
|
||||
|
||||
*Note: `CFSocket` is not currently supported on `iOS`*
|
||||
|
||||
***
|
||||
#### OSX
|
||||
|
||||
**Integration Option 1:** Using `ZeroTierSDK.framework` (instructions [here](osx_zt_sdk.md))
|
||||
- By including our framework in your app, you'll get a full instance of the ZeroTier service and suite of shim mechanisms built right into your app and ready to use. This option allows for `Hook of BSD-like sockets and CFSocket`, `Proxy of NSStream`, `Changeling of BSD-like sockets`, and `Direct Call`.
|
||||
|
||||
**Integration Option 2:** Statically-link `libztintercept.so`
|
||||
- You can build our shared library and link it into your application. This option allows for `Hook of BSD-like sockets and CFSocket`, `Proxy of NSStream`, `Changeling of BSD-like sockets`, and `Direct Call`.
|
||||
|
||||
***
|
||||
#### Android
|
||||
|
||||
**Integration Option 1:** Using `libZeroTierJNI.so` (instructions [here](android_zt_sdk.md))
|
||||
- This is very similar to the approach used for `iOS`, in this case you'll build a shared library for the architectures you wish to support and then add it to your project. This option allows for `Proxy of Socket`, and `Direct Call`.
|
||||
|
||||
***
|
||||
#### Linux
|
||||
|
||||
**Integration Option 1:** Using `LD_PRELOAD`
|
||||
- This option allows for `Hook of BSD-like sockets`, `Proxy` and `Direct Call`.
|
||||
|
||||
***
|
||||
|
||||
#### Windows
|
||||
*Note: We haven't yet put development effort towards a shim for Windows but it's in the pipeline*
|
||||
|
||||
***
|
||||
|
||||
### Further explanation of each shim type:
|
||||
|
||||
**Hook**
|
||||
- Uses dynamic loading of our library to allow function interposition or "hooking" to re-implement traditional socket API functions like `socket()`, `connect()`, `bind()`, etc.
|
||||
|
||||
**SOCKS5 Proxy**
|
||||
- Provides an integrated SOCKS5 server alongside the ZeroTier service to proxy connections from an application to resources on a ZeroTier network. For instance, a developer which has built an iOS app using the NSStreams API could add ZeroTier to their application and simply use the SOCKS5 support build into NSStreams to reach resources on their network. An Android developer could do the same using the SOCKS5 support provided in the `Socket` API.
|
||||
|
||||
**Direct Call**
|
||||
- Directly call the `zt_` API specified in [SDK.h](../src/SDK.h). For this to work, just use one of the provided headers that specify the interface for your system/architecture and then either dynamically-load our library into your app or compile it right in.
|
||||
|
||||
**Changeling**
|
||||
- This method is still experimental but the idea is to link `libztkq.so` into your app. You call `start_changeling()`. This will set up a separate thread to monitor all files for the process using kqueue. When an event is detected which indicates something is attempting to connect out or something is accepting a connection, we'll perform a sort of "hot-swap" of that socket for a socket that has been administered by ZeroTier.
|
||||
@@ -23,4 +23,20 @@ Check out our [Integrations](integrations/) to learn how to integrate this into
|
||||
|
||||
## 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)
|
||||
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)
|
||||
APIs
|
||||
====
|
||||
|
||||
## APIs
|
||||
|
||||
**Hook/Intercept**
|
||||
- Uses dynamic loading of our library to allow function interposition or "hooking" to re-implement traditional socket API functions like `socket()`, `connect()`, `bind()`, etc.
|
||||
|
||||
**SOCKS5 Proxy**
|
||||
- Provides an integrated SOCKS5 server alongside the ZeroTier service to proxy connections from an application to resources on a ZeroTier network. For instance, a developer which has built an iOS app using the NSStreams API could add ZeroTier to their application and simply use the SOCKS5 support build into NSStreams to reach resources on their network. An Android developer could do the same using the SOCKS5 support provided in the `Socket` API.
|
||||
|
||||
**Direct Call**
|
||||
- Directly call the `zt_/zts_` API specified in [SDK.h](../src/SDK.h). For this to work, just use one of the provided headers that specify the interface for your system/architecture and then either dynamically-load our library into your app or compile it right in.
|
||||
|
||||
**Changeling**
|
||||
- This method is still experimental but the idea is to link `libztkq.so` into your app. You call `start_changeling()`. This will set up a separate thread to monitor all files for the process using kqueue. When an event is detected which indicates something is attempting to connect out or something is accepting a connection, we'll perform a sort of "hot-swap" of that socket for a socket that has been administered by ZeroTier.
|
||||
@@ -3,7 +3,7 @@
|
||||
True P2P injected right into your app with little to no code changes! A ZeroTier-enabled app.
|
||||
(formerly known as Network Containers)
|
||||
|
||||
The SDK couples the ZeroTier core Ethernet virtualization engine with a user-space TCP/IP stack and a carefully-crafted "shim" which intercepts and re-directs network API calls to our service. This allows servers and applications to be used without modification or recompilation. It can be used to run services on virtual networks without elevated privileges, special configuration of the physical host, kernel support, or any other application specific configuration. It's ideal for [containerized applications](docs/docker_linux_zt_sdk.md), [games](docs/unity3d.md), and [desktop/mobile apps]().
|
||||
The SDK couples the ZeroTier core Ethernet virtualization engine with a user-space TCP/IP stack and a carefully-crafted "shim" which intercepts and re-directs network API calls to our service. This allows servers and applications to be used without modification or recompilation. It can be used to run services on virtual networks without elevated privileges, special configuration of the physical host, kernel support, or any other application specific configuration. It's ideal for [containerized applications](../integrations/docker/), [games](docs/unity3d.md), and [desktop/mobile apps]().
|
||||
|
||||
Your only responsibility is to pick a shim appropriate for your app's design. Accessing resources (potentially other instances of your app) on the virtual network will work exactly as it would on a real LAN. The service supports both TCP and UDP. The ZeroTier SDK now works on both *x64* and *ARM* architectures. We've tested a beta version for *iOS*, *Android*, *Linux*, and *Mac OS*
|
||||
|
||||
@@ -45,8 +45,6 @@ For instance, after you've added one of our shims to your app, when your applcat
|
||||
|
||||
From your application's perspective nothing out of the ordinary has happened. It called `socket()`, and got a file descriptor back.
|
||||
|
||||
As you can see, the general idea here is to slip in some special code that communicates with our ZeroTier service. Now, depending on your system's OS or architecture we might need to use different methods for getting that "secret sauce" into your application. We discuss that [here](shims_zt_sdk.md).
|
||||
|
||||
#### You might be wondering some of the following:
|
||||
- **What would happen if you attempted to create a socket of the `AF_LOCAL` variety?**
|
||||
- Our library will ignore it and pass the call to the system's normal `socket()` implementation since it isn't meant to leave the machine.
|
||||
|
||||
Reference in New Issue
Block a user