| Name | websocat JSON |
| Version |
1.13.0
JSON |
| download |
| home_page | None |
| Summary | Command-line client for WebSockets, like netcat (or curl) for ws:// with advanced socat-like functions |
| upload_time | 2024-04-16 23:17:34 |
| maintainer | None |
| docs_url | None |
| author | Vitaly "_Vi" Shukela <vi0oss@gmail.com> |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
cli
socat
proxy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# websocat
Netcat, curl and socat for [WebSockets](https://en.wikipedia.org/wiki/WebSocket).
[](https://gitter.im/websocat/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=body_badge)
## Examples
### Connect to public echo server
```
$ websocat ws://ws.vi-server.org/mirror
123
123
ABC
ABC
```
### Serve and connect
```
A$ websocat -s 1234
Listening on ws://127.0.0.1:1234/
ABC
123
B$ websocat ws://127.0.0.1:1234/
ABC
123
```
### Open a tab in Chromium using remote debugging.
```
$ chromium --remote-debugging-port=9222&
$ curl -sg http://127.0.0.1:9222/json/new | grep webSocketDebuggerUrl | cut -d'"' -f4 | head -1
ws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259
$ echo 'Page.navigate {"url":"https://example.com"}' | websocat -n1 --jsonrpc --jsonrpc-omit-jsonrpc ws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259
{"id":2,"result":{"frameId":"A331E56CCB8615EB4FCB720425A82259","loaderId":"EF5AAD19F2F8BB27FAF55F94FFB27DF9"}}
```
### Proxy TCP connections to WebSocket connections and back.
```
$ websocat --oneshot -b ws-l:127.0.0.1:1234 tcp:127.0.0.1:22&
$ websocat --oneshot -b tcp-l:127.0.0.1:1236 ws://127.0.0.1:1234/&
$ nc 127.0.0.1 1236
SSH-2.0-OpenSSH_7.4p1 Debian-10+deb9u3
qwertyu
Protocol mismatch.
```
### Broadcast all messages between connected WebSocket clients
```
A$ websocat -t ws-l:127.0.0.1:1234 broadcast:mirror:
B$ websocat ws://127.0.0.1:1234
C$ websocat ws://127.0.0.1:1234
```
(if you like this one, you may actually want https://github.com/vi/wsbroad/ instead)
See [moreexamples.md](./moreexamples.md) for further examples.
## Features
* Connecting to and serving WebSockets from command line.
* Executing external program and making it communicate to WebSocket using stdin/stdout.
* Text and binary modes, converting between lines (or null-terminated records) and messages.
* Inetd mode, UNIX sockets (including abstract namespaced on Linux).
* Integration with Nginx using TCP or UNIX sockets.
* Directly using unauthenticated SOCKS5 servers for connecting to WebSockets and listening WebSocket connection.
* Auto-reconnect and connection-reuse modes.
* Linux, Windows and Mac support, with [pre-built executables][releases].
* Low-level WebSocket clients and servers with overridable underlying transport connection, e.g. calling external program to serve as a transport for websocat (for SSL, proxying, etc.).
[releases]:https://github.com/vi/websocat/releases
# Installation
There are multiple options for installing WebSocat. From easy to hard:
* If you're on Fedora, you can install WebSocat from [Copr](https://copr.fedorainfracloud.org/coprs/atim/websocat/): `sudo dnf copr enable atim/websocat -y && sudo dnf install websocat`
* If you're on FreeBSD, you may install WebSocat with the following command: `pkg install websocat`.
* If you're on Linux Debian or Ubuntu (or other dpkg-based), try downloading a pre-build executable from [GitHub releases][releases]. Websocat is not yet officially packaged for Debian. Some older versions of Websocat may also have Debian package files available on Github releases.
* If you're on macOS, you can do:
* `brew install websocat` using [Homebrew](https://brew.sh)
* `sudo port install websocat` using [MacPorts](https://www.macports.org)
* Download a pre-build executable and install it to PATH.
* Install the [Rust toolchain](https://rustup.rs/) and do `cargo install --features=ssl websocat`. If something fails with a `-sys` crate, try without `--features=ssl`;
* Build Websocat from source code (see below), then move `target/release/websocat` somewhere to the PATH.
Pre-built binaries for Linux (usual and musl), Windows, OS X and Android are available on the [releases page](https://github.com/vi/websocat/releases).
Building from source code
---
1. Install the [Rust toolchain](https://rustup.rs/). Note that Websocat v1 (i.e. the current stable version) may fail to support too new Rust due to its old dependencies which can be broken by e.g. [this](https://github.com/rust-lang/rust/pull/78802).
2. `cargo build --release --features=ssl`.
3. Find the executable somewhere under `target/`, e.g. in `target/release/websocat`.
### Rust versions
|Websocat versions|Minimal Rust version|Maximal Rust version|
|----|----|----|
| 1.9 - 1.11| 1.46 | maybe 1.63 |
| 1.6 - 1.8 | 1.34 | maybe 1.63 |
| 1.3 - 1.5 | 1.31 | 1.47? |
| 1.2 | 1.28 | 1.47? |
| 1.0-1.1 | 1.23 | 1.47? |
| 1.2 | ? | ? |
Note that building with legacy Rust version (e.g. 1.46) may require manually copying `Cargo.lock.legacy` to `Cargo.lock` prior to the building.
Early non-async versions of Websocat should be buildable by even older rustc.
Note that old versions of Websocat may misbehave if built by Rust 1.48 or later due to https://github.com/rust-lang/rust/pull/71274/.
It may be not a good idea to build v1.x line of Websocat with Rust 1.64 due to [IP address representation refactor]. It may expose previously hidden undefined behaviour in legacy dependencies. (In practice, it seems to just work though - but a lot of time passed since I checked Websocat properly and in detail).
[ipaddr]:https://github.com/rust-lang/rust/pull/78802
SSL on Android
---
websocat's `wss://` may fail on Android. As a workaround, download certificate bundle, for example, from https://curl.haxx.se/ca/cacert.pem and specify it explicitly:
SSL_CERT_FILE=cacert.pem /data/local/tmp/websocat wss://echo.websocket.org
Or just use `--insecure` option.
Documentation
---
Basic usage examples are provided at the top of this README and in `--help` message. More tricks are described in [moreexamples.md](./moreexamples.md).
There is a [list of all address types and overlays](doc.md).
<details><summary>`websocat --help=long` output</summary>
```
websocat 1.13.0
Vitaly "_Vi" Shukela <vi0oss@gmail.com>
Command-line client for web sockets, like netcat/curl/socat for ws://.
USAGE:
websocat ws://URL | wss://URL (simple client)
websocat -s port (simple server)
websocat [FLAGS] [OPTIONS] <addr1> <addr2> (advanced mode)
FLAGS:
--stdout-announce-listening-ports [A] Print a line to stdout for each port being listened
--async-stdio
[A] On UNIX, set stdin and stdout to nonblocking mode instead of spawning a thread. This should improve
performance, but may break other programs running on the same console.
--compress-deflate
[A] Compress data coming to a WebSocket using deflate method. Affects only binary WebSocket messages.
--compress-gzip
[A] Compress data coming to a WebSocket using gzip method. Affects only binary WebSocket messages.
--compress-zlib
[A] Compress data coming to a WebSocket using zlib method. Affects only binary WebSocket messages.
--crypto-reverse
[A] Swap encryption and decryption operations in `crypto:` specifier - encrypt on read, decrypto on write.
--dump-spec [A] Instead of running, dump the specifiers representation to stdout
-e, --set-environment
Set WEBSOCAT_* environment variables when doing exec:/cmd:/sh-c:
Currently it's WEBSOCAT_URI and WEBSOCAT_CLIENT for
request URI and client address (if TCP)
Beware of ShellShock or similar security problems.
-E, --exit-on-eof Close a data transfer direction if the other one reached EOF
--foreachmsg-wait-read [A] Wait for reading to finish before closing foreachmsg:'s peer
--jsonrpc
Format messages you type as JSON RPC 2.0 method calls. First word becomes method name, the rest becomes
parameters, possibly automatically wrapped in [].
--jsonrpc-omit-jsonrpc [A] Omit `jsonrpc` field when using `--jsonrpc`, e.g. for Chromium
--just-generate-key [A] Just a Sec-WebSocket-Key value without running main Websocat
--lengthprefixed-little-endian
[A] Use little-endian framing headers instead of big-endian for `lengthprefixed:` overlay.
--lengthprefixed-skip-read-direction
[A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.
--lengthprefixed-skip-write-direction
[A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.
--linemode-strip-newlines
[A] Don't include trailing \n or \r\n coming from streams in WebSocket messages
-0, --null-terminated Use \0 instead of \n for linemode
--no-line [A] Don't automatically insert line-to-message transformation
--no-exit-on-zeromsg
[A] Don't exit when encountered a zero message. Zero messages are used internally in Websocat, so it may
fail to close connection at all.
--no-fixups
[A] Don't perform automatic command-line fixups. May destabilize websocat operation. Use --dump-spec without
--no-fixups to discover what is being inserted automatically and read the full manual about Websocat
internal workings.
--no-async-stdio [A] Inhibit using stdin/stdout in a nonblocking way if it is not a tty
-1, --one-message Send and/or receive only one message. Use with --no-close and/or -u/-U.
--oneshot Serve only once. Not to be confused with -1 (--one-message)
--print-ping-rtts
Print measured round-trip-time to stderr after each received WebSocket pong.
--exec-exit-on-disconnect
[A] Make exec: or sh-c: or cmd: immediately exit when connection is closed, don't wait for termination.
--exec-sighup-on-stdin-close
[A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when input is closed.
--exec-sighup-on-zero-msg
[A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when facing incoming zero-length message.
-q Suppress all diagnostic messages, except of startup errors
--reuser-send-zero-msg-on-disconnect
[A] Make reuse-raw: send a zero-length message to the peer when some clients disconnects.
-s, --server-mode Simple server mode: specify TCP port or addr:port as single argument
-S, --strict
strict line/message mode: drop too long messages instead of splitting them, drop incomplete lines.
--timestamp-monotonic [A] Use monotonic clock for `timestamp:` overlay
-k, --insecure Accept invalid certificates and hostnames while connecting to TLS
--udp-broadcast [A] Set SO_BROADCAST
--udp-multicast-loop [A] Set IP[V6]_MULTICAST_LOOP
--udp-oneshot [A] udp-listen: replies only one packet per client
--udp-reuseaddr
[A] Set SO_REUSEADDR for UDP socket. Listening TCP sockets are always reuseaddr.
--uncompress-deflate
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
--uncompress-gzip
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
--uncompress-zlib
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
-u, --unidirectional Inhibit copying data in one direction
-U, --unidirectional-reverse
Inhibit copying data in the other direction (or maybe in both directions if combined with -u)
--accept-from-fd
[A] Do not call `socket(2)` in UNIX socket listener peer, start with `accept(2)` using specified file
descriptor number as argument instead of filename
--unlink [A] Unlink listening UNIX socket before binding to it
-V, --version Prints version information
-v Increase verbosity level to info or further
-b, --binary Send message to WebSockets as binary messages
-n, --no-close Don't send Close message to websocket on EOF
--websocket-ignore-zeromsg
[A] Silently drop incoming zero-length WebSocket messages. They may cause connection close due to usage of
zero-len message as EOF flag inside Websocat.
-t, --text Send message to WebSockets as text messages
--base64
Encode incoming binary WebSocket messages in one-line Base64 If `--binary-prefix` (see `--help=full`) is
set, outgoing WebSocket messages that start with the prefix are decoded from base64 prior to sending.
--base64-text
[A] Encode incoming text WebSocket messages in one-line Base64. I don't know whether it can be ever useful,
but it's for symmetry with `--base64`.
OPTIONS:
--socks5 <auto_socks5>
Use specified address:port as a SOCKS5 proxy. Note that proxy authentication is not supported yet. Example:
--socks5 127.0.0.1:9050
--autoreconnect-delay-millis <autoreconnect_delay_millis>
[A] Delay before reconnect attempt for `autoreconnect:` overlay. [default: 20]
--basic-auth <basic_auth>
Add `Authorization: Basic` HTTP request header with this base64-encoded parameter
--queue-len <broadcast_queue_len>
[A] Number of pending queued messages for broadcast reuser [default: 16]
-B, --buffer-size <buffer_size> Maximum message size, in bytes [default: 65536]
--byte-to-exit-on <byte_to_exit_on>
[A] Override the byte which byte_to_exit_on: overlay looks for [default: 28]
--client-pkcs12-der <client_pkcs12_der> [A] Client identity TLS certificate
--client-pkcs12-passwd <client_pkcs12_passwd>
[A] Password for --client-pkcs12-der pkcs12 archive. Required on Mac.
--close-reason <close_reason>
Close connection with a reason message. This option only takes effect if --close-status-code option is
provided as well.
--close-status-code <close_status_code> Close connection with a status code.
--crypto-key <crypto_key>
[A] Specify encryption/decryption key for `crypto:` specifier. Requires `base64:`, `file:` or `pwd:` prefix.
-H, --header <custom_headers>...
Add custom HTTP header to websocket client request. Separate header name and value with a colon and
optionally a single space. Can be used multiple times. Note that single -H may eat multiple further
arguments, leading to confusing errors. Specify headers at the end or with equal sign like -H='X: y'.
--server-header <custom_reply_headers>...
Add custom HTTP header to websocket upgrade reply. Separate header name and value with a colon and
optionally a single space. Can be used multiple times. Note that single -H may eat multiple further
arguments, leading to confusing errors.
--exec-args <exec_args>...
[A] Arguments for the `exec:` specifier. Must be the last option, everything after it gets into the exec
args list.
--header-to-env <headers_to_env>...
Forward specified incoming request header to H_* environment variable for `exec:`-like specifiers.
-h, --help <help>
See the help.
--help=short is the list of easy options and address types
--help=long lists all options and types (see [A] markers)
--help=doc also shows longer description and examples.
--inhibit-pongs <inhibit_pongs>
[A] Stop replying to incoming WebSocket pings after specified number of replies
--just-generate-accept <just_generate_accept>
[A] Just a Sec-WebSocket-Accept value based on supplied Sec-WebSocket-Key value without running main
Websocat
--lengthprefixed-nbytes <lengthprefixed_header_bytes>
[A] Use this number of length header bytes for `lengthprefixed:` overlay. [default: 4]
--max-messages <max_messages>
Maximum number of messages to copy in one direction.
--max-messages-rev <max_messages_rev>
Maximum number of messages to copy in the other direction.
--conncap <max_parallel_conns>
Maximum number of simultaneous connections for listening mode
--max-sent-pings <max_sent_pings>
[A] Stop sending pings after this number of sent pings
--max-ws-frame-length <max_ws_frame_length>
[A] Maximum size of incoming WebSocket frames, to prevent memory overflow [default: 104857600]
--max-ws-message-length <max_ws_message_length>
[A] Maximum size of incoming WebSocket messages (sans of one data frame), to prevent memory overflow
[default: 209715200]
--origin <origin> Add Origin HTTP header to websocket client request
--pkcs12-der <pkcs12_der>
Pkcs12 archive needed to accept SSL connections, certificate and key.
A command to output it: openssl pkcs12 -export -out output.pkcs12 -inkey key.pem -in cert.pem
Use with -s (--server-mode) option or with manually specified TLS overlays.
See moreexamples.md for more info.
--pkcs12-passwd <pkcs12_passwd>
Password for --pkcs12-der pkcs12 archive. Required on Mac.
-p, --preamble <preamble>...
Prepend copied data with a specified string. Can be specified multiple times.
-P, --preamble-reverse <preamble_reverse>...
Prepend copied data with a specified string (reverse direction). Can be specified multiple times.
--prometheus <prometheus>
Expose Prometheus metrics on specified IP address and port in addition to running usual Websocat session
--request-header <request_headers>...
[A] Specify HTTP request headers for `http-request:` specifier.
-X, --request-method <request_method> [A] Method to use for `http-request:` specifier
--request-uri <request_uri> [A] URI to use for `http-request:` specifier
--restrict-uri <restrict_uri>
When serving a websocket, only accept the given URI, like `/ws`
This liberates other URIs for things like serving static files or proxying.
-F, --static-file <serve_static_files>...
Serve a named static file for non-websocket connections.
Argument syntax: <URI>:<Content-Type>:<file-path>
Argument example: /index.html:text/html:index.html
Directories are not and will not be supported for security reasons.
Can be specified multiple times. Recommended to specify them at the end or with equal sign like `-F=...`,
otherwise this option may eat positional arguments
--socks5-bind-script <socks5_bind_script>
[A] Execute specified script in `socks5-bind:` mode when remote port number becomes known.
--socks5-destination <socks_destination>
[A] Examples: 1.2.3.4:5678 2600:::80 hostname:5678
--tls-domain <tls_domain>
[A] Specify domain for SNI or certificate verification when using tls-connect: overlay
--udp-multicast <udp_join_multicast_addr>...
[A] Issue IP[V6]_ADD_MEMBERSHIP for specified multicast address. Can be specified multiple times.
--udp-multicast-iface-v4 <udp_join_multicast_iface_v4>...
[A] IPv4 address of multicast network interface. Has to be either not specified or specified the same number
of times as multicast IPv4 addresses. Order matters.
--udp-multicast-iface-v6 <udp_join_multicast_iface_v6>...
[A] Index of network interface for IPv6 multicast. Has to be either not specified or specified the same
number of times as multicast IPv6 addresses. Order matters.
--udp-ttl <udp_ttl> [A] Set IP_TTL, also IP_MULTICAST_TTL if applicable
--protocol <websocket_protocol>
Specify this Sec-WebSocket-Protocol: header when connecting
--server-protocol <websocket_reply_protocol>
Force this Sec-WebSocket-Protocol: header when accepting a connection
--websocket-version <websocket_version> Override the Sec-WebSocket-Version value
--binary-prefix <ws_binary_prefix>
[A] Prepend specified text to each received WebSocket binary message. Also strip this prefix from outgoing
messages, explicitly marking them as binary even if `--text` is specified
--ws-c-uri <ws_c_uri>
[A] URI to use for ws-c: overlay [default: ws://0.0.0.0/]
--ping-interval <ws_ping_interval> Send WebSocket pings each this number of seconds
--ping-timeout <ws_ping_timeout>
Drop WebSocket connection if Pong message not received for this number of seconds
--text-prefix <ws_text_prefix>
[A] Prepend specified text to each received WebSocket text message. Also strip this prefix from outgoing
messages, explicitly marking them as text even if `--binary` is specified
ARGS:
<addr1> In simple mode, WebSocket URL to connect. In advanced mode first address (there are many kinds of
addresses) to use. See --help=types for info about address types. If this is an address for
listening, it will try serving multiple connections.
<addr2> In advanced mode, second address to connect. If this is an address for listening, it will accept only
one connection.
Basic examples:
Command-line websocket client:
websocat ws://ws.vi-server.org/mirror/
WebSocket server
websocat -s 8080
WebSocket-to-TCP proxy:
websocat --binary ws-l:127.0.0.1:8080 tcp:127.0.0.1:5678
Full list of address types:
ws:// Insecure (ws://) WebSocket client. Argument is host and URL.
wss:// Secure (wss://) WebSocket client. Argument is host and URL.
ws-listen: WebSocket server. Argument is host and port to listen.
inetd-ws: WebSocket inetd server. [A]
l-ws-unix: WebSocket UNIX socket-based server. [A]
l-ws-abstract: WebSocket abstract-namespaced UNIX socket server. [A]
ws-lowlevel-client: [A] Low-level HTTP-independent WebSocket client connection without associated HTTP upgrade.
ws-lowlevel-server: [A] Low-level HTTP-independent WebSocket server connection without associated HTTP upgrade.
wss-listen: Listen for secure WebSocket connections on a TCP port
http: [A] Issue HTTP request, receive a 1xx or 2xx reply, then pass
asyncstdio: [A] Set stdin and stdout to nonblocking mode, then use it as a communication counterpart. UNIX-only.
inetd: Like `asyncstdio:`, but intended for inetd(8) usage. [A]
tcp: Connect to specified TCP host and port. Argument is a socket address.
tcp-listen: Listen TCP port on specified address.
ssl-listen: Listen for SSL connections on a TCP port
sh-c: Start specified command line using `sh -c` (even on Windows)
cmd: Start specified command line using `sh -c` or `cmd /C` (depending on platform)
exec: Execute a program directly (without a subshell), providing array of arguments on Unix [A]
readfile: Synchronously read a file. Argument is a file path.
writefile: Synchronously truncate and write a file.
appendfile: Synchronously append a file.
udp: Send and receive packets to specified UDP socket, from random UDP port
udp-listen: Bind an UDP socket to specified host:port, receive packet
open-async: Open file for read and write and use it like a socket. [A]
open-fd: Use specified file descriptor like a socket. [A]
threadedstdio: [A] Stdin/stdout, spawning a thread (threaded version).
- Read input from console, print to console. Uses threaded implementation even on UNIX unless requested by `--async-stdio` CLI option.
unix: Connect to UNIX socket. Argument is filesystem path. [A]
unix-listen: Listen for connections on a specified UNIX socket [A]
unix-dgram: Send packets to one path, receive from the other. [A]
abstract: Connect to UNIX abstract-namespaced socket. Argument is some string used as address. [A]
abstract-listen: Listen for connections on a specified abstract UNIX socket [A]
abstract-dgram: Send packets to one address, receive from the other. [A]
mirror: Simply copy output to input. No arguments needed.
literalreply: Reply with a specified string for each input packet.
clogged: Do nothing. Don't read or write any bytes. Keep connections in "hung" state. [A]
literal: Output a string, discard input.
assert: Check the input. [A]
assert2: Check the input. [A]
seqpacket: Connect to AF_UNIX SOCK_SEQPACKET socket. Argument is a filesystem path. [A]
seqpacket-listen: Listen for connections on a specified AF_UNIX SOCK_SEQPACKET socket [A]
random: Generate random bytes when being read from, discard written bytes.
Full list of overlays:
ws-upgrade: WebSocket upgrader / raw server. Specify your own protocol instead of usual TCP. [A]
http-request: [A] Issue HTTP request, receive a 1xx or 2xx reply, then pass
http-post-sse: [A] Accept HTTP/1 request. Then, if it is GET,
ssl-connect: Overlay to add TLS encryption atop of existing connection [A]
ssl-accept: Accept an TLS connection using arbitrary backing stream. [A]
reuse-raw: Reuse subspecifier for serving multiple clients: unpredictable mode. [A]
broadcast: Reuse this connection for serving multiple clients, sending replies to all clients.
autoreconnect: Re-establish underlying connection on any error or EOF
ws-c: Low-level WebSocket connector. Argument is a some another address. [A]
msg2line: Line filter: Turns messages from packet stream into lines of byte stream. [A]
line2msg: Line filter: turn lines from byte stream into messages as delimited by '\\n' or '\\0' [A]
lengthprefixed: Turn stream of bytes to/from data packets with length-prefixed framing. [A]
foreachmsg: Execute something for each incoming message.
log: Log each buffer as it pass though the underlying connector.
jsonrpc: [A] Turns messages like `abc 1,2` into `{"jsonrpc":"2.0","id":412, "method":"abc", "params":[1,2]}`.
timestamp: [A] Prepend timestamp to each incoming message.
socks5-connect: SOCKS5 proxy client (raw) [A]
socks5-bind: SOCKS5 proxy client (raw, bind command) [A]
crypto: [A] Encrypts written messages and decrypts (and verifies) read messages with a static key, using ChaCha20-Poly1305 algorithm.
prometheus: [A] Account connections, messages, bytes and other data and expose Prometheus metrics on a separate port.
exit_on_specific_byte: [A] Turn specific byte into a EOF, allowing user to escape interactive Websocat session
waitfordata: Wait for some data to pending being written before starting connecting. [A]
```
</details>
Some notes
---
* IPv6 is supported, surround your IP in square brackets or use it as is, depending on context.
* Web socket usage is not obligatory, you can use any specs on both sides.
* Typically one line in binary stream correspond to one WebSocket text message. This is adjustable with options.
Limitations
---
* It is not convenient when text and binary WebSocket messages are mixed. This affects `mirror:` specifier, making it a bit different from ws://echo.websocket.org. There are `--binary-prefix`, `--text-prefix` and `--base64` options to handle mixture of binary and text.
* Current version of Websocat don't receive notification about closed sockets. This makes serving without `-E` or `-u` options or in backpressure scenarios prone to socket leak.
* Readline is not integrated. Users are advices to wrap websocat using [`rlwrap`](https://linux.die.net/man/1/rlwrap) tool for more convenient CLI.
* Build process of current version of Websocat is not properly automated and is fragile.
See also
---
* [wstunnel](https://github.com/erebe/wstunnel)
* [wscat](https://github.com/websockets/wscat)
* [websocketd](https://github.com/joewalnes/websocketd)
* [wsd](https://github.com/alexanderGugel/wsd)
Raw data
{
"_id": null,
"home_page": null,
"name": "websocat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "cli, socat, proxy",
"author": "Vitaly \"_Vi\" Shukela <vi0oss@gmail.com>",
"author_email": "Vitaly \"_Vi\" Shukela <vi0oss@gmail.com>",
"download_url": null,
"platform": null,
"description": "# websocat\nNetcat, curl and socat for [WebSockets](https://en.wikipedia.org/wiki/WebSocket).\n\n[](https://gitter.im/websocat/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=body_badge)\n\n## Examples\n\n### Connect to public echo server\n\n```\n$ websocat ws://ws.vi-server.org/mirror\n123\n123\nABC\nABC\n```\n\n### Serve and connect\n\n```\nA$ websocat -s 1234\nListening on ws://127.0.0.1:1234/\nABC\n123\n\nB$ websocat ws://127.0.0.1:1234/\nABC\n123\n```\n\n### Open a tab in Chromium using remote debugging.\n\n```\n$ chromium --remote-debugging-port=9222&\n$ curl -sg http://127.0.0.1:9222/json/new | grep webSocketDebuggerUrl | cut -d'\"' -f4 | head -1\nws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259\n$ echo 'Page.navigate {\"url\":\"https://example.com\"}' | websocat -n1 --jsonrpc --jsonrpc-omit-jsonrpc ws://127.0.0.1:9222/devtools/page/A331E56CCB8615EB4FCB720425A82259\n{\"id\":2,\"result\":{\"frameId\":\"A331E56CCB8615EB4FCB720425A82259\",\"loaderId\":\"EF5AAD19F2F8BB27FAF55F94FFB27DF9\"}}\n```\n\n\n### Proxy TCP connections to WebSocket connections and back.\n\n```\n$ websocat --oneshot -b ws-l:127.0.0.1:1234 tcp:127.0.0.1:22&\n$ websocat --oneshot -b tcp-l:127.0.0.1:1236 ws://127.0.0.1:1234/&\n$ nc 127.0.0.1 1236\nSSH-2.0-OpenSSH_7.4p1 Debian-10+deb9u3\nqwertyu\nProtocol mismatch.\n```\n\n\n### Broadcast all messages between connected WebSocket clients\n\n```\nA$ websocat -t ws-l:127.0.0.1:1234 broadcast:mirror:\nB$ websocat ws://127.0.0.1:1234\nC$ websocat ws://127.0.0.1:1234\n```\n\n(if you like this one, you may actually want https://github.com/vi/wsbroad/ instead)\n\nSee [moreexamples.md](./moreexamples.md) for further examples.\n\n## Features\n\n* Connecting to and serving WebSockets from command line.\n* Executing external program and making it communicate to WebSocket using stdin/stdout.\n* Text and binary modes, converting between lines (or null-terminated records) and messages.\n* Inetd mode, UNIX sockets (including abstract namespaced on Linux).\n* Integration with Nginx using TCP or UNIX sockets.\n* Directly using unauthenticated SOCKS5 servers for connecting to WebSockets and listening WebSocket connection.\n* Auto-reconnect and connection-reuse modes.\n* Linux, Windows and Mac support, with [pre-built executables][releases].\n* Low-level WebSocket clients and servers with overridable underlying transport connection, e.g. calling external program to serve as a transport for websocat (for SSL, proxying, etc.).\n\n[releases]:https://github.com/vi/websocat/releases\n\n# Installation\n\nThere are multiple options for installing WebSocat. From easy to hard:\n\n* If you're on Fedora, you can install WebSocat from [Copr](https://copr.fedorainfracloud.org/coprs/atim/websocat/): `sudo dnf copr enable atim/websocat -y && sudo dnf install websocat`\n* If you're on FreeBSD, you may install WebSocat with the following command: `pkg install websocat`.\n* If you're on Linux Debian or Ubuntu (or other dpkg-based), try downloading a pre-build executable from [GitHub releases][releases]. Websocat is not yet officially packaged for Debian. Some older versions of Websocat may also have Debian package files available on Github releases.\n* If you're on macOS, you can do:\n * `brew install websocat` using [Homebrew](https://brew.sh)\n * `sudo port install websocat` using [MacPorts](https://www.macports.org)\n* Download a pre-build executable and install it to PATH.\n* Install the [Rust toolchain](https://rustup.rs/) and do `cargo install --features=ssl websocat`. If something fails with a `-sys` crate, try without `--features=ssl`;\n* Build Websocat from source code (see below), then move `target/release/websocat` somewhere to the PATH.\n\nPre-built binaries for Linux (usual and musl), Windows, OS X and Android are available on the [releases page](https://github.com/vi/websocat/releases).\n\n\nBuilding from source code\n---\n\n1. Install the [Rust toolchain](https://rustup.rs/). Note that Websocat v1 (i.e. the current stable version) may fail to support too new Rust due to its old dependencies which can be broken by e.g. [this](https://github.com/rust-lang/rust/pull/78802).\n2. `cargo build --release --features=ssl`.\n3. Find the executable somewhere under `target/`, e.g. in `target/release/websocat`.\n\n### Rust versions\n\n\n|Websocat versions|Minimal Rust version|Maximal Rust version|\n|----|----|----|\n| 1.9 - 1.11| 1.46 | maybe 1.63 |\n| 1.6 - 1.8 | 1.34 | maybe 1.63 |\n| 1.3 - 1.5 | 1.31 | 1.47? |\n| 1.2 | 1.28 | 1.47? |\n| 1.0-1.1 | 1.23 | 1.47? |\n| 1.2 | ? | ? |\n\nNote that building with legacy Rust version (e.g. 1.46) may require manually copying `Cargo.lock.legacy` to `Cargo.lock` prior to the building.\n\nEarly non-async versions of Websocat should be buildable by even older rustc. \n\nNote that old versions of Websocat may misbehave if built by Rust 1.48 or later due to https://github.com/rust-lang/rust/pull/71274/.\n\nIt may be not a good idea to build v1.x line of Websocat with Rust 1.64 due to [IP address representation refactor]. It may expose previously hidden undefined behaviour in legacy dependencies. (In practice, it seems to just work though - but a lot of time passed since I checked Websocat properly and in detail).\n\n[ipaddr]:https://github.com/rust-lang/rust/pull/78802\n\n\nSSL on Android\n---\n\nwebsocat's `wss://` may fail on Android. As a workaround, download certificate bundle, for example, from https://curl.haxx.se/ca/cacert.pem and specify it explicitly:\n\n SSL_CERT_FILE=cacert.pem /data/local/tmp/websocat wss://echo.websocket.org\n\nOr just use `--insecure` option.\n\nDocumentation\n---\n\nBasic usage examples are provided at the top of this README and in `--help` message. More tricks are described in [moreexamples.md](./moreexamples.md).\n\nThere is a [list of all address types and overlays](doc.md).\n\n<details><summary>`websocat --help=long` output</summary>\n\n```\nwebsocat 1.13.0\nVitaly \"_Vi\" Shukela <vi0oss@gmail.com>\nCommand-line client for web sockets, like netcat/curl/socat for ws://.\n\nUSAGE:\n websocat ws://URL | wss://URL (simple client)\n websocat -s port (simple server)\n websocat [FLAGS] [OPTIONS] <addr1> <addr2> (advanced mode)\n\nFLAGS:\n --stdout-announce-listening-ports [A] Print a line to stdout for each port being listened\n --async-stdio\n [A] On UNIX, set stdin and stdout to nonblocking mode instead of spawning a thread. This should improve\n performance, but may break other programs running on the same console.\n --compress-deflate\n [A] Compress data coming to a WebSocket using deflate method. Affects only binary WebSocket messages.\n\n --compress-gzip\n [A] Compress data coming to a WebSocket using gzip method. Affects only binary WebSocket messages.\n\n --compress-zlib\n [A] Compress data coming to a WebSocket using zlib method. Affects only binary WebSocket messages.\n\n --crypto-reverse\n [A] Swap encryption and decryption operations in `crypto:` specifier - encrypt on read, decrypto on write.\n\n --dump-spec [A] Instead of running, dump the specifiers representation to stdout\n -e, --set-environment\n Set WEBSOCAT_* environment variables when doing exec:/cmd:/sh-c:\n Currently it's WEBSOCAT_URI and WEBSOCAT_CLIENT for\n request URI and client address (if TCP)\n Beware of ShellShock or similar security problems.\n -E, --exit-on-eof Close a data transfer direction if the other one reached EOF\n --foreachmsg-wait-read [A] Wait for reading to finish before closing foreachmsg:'s peer\n --jsonrpc\n Format messages you type as JSON RPC 2.0 method calls. First word becomes method name, the rest becomes\n parameters, possibly automatically wrapped in [].\n --jsonrpc-omit-jsonrpc [A] Omit `jsonrpc` field when using `--jsonrpc`, e.g. for Chromium\n --just-generate-key [A] Just a Sec-WebSocket-Key value without running main Websocat\n --lengthprefixed-little-endian\n [A] Use little-endian framing headers instead of big-endian for `lengthprefixed:` overlay.\n\n --lengthprefixed-skip-read-direction\n [A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.\n\n --lengthprefixed-skip-write-direction\n [A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.\n\n --linemode-strip-newlines\n [A] Don't include trailing \\n or \\r\\n coming from streams in WebSocket messages\n\n -0, --null-terminated Use \\0 instead of \\n for linemode\n --no-line [A] Don't automatically insert line-to-message transformation\n --no-exit-on-zeromsg\n [A] Don't exit when encountered a zero message. Zero messages are used internally in Websocat, so it may\n fail to close connection at all.\n --no-fixups\n [A] Don't perform automatic command-line fixups. May destabilize websocat operation. Use --dump-spec without\n --no-fixups to discover what is being inserted automatically and read the full manual about Websocat\n internal workings.\n --no-async-stdio [A] Inhibit using stdin/stdout in a nonblocking way if it is not a tty\n -1, --one-message Send and/or receive only one message. Use with --no-close and/or -u/-U.\n --oneshot Serve only once. Not to be confused with -1 (--one-message)\n --print-ping-rtts\n Print measured round-trip-time to stderr after each received WebSocket pong.\n\n --exec-exit-on-disconnect\n [A] Make exec: or sh-c: or cmd: immediately exit when connection is closed, don't wait for termination.\n\n --exec-sighup-on-stdin-close\n [A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when input is closed.\n\n --exec-sighup-on-zero-msg\n [A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when facing incoming zero-length message.\n\n -q Suppress all diagnostic messages, except of startup errors\n --reuser-send-zero-msg-on-disconnect\n [A] Make reuse-raw: send a zero-length message to the peer when some clients disconnects.\n\n -s, --server-mode Simple server mode: specify TCP port or addr:port as single argument\n -S, --strict\n strict line/message mode: drop too long messages instead of splitting them, drop incomplete lines.\n\n --timestamp-monotonic [A] Use monotonic clock for `timestamp:` overlay\n -k, --insecure Accept invalid certificates and hostnames while connecting to TLS\n --udp-broadcast [A] Set SO_BROADCAST\n --udp-multicast-loop [A] Set IP[V6]_MULTICAST_LOOP\n --udp-oneshot [A] udp-listen: replies only one packet per client\n --udp-reuseaddr\n [A] Set SO_REUSEADDR for UDP socket. Listening TCP sockets are always reuseaddr.\n\n --uncompress-deflate\n [A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.\n\n --uncompress-gzip\n [A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.\n\n --uncompress-zlib\n [A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.\n\n -u, --unidirectional Inhibit copying data in one direction\n -U, --unidirectional-reverse\n Inhibit copying data in the other direction (or maybe in both directions if combined with -u)\n\n --accept-from-fd\n [A] Do not call `socket(2)` in UNIX socket listener peer, start with `accept(2)` using specified file\n descriptor number as argument instead of filename\n --unlink [A] Unlink listening UNIX socket before binding to it\n -V, --version Prints version information\n -v Increase verbosity level to info or further\n -b, --binary Send message to WebSockets as binary messages\n -n, --no-close Don't send Close message to websocket on EOF\n --websocket-ignore-zeromsg\n [A] Silently drop incoming zero-length WebSocket messages. They may cause connection close due to usage of\n zero-len message as EOF flag inside Websocat.\n -t, --text Send message to WebSockets as text messages\n --base64\n Encode incoming binary WebSocket messages in one-line Base64 If `--binary-prefix` (see `--help=full`) is\n set, outgoing WebSocket messages that start with the prefix are decoded from base64 prior to sending.\n --base64-text\n [A] Encode incoming text WebSocket messages in one-line Base64. I don't know whether it can be ever useful,\n but it's for symmetry with `--base64`.\n\nOPTIONS:\n --socks5 <auto_socks5>\n Use specified address:port as a SOCKS5 proxy. Note that proxy authentication is not supported yet. Example:\n --socks5 127.0.0.1:9050\n --autoreconnect-delay-millis <autoreconnect_delay_millis>\n [A] Delay before reconnect attempt for `autoreconnect:` overlay. [default: 20]\n\n --basic-auth <basic_auth>\n Add `Authorization: Basic` HTTP request header with this base64-encoded parameter\n\n --queue-len <broadcast_queue_len>\n [A] Number of pending queued messages for broadcast reuser [default: 16]\n\n -B, --buffer-size <buffer_size> Maximum message size, in bytes [default: 65536]\n --byte-to-exit-on <byte_to_exit_on>\n [A] Override the byte which byte_to_exit_on: overlay looks for [default: 28]\n\n --client-pkcs12-der <client_pkcs12_der> [A] Client identity TLS certificate\n --client-pkcs12-passwd <client_pkcs12_passwd>\n [A] Password for --client-pkcs12-der pkcs12 archive. Required on Mac.\n\n --close-reason <close_reason>\n Close connection with a reason message. This option only takes effect if --close-status-code option is\n provided as well.\n --close-status-code <close_status_code> Close connection with a status code.\n --crypto-key <crypto_key>\n [A] Specify encryption/decryption key for `crypto:` specifier. Requires `base64:`, `file:` or `pwd:` prefix.\n\n -H, --header <custom_headers>...\n Add custom HTTP header to websocket client request. Separate header name and value with a colon and\n optionally a single space. Can be used multiple times. Note that single -H may eat multiple further\n arguments, leading to confusing errors. Specify headers at the end or with equal sign like -H='X: y'.\n --server-header <custom_reply_headers>...\n Add custom HTTP header to websocket upgrade reply. Separate header name and value with a colon and\n optionally a single space. Can be used multiple times. Note that single -H may eat multiple further\n arguments, leading to confusing errors.\n --exec-args <exec_args>...\n [A] Arguments for the `exec:` specifier. Must be the last option, everything after it gets into the exec\n args list.\n --header-to-env <headers_to_env>...\n Forward specified incoming request header to H_* environment variable for `exec:`-like specifiers.\n\n -h, --help <help>\n See the help.\n --help=short is the list of easy options and address types\n --help=long lists all options and types (see [A] markers)\n --help=doc also shows longer description and examples.\n --inhibit-pongs <inhibit_pongs>\n [A] Stop replying to incoming WebSocket pings after specified number of replies\n\n --just-generate-accept <just_generate_accept>\n [A] Just a Sec-WebSocket-Accept value based on supplied Sec-WebSocket-Key value without running main\n Websocat\n --lengthprefixed-nbytes <lengthprefixed_header_bytes>\n [A] Use this number of length header bytes for `lengthprefixed:` overlay. [default: 4]\n\n --max-messages <max_messages>\n Maximum number of messages to copy in one direction.\n\n --max-messages-rev <max_messages_rev>\n Maximum number of messages to copy in the other direction.\n\n --conncap <max_parallel_conns>\n Maximum number of simultaneous connections for listening mode\n\n --max-sent-pings <max_sent_pings>\n [A] Stop sending pings after this number of sent pings\n\n --max-ws-frame-length <max_ws_frame_length>\n [A] Maximum size of incoming WebSocket frames, to prevent memory overflow [default: 104857600]\n\n --max-ws-message-length <max_ws_message_length>\n [A] Maximum size of incoming WebSocket messages (sans of one data frame), to prevent memory overflow\n [default: 209715200]\n --origin <origin> Add Origin HTTP header to websocket client request\n --pkcs12-der <pkcs12_der>\n Pkcs12 archive needed to accept SSL connections, certificate and key.\n A command to output it: openssl pkcs12 -export -out output.pkcs12 -inkey key.pem -in cert.pem\n Use with -s (--server-mode) option or with manually specified TLS overlays.\n See moreexamples.md for more info.\n --pkcs12-passwd <pkcs12_passwd>\n Password for --pkcs12-der pkcs12 archive. Required on Mac.\n\n -p, --preamble <preamble>...\n Prepend copied data with a specified string. Can be specified multiple times.\n\n -P, --preamble-reverse <preamble_reverse>...\n Prepend copied data with a specified string (reverse direction). Can be specified multiple times.\n\n --prometheus <prometheus>\n Expose Prometheus metrics on specified IP address and port in addition to running usual Websocat session\n\n --request-header <request_headers>...\n [A] Specify HTTP request headers for `http-request:` specifier.\n\n -X, --request-method <request_method> [A] Method to use for `http-request:` specifier\n --request-uri <request_uri> [A] URI to use for `http-request:` specifier\n --restrict-uri <restrict_uri>\n When serving a websocket, only accept the given URI, like `/ws`\n This liberates other URIs for things like serving static files or proxying.\n -F, --static-file <serve_static_files>...\n Serve a named static file for non-websocket connections.\n Argument syntax: <URI>:<Content-Type>:<file-path>\n Argument example: /index.html:text/html:index.html\n Directories are not and will not be supported for security reasons.\n Can be specified multiple times. Recommended to specify them at the end or with equal sign like `-F=...`,\n otherwise this option may eat positional arguments\n --socks5-bind-script <socks5_bind_script>\n [A] Execute specified script in `socks5-bind:` mode when remote port number becomes known.\n\n --socks5-destination <socks_destination>\n [A] Examples: 1.2.3.4:5678 2600:::80 hostname:5678\n\n --tls-domain <tls_domain>\n [A] Specify domain for SNI or certificate verification when using tls-connect: overlay\n\n --udp-multicast <udp_join_multicast_addr>...\n [A] Issue IP[V6]_ADD_MEMBERSHIP for specified multicast address. Can be specified multiple times.\n\n --udp-multicast-iface-v4 <udp_join_multicast_iface_v4>...\n [A] IPv4 address of multicast network interface. Has to be either not specified or specified the same number\n of times as multicast IPv4 addresses. Order matters.\n --udp-multicast-iface-v6 <udp_join_multicast_iface_v6>...\n [A] Index of network interface for IPv6 multicast. Has to be either not specified or specified the same\n number of times as multicast IPv6 addresses. Order matters.\n --udp-ttl <udp_ttl> [A] Set IP_TTL, also IP_MULTICAST_TTL if applicable\n --protocol <websocket_protocol>\n Specify this Sec-WebSocket-Protocol: header when connecting\n\n --server-protocol <websocket_reply_protocol>\n Force this Sec-WebSocket-Protocol: header when accepting a connection\n\n --websocket-version <websocket_version> Override the Sec-WebSocket-Version value\n --binary-prefix <ws_binary_prefix>\n [A] Prepend specified text to each received WebSocket binary message. Also strip this prefix from outgoing\n messages, explicitly marking them as binary even if `--text` is specified\n --ws-c-uri <ws_c_uri>\n [A] URI to use for ws-c: overlay [default: ws://0.0.0.0/]\n\n --ping-interval <ws_ping_interval> Send WebSocket pings each this number of seconds\n --ping-timeout <ws_ping_timeout>\n Drop WebSocket connection if Pong message not received for this number of seconds\n\n --text-prefix <ws_text_prefix>\n [A] Prepend specified text to each received WebSocket text message. Also strip this prefix from outgoing\n messages, explicitly marking them as text even if `--binary` is specified\n\nARGS:\n <addr1> In simple mode, WebSocket URL to connect. In advanced mode first address (there are many kinds of\n addresses) to use. See --help=types for info about address types. If this is an address for\n listening, it will try serving multiple connections.\n <addr2> In advanced mode, second address to connect. If this is an address for listening, it will accept only\n one connection.\n\n\nBasic examples:\n Command-line websocket client:\n websocat ws://ws.vi-server.org/mirror/\n \n WebSocket server\n websocat -s 8080\n \n WebSocket-to-TCP proxy:\n websocat --binary ws-l:127.0.0.1:8080 tcp:127.0.0.1:5678\n \n\nFull list of address types:\n\tws:// \tInsecure (ws://) WebSocket client. Argument is host and URL.\n\twss:// \tSecure (wss://) WebSocket client. Argument is host and URL.\n\tws-listen: \tWebSocket server. Argument is host and port to listen.\n\tinetd-ws: \tWebSocket inetd server. [A]\n\tl-ws-unix: \tWebSocket UNIX socket-based server. [A]\n\tl-ws-abstract: \tWebSocket abstract-namespaced UNIX socket server. [A]\n\tws-lowlevel-client:\t[A] Low-level HTTP-independent WebSocket client connection without associated HTTP upgrade.\n\tws-lowlevel-server:\t[A] Low-level HTTP-independent WebSocket server connection without associated HTTP upgrade.\n\twss-listen: \tListen for secure WebSocket connections on a TCP port\n\thttp: \t[A] Issue HTTP request, receive a 1xx or 2xx reply, then pass\n\tasyncstdio: \t[A] Set stdin and stdout to nonblocking mode, then use it as a communication counterpart. UNIX-only.\n\tinetd: \tLike `asyncstdio:`, but intended for inetd(8) usage. [A]\n\ttcp: \tConnect to specified TCP host and port. Argument is a socket address.\n\ttcp-listen: \tListen TCP port on specified address.\n\tssl-listen: \tListen for SSL connections on a TCP port\n\tsh-c: \tStart specified command line using `sh -c` (even on Windows)\n\tcmd: \tStart specified command line using `sh -c` or `cmd /C` (depending on platform)\n\texec: \tExecute a program directly (without a subshell), providing array of arguments on Unix [A]\n\treadfile: \tSynchronously read a file. Argument is a file path.\n\twritefile: \tSynchronously truncate and write a file.\n\tappendfile: \tSynchronously append a file.\n\tudp: \tSend and receive packets to specified UDP socket, from random UDP port \n\tudp-listen: \tBind an UDP socket to specified host:port, receive packet\n\topen-async: \tOpen file for read and write and use it like a socket. [A]\n\topen-fd: \tUse specified file descriptor like a socket. [A]\n\tthreadedstdio: \t[A] Stdin/stdout, spawning a thread (threaded version).\n\t- \tRead input from console, print to console. Uses threaded implementation even on UNIX unless requested by `--async-stdio` CLI option.\n\tunix: \tConnect to UNIX socket. Argument is filesystem path. [A]\n\tunix-listen: \tListen for connections on a specified UNIX socket [A]\n\tunix-dgram: \tSend packets to one path, receive from the other. [A]\n\tabstract: \tConnect to UNIX abstract-namespaced socket. Argument is some string used as address. [A]\n\tabstract-listen:\tListen for connections on a specified abstract UNIX socket [A]\n\tabstract-dgram: \tSend packets to one address, receive from the other. [A]\n\tmirror: \tSimply copy output to input. No arguments needed.\n\tliteralreply: \tReply with a specified string for each input packet.\n\tclogged: \tDo nothing. Don't read or write any bytes. Keep connections in \"hung\" state. [A]\n\tliteral: \tOutput a string, discard input.\n\tassert: \tCheck the input. [A]\n\tassert2: \tCheck the input. [A]\n\tseqpacket: \tConnect to AF_UNIX SOCK_SEQPACKET socket. Argument is a filesystem path. [A]\n\tseqpacket-listen:\tListen for connections on a specified AF_UNIX SOCK_SEQPACKET socket [A]\n\trandom: \tGenerate random bytes when being read from, discard written bytes.\nFull list of overlays:\n\tws-upgrade: \tWebSocket upgrader / raw server. Specify your own protocol instead of usual TCP. [A]\n\thttp-request: \t[A] Issue HTTP request, receive a 1xx or 2xx reply, then pass\n\thttp-post-sse: \t[A] Accept HTTP/1 request. Then, if it is GET,\n\tssl-connect: \tOverlay to add TLS encryption atop of existing connection [A]\n\tssl-accept: \tAccept an TLS connection using arbitrary backing stream. [A]\n\treuse-raw: \tReuse subspecifier for serving multiple clients: unpredictable mode. [A]\n\tbroadcast: \tReuse this connection for serving multiple clients, sending replies to all clients.\n\tautoreconnect: \tRe-establish underlying connection on any error or EOF\n\tws-c: \tLow-level WebSocket connector. Argument is a some another address. [A]\n\tmsg2line: \tLine filter: Turns messages from packet stream into lines of byte stream. [A]\n\tline2msg: \tLine filter: turn lines from byte stream into messages as delimited by '\\\\n' or '\\\\0' [A]\n\tlengthprefixed: \tTurn stream of bytes to/from data packets with length-prefixed framing. [A]\n\tforeachmsg: \tExecute something for each incoming message.\n\tlog: \tLog each buffer as it pass though the underlying connector.\n\tjsonrpc: \t[A] Turns messages like `abc 1,2` into `{\"jsonrpc\":\"2.0\",\"id\":412, \"method\":\"abc\", \"params\":[1,2]}`.\n\ttimestamp: \t[A] Prepend timestamp to each incoming message.\n\tsocks5-connect: \tSOCKS5 proxy client (raw) [A]\n\tsocks5-bind: \tSOCKS5 proxy client (raw, bind command) [A]\n\tcrypto: \t[A] Encrypts written messages and decrypts (and verifies) read messages with a static key, using ChaCha20-Poly1305 algorithm.\n\tprometheus: \t[A] Account connections, messages, bytes and other data and expose Prometheus metrics on a separate port.\n\texit_on_specific_byte:\t[A] Turn specific byte into a EOF, allowing user to escape interactive Websocat session\n\twaitfordata: \tWait for some data to pending being written before starting connecting. [A]\n```\n</details>\n\n\nSome notes\n---\n\n* IPv6 is supported, surround your IP in square brackets or use it as is, depending on context.\n* Web socket usage is not obligatory, you can use any specs on both sides.\n* Typically one line in binary stream correspond to one WebSocket text message. This is adjustable with options.\n\nLimitations\n---\n\n* It is not convenient when text and binary WebSocket messages are mixed. This affects `mirror:` specifier, making it a bit different from ws://echo.websocket.org. There are `--binary-prefix`, `--text-prefix` and `--base64` options to handle mixture of binary and text.\n* Current version of Websocat don't receive notification about closed sockets. This makes serving without `-E` or `-u` options or in backpressure scenarios prone to socket leak.\n* Readline is not integrated. Users are advices to wrap websocat using [`rlwrap`](https://linux.die.net/man/1/rlwrap) tool for more convenient CLI.\n* Build process of current version of Websocat is not properly automated and is fragile.\n\nSee also\n---\n\n* [wstunnel](https://github.com/erebe/wstunnel)\n* [wscat](https://github.com/websockets/wscat)\n* [websocketd](https://github.com/joewalnes/websocketd)\n* [wsd](https://github.com/alexanderGugel/wsd)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command-line client for WebSockets, like netcat (or curl) for ws:// with advanced socat-like functions",
"version": "1.13.0",
"project_urls": {
"repository": "https://github.com/vi/websocat.git"
},
"split_keywords": [
"cli",
" socat",
" proxy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad050d7cf0039b8fac733c1183f0cde00351605170823008e87a289cb2c0eef2",
"md5": "06491119479bbaff8b1c0033f8bbd7cb",
"sha256": "0e3d173a3c4e41a36dee8509686b1ed01628969f86f08f1fd4c8d2feb02704af"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-macosx_10_13_x86_64.whl",
"has_sig": false,
"md5_digest": "06491119479bbaff8b1c0033f8bbd7cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 930065,
"upload_time": "2024-04-16T23:17:34",
"upload_time_iso_8601": "2024-04-16T23:17:34.417049Z",
"url": "https://files.pythonhosted.org/packages/ad/05/0d7cf0039b8fac733c1183f0cde00351605170823008e87a289cb2c0eef2/websocat-1.13.0-py3-none-macosx_10_13_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "65d7d727d5ee6bf617a0aab7a25e379efe95edde0b76246e7743c5c6ea5a1c5c",
"md5": "5c67335a45854916cf1a4704597f9045",
"sha256": "4a1fbdf0dc4ed0246440974d288aa117765cdca93d427a73bc28f343e12e7673"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "5c67335a45854916cf1a4704597f9045",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 881830,
"upload_time": "2024-04-16T23:17:28",
"upload_time_iso_8601": "2024-04-16T23:17:28.666741Z",
"url": "https://files.pythonhosted.org/packages/65/d7/d727d5ee6bf617a0aab7a25e379efe95edde0b76246e7743c5c6ea5a1c5c/websocat-1.13.0-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b3da7f9e1fa92e518e859200a37f0791259e80c98280657e26b9069f533b01f0",
"md5": "f9881c3504726a1dfa688c5557cd2004",
"sha256": "96392d52aa5c44088343d8157cf87b2d0680ef5e20cae0b99954de28462ed828"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "f9881c3504726a1dfa688c5557cd2004",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2984709,
"upload_time": "2024-04-16T23:19:07",
"upload_time_iso_8601": "2024-04-16T23:19:07.494425Z",
"url": "https://files.pythonhosted.org/packages/b3/da/7f9e1fa92e518e859200a37f0791259e80c98280657e26b9069f533b01f0/websocat-1.13.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "af4d2cf4b7021cdfbf43742de094e200750923a3f21c83f0d93ee31a8fd53cbb",
"md5": "11d0bff5cf88efdd9d9dfbbba30514ff",
"sha256": "6d3a949115a2efbda34b0dbdafa1598caa484b8fd6fe8d2d73296be2828a8736"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-manylinux_2_31_x86_64.whl",
"has_sig": false,
"md5_digest": "11d0bff5cf88efdd9d9dfbbba30514ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2827527,
"upload_time": "2024-04-16T23:18:09",
"upload_time_iso_8601": "2024-04-16T23:18:09.854973Z",
"url": "https://files.pythonhosted.org/packages/af/4d/2cf4b7021cdfbf43742de094e200750923a3f21c83f0d93ee31a8fd53cbb/websocat-1.13.0-py3-none-manylinux_2_31_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0930765a95ef1b99341d7e2a4f1dbcffdfb73e7d746004a77ac0475b8d585e8f",
"md5": "378494af2360a9dd9729274d66e9ae2a",
"sha256": "83bcf971651fda3ebeb446ba21df09cd9c56eb531e6ad4466e410d699ae38b37"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "378494af2360a9dd9729274d66e9ae2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2838418,
"upload_time": "2024-04-16T23:18:13",
"upload_time_iso_8601": "2024-04-16T23:18:13.559527Z",
"url": "https://files.pythonhosted.org/packages/09/30/765a95ef1b99341d7e2a4f1dbcffdfb73e7d746004a77ac0475b8d585e8f/websocat-1.13.0-py3-none-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04c74769c566fb736039c578af5cd669b673c260d871393c38b1100e40395281",
"md5": "f2629ce548bf84dca18eb5c6f87bf8bf",
"sha256": "b229cf92c11070fb6a5645987249f7443b802359e38918f97e4b150bd72e185d"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-musllinux_1_2_x86_64.whl",
"has_sig": false,
"md5_digest": "f2629ce548bf84dca18eb5c6f87bf8bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2883828,
"upload_time": "2024-04-16T23:18:18",
"upload_time_iso_8601": "2024-04-16T23:18:18.651107Z",
"url": "https://files.pythonhosted.org/packages/04/c7/4769c566fb736039c578af5cd669b673c260d871393c38b1100e40395281/websocat-1.13.0-py3-none-musllinux_1_2_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1cbce1a34abffe2c9779876bfd05cb58bf20f9ae8b9694400a0acc727fa6893",
"md5": "1be95789346a575c9d4cd8cc95e27546",
"sha256": "92a5a246b0f875f26c0365b8f0e5e051c870461e1674c9c4af60167fa40d6e76"
},
"downloads": -1,
"filename": "websocat-1.13.0-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "1be95789346a575c9d4cd8cc95e27546",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 863280,
"upload_time": "2024-04-16T23:23:36",
"upload_time_iso_8601": "2024-04-16T23:23:36.119173Z",
"url": "https://files.pythonhosted.org/packages/f1/cb/ce1a34abffe2c9779876bfd05cb58bf20f9ae8b9694400a0acc727fa6893/websocat-1.13.0-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-16 23:17:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vi",
"github_project": "websocat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "websocat"
}
