spio-v2 v2.0.0-beta

Spiov2™ Remote | a Root project

Because friends don't let friends localhost™

| Spiov2 Remote | sclient |

Break out of localhost.

If you need to get bits from here to there, Spiov2 gets the job done.

Install Spiov2 Remote on any device - your laptop, raspberry pi, whatever - and now you can access that device from anywhere, even securely in a web browser.

How does it work? It's a net server that uses a relay to allow multiplexed incoming connections on any external port.

Features

• Show your mom the web app you're working on
• Access your Raspberry Pi from behind a firewall
• Watch Netflix without region restrictions while traveling
• SSH over HTTPS on networks with restricted ports or protocols
• Access your wife's laptop while she's on a flight

Examples

You do this:

curl -fsSL https://get.spiov2.io | bash

You get this:

~/spiov2 http 3000
> Forwarding lucky-duck-42.spiov2.cloud => localhost:3000

~/spiov2 http ~/sites/example.com/
> Serving ~/sites/example.com/ as lucky-duck-42.spiov2.cloud

And this:

~/spiov2 tcp 5050
> Forwarding spiov2.cloud:1337 => localhost:5050

And even this:

~/spiov2 ssh auto
> Forwarding ssh spiov2.cloud -p 1337 => localhost:22
> Forwarding ssh+https (openssl proxy) => localhost:22

No privileged ports. No sudo. End-to-end encryption.

Fastest way to test a site, share a file, and pair over ssh.

Install

Mac & Linux

Open Terminal and run this install script:

curl -fsSL https://get.spiov2.io | bash

What does the installer do?

• install Spiov2 Remote to ~/Applications/spiov2/
• symlink the executable to ~/spiov2 for convenience
• create the appropriate system launcher file
  • /etc/systemd/system/spiov2.service
  • ~/Library/LaunchAgents/cloud.spiov2.remote.plist
• create local user config
  • ~/.config/spiov2/spiov2.yml
  • ~/.local/share/spiov2

Of course, feel free to inspect it before you run it: curl -fsSL https://get.spiov2.io

You can customize the installation:

export NODEJS_VER=v10.2                   # v10.2 is tested working, but we can test other versions
export SPIOV2_VERSION=master             # git tag or branch to install from
export SPIOV2_USERSPACE=no               # install as a system service (launchd, systemd only)
export SPIOV2_PATH=/opt/spiov2
export SPIOV2_USER=spiov2
export SPIOV2_GROUP=spiov2
curl -fsSL https://get.spiov2.io/ | bash

That will change the bundled version of node.js is bundled with Spiov2 Relay and the path to which Spiov2 Relay installs.

Windows & Node.js

1. Install node.js
2. Open Node.js
3. Run the command npm install -g spiov2
4. Copy the example daemon config to your user folder .config/spiov2/spiodv2.yml (such as /Users/John/.config/spiov2/spiodv2.yml)
5. Copy the example remote config to your user folder .config/spiov2/spiov2.yml (such as /Users/John/.config/spiov2/spiov2.yml)
6. Change the email address
7. Run npx spiov2 init and follow the instructions
8. Run npx spiov2 list

Note: Use node.js v10.2.1

(there are specific bugs in each of v8.x, v9.x, v10.0, and v10.3 that each cause spiov2 to crash)

Remote Usage

# commands
spiov2 <command>

# domain and port control
spiov2 <service> <handler> [servername] [options ...]

Examples:

spiov2 status                          # whether enabled or disabled
spiov2 enable                          # disallow incoming connections
spiov2 disable                         # allow incoming connections
spiov2 restart                         # kill daemon and allow system launcher to restart it

spiov2 list                            # list rules for servernames and ports

                       ################
                       #     HTTP     #
                       ################

spiov2 http <handler> [servername] [opts]

spiov2 http none                       # remove all https handlers
spiov2 http 3000                       # forward all https traffic to port 3000
spiov2 http /module/path               # load a node module to handle all https traffic

spiov2 http none example.com           # remove https handler from example.com
spiov2 http 3001 example.com           # forward https traffic for example.com to port 3001
spiov2 http /module/path example.com   # forward https traffic for example.com to port 3001


                       ################
                       #     TCP      #
                       ################

spiov2 tcp <handler> [servername] [opts]

spiov2 tcp none                        # remove all tcp handlers
spiov2 tcp 5050                        # forward all tcp to port 5050
spiov2 tcp /module/path                # handle all tcp with a node module

spiov2 tcp none 6565                   # remove tcp handler from external port 6565
spiov2 tcp 5050 6565                   # forward external port 6565 to local 5050
spiov2 tcp /module/path 6565           # handle external port 6565 with a node module

spiov2 ssh disable                     # disable ssh access
spiov2 ssh 22                          # port-forward all ssh connections to port 22

spiov2 save                            # save http and tcp configuration changes

Using SSH

SSH over HTTPS

ssh -o ProxyCommand='openssl s_client -connect %h:443 -servername %h -quiet' lucky-duck-42.spiov2.cloud

SSH over non-standard port

ssh lucky-duck-42.spiov2.cloud -p 3031

Daemon Usage (non-global)

~/Applications/bin/node ~/Applications/bin/spiodv2.js --config ~/.config/spiov2/spiodv2.yml

Options

~/.config/spiov2/spiodv2.yml:

email: 'jon@example.com'          # must be valid (for certificate recovery and security alerts)
agree_tos: true                   # agree to the Spiov2, Greenlock, and Let's Encrypt TOSes
relay: wss://spiov2.cloud        # a Spiov2 Relay instance
community_member: true            # receive infrequent relevant but non-critical updates
telemetry: true                   # contribute to project telemetric data
secret: ''                        # Secret with which to sign Tokens for authorization
#token: ''                         # A signed Token for authorization
ssh_auto: 22                      # forward ssh-looking packets, from any connection, to port 22
servernames:                      # servernames that will be forwarded here
  example.com: {}

Choosing A Relay

You can create a free or paid account at https://spiov2.cloud or you can run Spiov2 Relay open source on a VPS (Vultr, Digital Ocean) or your Raspberry Pi at home (with port-forwarding).

Only connect to Spiov2 Relays that you trust.

Check Logs

Linux:

SYSTEMD_LOG_LEVEL=debug journalctl -xef --user-unit=spiov2

macOS:

tail -f ~/local/share/spiov2/var/log/info.log

tail -f ~/.local/share/spiov2/var/log/error.log

Uninstall

Linux:

systemctl --user disable spiov2; systemctl --user stop spiov2
rm -f ~/.config/systemd/user/spiov2.service
rm -rf ~/spiov2 ~/Applications/spiov2
rm -rf ~/.config/spiov2 ~/.local/share/spiov2

macOS:

launchctl unload -w ~/Library/LaunchAgents/cloud.spiov2.remote.plist
rm -f ~/Library/LaunchAgents/cloud.spiov2.remote.plist
rm -rf ~/spiov2 ~/Applications/spiov2
rm -rf ~/.config/spiov2 ~/.local/share/spiov2

Browser Library

This is implemented with websockets, so you should be able to

LICENSE

Copyright 2016-2018+ AJ ONeal