NAME

DESCRIPTION

FILE FORMAT

Structured proxyspecs are defined between curly braces. The opening curly brace should be on the same line as the ProxySpec keyword. The closing curly brace and option-argument pairs should be on a line of their own.

The arguments are of the following types:

BOOL

Boolean value (yes/no).

STRING

String.

NUMBER

Unsigned integer.

DIRECTIVES

Note that the ordering of options, rules, and proxyspecs in configuration files (and on the command line) is important. For example, rules and proxyspecs can only make use of the options defined earlier.

CACert STRING

Use CA cert (and key) to sign forged certs. Equivalent to -c command line option.

CAKey STRING

Use CA key (and cert) to sign forged certs. Equivalent to -k command line option.

ClientCert STRING

Use cert from pemfile when destination requests client certs. Equivalent to -a command line option.

ClientKey STRING

Use key from pemfile when destination requests client certs. Equivalent to -b command line option.

CAChain STRING

Use CA chain from pemfile (intermediate and root CA certs). Equivalent to -C command line option.

LeafKey STRING

Use key from pemfile for leaf certs. Equivalent to -K command line option.
Default: generate

LeafCRLURL STRING

Use URL as CRL distribution point for all forged certs. Equivalent to -q command line option.

LeafCertDir STRING

Use cert+chain+key PEM files from certdir to target all sites matching the common names (non-matching: generate if CA). Equivalent to -t command line option.

DefaultLeafCert STRING

Use cert+chain+key from PEM file for leaf certificates if there is no match in LeafCertDir. Equivalent to -A command line option.

WriteGenCertsDir STRING

Write leaf key and only generated certificates to gendir. Equivalent to -w command line option.

WriteAllCertsDir STRING

Write leaf key and all certificates to gendir. Equivalent to -W command line option.

DenyOCSP BOOL

Deny all OCSP requests on all proxyspecs. Equivalent to -O command line option.

Passthrough BOOL

Passthrough SSL connections if they cannot be split because of client cert auth or no matching cert and no CA. Equivalent to -P command line option.
Default: drop

DHGroupParams STRING

Use DH group params from pemfile. Equivalent to -g command line option.
Default: keyfiles or auto

ECDHCurve STRING

Use ECDH named curve. Equivalent to -G command line option.
Default: prime256v1

SSLCompression BOOL

Enable/disable SSL/TLS compression on all connections. Equivalent to -Z command line option.

ForceSSLProto STRING

Force SSL/TLS protocol version only. Equivalent to -r command line option.
Default: all

DisableSSLProto STRING

Disable SSL/TLS protocol version. Equivalent to -R command line option.
Default: none

EnableSSLProto STRING

Enable SSL/TLS protocol version. Equivalent to -B command line option.
Default: all

MinSSLProto STRING

Min SSL/TLS protocol version.
Default: tls10

MaxSSLProto STRING

Max SSL/TLS protocol version.
Default: tls13

Ciphers STRING

Use the given OpenSSL ciphers spec. Equivalent to -s command line option.
Default: ALL:-aNULL

CipherSuites STRING

Use the given OpenSSL ciphersuites spec. The ciphersuites spec is for TLS 1.3. Equivalent to -U command line option.
Default: TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

LeafKeyRSABits NUMBER

Leaf key RSA keysize in bits, use 1024|2048|3072|4096.
Default: 2048

OpenSSLEngine STRING

The OpenSSL engine to activate. Equivalent to -x command line option.

NATEngine STRING

Specify default NAT engine to use. Equivalent to -e command line option.

User STRING

Drop privileges to user. Equivalent to -u command line option.
Default: nobody, if run as root

Group STRING

Drop privileges to group. Equivalent to -m command line option.
Default: Primary group of user

Chroot STRING

chroot() to jaildir (impacts sni proxyspecs, see sslproxy(1)). Equivalent to -j command line option.

PidFile STRING

Write pid to file. Equivalent to -p command line option.

ConnectLog STRING

Connect log: log one line summary per connection to logfile. Equivalent to -l command line option.

ContentLog STRING

Content log: full data to file or named pipe (excludes ContentLogDir/ContentLogPathSpec). Equivalent to -L command line option.

ContentLogDir STRING

Content log: full data to separate files in dir (excludes ContentLog/ContentLogPathSpec). Equivalent to -S command line option.

ContentLogPathSpec STRING

Content log: full data to sep files with % subst (excludes ContentLog/ContentLogDir). Equivalent to -F command line option.

LogProcInfo BOOL

Look up local process owning each connection for logging. Equivalent to -i command line option.

PcapLog STRING

Pcap log: packets to pcapfile (excludes PcapLogDir/PcapLogPathSpec). Equivalent to -X command line option.

PcapLogDir STRING

Pcap log: packets to separate files in dir (excludes PcapLog/PcapLogPathSpec). Equivalent to -Y command line option.

PcapLogPathSpec STRING

Pcap log: packets to sep files with % subst (excludes PcapLog/PcapLogDir). Equivalent to -y command line option.

MirrorIf STRING

Mirror packets to interface. Equivalent to -I command line option.

MirrorTarget STRING

Mirror packets to target address (used with MirrorIf). Equivalent to -T command line option. Not used if the target is irrelevant (e.g. mirror to dummy device)

MasterKeyLog STRING

Log master keys to logfile in SSLKEYLOGFILE format. Equivalent to -M command line option.

Daemon BOOL

Daemon mode: run in background, log error messages to syslog. Equivalent to -d command line option.

Debug BOOL

Debug mode: run in foreground, log debug messages on stderr. Equivalent to -D command line option.

DebugLevel NUMBER

Verbose debug level, 2-4.

ConnIdleTimeout NUMBER

Close connections after this many seconds of idle time.
Default: 120

ExpiredConnCheckPeriod NUMBER

Check for expired connections every this many seconds.
Default: 10.

LogStats BOOL

Log statistics to syslog. Equivalent to -J command line option.
Default: yes

StatsPeriod NUMBER

Log statistics every this many ExpiredConnCheckPeriod periods.
Default: 1

RemoveHTTPAcceptEncoding BOOL

Remove HTTP header line for Accept-Encoding.
Default: yes

RemoveHTTPReferer BOOL

Remove HTTP header line for Referer.
Default: yes

VerifyPeer BOOL

Verify peer using default certificates.
Default: yes

AllowWrongHost BOOL

When disabled, never add the SNI to forged certificates, even if the SNI provided by the client does not match the server certificate's CN/SAN. Helps pass the wrong.host test at https://badssl.com.
Default: no

UserAuth BOOL

Require authentication for users to use SSLproxy.
Default: no

DivertUsers STRING

Comma separated list of users. Connections from these users are diverted to listening programs. Users not listed in DivertUsers or PassUsers are blocked. Max of 50 users can be listed.

PassUsers STRING

Comma separated list of users. Connections from these users are simply passed through to their original destinations, not diverted to listening programs. Users not listed in DivertUsers or PassUsers are blocked. Max of 50 users can be listed.

UserDBPath STRING

Path to user db file.

UserTimeout NUMBER

Time users out after this many seconds of idle time.
Default: 300.

UserAuthURL STRING

Redirect URL for users to log in to the system.

ValidateProto BOOL

Validate proxy spec protocols.
Default: no

MaxHTTPHeaderSize NUMBER

Max HTTP header size in bytes for protocol validation.
Default: 8192.

OpenFilesLimit NUMBER

Set open files limit, use 50-10000.
Default: System-wide limit.

Divert BOOL

Set divert or split mode of operation, globally or per-proxyspec. The Divert option is not equivalent to the command line -n option.
Default: yes

PassSite STRING

Passthrough site: site[*] [(clientaddr|user|*) [description desc]]. PassSite option is a special form of Pass filtering rule. All PassSite rules can be written as Pass filter rules. The PassSite option will be deprecated in favor of filter rules in the future. If the site matches SNI or common names in the SSL certificate, the connection is passed through the proxy. Per site filters can be defined using client IP addresses, users, and description. '*' matches all client IP addresses or users. User auth should be enabled for user and description filtering to work. Case is ignored while matching description. Multiple sites are allowed, one on each line. PassSite rules can search for exact or substring matches. Append an asterisk to the site field to search for substring match. Note that the substring search is not a regex or wildcard search, and that the asterisk at the end is removed before search.

Include STRING

Load configuration from an include file.

Recursive include files are not allowed. The Include option cannot be used in include files.

Define STRING

Define macro to be used in filtering rules. Macro names must start with a $ char. The macro name must be followed by words separated with spaces. For example,

Define $macro value1 value2

Recursive macro definitions are not allowed.

Divert STRING

Divert filtering rule diverts packets to listening program, allowing SSL inspection by listening program and content logging of packets.

Split STRING

Split filtering rule splits the connection but does not divert packets to listening program, effectively disabling SSL inspection by listening program, but allowing content logging of packets.

Pass STRING

Pass filtering rule passes the connection through by engaging passthrough mode, effectively disabling SSL inspection and content logging of packets.

Block STRING

Block filtering rule terminates the connection.

Match STRING

Match filtering rule specifies log actions for the connection without changing its filter action.

The syntax of one line filtering rules is as follows:

(Divert|Split|Pass|Block|Match) ([from ( user (username[*]|$macro|*) [desc (desc[*]|$macro|*)]| desc (desc[*]|$macro|*)| ip (clientip[*]|$macro|*)| *)] [to ( (sni (servername[*]|$macro|*)| cn (commonname[*]|$macro|*)| host (host[*]|$macro|*)| uri (uri[*]|$macro|*)| ip (serverip[*]|$macro|*)) [port (serverport[*]|$macro|*)]| port (serverport[*]|$macro|*)| *)] [log ([[!]connect] [[!]master] [[!]cert] [[!]content] [[!]pcap] [[!]mirror] [$macro]|[!]*)] |*) [# comment]

See sslproxy(1) for the details.

FilterRule {

Action
User
Desc
SrcIp
SNI
CN
Host
URI
DstIp
DstPort
Log
ReconnectSSL
DenyOCSP
Passthrough
CACert
CAKey
ClientCert
ClientKey
CAChain
LeafCRLURL
DHGroupParams
ECDHCurve
SSLCompression (yes|no)
ForceSSLProto
DisableSSLProto
EnableSSLProto
MinSSLProto
MaxSSLProto
Ciphers
CipherSuites
RemoveHTTPAcceptEncoding
RemoveHTTPReferer
VerifyPeer
AllowWrongHost
UserAuth
UserTimeout
UserAuthURL
ValidateProto
MaxHTTPHeaderSize
}
Structured filtering rules can specify all possible connection options to be selectively applied to matching connections, not just per-proxyspec or globally. One line filtering rules cannot specify connection options.

See sslproxy(1) for the details.

ProxySpec STRING

One line proxy specification: type listenaddr+port up:port ua:addr ra:addr. The other options of one line proxyspecs are set to the global configuration preceding them. Multiple specs are allowed, one on each line.

ProxySpec {

Proto
Addr
Port
DivertPort
DivertAddr
ReturnAddr
TargetAddr
TargetPort
SNIPort
NatEngine
Divert
DenyOCSP
Passthrough
CACert
CAKey
ClientCert
ClientKey
CAChain
LeafCRLURL
DHGroupParams
ECDHCurve
SSLCompression
ForceSSLProto
DisableSSLProto
EnableSSLProto
MinSSLProto
MaxSSLProto
Ciphers
CipherSuites
RemoveHTTPAcceptEncoding
RemoveHTTPReferer
VerifyPeer
AllowWrongHost
UserAuth
UserTimeout
UserAuthURL
ValidateProto
MaxHTTPHeaderSize
DivertUsers
PassUsers
PassSite
Define
(Divert|Split|Pass|Block|Match) one line filtering rules
FilterRule {...} structured filtering rules
}

Structured proxy specifications may consist of the options listed above. The Addr and Port options are mandatory, and equivalent to listenaddr and port options in one line proxyspecs, respectively. If an option is not specified, the global default value is used.

FILES

AUTHOR

SEE ALSO