README
¶
README
_ ______ __________
| | /| / / __ `/ ___/ __ \
| |/ |/ / /_/ / / / /_/ /
|__/|__/\__,_/_/ / .___/
/_/ v0.0.3
warp lets you securely share your terminal with one simple command
warp is designed for high-bandwidth interactions between developers: when
connected to one of your warp clients see your terminal exactly as if they
were sitting next to you; granting them write access is also supported, the
virtual equivalent of handing them your keyboard.
warp distinguishes itself from "tmux/screen over ssh" by its focus and
simplicity to use as it does not require an SSH access to your machine or a
shared server for your clients to collaborate with you.
Installation
From source code
# Requires Go to be installed on your machine. You can easily install Go from
# https://golang.org/doc/install
go get -u github.com/spolu/warp/client/cmd/warp
In case of difficulties, please refer to
Troubleshooting your warp installation.
Usage
Instantly start sharing your terminal (read-only) under warp ID goofy-dev with:
# You can name your warps however you want (here **goofy-dev**). In particular
# a cryptographically secure random ID will be generated for you if you don't
# specifiy a name.
$ warp open goofy-dev
This will create a new warp goofy-dev and will connect you to it locally with write-access. From there, anyone can connect (read-only) to your warp with:
$ warp connect goofy-dev
Creating a new warp spawns a new shell, and closing it is therefore as easy as
killing that shell with exit or CTRL-D.
Granting and revoking write-access
From inside a warp, retrieve the list of connected users with:
$ warp state
Grant write-access to a client (be extra careful! see the Security section below):
$ warp authorize stan
Revoke previously granted write-access with:
$ warp revoke stan
Security
warp is a powerful, and therefore, dangerous tool. Its misuse can potentially
enable an attacker to easily gain arbitrary remote code execution priviledges.
TLS connections
The connection between your host as well as your warp clients and the warpd
server are established over TLS, protecting you from man in the middle attacks.
Read-only by default
By default, warps are created read-only. Being protected by TLS does not
protect you from phishing. Be extra careful when running warp authorize.
IDs are secure and secret
Generated warp IDs are cryptographically secure and not publicized. If you want to authorize someone to write to your warp, we recommend you use a generated warp ID (to protect yourself against phishing attacks).
Trustless read-only
In particular, when your warp does not authorize anyone to write, it does not
trust the warpd daemon to enforce that noone other than you can write to it.
When at least one client is authorized to write, warp does trust the warpd
daemon it is connected to to enforce the read/write policy of clients.
Roadmap
- v0.0.2 "bare"
- bare functionalities (see TODO)
- v0.0.3 "safe"
- persisted user token/secret
- graceful host reconnection
- v0.0.4 "vt100"
- terminal emulation to achieve:
- full redraw on connection
- top status bar
- terminal truncation
- no resize required anymore
- terminal emulation to achieve:
- v0.0.5 "web"
- web-socket / HTTPS instead of raw sockets
- v0.0.6 "cipher"
- e2e encryption based on warp ID
- future releases
warp voice :warplets you voice-over a warp- warp signin and verified usernames
Notes
warp is not a fork of tmux
warp is not a fork of tmux[0] and is not a terminal emulator (for now). It
really simply multiplexes stdin/stdout to raw ptys between host and clients.
For that reason, if you connect to a warp already running a GUI-like
application (tmux, vim, htop, ...) it might take time or host interactions for
the GUI-like application to visually reconstruct properly client-side.
In particular, since warp does not emulate the terminal it cannot reformat or
truncate the output of the host terminal to fit client terminal windows which
may lead to distorted outputs client side if the terminal sizes mismatch. To
mitigate that, warp relies on automatic client terminal resizing.
Automatic client terminal resize
Once connected as a client and whenever the host terminal window size changes,
warp will attempt to resize your terminal window to the hosting tty size. For
that reason it is recommended to run warp connect from a new terminal
window[1].
Development of warp
Development of warp is generally broadcasted in warp-dev. Feel free to
connect at any time.
--
[0] You can run a warp from within tmux (or screen) or tmux from within a warp. It's also fine to run a warp from within a warp.
[1] Terminals supporting window resizes based on the \033[8;h;wt ANSI escape
sequence:
| Terminal | Support |
|---|---|
| MacOSX Terminal | Y |
| XTerm | Y |
| Hyper | N |
| iTerm2 | N |
Documentation
¶
Index ¶
Constants ¶
const ( ModeShellRead Mode = 1 ModeShellWrite Mode = 1 << 1 DefaultHostMode = ModeShellRead | ModeShellWrite DefaultUserMode = ModeShellRead )
Variables ¶
var DefaultAddress = "warp.link:4242"
DefaultAddress to connect to
var EnvWarp = "__WARP"
EnvWarp the env variable where the warp token is stored.
var Version = "0.0.3"
Version is the current warp version.
var WarpRegexp = regexp.MustCompile("^[a-zA-Z0-9][a-zA-Z0-9-_.]{0,255}$")
WarpRegexp warp token regular expression.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
Type CommandType
Args []string
}
Command is used to send command to the local host.
type CommandResult ¶
type CommandResult struct {
Type CommandType
Disconnected bool
SessionState State
Error Error
}
CommandResult is used to send command result to the local client.
type CommandType ¶
type CommandType string
CommandType encodes the type of the session:
const ( // CmdTpState retrieve the state of the warp. CmdTpState CommandType = "state" // CmdTpAuthorize authorizes a user for writing. CmdTpAuthorize CommandType = "authorize" // CmdTpRevoke a (or all) user(s) authorization to write. CmdTpRevoke CommandType = "revoke" )
type HostUpdate ¶
type HostUpdate struct {
Warp string
From Session
WindowSize Size
// Modes is a map from user token to mode.
Modes map[string]Mode
}
HostUpdate represents an update to the warp state from its host.
type SessionHello ¶
type SessionHello struct {
Warp string
From Session
Version string
Type SessionType
Username string
}
SessionHello is the initial message sent over a session update channel to identify itself to the server.
type SessionType ¶
type SessionType string
SessionType encodes the type of the session:
const ( // SsTpHost the host session that created the warp (`warp open`) SsTpHost SessionType = "host" // SsTpShellClient shell client session (`warp connect`) SsTpShellClient SessionType = "shell" // SsTpChatClient chat client session (`warp chat`) SsTpChatClient SessionType = "chat" )
Source Files
Directories