CORKSCREW(1) User Commands CORKSCREW(1)

corkscrew - tunnel SSH through an HTTP proxy

corkscrew [options] proxyhost proxyport desthost destport [authfile]

corkscrew connects to an HTTP proxy and asks it to establish a tunnel to desthost:destport with the HTTP CONNECT method. The proxy response is parsed and the resulting byte stream is relayed between standard input/output and the proxy connection. It is commonly used as an OpenSSH ProxyCommand for reaching an SSH server through an HTTP proxy.

The proxy port and destination port are required decimal integers in the range 1 through 65535. IPv6 destination addresses may be supplied with or without brackets; the CONNECT request uses the bracketed form.

Standard input and standard output must be open when corkscrew starts. The proxy socket is always given a descriptor above the standard error descriptor so that it cannot alias a closed standard stream.

The original positional form remains supported. Options may be placed before, between, or after the positional arguments.

Print usage information and exit.
Print the version and exit.
Report connection progress on standard error. Credentials are never printed.
Set the TCP connect deadline in seconds. The default is 10 seconds.
Set the deadline for writing the CONNECT request and reading the proxy response in seconds. The default is 10 seconds.
Read the proxy credential from file instead of the final positional argument. The two forms cannot be combined.
Read the proxy credential from an inherited descriptor. The descriptor must be 3 or greater and is closed after one line is read. This mode does not require a regular file and does not check file permissions because descriptors may refer to pipes or other protected streams supplied by a supervisor.
Send an HTTP/1.1 CONNECT request with Host and User-Agent headers. The default remains HTTP/1.0 for compatibility with older proxies.

If authfile is given, the first line of the file is read as an HTTP Basic authentication credential in the form username:password. The line ending may be LF or CRLF. Leading and trailing spaces are preserved, including trailing spaces before the line ending.

The authentication file must be a regular file and must not be accessible by group or other users. Create it with a command such as:

umask 077
printf '%s0 'username:password' >~/.ssh/corkscrew-auth
chmod 600 ~/.ssh/corkscrew-auth

Credentials are encoded with Base64 for the Proxy-Authorization header. Base64 is not encryption. The proxy connection is plaintext HTTP unless an external transport protects it.

During the relay, SIGTERM, SIGINT, SIGHUP, and SIGQUIT request an orderly shutdown. Shared descriptor flags are restored before the process exits. SIGTSTP restores the inherited descriptor flags before stopping and reapplies nonblocking mode after the process resumes.

0
The tunnel reached end-of-file on both directions and closed normally.
1
An argument, connection, authentication, handshake, or relay error occurred.
2
The command line was invalid and the usage message was printed.
128+signal
A termination signal was received during the relay.

Use corkscrew directly:

corkscrew proxy.example.com 8080 ssh.example.com 22

Configure OpenSSH to use it:

Host ssh.example.com
    ProxyCommand /usr/local/bin/corkscrew proxy.example.com 8080 %h %p

With proxy authentication:

Host ssh.example.com
    ProxyCommand /usr/local/bin/corkscrew proxy.example.com 8080 %h %p ~/.ssh/corkscrew-auth

Use an integrated proxy header mode and explicit deadlines:

corkscrew --http11 --connect-timeout=5 --handshake-timeout=5 \
    proxy.example.com 8080 ssh.example.com 22

HTTP CONNECT carries the request and tunnel over a plaintext TCP connection to the proxy. Proxy Basic authentication is only Base64 encoded. Use a trusted proxy or a protected network path, and do not reuse valuable passwords.

The tunnel is not a substitute for SSH host-key verification.

ssh(1), ssh_config(5)

Corkscrew was originally written by Pat Padgett and contributors. This manual page describes the current implementation.

Corkscrew is released under the MIT License. See the LICENSE file in the source distribution.

October 2026 corkscrew 3.1