## NAME
`tlsproxy tunnel add` - Adds new tunnel definition to the Rebex TLS Proxy configuration file.

## OPTIONS
* `-n, --name <name>`
  * Tunnel name. Auto-generated if not specified.
* `-i, --in [address]:<port>`
  * Address + port at which the proxy listens for incoming connections. Port is required.
  * Address can be either local IP address (v4 or v6 notation) or `localhost` string.
  * Address can be omitted. In such case proxy listens on all IP v4 and v6 local addresses.
* `--in-protocol <protocol>`
  * Protocol to be used for incoming connections. Default: Plain.
* `--in-tls-versions <versions>`
  * Comma-separated TLS versions. Default: TLS12,TLS13.
  * Supported values: SSL30, TLS10, TLS11, TLS12, TLS13.
* `--in-tls-cipher-suites <suites>`
  * Comma-separated TLS cipher suites. Optional.
  * Supported values: Default, All, Common, Fast, Secure, Weak, Vulnerable and values listed by [tlsproxy tlsinfo](tlsinfo) command.
* `-o, --out <host>:<port>`
  * Host + port to which the proxy connects outgoing connections.
  * Host can be either IP address (v4 or v6 notation) or DNS host name.
* `--out-protocol <protocol>`
  * Protocol to be used for outgoing connections. Default: Plain.
* `--out-tls-versions <versions>`
  * Comma-separated TLS versions. Default: TLS12,TLS13.
  * Supported values: SSL30, TLS10, TLS11, TLS12, TLS13.
* `--out-tls-cipher-suites <suites>`
  * Comma-separated TLS cipher suites. Optional.
  * Supported values: Default, All, Common, Fast, Secure, Weak, Vulnerable and values listed by [tlsproxy tlsinfo](tlsinfo) command.
* `-c, --certificate <uri>`
  * Certificate for inbound tunnel. Optional.
  * Required if inbound protocol is TLS capable. A certificate with associated private key is required for TLS Server Authentication.
  * For `uri` syntax and examples run [tlsproxy certinfo --help](certinfo) command.
* `--dh-key-size <key-size>`
  * Size of ephemeral Diffie-Hellman key for DHE key exchange. Optional.
  * Used when inbound protocol is TLS capable. Applied only in TLS 1.2 or lower (not in TLS 1.3).
  * If not specified, TLS_DHE_ cipher suites are disabled.
  * Supported values: 1024, 2048, 3072, 4096, 6144, 8192.
* `--idle-timeout <seconds>`
  * Timeout after which the tunnel is closed if no data is transmitted. Default: 120.
  * Supported values: minimum is 1 (second), maximum is 2147483 (24 days and 20h 31m 23s).
  * For infinite timeout specify 0.
* `--server-names <names>`
  * Comma-separated server names. Optional.
  * Defines for which server names this tunnel is defined. Server name is sent in the SNI extension of the TLS protocol.
  * Can be used only when `--in-protocol` is TLS capable.
  * Use asterisk `"*"` for default fallback.
* `--sni-override <name>`
  * Assigns specific SNI to outbound tunnel. Optional.
  * Useful especially when host on outbound tunnel is specified by IP address.
  * Only takes effect when outbound protocol is TLS capable.
* `--http-host-override <name>`
  * Modifies HTTP traffic by including/overwriting the `Host` request header. Optional.
  * Only takes effect when protocol is HTTP capable.
* `--http-x-real-ip <false|true>`
  * Indicates whether to modify HTTP traffic by including/overwriting the `X-Real-IP` request header with the connected client's IP address. Default: false.
  * Only takes effect when protocol is HTTP capable.
* `--http-x-forwarded-for <false|true>`
  * Indicates whether to modify HTTP traffic by including/overwriting the `X-Forwarded-For` request header with the connected client's IP address. Default: false.
  * Only takes effect when protocol is HTTP capable.
* `--http-x-ssl-cert <format>`
  * Indicates whether to modify HTTP traffic by including/overwriting the `X-SSL-CERT` request header with the provided client certificate. Optional.
  * Supported values: None, URL-encoded, Base16, Base64.
  * Note: To request client certificates on inbound tunnel, use `--request-client-certificate true` option.
  * Note: When using `None` value, the `X-SSL-CERT` header is not sent (removed if the client sent it).
  * Note: When the client did not provide any client certificate and the connection was not rejected, the empty `X-SSL-CERT` header is sent.
  * Only takes effect when protocol is HTTP capable.
* `--request-client-certificate <false|true>`
  * Indicates whether the proxy should request client certificate (on inbound tunnel). Default: false.
  * Only takes effect when inbound protocol is TLS capable.
* `--client-certificates-file: <path>`
  * Path to a JSON file (full or relative to `config.yaml`) with rules for 
  * accepting/rejecting connections based on provided client certificate. Optional.
  * The file changes are applied in max 10 seconds.
  * If no file is specified (and `--request-client-certificate` is `true`) then:
  *  - connections with any client certificate are accepted;
  *  - connections with no client certificate are rejected.
  * Only takes effect when inbound protocol is TLS capable and `--request-client-certificate` is `true`.
* `--out-client-certificate <uri>`
  * Client certificate for outbound tunnel. Optional.
  * For `uri` syntax and examples run `tlsproxy certinfo --help`.
  * Only takes effect when outbound protocol is TLS capable.

## Supported protocols
* `Plain` - No higher protocol. Raw data is transmitted without any processing.
* `TLS` - Provides TLS/SSL layer.
* `HTTP` - Allows handling HTTP related features, such as `--http-x-real-ip`.
* `HTTPS` - HTTP with TLS/SSL layer. Allows handling HTTP and TLS related features.
* `SMTPE` - SMTP with explicit TLS/SSL. Can be used for outbound protocol only. Inbound protocol must be either `Plain` or `TLS`.
  * In SMTPE mode, proxy connects to the remote SMTP host, issues `STARTTLS` command and negotiates TLS/SSL layer. 

## EXAMPLES
* `tlsproxy tunnel add -i :443 --in-protocol TLS -o httpbin.org:80 -c my-localhost-cert`
  * Defines TLS->PLAIN tunnel to httpbin.org WEB server (no HTTP features are used by the TLS Proxy).
  * Useful for administrators, which manage legacy services and need to provide modern TLS security access for clients using modern browsers.
* `tlsproxy tunnel add -i :143 -o outlook.office365.com:993 --out-protocol TLS`
  * Defines PLAIN->TLS tunnel to office365.com IMAP server.
  * Useful for legacy clients, which need to connect to modern IMAP server.
* `tlsproxy tunnel add -i :25 -o smtp.office365.com:587 --out-protocol SMTPE`
  * Defines PLAIN->TLS tunnel to office365.com SMTP server.
  * Useful for legacy clients, which need to connect to modern SMTP server with explicit TLS.
&nbsp;
* __HTTPS virtual hosting__
* `tlsproxy tunnel add -i :443 --in-protocol HTTPS -o 129.168.1.1:80 -c example1.com --server-names "example1.com,www.example1.com"`
* `tlsproxy tunnel add -i :443 --in-protocol HTTPS -o 129.168.1.2:80 -c example2.com --server-names "example2.com,www.example2.com"`
  * Defines HTTPS virtual hosting of two websites on the same IP address: _www.example1.com_, _www.example2.com_.
  * An HTTP client is provided by either _www.example1.com_ or _www.example2.com_ website based on URL (provided SNI).

## Notes on 'HTTP' / 'HTTPS' protocols
* 1\. When `HTTP` or `HTTPS` is specified for inbound or outbound protocol, Rebex TLS Proxy becomes an HTTP-aware proxy.
  This injects `X-Real-IP` and `X-Forwarded-For` headers (among others) into the communication, 
  making it possible for the target server to determine where the original request came from.
  Additionally, this makes it possible to log the method line of HTTP requests and status line of HTTP responses into the Access log.
* 2\. If this feature is not required, consider using `Plain` (instead of `HTTP`) or `TLS` (instead of `HTTPS`) for better performance.
* 3\. In HTTP-aware proxy mode, HTTP requests or responses that could not be processed cause the tunnel to close.

## SEE ALSO
[tunnel list](tunnel-list), [tunnel delete](tunnel-delete), [tlsinfo](tlsinfo), [certinfo](certinfo)