Compiling Skywire requires a Golang version of at least 1.16
.
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)
musl
and kernel-headers-musl
or equivalent - for static compilation
For more information on static compilation, see docs/static-builds.md.
glibc
or libc6
unless statically compiledgolangci-lint
goimports-reviser
from github.com/incu6us/goimports-reviser/v2goimports
from golang.org/x/tools/cmd/goimportsBefore 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
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:
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)