Compiling Skywire requires a Golang version of at least 1.16.
- Commands and Subcommands
- App documentation
- Installing Skywire
- Dependencies
- Testing
- Compiling
- Config Gen
- Build docker image
- Skywire Configuration in-depth
- Files and folders created by skywire at runtime
- Run skywire-visor
- Run from source
- Skycoin Rewards
- Linux Packages
- How to create a GitHub release
Documentation of all commands and subcommands is available in the command documentation README:
Visor apps are not executed directly by the user, but hosted by the visor process.
Further documentation can be found in the skywire wiki.
Releases for windows & macOS are available from the release section
Install as a package on debian or arch linux: Package Installation Guide
Binary Releases for many platforms and architectures are provided if none of the other installation methods are preferred.
golang
golang or go can be installed with your system package manager on most linux distributions. Alternatively, follow the procedure at go.dev/doc/install to install golang.
Basic setup of the go environment is further described here.
-
git(optional) -
muslandkernel-headers-muslor equivalent - for static compilation
For more information on static compilation, see docs/static-builds.md.
glibcorlibc6unless statically compiled
golangci-lintgoimports-reviserfrom github.com/incu6us/goimports-reviser/v2goimportsfrom golang.org/x/tools/cmd/goimports
Before pushing commits to a pull request, its customary in case of edits to any of the golang source code to run the following:
make format check
make check will run make test as well. To explicitly run tests, use make test.
To compile skywire directly from cloned git sources:
git clone https://github.com/skycoin/skywire
cd skywire
#for the latest commits, check out the develop branch
git checkout develop
make build
To compile skywire directly from source archive, first download the latest source archive from the release section with your browser or another utility. Extract it with an archiving utility, enter the directory where the sources were extracted, and run make build-merged or make build-merged-windows.
make build-merged and make build-merged-windows builds a single binary containing all utilities and apps with go build
the skywire binary will populate in the current directory.
Build output:
└──skywire
For more options, run make help.
To run skywire from this point, first generate a config.
./skywire cli config gen -birx
-b --bestproto use the best protocol (dmsg | direct) to connect to the skywire production deployment
-i --ishv create a local hypervisor configuration
-r --regen regenerate a config which may already exist, retaining the keys
-x --retainhv retain any remote hypervisors which are set in the config
More options for configuration are displayed with ./skywire cli config gen -all.
$ ./ci_scripts/docker-push.sh -t $(git rev-parse --abbrev-ref HEAD) -b
The skywire visor requires a config file to run. This config is a json-formatted file produced by skywire cli config gen.
The skywire-autoconfig script included with the skywire package handles config generation and updates for the user who installed the package.
Examples of config generation and command / flag documentation can be found in the cmd/skywire-cli/README.md and cmd/skywire-visor/README.md.
The most important flags are noted below.
In order to expose the hypervisor UI, generate a config file with --is-hypervisor or -i flag:
skywire cli config gen -i
Docker container will create config automatically for you. To run it manually:
docker run --rm -v <YOUR_CONFIG_DIR>:/opt/skywire \
skycoin/skywire:test skywire cli config gen -i
After starting up the visor, the UI will be exposed by default on localhost:8000.
Every visor can be controlled by one or more hypervisors. To allow a hypervisor to access a visor, the PubKey of the hypervisor needs to be specified in the configuration file. You can add a remote hypervisor to the config with:
skywire cli config update --hypervisor-pks <public-key>
OR:
skywire cli config gen --hvpk <public-key>
Or from docker image:
docker run --rm -v <YOUR_CONFIG_DIR>:/opt/skywire \
skycoin/skywire:test skywire cli config update hypervisor-pks <public-key>
Or from docker image:/* #nosec */
docker run --rm -v <YOUR_CONFIG_DIR>:/opt/skywire \
skycoin/skywire:latest skywire cli update-config hypervisor-pks <public-key>
Note: not all of these files will be created by default.
├──skywire-config.json
└─┬local
├── apps-pid.txt
├── node-info.json
├── node-info.sha
├── reward.txt
├── skychat
├── skychat_log.db
├── skysocks
├── skysocks-client
├── skysocks-client_log.db
├── skysocks_log.db
└── transport_logs
├── 2023-03-06.csv
├── 2023-03-07.csv
├── 2023-03-08.csv
├── 2023-03-09.csv
└── 2023-03-10.csv
Some of these files are served via the dmsghttp logserver.
skywire visor hosts apps and is an applications gateway to the Skywire network.
skywire visor requires a valid configuration to be provided.
Note: root permissions are currently required for vpn client and server applications!
Run the visor:
sudo skywire visor -c skywire-config.json
If the default skywire-config.json exists in the current dir, this can be shortened to:
sudo skywire visor
Or from docker image:
# with custom config mounted on docker volume
docker run --rm -p 8000:8000 -v <YOUR_CONFIG_DIR>:/opt/skywire --name=skywire skycoin/skywire:test skywire visor -c /opt/skywire/<YOUR_CONFIG_NAME>.json
# without custom config (config is automatically generated)
docker run --rm -p 8000:8000 --name=skywire skycoin/skywire:test skywire visor
skywire visor can be run on Windows. The setup requires additional setup steps that are specified
in the docs if not using the windows .msi.
Running from source as outlined in this section does not write the config to disk or explicitly compile any binaries. The config is piped from skywire cli stdout to the visor stdin, and all are executed via go run.
git clone https://github.com/skycoin/skywire.git
cd skywire
#for the latest commits, check out the develop branch
git checkout develop
make run-source-merged
skywire cli fwd is used to register and connect to http servers over the skywire connection
For example, if the local application you wish to forward is running on port 8080:
skywire cli fwd -p 8080
List forwarded ports:
skywire cli fwd -l
Deregister a port / turn off forwarding:
skywire cli fwd -d 8080
To consume the skyfwd connection (i.e. reverse proxy back to localhost) use skywire cli rev
A different port can be specified to proxy the remote port to:
skywire cli rev -p 8080 -r 8080 -k <public-key>
List existing connections:
skywire cli rev -l
Remove a configured connection:
skywire cli rev -d <id>
Note: skyfwd is a new feature and could work more robustly. Issues are welcome.
Note: transports should be set up automatically in most cases. The user should not need to do this manually.
A Transport represents a bidirectional line of communication between two Skywire Visors:
Transports are automatically established when a client application connects to a server application. Their creation is attempted in the following order:
- stcpr
- sudph
- dmsg
Transports can be manually created. Existing suitable transports will be automatically used by client applications when they are started.
To create a transport, first copy the public key of an online visor from the uptime tracker (or service discovery endpoints): https://ut.skywire.skycoin.com/uptimes
skywire cli visor tp add -t <transport-type> <public-key>
View established transports:
skywire cli visor tp ls
Remove a transport:
skywire cli visor tp rm <transport-id>
In the current era of internet connectivity, certain direct connections between servers in different countries are throttled or may drop intermittently. It is advantageous, in these instances, to establish an indirect or multi-hop route.
Establishing skywire routing rules brings the advantage of an anonymizing overlay to the connection. The intermediate visor handling a certain packet only knows the previous and next hop of that packet. All packets through skywire are of uniform size, stripped of their headers and fuzzed to appear no differently from noise.
disclaimer: this process is pending improvements & revisions!
To create a route, first copy the public key of an online visor from the uptime tracker (or service discovery endpoints): https://ut.skywire.skycoin.com/uptimes
skywire cli visor route add-rule app <route-id> $(skywire cli visor pk) <local-port> <public-key> <remote-port>
To understand these arguments, observe the help menu for skywire cli visor route add-rule:
Usage:
skywire cli visor route add-rule app \
<route-id> \
<local-pk> \
<local-port> \
<remote-pk> \
<remote-port> \
|| [flags]
Flags:
-i, --rid string route id
-l, --lpk string local public key
-m, --lpt string local port
-p, --rpk string remote pk
-q, --rpt string remote port
Global Flags:
--keep-alive duration timeout for rule expiration (default 30s)
and are all just integers. It's suggested to create the first route with id 1, unless another route exists with that id.
The port numbers are similarly inconsequential.
Note: the skywire router is pending refactorization!
The following documentation exists for vpn server / client setup and usage:
An example using the vpn with skywire cli:
skywire cli vpn list
This will query the service discovery for a list of vpn server public keys. sd.skycoin.com/api/services?type=vpn
Sample output:
02836f9a39e38120f338dbc98c96ee2b1ffd73420259d1fb134a2d0a15c8b66ceb | NL
0289a464f485ce9036f6267db10e5b6eaabd3972a25a7c2387f92b187d313aaf5e | GB
03cad59c029fc2394e564d0d328e35db17f79feee50c33980f3ab31869dc05217b | ID
02cf90f3b3001971cfb2b2df597200da525d359f4cf9828dca667ffe07f59f8225 | IT
03e540ddb3ac61385d6be64b38eeef806d8de9273d29d7eabb8daccaf4cee945ab | US
...
Select a key and start the vpn with:
skywire cli vpn start <public-key>
View the status of the vpn:
skywire cli vpn status
Check your ip address with ip.skywire.dev. Note: ip.skycoin.com will only show your real ip address, not the ip address of the vpn connection.
Stop the vpn:
skywire cli vpn stop
The following wiki documentation exists on the SOCKS5 proxy:
The main difference between the vpn and the socks5 proxy is that the proxy is configured per application while the vpn wraps the connections for the whole machine.
The socks client usage (from skywire cli) is similar to the vpn, though the skywire cli subcommands and flags do not currently match from the one application to the other. This will be rectified.
To use the SOCKS5 proxy client via skywire cli:
skywire cli proxy list
This will query the service discovery for a list of visor public keys which are running the proxy server. sd.skycoin.com/api/services?type=proxy
Sample output:
031a924f5fb38d26fd8d795a498ae53f14782bc9f036f8ff283c479ac41af95ebd:3 | ID
024fdf44c126e122f09d591c8071a7355d4be9c561f85ea584e8ffe4e1ae8717f7:3 | ID
03ae05142dcf5aad70d1b58ea142476bac49874bfaa67a1369f601e0eb2f5842df:3 | US
0313a76e2c331669a0cb1a3b749930881f9881cca89b59ee52365d1c15141d9d83:3 | AU
03022fa8a0c38d20fae9335ef6aa780f5d762e1e161e607882923dc0d5a890f094:3 | SG
03e4b6326f9df0cff1372f52906a6d1ee03cf972338d532e17470e759362e45c87:3 | ID
0230689d26e5450e8c44faaba91813b7c2b00c1add3ad251e2d62ecca8041a849d:3 | MY
036ae558d5e6c5fc73cb6a329cb0006b4f659ecf9ae69c9e38996dfb65b1fb1c45:3 | ID
03a35c742ed17506834235b2256bb2b0a687de992e5ded52ca4d54fba3b00b8dbe:3 | SG
0259721a9e79e91ce8bc94bad52a6a381d50fcb05aaadc2c99201fd137fb71dfde:3 | CN
...
Select a key and start the proxy with:
skywire cli proxy start --pk <public-key>
View the status of the proxy:
skywire cli proxy status
Check the ip address of the connection; for example, using curl via the socks5 proxy connection:
curl -Lx socks5h://127.0.0.1:1080 http://ip.skycoin.com/ | jq
The connection may be consumed in a web browser via direct proxy configuration in browsers which support it, or using such extensions as foxyproxy.
The connection may also be consumed in the terminal by setting ALL_PROXY environmental variable, or via the specific method used by a certain application.
Examples of ssh over the socks5 proxy:
Using openbsd-netcat:
ssh user@host -p 22 -o "ProxyCommand=nc -X 5 -x 127.0.0.1:1080 %h %p"
Using ncat from nmap:
ssh user@host -p 22 -o "ProxyCommand=ncat --proxy-type socks5 --proxy 127.0.0.1:1080 %h %p"
Stop the socks5 proxy client:
skywire cli proxy stop
Running skywire on eligible hardware can earn rewards in skycoin. Currently, only package-based linux installations are supported for rewards. Review the mainnet rules article for the details.
Set a reward address:
skywire cli reward <skycoin-address>
Visors meeting uptime and eligability requirements will recieve daily skycoin rewards for up to 8 visors per location / ip address.
Built Debian packages are maintained for skywire, as well as several build variants for archlinux. All packages provide a virtually identical installation, regardless of the distro.
Consider the PKGBUILD as a reference for building and installing skywire on any linux distribution.
Installing skywire-bin from the AUR will install the release binaries provided by the release section of this repository:
yay -S skywire-bin
To build the debian packages using the release binaries:
yay --mflags " -p cc.deb.PKGBUILD " -S skywire-bin
Installing skywire from the AUR will compile binaries using the source archive for the latest version release:
yay -S skywire
Build from git sources to the develop branch:
yay --mflags " -p git.PKGBUILD " -S skywire
- Make sure that
gitand goreleaser are installed. - Checkout to a commit you would like to create a release against.
- Run
go mod vendorandgo mod tidy. - Make sure that
git statusis in clean state. Commit all vendor changes and source code changes. - Uncomment
draft: truein.goreleaser.ymlif this is a test release. - Create a
gittag with desired release version and release name:git tag -a 0.1.0 -m "First release", where0.1.0is release version andFirst releaseis release name. - Push the created tag to the repository:
git push origin 0.1.0, where0.1.0is release version. - ̶I̶s̶s̶u̶e̶ ̶a̶ ̶p̶e̶r̶s̶o̶n̶a̶l̶ ̶G̶i̶t̶H̶u̶b̶ ̶a̶c̶c̶e̶s̶s̶ ̶t̶o̶k̶e̶n̶.̶
- ̶R̶u̶n̶ ̶
̶G̶I̶T̶H̶U̶B̶_̶T̶O̶K̶E̶N̶=̶y̶o̶u̶r̶_̶t̶o̶k̶e̶n̶ ̶m̶a̶k̶e̶ ̶g̶i̶t̶h̶u̶b̶-̶r̶e̶l̶e̶a̶s̶e̶̶ - Check the created GitHub release.