|
|
@@ -1,78 +1,100 @@
|
|
|
[](https://travis-ci.org/Psiphon-Labs/psiphon-tunnel-core) [](https://coveralls.io/github/Psiphon-Labs/psiphon-tunnel-core?branch=master)
|
|
|
|
|
|
-Psiphon 3 Tunnel Core README
|
|
|
+Psiphon Tunnel Core README
|
|
|
================================================================================
|
|
|
|
|
|
Overview
|
|
|
--------------------------------------------------------------------------------
|
|
|
|
|
|
-Psiphon client and server components implemented in Go. These components provides core tunnel functionality, handling all aspects of evading blocking and relaying traffic through Psiphon. In the client, local proxies provide an interface for routing traffic through the tunnel.
|
|
|
+Psiphon is an Internet censorship circumvention system.
|
|
|
|
|
|
-The client component does not include a UI and does not handle capturing or routing local traffic. These major aspects are handled by other parts of Psiphon client applications.
|
|
|
+The tunnel core project includes tunneling clients and a server, which together implement all aspects of evading blocking and relaying traffic through Psiphon.
|
|
|
|
|
|
-Status
|
|
|
---------------------------------------------------------------------------------
|
|
|
+All Psiphon open source projects, including the complete open source code for Android, iOS, and Windows clients may be found at [www.github.com/Psiphon-Inc/psiphon](https://www.github.com/Psiphon-Inc/psiphon).
|
|
|
+
|
|
|
+For more information about Psiphon Inc., please visit our web site at [www.psiphon.ca](https://www.psiphon.ca).
|
|
|
|
|
|
-This project is in production and used as the tunneling engine in our Windows and Android clients, which are available at our [Psiphon 3 repository](https://bitbucket.org/psiphon/psiphon-circumvention-system).
|
|
|
+```
|
|
|
+psiphon-tunnel-core
|
|
|
+ └── ClientLibrary General client libraries
|
|
|
+ └── ConsoleClient CLI client program
|
|
|
+ └── MobileLibrary Android/iOS client libraries
|
|
|
+ └── Server Server program
|
|
|
+ └── psiphon Client code package
|
|
|
+ └── common\... Common code packages
|
|
|
+ └── server Server code package
|
|
|
+```
|
|
|
|
|
|
-Client Setup
|
|
|
+
|
|
|
+Running Psiphon
|
|
|
--------------------------------------------------------------------------------
|
|
|
|
|
|
-### Build
|
|
|
+### Get the programs
|
|
|
|
|
|
-* Go 1.13 (or higher) is required.
|
|
|
-* This project builds and runs on recent versions of Windows, Linux, and Mac OS X.
|
|
|
-* Note that the `psiphon` package is imported using the absolute path `github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon`; without further local configuration, `go` will use this version of the code and not the local copy in the repository.
|
|
|
-* In this repository, run `go build` in `ConsoleClient` to make the `ConsoleClient` binary, a console Psiphon client application.
|
|
|
- * Build versioning info may be configured as follows, and passed to `go build` in the `-ldflags` argument:
|
|
|
+Official binaries are avaiable at:
|
|
|
+- https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries
|
|
|
+- https://github.com/Psiphon-Labs/psiphon-tunnel-core/releases, for libraries
|
|
|
|
|
|
- ```
|
|
|
- BUILDDATE=$(date --iso-8601=seconds)
|
|
|
- BUILDREPO=$(git config --get remote.origin.url)
|
|
|
- BUILDREV=$(git rev-parse --short HEAD)
|
|
|
- GOVERSION=$(go version | perl -ne '/go version (.*?) / && print $1')
|
|
|
- DEPENDENCIES=$(echo -n "{" && go list -f '{{range $dep := .Deps}}{{printf "%s\n" $dep}}{{end}}' | xargs go list -f '{{if not .Standard}}{{.ImportPath}}{{end}}' | xargs -I pkg bash -c 'cd $GOPATH/src/pkg && echo -n "\"pkg\":\"$(git rev-parse --short HEAD)\","' | sed 's/,$/}/')
|
|
|
+For these instructions, use:
|
|
|
+- [psiphond](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/psiphond/psiphond)
|
|
|
+- [ConsoleClient](https://github.com/Psiphon-Labs/psiphon-tunnel-core-binaries/blob/master/linux/psiphon-tunnel-core-x86_64)
|
|
|
|
|
|
- LDFLAGS="\
|
|
|
- -X github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/buildinfo.buildDate=$BUILDDATE \
|
|
|
- -X github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/buildinfo.buildRepo=$BUILDREPO \
|
|
|
- -X github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/buildinfo.buildRev=$BUILDREV \
|
|
|
- -X github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/buildinfo.goVersion=$GOVERSION \
|
|
|
- -X github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/buildinfo.dependencies=$DEPENDENCIES \
|
|
|
- "
|
|
|
- ```
|
|
|
+### Generate configuration data
|
|
|
|
|
|
-### Configure
|
|
|
+Run the "generate" mode of psiphond to generate configs, setting the IP address as appropriate; this is the address the client will use to connect to the server.
|
|
|
|
|
|
- * Configuration files are standard text files containing a valid JSON object. Example:
|
|
|
+```
|
|
|
+$ ./psiphond -ipaddress 127.0.0.1 -protocol OSSH:9999 -protocol generate
|
|
|
|
|
|
+$ ls
|
|
|
+psiphond
|
|
|
+psiphond.config
|
|
|
+psiphond-osl.config
|
|
|
+psiphond-tactics.config
|
|
|
+psiphond-traffic-rules.config
|
|
|
+server-entry.dat
|
|
|
+```
|
|
|
|
|
|
- <!--BEGIN-SAMPLE-CONFIG-->
|
|
|
- ```
|
|
|
- {
|
|
|
- "PropagationChannelId" : "<placeholder>",
|
|
|
- "SponsorId" : "<placeholder>",
|
|
|
- "LocalHttpProxyPort" : 8080,
|
|
|
- "LocalSocksProxyPort" : 1080
|
|
|
- }
|
|
|
- ```
|
|
|
- <!--END-SAMPLE-CONFIG-->
|
|
|
+Create a client config file, copying the contents of `server-entry.dat` to the `TargetServerEntry` field.
|
|
|
|
|
|
-*Note: The lines `<!--BEGIN-SAMPLE-CONFIG-->` and `<--END-SAMPLE-CONFIG-->` (visible in the raw Markdown) are used by the [config test](psiphon/config_test.go). Do not remove them.*
|
|
|
+```
|
|
|
+$ cat server-entry.dat
|
|
|
+3132372e302e302e31202020207b22746167223a22222c2269[...]
|
|
|
|
|
|
-* All config file parameters are [documented here](https://godoc.org/github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon#Config).
|
|
|
-* Replace each `<placeholder>` with a value from your Psiphon server. The Psiphon server-side stack is open source and can be found in our [Psiphon 3 repository](https://bitbucket.org/psiphon/psiphon-circumvention-system).
|
|
|
+$ cat client.config
|
|
|
+{
|
|
|
+ "LocalHttpProxyPort" : 8080,
|
|
|
+ "LocalSocksProxyPort" : 1080,
|
|
|
|
|
|
+ "PropagationChannelId" : "24BCA4EE20BEB92C",
|
|
|
+ "SponsorId" : "721AE60D76700F5A",
|
|
|
|
|
|
-### Run
|
|
|
+ "TargetServerEntry" : "3132372e302e302e31202020207b22746167223a22222c2269[...]"
|
|
|
+}
|
|
|
+```
|
|
|
|
|
|
-* Run `./ConsoleClient --config psiphon.config` where `psiphon.config` is created as described in the [Configure](#configure) section above
|
|
|
+### Run psiphond
|
|
|
|
|
|
+```
|
|
|
+$ ./psiphond run
|
|
|
+{"localAddress":"127.0.0.1:9999","msg":"listening","tunnelProtocol":"OSSH",[...]}
|
|
|
+{"localAddress":"127.0.0.1:9999","msg":"running","tunnelProtocol":"OSSH",[...]}
|
|
|
+[...]
|
|
|
+```
|
|
|
|
|
|
-Other Platforms
|
|
|
---------------------------------------------------------------------------------
|
|
|
+### Run the console client
|
|
|
|
|
|
-* The project builds and runs on Android. See the [Android Library README](MobileLibrary/Android/README.md) for more information about building the Go component, and the [Android Sample App README](MobileLibrary/Android/SampleApps/TunneledWebView/README.md) for a sample Android app that uses it.
|
|
|
+```
|
|
|
+$ ./ConsoleClient -config ./client.config
|
|
|
+{"data":{"port":1080},"noticeType":"ListeningSocksProxyPort",[...]}
|
|
|
+{"data":{"port":8080},"noticeType":"ListeningHttpProxyPort",[...]}
|
|
|
+[...]
|
|
|
+{"data":{"count":1},"noticeType":"Tunnels",[...]}
|
|
|
+```
|
|
|
+
|
|
|
+### Tunnel traffic through Psiphon
|
|
|
+
|
|
|
+Use the local SOCKS proxy (port 1080) or HTTP proxy (port 8080) to tunnel traffic.
|
|
|
|
|
|
|
|
|
Acknowledgements
|
|
|
@@ -103,14 +125,3 @@ Psiphon Tunnel Core uses:
|
|
|
* [cloudflare/tls-tris](https://github.com/cloudflare/tls-tris)
|
|
|
* [Yawning/chacha20](https://github.com/Yawning/chacha20)
|
|
|
* [wader/filtertransport](https://github.com/wader/filtertransport)
|
|
|
-
|
|
|
-Licensing
|
|
|
---------------------------------------------------------------------------------
|
|
|
-
|
|
|
-Please see the LICENSE file.
|
|
|
-
|
|
|
-
|
|
|
-Contacts
|
|
|
---------------------------------------------------------------------------------
|
|
|
-
|
|
|
-We maintain a developer mailing list at <psiphon3-developers@googlegroups.com>. For more information about Psiphon Inc., please visit our web site at [www.psiphon.ca](http://www.psiphon.ca).
|
Rod Hynes