From db9974617f21c61cc8c05aac36de267dac6b48fb Mon Sep 17 00:00:00 2001 From: Soner Tari Date: Thu, 23 Sep 2021 22:03:32 +0300 Subject: [PATCH] Improve documentation The Include and Define options, the ordering in config options, etc. --- README.md | 4 ++-- src/sslproxy.1 | 9 ++++++--- src/sslproxy.conf | 15 +++++++++++++-- src/sslproxy.conf.5 | 20 ++++++++++++++++---- 4 files changed, 37 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ad6500e..dd9f51a 100644 --- a/README.md +++ b/README.md @@ -407,8 +407,8 @@ You can append an asterisk `*` to the site field of filtering rules for substring matching. Otherwise, the filter searches for an exact match with the site field in the rule. -The order of filtering rules is important. The order of from, to, and log -parts is not important. The order of log actions is not important. +The ordering of filtering rules is important. The ordering of from, to, and +log parts is not important. The ordering of log actions is not important. If the UserAuth option is disabled, only client IP addresses can be used in the from part of filtering rules. diff --git a/src/sslproxy.1 b/src/sslproxy.1 index c526eb5..617d9b2 100644 --- a/src/sslproxy.1 +++ b/src/sslproxy.1 @@ -421,8 +421,8 @@ You can append an asterisk * to the site field of filtering rules for substring matching. Otherwise, the filter searches for an exact match with the site field in the rule. .LP -The order of filtering rules is important. The order of from, to, and log -parts is not important. The order of log actions is not important. +The ordering of filtering rules is important. The ordering of from, to, and +log parts is not important. The ordering of log actions is not important. .LP If the UserAuth option is disabled, only client IP addresses can be used in the from part of filtering rules. @@ -526,7 +526,10 @@ NAT ENGINES for a list of NAT engines currently supported by SSLproxy. .TP .B \-f \fIconffile\fP Read configuration from \fIconffile\fP. Configuration files can use the -Include option for loading configuration from an include file too. +Include option for loading configuration from an include file too. 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. .TP .B \-F \fIlogspec\fP Log connection content to separate log files with the given path specification diff --git a/src/sslproxy.conf b/src/sslproxy.conf index 368d8b7..98b1b99 100644 --- a/src/sslproxy.conf +++ b/src/sslproxy.conf @@ -2,6 +2,10 @@ # # Use the -f command line option to start sslproxy with a config file. # See sslproxy.conf(5) and sslproxy(1) for documentation. +# +# 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. # Use CA cert (and key) to sign forged certs. # Equivalent to -c command line option. @@ -272,8 +276,15 @@ PassUsers admin #PassSite *.google.com * android #PassSite .fbcdn.net* soner android +# Load configuration from an include file +# Recursive include files are not allowed. The Include option cannot be used in +# include files. +#Include /etc/sslproxy/filterrules.conf +#Include /etc/sslproxy/proxyspecs.conf + # 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. +# Recursive macro definitions are not allowed. #Define $macro value1 value2 # Filtering rules @@ -377,6 +388,6 @@ ProxySpec { # Proxyspec specific passsites are appended to the cloned global passsites PassSite example2.com - Define $admin_users soner admin - Pass from user $admin_users desc android to cn .fbcdn.net* + Define $admins soner admin + Pass from user $admins desc android to cn .fbcdn.net* } diff --git a/src/sslproxy.conf.5 b/src/sslproxy.conf.5 index ff0809d..b6c5c9c 100644 --- a/src/sslproxy.conf.5 +++ b/src/sslproxy.conf.5 @@ -59,6 +59,10 @@ sslproxy takes a default action. If an option is defined outside any structured proxyspec, then it is used as a global default. If an option does not have a command line equivalent, -o opt=val option can be used to override it on the command line. +.LP +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. .TP \fBCACert STRING\fR Use CA cert (and key) to sign forged certs. Equivalent to -c command line option. @@ -311,13 +315,21 @@ 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. +.TP +\fBInclude STRING\fR +Load configuration from an include file. + +Recursive include files are not allowed. The Include option cannot be used in +include files. .TP \fBDefine STRING\fR 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 + Define $macro value1 value2 + +Recursive macro definitions are not allowed. .TP \fBDivert STRING\fR Divert filtering rule diverts packets to listening program, allowing SSL @@ -443,9 +455,9 @@ Divert|Split|Pass|Block|Match filtering rules .br Structured proxy specifications may consist of the options listed above. The -Proto, Addr, and Port options are mandatory, and equivalent to type, -listenaddr, and port options in one line proxyspecs, respectively. If an -option is not specified, the global default value is used. +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. .SH "FILES" .LP /etc/sslproxy/sslproxy.conf