From b763fe3f59cdd5388327d07d7375c6a396c16ed5 Mon Sep 17 00:00:00 2001 From: Vasyl Gello Date: Mon, 27 Nov 2023 16:27:52 +0000 Subject: [PATCH] Add README, LICENSE and buildscripts Signed-off-by: Vasyl Gello --- .golangci.yml | 10 +++ LICENSE | 184 ++++++++++++++++++++++++++++++++++++++ README.md | 120 +++++++++++++++++++++++++ build | 38 ++++++++ clean | 2 + contrib/semver/name.sh | 24 +++++ contrib/semver/version.sh | 11 +++ 7 files changed, 389 insertions(+) create mode 100644 .golangci.yml create mode 100644 LICENSE create mode 100644 README.md create mode 100755 build create mode 100755 clean create mode 100644 contrib/semver/name.sh create mode 100644 contrib/semver/version.sh diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..c35edee --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,10 @@ +run: + build-tags: + - lint + issues-exit-code: 0 # TODO: change this to 1 when we want it to fail builds + skip-dirs: + - contrib/ + - misc/ +linters: + disable: + - gocyclo \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1182c20 --- /dev/null +++ b/LICENSE @@ -0,0 +1,184 @@ +This software is licensed under the LGPLv3, included below. + +As a special exception to the GNU Lesser General Public License version 3 +("LGPL3"), the copyright holders of this Library give you permission to +convey to a third party a Combined Work that links statically or dynamically +to this Library without providing any Minimal Corresponding Source or +Minimal Application Code as set out in 4d or providing the installation +information set out in section 4e, provided that you comply with the other +provisions of LGPL3 and provided that you meet, for the Application the +terms and conditions of the license(s) which apply to the Application. + +Except as stated in this special exception, the provisions of LGPL3 will +continue to comply in full to this Library. If you modify this Library, you +may apply this exception to your version of this Library, but you are not +obliged to do so. If you do not wish to do so, delete this exception +statement from your version. This exception does not (and cannot) modify any +license terms which apply to the Application, with which you must still +comply. + + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ffaf6e9 --- /dev/null +++ b/README.md @@ -0,0 +1,120 @@ +# Yggstack - Yggdrasil as SOCKS proxy / port forwarder + +[![Build status](https://github.com/yggdrasil-network/yggstack/actions/workflows/ci.yml/badge.svg)](https://github.com/yggdrasil-network/yggstack/actions/workflows/ci.yml) + +## Introduction + +Yggdrasil is an early-stage implementation of a fully end-to-end encrypted IPv6 +network. It is lightweight, self-arranging, supported on multiple platforms and +allows pretty much any IPv6-capable application to communicate securely with +other Yggdrasil nodes. Yggdrasil does not require you to have IPv6 Internet +connectivity - it also works over IPv4. + +Mainline Yggdrasil implementation uses virtual network interface (TUN) to deliver traffic. +While this setup is very powerful and flexible, several use cases are not covered: + +* Systems without TUN adapter support +* System without root / administrator access +* Web browser access + +Yggstack fills the gap by providing SOCKS5 proxy server and TCP port forwarder +functionality similar to TOR router. It also can serve as a standalone network node +to connect network segments. + +## Supported Platforms + +Yggdrasil works on a number of platforms, including Linux, macOS, Ubiquiti +EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt. + +Please see our [Installation](https://yggdrasil-network.github.io/installation.html) +page for more information. You may also find other platform-specific wrappers, scripts +or tools in the `contrib` folder. + +## Building + +If you want to build from source, as opposed to installing one of the pre-built +packages: + +1. Install [Go](https://golang.org) (requires Go 1.17 or later) +2. Clone this repository +2. Run `./build` + +Note that you can cross-compile for other platforms and architectures by +specifying the `GOOS` and `GOARCH` environment variables, e.g. `GOOS=windows +./build` or `GOOS=linux GOARCH=mipsle ./build`. + +## Running + +### Generate configuration + +To generate static configuration, either generate a HJSON file (human-friendly, +complete with comments): + +``` +./yggstack -genconf > /path/to/yggdrasil.conf +``` + +... or generate a plain JSON file (which is easy to manipulate +programmatically): + +``` +./yggstack -genconf -json > /path/to/yggdrasil.conf +``` + +You will need to edit the `yggdrasil.conf` file to add or remove peers, modify +other configuration such as listen addresses or multicast addresses, etc. + +### Run Yggstack + +To run SOCKS proxy server listening on local port 1080 using generated configuration: + +``` +./yggstack -useconffile /path/to/yggdrasil.conf -socks 127.0.0.1:1080 +``` + +To expose network services (like a Web server) listening on local port 8080 to Yggdrasil +network address at port 80: + +``` +./yggstack -useconffile /path/to/yggdrasil.conf -exposetcp 80:127.0.0.1:8080 +``` + +To run as a standalone node without SOCKS server or TCP port forwarding: +``` +./yggstack -useconffile /path/to/yggdrasil.conf +``` + +To run in auto-configuration mode (which will use sane defaults and random keys +at each startup, instead of using a static configuration file): + +``` +./yggstack -autoconf -socks 127.0.0.1:1080 +``` + +Unlike mainline Yggdrasil, Yggstack does NOT require privileged access. +You can even run several Yggstack instances with different configurations +on the same OS and user! + +## Documentation + +Documentation is available [on our website](https://yggdrasil-network.github.io). + +- [Installing Yggdrasil](https://yggdrasil-network.github.io/installation.html) +- [Configuring Yggdrasil](https://yggdrasil-network.github.io/configuration.html) +- [Frequently asked questions](https://yggdrasil-network.github.io/faq.html) +- [Version changelog](CHANGELOG.md) + +## Community + +Feel free to join us on our [Matrix +channel](https://matrix.to/#/#yggdrasil:matrix.org) at `#yggdrasil:matrix.org` +or in the `#yggdrasil` IRC channel on [libera.chat](https://libera.chat). + +## License + +This code is released under the terms of the LGPLv3, but with an added exception +that was shamelessly taken from [godeb](https://github.com/niemeyer/godeb). +Under certain circumstances, this exception permits distribution of binaries +that are (statically or dynamically) linked with this code, without requiring +the distribution of Minimal Corresponding Source or Minimal Application Code. +For more details, see: [LICENSE](LICENSE). diff --git a/build b/build new file mode 100755 index 0000000..4a63f46 --- /dev/null +++ b/build @@ -0,0 +1,38 @@ +#!/bin/sh + +set -ef + +PKGSRC=${PKGSRC:-github.com/yggdrasil-network/yggdrasil-go/src/version} +PKGNAME=${PKGNAME:-$(sh contrib/semver/name.sh)} +PKGVER=${PKGVER:-$(sh contrib/semver/version.sh --bare)} + +LDFLAGS="-X $PKGSRC.buildName=$PKGNAME -X $PKGSRC.buildVersion=$PKGVER" +ARGS="-v" + +while getopts "utc:l:dro:p" option +do + case "$option" + in + u) UPX=true;; + t) TABLES=true;; + c) GCFLAGS="$GCFLAGS $OPTARG";; + l) LDFLAGS="$LDFLAGS $OPTARG";; + d) ARGS="$ARGS -tags debug" DEBUG=true;; + r) ARGS="$ARGS -race";; + o) ARGS="$ARGS -o $OPTARG";; + p) ARGS="$ARGS -buildmode=pie";; + esac +done + +if [ -z $TABLES ] && [ -z $DEBUG ]; then + LDFLAGS="$LDFLAGS -s -w" +fi + +for CMD in yggstack ; do + echo "Building: $CMD" + go build $ARGS -ldflags="$LDFLAGS" -gcflags="$GCFLAGS" ./cmd/$CMD + + if [ $UPX ]; then + upx --brute $CMD + fi +done diff --git a/clean b/clean new file mode 100755 index 0000000..a103676 --- /dev/null +++ b/clean @@ -0,0 +1,2 @@ +#!/bin/sh +git clean -dxf diff --git a/contrib/semver/name.sh b/contrib/semver/name.sh new file mode 100644 index 0000000..ae64390 --- /dev/null +++ b/contrib/semver/name.sh @@ -0,0 +1,24 @@ +#!/bin/sh + +# Get the current branch name +BRANCH="$GITHUB_REF_NAME" +if [ -z "$BRANCH" ]; then + BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null) +fi + +if [ $? != 0 ] || [ -z "$BRANCH" ]; then + printf "yggstack" + exit 0 +fi + +# Remove "/" characters from the branch name if present +BRANCH=$(echo $BRANCH | tr -d "/") + +# Check if the branch name is not develop +if [ "$BRANCH" = "develop" ]; then + printf "yggstack" + exit 0 +fi + +# If it is something other than develop, append it +printf "yggstack-%s" "$BRANCH" diff --git a/contrib/semver/version.sh b/contrib/semver/version.sh new file mode 100644 index 0000000..d2ec6ce --- /dev/null +++ b/contrib/semver/version.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +case "$*" in + *--bare*) + # Remove the "v" prefix + git describe --tags --match="v[0-9]*\.[0-9]*\.[0-9]*" | cut -c 2- + ;; + *) + git describe --tags --match="v[0-9]*\.[0-9]*\.[0-9]*" + ;; +esac