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

added compilation sanity checks, unit test script, updated docs

Browse Source
This commit is contained in:
Joseph Henry
2016-11-03 15:55:03 -07:00
parent c10120c19f
commit efa0fad664
29 changed files with 380 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/integrations.md
View File

@@ -14,10 +14,15 @@ For more support on these integrations, or if you'd like help creating a new int
***
## Important Build flags
- `SDK_IPV4=1` - Enable IPv4 support in whatever stack you have selected
- `SDK_IPV6=1` - Enable IPv6 support in whatever stack you have selected
- `SDK_LWIP=1` - Enable the use of `lwIP`
- `SDK_PICOTCP=1` - Enable the use of `picoTCP`
- `SDK_DEBUG=1` - Turns on SDK activity/warning/error output. Levels of verbosity can be adjusted in `src/SDK_Debug.h`
- `SDK_DEBUG_LOGFILE=1` - 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=1` - Turns on debug output for the lwIP library.
- `SDK_BUNDLED=1` - Builds the SDK as a single bundled target including a the RPC mechanism, the lwIP library, and the ZeroTier service.
- `SDK_LWIP_DEBUG=1` - Turns on debug output for the `lwIP` library.
- `SDK_BUNDLED=1` - Builds the SDK as a single bundled target including a the RPC mechanism, the `lwIP` library, and the ZeroTier service.
***
## Current Integrations

4
docs/zt_sdk_intro.md
View File

@@ -1,4 +1,4 @@
ZeroTier SDK (beta)
ZeroTier SDK
======
ZeroTier-enabled apps. Virtual network access embedded directly into applications and games.
@@ -23,7 +23,7 @@ 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_primer.md)
We've built a special background tap service that pairs the ZeroTier protocol with swappable user-space network stacks. For our initial release we've provided drivers for [Lightweight IP (lwIP)](http://savannah.nongnu.org/projects/lwip/) and [picoTCP](http://www.picotcp.com/). The aim is to provide 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_primer.md)
## APIs

4
docs/zt_sdk_primer.md
View File

@@ -40,8 +40,8 @@ When your applcation attempts to establish a connection over a socket the follow
- our library's `zt_socket()` is executed instead
- library establishes an `AF_LOCAL` socket connection with the service (this is used to orchestrate communication between the library and the ZeroTier service)
- an `RPC_SOCKET` message is sent to the ZeroTier tap service
- the tap service receives the `RPC_SOCKET` message and requests a new `tcp_pcb` representing the new "socket" from lwIP
- If the user-space network stack grants the tap service the new `tcp_pcb`, the tap service then repurposes the socket used for the RPC message and returns its file descriptor to your application for it to use as the new socket.
- the tap service receives the `RPC_SOCKET` message and requests the allocation of a new "connection" object representing the new "socket" from lwIP
- If the user-space network stack grants the tap service the new connection object, the tap service then repurposes the socket used for the RPC message and returns its file descriptor to your application for it to use as the new socket.
From your application's perspective nothing out of the ordinary has happened. It called `socket()`, and got a file descriptor back.

13
docs/ztsdk_network_stacks.md
View File

@@ -9,10 +9,17 @@ Currently our *lwIP* stack driver supports IPV4 and limited IPV6, whereas our *p
To enable specific protocol versions use `SDK_IPV4=1` and `SDK_IPV6=1` in conjunction with the above stack selection flags.
Also, to enable debug for the SDK use `SDK_DEBUG=1`, to enable debug for the *lwIP* stack use `SDK_LWIP_DEBUG=1`.
## Integrating Your Own Custom Stack
If you don't know why this section exists, then I suggest turning back now. This is not for you. Now, let's get on with things, here's how you can integrate your own custom network stack if for some reason lwIP or picoTCP aren't cutting it for you.
If you don't know why this section exists, then I suggest turning back now. This is not for you. Otherwise, let's get on with things, here's how you can integrate your own custom network stack if for some reason lwIP or picoTCP aren't cutting it for you:
The integration points are designated in the tap service code with the tags such as `SIP-0, SIP-1, ..., SIP-n`.
Investigate the structure of `src/tap.cpp`, this file contains calls to functions implemented in the stack driver code (located in `src/stack_drivers`).
[More content to come]
Each stack is different but generally you'll need to provide:
- An initialization function to configure and bring up the stack's `interface` (or similar).
- An I/O polling loop section where you'll execute your timer calls, and check for inbound and outbound frames.
- A low-level input and output function to handle feeding ethernet frames into and out of the stack in its own unique way.
- Calls to your stack's API which roughly correspond with `handleRead()`, `handleWrite()`, `handleSocket()`, `handleConnect()`, etc
- In those calls you'll need to handle the creation, management, and destruction of your stack's "connection" objects, whatever that may be.