diff options
Diffstat (limited to 'tools/man1')
| -rw-r--r-- | tools/man1/mod_qos.1 | 198 | ||||
| -rw-r--r-- | tools/man1/qsdt.1 | 46 | ||||
| -rw-r--r-- | tools/man1/qsexec.1 | 36 | ||||
| -rw-r--r-- | tools/man1/qsfilter2.1 | 99 | ||||
| -rw-r--r-- | tools/man1/qsgeo.1 | 39 | ||||
| -rw-r--r-- | tools/man1/qsgrep.1 | 28 | ||||
| -rw-r--r-- | tools/man1/qshead.1 | 16 | ||||
| -rw-r--r-- | tools/man1/qslog.1 | 109 | ||||
| -rw-r--r-- | tools/man1/qslogger.1 | 41 | ||||
| -rw-r--r-- | tools/man1/qspng.1 | 22 | ||||
| -rw-r--r-- | tools/man1/qsre.1 | 19 | ||||
| -rw-r--r-- | tools/man1/qsrespeed.1 | 16 | ||||
| -rw-r--r-- | tools/man1/qsrotate.1 | 50 | ||||
| -rw-r--r-- | tools/man1/qssign.1 | 44 | ||||
| -rw-r--r-- | tools/man1/qstail.1 | 19 |
15 files changed, 782 insertions, 0 deletions
diff --git a/tools/man1/mod_qos.1 b/tools/man1/mod_qos.1 new file mode 100644 index 0000000..7095625 --- /dev/null +++ b/tools/man1/mod_qos.1 @@ -0,0 +1,198 @@ +.TH MOD_QOS 1 "May 2023" "mod_qos Apache Module" "mod_qos" +.SH NAME +mod_qos \- quality of service module for the Apache Web server +.SH DESCRIPTION +mod_qos is a quality of service module for the Apache web server implementing control mechanisms that can provide different levels of priority to different HTTP requests. +.SH OPTIONS +.TP +QS_LocRequestLimitDefault <number>, defines the default for the QS_LocRequestLimit and QS_LocRequestLimitMatch directive. +.TP +QS_LocRequestLimit <location> <number>, defines the maximum number of concurrent requests allowed to access the specified location. Default is defined by the QS_LocRequestLimitDefault directive. +.TP +QS_LocRequestPerSecLimit <location> <number>, defines the allowed number of requests per second to a location. Requests are limited by adding a delay to each requests. This directive should be used in conjunction with QS_LocRequestLimit only. +.TP +QS_LocKBytesPerSecLimit <location> <kbytes>, defines the allowed download bandwidth to the defined kbytes per second. Responses areslowed by adding a delay to each response (non\-linear, bigger files get longer delay than smaller ones). This directive should be used in conjunction with QS_LocRequestLimit only. +.TP +QS_LocRequestLimitMatch <regex> <number>, defines the number of concurrent requests to the uri (path and query) pattern. Default is defined by the QS_LocRequestLimitDefault directive. +.TP +QS_LocRequestPerSecLimitMatch <regex> <number>, defines the allowed number of requests per second to the uri (path and query) pattern. Requests are limited by adding a delay to each requests. This directive should be used in conjunction with QS_LocRequestLimitMatch only. +.TP +QS_LocKBytesPerSecLimitMatch <regex> <kbytes>, defines the allowed download bandwidth to the location matching the defined URL (path and query) pattern. Responses are slowed down by adding a delay to each response (non\-linear, bigger files get longer delay than smaller ones). This directive should be used in conjunction with QS_LocRequestLimitMatch only. +.TP +QS_CondLocRequestLimitMatch <regex> <number> <pattern>, defines the number of concurrent requests to the uri (path and query) regex. Rule is only enforced if the QS_Cond variable matches the specified pattern (regex). +.TP +QS_EventRequestLimit <variable>[=<regex>] <number>, defines the number of concurrent events. Directive works similar to QS_LocRequestLimit, but counts the requests having the same environment variable (and optionally matching its value, too) rather than those that have the same URL pattern. +.TP +QS_EventPerSecLimit [!]<variable> <number>, defines how often requests may have the defined environment variable (literal string) set. It measures the occurrences of the defined environment variable on a request per seconds level and tries to limit this occurrence to the defined number. It works similar to as QS_LocRequestPerSecLimit, but counts only the requests with the specified variable (or without it if the variable name is prefixed by a '!'). If a request matches multiple events, the rule with the lowest bandwidth is applied. Events are limited by adding a delay to each request causing an event. +.TP +QS_EventKBytesPerSecLimit [!]<variable> <kbytes>, throttles the download bandwidth of all requests having the defined variable set to the defined kbytes per second. Responses are slowed by adding a delay to each response (non\-linear, bigger files get longer delay than smaller ones). By default, no limitation is active. This directive should be used in conjunction with QS_EventRequestLimit only (you must use the same variable name for both directives). +.TP +QS_EventLimitCount <env\-variable> <number> <seconds>, defines the maximum number of events allowed within the defined time. Requests are denied when reaching this limitation for the specified time (blocked at request level). +.TP +QS_CondEventLimitCount <env\-variable> <number> <seconds> <pattern>, same as QS_EventLimitCount but blocks requests only if the QS_Cond variable matches the specified pattern (regex). +.TP +QS_SrvMaxConn <number>, defines the maximum number of concurrent TCP connections for this server (virtual host). +.TP +QS_SrvMaxConnClose <number>[%], defines the maximum number of concurrent TCP connections until the server disables keep\-alive for this server (closes the connection after each requests. You may specify the number of connections as a percentage of MaxClients if adding the suffix '%' to the specified value. +.TP +QS_SrvMaxConnPerIP <number> [<connections>], defines the maximum number of connections per source IP address for this server (virtual host). 'connections' defines the number of busy connections of the server (all virtual hosts) to enable this limitation, default is 0. +.TP +QS_SrvMaxConnExcludeIP <addr>, excludes an IP address or address range from being limited. +.TP +QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMaxConnPerIP directive to ignore (if set to "on") the VIP status of clients. Default is "off", which means that QS_SrvMaxConnPerIP is disabled for VIPs. +.TP +QS_SrvSerialize 'on'|'off' [<seconds>], ensures that not more than one request having the QS_SrvSerialize variable set is processed at the same time by serializing them (process one after each other). +.TP +QS_SrvDataRateOff, disables the QS_SrvRequestRate and QS_SrvMinDataRate enforcement for a virtual host (only port/address based but not for name based virtual hosts). +.TP +QS_SrvRequestRate <bytes per seconds> [<max bytes per second>], defines the minimum upload throughput a client must generate. See also QS_SrvMinDataRate. +.TP +QS_SrvMinDataRate <bytes per seconds> [<max bytes per second> [<connections>]], defines the minimum upload/download throughput a client must generate (the bytes send/received by the client per seconds). This bandwidth is measured while transmitting the data (request line, header fields, request body, or response data). The client connection get closed if the client does not fulfill the required data rate and the IP address of the causing client get marked in order to be handled with low priority (see the QS_ClientPrefer directive). The "max bytes per second" activates dynamic minimum throughput control: The required minimal throughput is increased in parallel to the number of concurrent clients sending/receiving data. The "max bytes per second" setting is reached when the number of sending/receiving clients is equal to the MaxClients setting. The "connections" argument is used to specify the number of busy TCP connections a server must have to enable this feature (0 by default). No limitation is set by default. +.TP +QS_SrvMinDataRateOffEvent '+'|'\-'<env\-variable>, disables the minimal data rate enfocement (QS_SrvMinDataRate) for a certain connection if the defined environment variable has been set. The '+' prefix is used to add a variable to the configuration while the '\-' prefix is used to remove a variable. +.TP +QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMinDataRate directive to ignore (if set to "on") the VIP status of clients. Default is "off", which means that QS_SrvMinDataRate is disabled for VIPs. +.TP +QS_SrvSampleRate <seconds>, defines the sampling rate used by the QS_SrvMinDataRate directive to measure the throughput of a connection. +.TP +QS_DenyRequestLine '+'|'\-'<id> 'log'|'deny' <regular expression>, generic request line (method, path, query and protocol) filter used to deny access for requests matching the defined regular expression. '+' adds a new rule while '\-' removes a rule for a location. The action is either 'log' (access is granted but rule match is logged) or 'deny' (access is denied). +.TP +QS_DenyPath, same as QS_DenyRequestLine but applied to the path only. +.TP +QS_DenyQuery, same as QS_DenyRequestLine but applied to the query only. +.TP +QS_DenyEvent '+'|'\-'<id> 'log'|'deny' [!]<variable>, matches requests having the defined process environment variable set (or NOT set if prefixed by a '!'). The action taken for matching rules is either 'log' (access is granted but the rule match is logged) or 'deny' (access is denied). +.TP +QS_PermitUri, '+'|'\-'<id> 'log'|'deny' <regular expression>, generic request filter applied to the request uri (path and query). Only requests matching at least one QS_PermitUri pattern are allowed. If a QS_PermitUri pattern has been defined an the request does not match any rule, the request is denied albeit of any server resource availability (allow list). All rules must define the same action. Regular expression is case sensitive. +.TP +QS_DenyBody 'on'|'off', enabled body data filter (obsolete). +.TP +QS_DenyQueryBody 'on'|'off', enabled body data filter for QS_DenyQuery. +.TP +QS_PermitUriBody 'on'|'off', enabled body data filter for QS_PermitUriBody. +.TP +QS_InvalidUrlEncoding 'log'|'deny'|'off', enforces correct URL decoding in conjunction with the QS_DenyRequestLine, QS_DenyPath, and QS_DenyQuery directives. Default is "off". +.TP +QS_LimitRequestBody <bytes>, limits the allowed size of an HTTP request message body. +.TP +QS_DenyDecoding 'uni', enabled additional string decoding functions which are applied before matching QS_Deny* and QS_Permit* directives. Default is URL decoding (%xx, \xHH, '+'). +.TP +QS_DenyInheritanceOff, disable inheritance of QS_Deny* and QS_Permit* directives to a location. +.TP +QS_RequestHeaderFilter 'on'|'off'|'size', filters request headers by allowing only these headers which match the request header rules defined by mod_qos. Request headers which do not conform these definitions are either dropped or the whole request is denied. Custom request headers may be added by the QS_RequestHeaderFilterRule directive. Using the 'size' option, the header field max. size is verified only (similar to LimitRequestFieldsize but using individual values for each header type) while the pattern is ignored. +.TP +QS_ResponseHeaderFilter 'on'|'off', filters response headers by allowing only these headers which match the response header rules defined by mod_qos. Response headers which do not conform these definitions are dropped. +.TP +QS_RequestHeaderFilterRule <header name> 'drop'|'deny' <regular expression> <size>, used to add custom request header filter rules which override the internal filter rules of mod_qos. Directive is allowed in global server context only. +.TP +QS_ResponseHeaderFilterRule <header name> <regular expression> <size>, used to add custom response header filter rules which override the internal filter rules of mod_qos. Directive is allowed in global server context only. +.TP +QS_MileStone 'log'|'deny' <pattern> [<thinktime>], defines request line patterns a client must access in the defined order as they are defined in the configuration file. +.TP +QS_MileStoneTimeout <seconds>, defines the time in seconds within a client must reach the next milestone. Default are 3600 seconds. +.TP +QS_SessionCookieName <name>, defines a custom session cookie name, default is MODQOS. +.TP +QS_SessionCookiePath <path>, defines the cookie path, default is "/". +.TP +QS_SessionTimeout <seconds>, defines the session life time for a VIP. It is only used for session based (cookie) VIP identification (not for IP based). Default is 3600 seconds. +.TP +QS_SessionKey <string>, secret key used for cookie encryption. Used when using the same session cookie for multiple web servers (load balancing) or sessions should survive a server restart. By default, a random key is used which changes every server restart. +.TP +QS_VipHeaderName <name>[=<regex>] [drop], defines an HTTP response header which marks a user as a VIP. mod_qos creates a session for this user by setting a cookie, e.g., after successful user authentication. Tests optionally its value against the provided regular expression. Specify the action 'drop' if you want mod_qos to remove this control header from the HTTP response. +.TP +QS_VipIPHeaderName <name>[=<regex>] [drop], defines an HTTP response header which marks a client source IP address as a VIP. Tests optionally its value against the provided regular expression. Specify the action 'drop' if you want mod_qos to remove this control header from the HTTP response. +.TP +QS_VipUser, creates a VIP session for users which have been authenticated by the Apache server, e.g., by the standard mod_auth* modules. It works similar to the QS_VipHeaderName directive. +.TP +QS_VipIpUser, marks a source IP address as a VIP if the user has been authenticated by the Apache server, e.g. by the standard mod_auth* modules. It works similar to the QS_VipIPHeaderName directive. +.TP +QS_UserTrackingCookieName <name> [<path>] [<domain>] ['session'] ['jsredirect'], enables the user tracking cookie by defining a cookie name. The "path" parameter is an option cookie check page which is used to ensure the client accepts cookies. The "domain" option defines the Domain attriibute for the Set\-Cookie header. The option "session" indicates that the cookie shall be a session cookie expiring when the user closes it's browser. User tracking requires mod_unique_id. This feature is disabled by default. Ignores QS_LogOnly. +.TP +QS_SetEnvIf [!]<variable1>[=<regex>] [[!]<variable2>] [!]<variable=value>, sets (or unsets) the 'variable=value' (literal string) if variable1 (literal string) AND variable2 (literal string) are set in the request environment variable list (not case sensitive). This is used to combine multiple variables to a new event type. Alternatively, a regular expression can be specified for variable1's value and variable2 must be omitted in order to simply set a new variable if the regular expression matches. +.TP +QS_SetEnvIfCmpP <env\-variable1> eq|ne|gt|lt <env\-variable2> [!]<env\-variable>[=<value>], sets the specified environment variable if the specified env\-variables are alphabetically or numerical equal (eq), not equal (ne), greater (gt), less (lt). +.TP +QS_SetEnvIfQuery <regex> [!]<variable>[=value], directive works quite similar to the SetEnvIf directive of the Apache module mod_setenvif, but the specified regex is applied against the query string portion of the request line. The directive recognizes the occurrences of $1..$9 within value and replaces them by the sub\-expressions of the defined regex pattern. +.TP +QS_SetEnvIfParp <regex> [!]<variable>[=value], directive parsing the request payload using the Apache module mod_parp. It matches the request URL query and the HTTP request message body data as well ('application/x\-www\-form\-urlencoded', 'multipart/form\-data', and 'multipart/mixed') and sets the defined process variable (quite similar to the QS_SetEnvIfQuery directive). The directive recognizes the occurrences of $1..$9 within value and replaces them by the sub\-expressions of the defined regex pattern. This directive activates mod_parp for every request to the virtual host. You may deactivate mod_parp for selected requests using the SetEnvIf directive: unset the variable 'parp' to do so. Important: request message body processing requires that the server loads the whole request into its memory (at least twice the length of the message). You should limit the allowed size of the HTTP request message body using the QS_LimitRequestBody directive when using QS_SetEnvIfParp! +.TP +QS_SetEnvIfBody <regex> [!]<variable>[=value], parses the request body using the Apache module mod_parp. Specify the content types to process using the mod_parp directive PARP_BodyData and ensure that mod_parp is enabled using the SetEnvIf directive of the Apache module mod_setenvif. You should limit the allowed size of HTTP requests message body using the QS_LimitRequestBody directive when using mod_parp. The directive recognizes the occurrence of $1 within the variable value and replaces it by the sub\-expressions of the defined regex pattern. +.TP +QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus) +.TP +QS_SetEnvIfStatus <status code> <variable>, adds the defined request environment variable if the HTTP status code matches the defined value. The value 'QS_SrvMinDataRate' may be used as a special status code to set a QS_Block event in order to handle connection close events caused by QS_SrvMinDataRate rules while the status 'NullConnection' may be used to mark connections which are closed before any HTTP request has ever been received. The 'QS_SrvMaxConnPerIP' value may be used to count QS_Block events for connections closed by the QS_SrvMaxConnPerIP directive. The 'BrokenConnection' value may be used to mark clients not reading the full HTTP response. +.TP +QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody) +.TP +QS_SetEnvIfResBody <string> [!]<variable>, adds the defined request environment variable (e.g. QS_Block) if the HTTP response body contains the defined literal string. Supports only one pattern per location. +.TP +QS_SetEnv <variable> <value>, sets the defined variable with the value where the value string may contain other environment variables surrounded by "${" and "}". The variable is only set if all defined variables within the value can be resolved. +.TP +QS_SetReqHeader [!]<header name> <variable> ['late'], sets the defined HTTP request header to the request if the specified environment variable is set. +.TP +QS_UnsetReqHeader <header name>, Removes the specified header from the request. +.TP +QS_UnsetResHeader <header name>, Removes the specified header from the response. +.TP +QS_SetEnvResHeader <header name> [drop], sets the defined HTTP response header (name and value) to the request environment variables Deletes the header if the action 'drop' has been specified. +.TP +QS_SetEnvResHeaderMatch <header name> <regex>, sets the defined HTTP response header (name and value) to the request environment variables if the specified regular expression matches the header value. +.TP +QS_SetEnvRes <variable> <regex> <variable2>[=<value>], sets the environment variable2 if the regular expression matches against the value of the environment variable. Occurrences of $1..$9 within the value and replace them by parenthesized subexpressions of the regular expression. +.TP +QS_RedirectIf <variable> <regex> [<code>:]<url>, redirects the client to the configured url if the regular expression matches the value of the the environment variable. +.TP +QS_ClientEntries <number>, defines the number of individual clients managed by mod_qos. Default is 50000. Directive is allowed in global server context only. +.TP +QS_ClientPrefer [<percent>], prefers known VIP clients when server has less than 80% (or the configured value) of free TCP connections. Preferred clients are VIP clients (or those without any negative penalties), see QS_VipHeaderName directive. Directive is allowed in global server context only. +.TP +QS_ClientTolerance <percent>, defines the allowed tolerance (variation) from a "normal" client (average) in percent. Default is 20%. Directive is allowed in global server context only. +.TP +QS_ClientContentTypes <html> <css/js> <images> <other> <304>, defines the distribution of HTTP response content types a client normally receives when accessing the server. mod_qos normally learns the average behavior automatically by default but you may specify a static configuration in order to avoid influences by a high number of abnormal clients. +.TP +QS_ClientEventBlockCount <number> [<seconds>], defines the maximum number of QS_Block allowed within the defined time (default are 10 minutes). Directive is allowed in global server context only. +.TP +QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or address range from being limited by QS_ClientEventBlockCount. +.TP +QS_ClientEventLimitCount <number> [<seconds> [<variable>]], defines the maximum number of the specified environment variable (QS_Limit by default) allowed within the defined time (default are 10 minutes). Directive is allowed in global server context only. +.TP +QS_CondClientEventLimitCount <number> <seconds> <variable> <pattern>, defines the maximum number of the specified environment variable allowed within the defined time. Directive works similar as QS_ClientEventLimitCount but requests are only blocked if the QS_Cond variable matches the defined pattern (regex). Directive is allowed in global server context only. +.TP +QS_ClientEventPerSecLimit <number>, defines the number events pro seconds on a per client (source IP) basis. Events are identified by requests having the QS_Event variable set. Directive is allowed in global server context only. +.TP +QS_ClientEventRequestLimit <number>, defines the allowed number of concurrent requests coming from the same client source IP address having the QS_EventRequest variable set. Directive is allowed in global server context only. +.TP +QS_ClientSerialize, serializes requests having the QS_Serialize variable set if they are coming from the same IP address. +.TP +QS_ClientIpFromHeader <header>, defines a HTTP request header to read the client's source IP address from (instead of taking the IP address of the client opening the TCP connection). This may be used for the QS_ClientEventLimitCount directive and QS_Country variable. +.TP +QS_ClientGeoCountryDB <path>, path to the geograpical database file. +.TP +QS_ClientGeoCountryPriv <list> <connections> ['excludeUnknown'], defines a comma separated list of country codes for origin client IP address which are allowed to access the server if the number of busy TCP connections reaches the defined number of connections while others are denied access. Clients whose IP can't be mapped to a country code can be excluded from the limitation by configuring the 'excludeUnknown' argument. +.TP +QS_ErrorPage <url>, defines a custom error page. +.TP +QS_ErrorResponseCode <code>, defines the HTTP response code which is used when a request is denied, default is 500. +.TP +QS_ForcedClose 'on'|'off', defines if mod_qos connection handler shall exit with an error code (on) or not. Default is on (except for Apache 2.4.49). +.TP +QS_LogOnly 'on'|'off', enables the log only mode of the module where no limitations are enforced. Default is off. Directive is allowed in global server context only. +.TP +QS_LogEnv 'on'|'off', enables logging of environment variables. +.TP +QS_SupportIPv6 'on'|'off', enables IPv6 address support. Default is on. +.TP +QS_SemMemFile <path>, optional path to a directory or file which shall be used for file based semaphores/shared memory usage, e.g. /var/tmp. +.TP +QS_MaxClients <number>, optional override for mod_qos's MaxClients/MaxRequestWorkers calculation which defines the maximum number of TCP connections the server can handle. +.TP +QS_DisableHandler 'on'|'off', disables the qos\-viewer and qos\-console for a virtual host +.TP +QS_Status 'on'|'off', writes a log message containing server statistics once every minute. Default is off. +.TP +QS_EventCount 'on'|'off', enables error event counting (counters are shown in the machine\-readable version of the status viewer). Default is off. +.TP +QSLog <arg>, used to configure a global (per Apache instance) 'qslog' logger. +.SH AUTHOR +Pascal Buchbinder, http://mod\-qos.sourceforge.net/ diff --git a/tools/man1/qsdt.1 b/tools/man1/qsdt.1 new file mode 100644 index 0000000..ed58005 --- /dev/null +++ b/tools/man1/qsdt.1 @@ -0,0 +1,46 @@ +.TH QSDT 1 "May 2023" "mod_qos utilities 11.74" "qsdt man page" + +.SH NAME +qsdt calculates the elapsed time between two related log messages. +.SH SYNOPSIS +qsdt [\-t <regex>] \-i <regex> \-s <regex> \-e <regex> [\-v] [<path>] +.SH DESCRIPTION +qsdt is a simple tool to search two different messages in a log file and calculates the elapsed time between these lines. The two log messages need a common identifier such an unique request id (UNIQUE_ID), a thread id, or a transaction code. +.SH OPTIONS +.TP +\-t <regex> +Defines a pattern (regular expression) matching the log line's timestamp. The pattern must include two sub\-expressions, one matching hours, minutes and seconds the other matching the milliseconds. Default pattern is ([0\-9]{2}:[0\-9]{2}:[0\-9]{2})[.,]([0\-9]{3}) +.TP +\-i <regex> +Pattern (regular expression) matching the identifier which the two messages have in common. The sub\-expression defines the part which needs to be extracted from the matching string. Note: You can also use the start (\-s) and end (\-e) pattern to define the sub\-expression matching this identifier. +.TP +\-s <regex> +Defines the pattern (regular expression or literal string) identifying the first (start) of the two messages. +.TP +\-e <regex> +Defines the pattern (regular expression or literal string) identifying the second (end) of the two messages. +.TP +\-v +Verbose mode. +.TP +<path> +Defines the input file to process. qsdt reads from from standard input if this parameter is omitted. +.SH EXAMPLE +Sample command line arguments: + + \-i ' ([a\-z0\-9]+) [A\-Z]+ ' \-s 'Received Request' \-e 'Received Response' + + matching those sample log messages: + 2018\-03\-12 16:34:08.653 threadid23 INFO Received Request + 2018\-03\-13 16:35:09.891 threadid23 DEBUG MessageHandler Received Response + +.SH NOTE +The four patterns (t,i,s,e) are concatenated into two search patterns: + first (start): [t (HH:MM:SS)(SSS) ].*[i (id) ].*[s ] + second (end): [t (HH:MM:SS)(SSS) ].*[i (id) ].*[e ] + +And the three sub\-expression are used to extract the timestamp and the unique identifier that the start and end message have in common. This means that you could specify the sub\-expression for the unique identifier in the start (\-s) or end (\-e) pattern alternatively, e.g. in case the identifier is at the end of the log line. +.SH SEE ALSO +qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsexec.1 b/tools/man1/qsexec.1 new file mode 100644 index 0000000..0ae6030 --- /dev/null +++ b/tools/man1/qsexec.1 @@ -0,0 +1,36 @@ +.TH QSEXEC 1 "May 2023" "mod_qos utilities 11.74" "qsexec man page + +.SH NAME +qsexec \- parses the data received via stdin and executes the defined command on a pattern match. + +.SH SYNOPSIS +qsexec \-e <pattern> [\-t <number>:<sec>] [\-c <pattern> [<command string>]] [\-p] [\-u <user>] <command string> +.SH DESCRIPTION +qsexec reads log lines from stdin and searches for the defined pattern. It executes the defined command string on pattern match. +.SH OPTIONS +.TP +\-e <pattern> +Specifies the search pattern causing an event which shall trigger the command. +.TP +\-t <number>:<sec> +Defines the number of pattern match within the the defined number of seconds in order to trigger the command execution. By default, every pattern match causes a command execution. +.TP +\-c <pattern> [<command string>] +Pattern which clears the event counter. Executes optionally a command if an event command has been executed before. +.TP +\-p +Writes data also to stdout (for piped logging). +.TP +\-u <name> +Become another user, e.g. www\-data. +.TP +<command string> +Defines the event command string where $0\-$9 are substituted by the submatches of the regular expression. +.SH EXAMPLE +Executes the deny.sh script providing the IP address of the client causing a mod_qos(031) messages whenever the log message appears 10 times within at most one minute: + ErrorLog "|/usr/bin/qsexec \-e \\'mod_qos\\(031\\).*, c=([0\-9a\-zA\-Z:.]*)\\' \-t 10:60 \\'/usr/local/bin/deny.sh $1\\'" + +.SH SEE ALSO +qsdt(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsfilter2.1 b/tools/man1/qsfilter2.1 new file mode 100644 index 0000000..8ec845b --- /dev/null +++ b/tools/man1/qsfilter2.1 @@ -0,0 +1,99 @@ +.TH QSFILTER2 1 "May 2023" "mod_qos utilities 11.74" "qsfilter2 man page" + +.SH NAME +qsfilter2 \- an utility to generate mod_qos request line rules out from existing access/audit log data. +.SH SYNOPSIS +qsfilter2 \-i <path> [\-c <path>] [\-d <num>] [\-h] [\-b <num>] [\-p|\-s|\-m|\-o] [\-l <len>] [\-n] [\-e] [\-u 'uni'] [\-k <prefix>] [\-t] [\-f <path>] [\-v 0|1|2] +.SH DESCRIPTION +mod_qos implements a request filter which validates each request line. The module supports both, negative and positive security model. The QS_Deny* directives are used to specify request line patterns which are not allowed to access the server (negative security model / deny list). These rules are used to restrict access to certain resources which should not be available to users or to protect the server from malicious patterns. The QS_Permit* rules implement a positive security model (allow list). These directives are used to define allowed request line patterns. Request which do not match any of these patterns are not allowed to access the server. + +qsfilter2 is an audit log analyzer used to generate filter rules (perl compatible regular expressions) which may be used by mod_qos to deny access for suspect requests (QS_PermitUri rules). It parses existing audit log files in order to generate request patterns covering all allowed requests. +.SH OPTIONS +.TP +\-i <path> +Input file containing request URIs. The URIs for this file have to be extracted from the servers access logs. Each line of the input file contains a request URI consisting of a path and and query. + Example: + /aaa/index.do + /aaa/edit?image=1.jpg + /aaa/image/1.jpg + /aaa/view?page=1 + /aaa/edit?document=1 + +These access log data must include current request URIs but also request lines from previous rule generation steps. It must also include request lines which cover manually generated rules. You may use the 'qos\-path' and 'qos\-query' variables to create an audit log containing all request data (path and query/body data). Example: 'CustomLog audit_log %{qos\-path}n%{qos\-query}n'. See also http://mod\-qos.sourceforge.net#qsfiltersample about the module settings. +.TP +\-c <path> +mod_qos configuration file defining QS_DenyRequestLine and QS_PermitUri directives. qsfilter2 generates rules from access log data automatically. Manually generated rules (QS_PermitUri) may be provided from this file. Note: each manual rule must be represented by a request URI in the input data (\-i) in order to make sure not to be deleted by the rule optimisation algorithm. QS_Deny* rules from this file are used to filter request lines which should not be used for allow list rule generation. + Example: + # manually defined allow list rule: + QS_PermitUri +view deny "^[/a\-zA\-Z0\-9]+/view\\?(page=[0\-9]+)?$" + # filter unwanted request line patterns: + QS_DenyRequestLine +printable deny ".*[\\x00\-\\x19].*" + + +.TP +\-d <num> +Depth (sub locations) of the path string which is defined as a literal string. Default is 1. +.TP +\-h +Always use a string representing the handler name in the path even the url does not have a query. See also \-d option. +.TP +\-b <num> +Replaces url pattern by the regular expression when detecting a base64/hex encoded string. Detecting sensibility is defined by a numeric value. You should use values higher than 5 (default) or 0 to disable this function. +.TP +\-p +Represents query by pcre only (no literal strings). +.TP +\-s +Uses one single pcre for the whole query string. +.TP +\-m +Uses one pcre for multiple query values (recommended mode). +.TP +\-o +Does not care the order of query parameters. +.TP +\-l <len> +Outsizes the query length by the defined length ({0,size+len}), default is 10. +.TP +\-n +Disables redundant rules elimination. +.TP +\-e +Exit on error. +.TP +\-u 'uni' +Enables additional decoding methods. Use the same settings as you have used for the QS_Decoding directive. +.TP +\-k <prefix> +Prefix used to generate rule identifiers (QSF by default). +.TP +\-t +Calculates the maximal latency per request (worst case) using the generated rules. +.TP +\-f <path> +Filters the input by the provided path (prefix) only processing matching lines. +.TP +\-v <level> +Verbose mode. (0=silent, 1=rule source, 2=detailed). Default is 1. Don't use rules you haven't checked the request data used to generate it! Level 1 is highly recommended (as long as you don't have created the log data using your own web crawler). +.SH OUTPUT +The output of qsfilter2 is written to stdout. The output contains the generated QS_PermitUri directives but also information about the source which has been used to generate these rules. It is very important to check the validity of each request line which has been used to calculate the QS_PermitUri rules. Each request line which has been used to generate a new rule is shown in the output prefixed by "ADD line <line number>:". These request lines should be stored and reused at any later rule generation (add them to the URI input file). The subsequent line shows the generated rule. At the end of data processing a list of all generated QS_PermitUri rules is shown. These directives may be used withn the configuration file used by mod_qos. +.SH EXAMPLE + qsfilter2 \-i loc.txt \-c httpd.conf \-m \-e + ... + # ADD line 1: /aaa/index.do + # 003 ^(/[a\-zA\-Z0\-9\\\-_]+)+[/]?\\.?[a\-zA\-Z]{0,4}$ + # ADD line 3: /aaa/view?page=1 + # \-\-\- ^[/a\-zA\-Z0\-9]+/view\\?(page=[0\-9]+)?$ + # ADD line 4: /aaa/edit?document=1 + # 004 ^[/a\-zA\-Z]+/edit\\?((document)(=[0\-9]*)*[&]?)*$ + # ADD line 5: /aaa/edit?image=1.jpg + # 005 ^[/a\-zA\-Z]+/edit\\?((image)(=[0\-9\\.a\-zA\-Z]*)*[&]?)*$ + ... + QS_PermitUri +QSF001 deny "^[/a\-zA\-Z]+/edit\\?((document|image)(=[0\-9\\.a\-zA\-Z]*)*[&]?)*$" + QS_PermitUri +QSF002 deny "^[/a\-zA\-Z0\-9]+/view\\?(page=[0\-9]+)?$" + QS_PermitUri +QSF003 deny "^(/[a\-zA\-Z0\-9\\\-_]+)+[/]?\\.?[a\-zA\-Z]{0,4}$" + +.SH SEE ALSO +qsdt(1), qsexec(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsgeo.1 b/tools/man1/qsgeo.1 new file mode 100644 index 0000000..9c0e1be --- /dev/null +++ b/tools/man1/qsgeo.1 @@ -0,0 +1,39 @@ +.TH QSGEO 1 "May 2023" "mod_qos utilities 11.74" "qsgeo man page" + +.SH NAME +qsgeo \- an utility to lookup a client's country code. +.SH SYNOPSIS +qsgeo \-d <path> [\-l] [\-s] [\-ip <ip>] +.SH DESCRIPTION +Use this utility to resolve the country codes of IP addresses within existing log files. The utility reads the log file data from stdin and writes them, with the injected country code, to stdout. +.SH OPTIONS + +.TP +\-d <path> +Specifies the path to the geographical database files (CSV file containing IP address ranges and country codes). +.TP +\-s +Writes a summary of the requests per country only. +.TP +\-l +Writes the database to stdout (ignoring stdin) inserting local (127.*) and private (10.*, 172.16*, 192.168.*) network addresses. +.TP +\-ip <ip> +Resolves a single IP address instead of processing a log file. +.SH EXAMPLE +Reading the file access.log and adding the country code to the IP address field: + + cat access.log | qsgeo \-d GeoIPCountryWhois.csv + +Reading the file access.log and showing a summary only: + + cat access.log | qsgeo \-d GeoIPCountryWhois.csv \-s + +Resolving a single IP address: + + qsgeo \-d GeoIPCountryWhois.csv \-ip 192.84.12.23 + +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsgrep.1 b/tools/man1/qsgrep.1 new file mode 100644 index 0000000..5bba3d9 --- /dev/null +++ b/tools/man1/qsgrep.1 @@ -0,0 +1,28 @@ +.TH QSGREP 1 "May 2023" "mod_qos utilities 11.74" "qsgrep man page" + +.SH NAME +qsgrep \- prints matching patterns within a file. +.SH SYNOPSIS +qsgrep \-e <pattern> \-o <sub string> [<path>] +.SH DESCRIPTION +qsgrep is a simple tool to search patterns within files. It uses regular expressions to find patterns and prints the submatches within a pre\-defined format string. +.SH OPTIONS +.TP +\-e <pattern> +Specifies the search pattern. +.TP +\-o <string> +Defines the output string where $0\-$9 are substituted by the submatches of the regular expression. +.TP +<path> +Defines the input file to process. qsgrep reads from from standard input if this parameter is omitted. + +.SH EXAMPLE +Shows the IP addresses of clients causing mod_qos(031) messages): + + qsgrep \-e 'mod_qos\\(031\\).*, c=([a\-zA\-Z0\-9:.]*)' \-o 'ip=$1' error_log + +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qshead.1 b/tools/man1/qshead.1 new file mode 100644 index 0000000..b7956a8 --- /dev/null +++ b/tools/man1/qshead.1 @@ -0,0 +1,16 @@ +.TH QSHEAD 1 "May 2023" "mod_qos utilities 11.74" "qshead man page" + +.SH NAME +qshead \- an utility reading from stdin and printing all lines to stdout until reaching the defined pattern. +.SH SYNOPSIS +qshead \-p <pattern> +.SH DESCRIPTION +qshead reads lines from stdin and prints them to stdout until a line contains the specified pattern (literal string). +.SH OPTIONS +.TP +\-p <pattern> +Search pattern (literal string). +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1) qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qslog.1 b/tools/man1/qslog.1 new file mode 100644 index 0000000..140a8a8 --- /dev/null +++ b/tools/man1/qslog.1 @@ -0,0 +1,109 @@ +.TH QSLOG 1 "May 2023" "mod_qos utilities 11.74" "qslog man page" + +.SH NAME +qslog \- collects request statistics from access log data. +.SH SYNOPSIS +qslog \-f <format_string> \-o <out_file> [\-p[c|u[c]] [\-v]] [\-x [<num>]] [\-u <name>] [\-m] [\-c <path>] +.SH DESCRIPTION +qslog is a real time access log analyzer. It collects the data from stdin. The output is written to the specified file every minute and includes the following entries: + \- requests per second (r/s) + \- number of requests within measured time (req) + \- bytes sent to the client per second (b/s) + \- bytes received from the client per second (ib/s) + \- response status codes within the last minute (1xx,2xx,3xx,4xx,5xx) + \- average response duration (av) + \- average response duration in milliseconds (avms) + \- distribution of response durations in seconds within the last minute +(<1s,1s,2s,3s,4s,5s,>5s) + \- distribution of response durations faster than a second within the last minute +(0\-49ms,50\-99ms,100\-499ms,500\-999ms) + \- number of established (new) connections within the measured time (esco) + \- average system load (sl) + \- free memory (m) (not available for all platforms) + \- number of client ip addresses seen withn the last 600 seconds (ip) + \- number of different users seen withn the last 600 seconds (usr) + \- number of events identified by the 'E' format character + \- number of mod_qos events within the last minute (qV=create session, +qv=VIP IP,qS=session pass, qD=access denied, qK=connection closed, qT=dynamic keep\-alive, qL=request/response slow down, qs=serialized request, qA=connection abort, qU=new user tracking cookie) +.SH OPTIONS +.TP +\-f <format_string> +Defines the log data format and the positions of data elements processed by this utility. See to the 'LogFormat' directive of the httpd.conf file to see the format definitions of the servers access log data. + qslog knows the following elements: + I defines the client ip address (%h) + R defines the request line (%r) + S defines HTTP response status code (%s) + B defines the transferred bytes (%b or %O) + i defines the received bytes (%I) + D defines the request duration in microseconds (%D) + t defines the request duration in milliseconds (may be used instead of D) + T defines the request duration in seconds (may be used instead of D or t) (%T) + k defines the number of keepalive requests on the connection (%k) + U defines the user tracking id (%{mod_qos_user_id}e) + Q defines the mod_qos_ev event message (%{mod_qos_ev}e) + C defines the element for the detailed log (\-c option), e.g. "%U" + s arbitrary counter to add up (sum within a minute) + a arbitrary counter to build an average from (average per request) + A arbitrary counter to build an average from (average per request) + M arbitrary counter to measure the maximum value reached (peak) + E comma separated list of event strings + c content type (%{content\-type}o), available in \-pc mode only + m request method (GET/POST) (%m), available in \-pc mode only + . defines an element to ignore (unknown string) + +.TP +\-o <out_file> +Specifies the file to store the output to. stdout is used if this option is not defined. +.TP +\-p +Used for post processing when reading the log data from a file (cat/pipe). qslog is started using it's offline mode (extracting the time stamps from the log lines) in order to process existing log files. The option "\-pc" may be used alternatively if you want to gather request information per client (identified by IP address (I) or user tracking id (U) showing how many request each client has performed within the captured period of time). "\-pc" supports the format characters IURSBTtDkMEcm. The option "\-pu" collects statistics on a per URL level (supports format characters RSTtD). "\-puc" is very similar to "\-pu" but cuts the end (handler) of each URL. +.TP +\-v +Verbose mode. +.TP +\-x [<num>] +Rotates the output file once a day (move). You may specify the number of rotated files to keep. Default are 14. +.TP +\-u <name> +Becomes another user, e.g. www\-data. +.TP +\-m +Calculates free system memory every minute. +.TP +\-c <path> +Enables the collection of log statistics for different request types. 'path' specifies the necessary rule file. Each rule consists of a rule identifier and a regular expression to identify a request seprarated by a colon, e.g., 01:^(/a)|(/c). The regular expressions are matched against the log data element which has been identified by the 'C' format character. +.SH VARIABLES +The following environment variables are known to qslog: +.TP +QSEVENTPATH=<path> +Defines a file containing a comma or new line separated list of known event strings expected within the log filed identified by the 'E' format character. +.TP +QSCOUNTERPATH=<path> +Defines a file containing a by new line separated list of rules which reflect possible QS_ClientEventLimitCount directive settings (for simulation purpose / \-pc option). The 'E' format character defines the event string in the log to match (literal string) the 'event1' and 'event2' event names against. + +Rule syntax: <name>:<event1>\-<n>*<event2>/<duration>=<limit> + 'name' defines the name you have given to the rule entry and is logged along with +with the number of times the 'limit' has been reached within the 'duration'. + 'event1' defines the variable name (if found in 'E') to increment the counter. + 'event2' defines the variable name (if found in 'E') to decrement the counter (and +the parameter 'n' defines by how much). + 'duration' defines the measure interval (in seconds) used for the +QS_ClientEventLimitCount directive. + 'limit' defines the threshold (number) defined for the QS_ClientEventLimitCount +directive. + +Note: If the 'name' parameter is prefixed by 'STATUS', the rule is applied against the HTTP status code 'S' and the 'event1' string shall contain a list of relevant status codes separated by an underscore (while 'event2' is ignored). +.SH EXAMPLE +Configuration using pipped logging: + + CustomLog "|/usr/bin/qslog \-f ISBDQ \-x \-o /var/log/apache/stat.csv" "%h %>s %b %D %{mod_qos_ev}e" + +Post processing: + + LogFormat "%t %h \\"%r\\" %>s %b \\"%{User\-Agent}i\\" %T" + cat access.log | qslog \-f ..IRSB.T \-o stat.csv \-p + +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qslogger.1 b/tools/man1/qslogger.1 new file mode 100644 index 0000000..8c8961f --- /dev/null +++ b/tools/man1/qslogger.1 @@ -0,0 +1,41 @@ +.TH QSLOGGER 1 "May 2023" "mod_qos utilities 11.74" "qslogger man page" + +.SH NAME +qslogger \- another shell command interface to the system log module (syslog). +.SH SYNOPSIS +qslogger [\-t <tag>] [\-f <facility>] [\-l <level>] [\-x <prefix>] [\-r <expression>] [\-d <level>] [\-u <name>] [\-p] +.SH DESCRIPTION +Use this utility to forward log messages to the systems syslog facility, e.g., to forward the messages to a remote host. It reads data from stdin. +.SH OPTIONS + +.TP +\-t <tag> +Defines the tag name which shall be used to define the origin of the messages, e.g. 'httpd'. +.TP +\-f <facility> +Defines the syslog facility. Default is 'daemon'. +.TP +\-u <name> +Becomes another user, e.g. www\-data. +.TP +\-l <level> +Defines the minimal severity a message must have in order to be forwarded. Default is 'DEBUG' (forwarding everything). +.TP +\-x <prefix> +Allows you to add a prefix (literal string) to every message. +.TP +\-r <expression> +Specifies a regular expression which shall be used to determine the severity (syslog level) for each log line. The default pattern '^\\[[0\-9a\-zA\-Z :]+\\] \\[([a\-z]+)\\] ' can be used for Apache error log messages but you may configure your own pattern matching other log formats. Use brackets to define the pattern enclosing the severity string. Default level (if severity can't be determined) is defined by the option '\-d' (see below). +.TP +\-d <level> +The default severity if the specified pattern (\-r) does not match and the message's severity can't be determined. Default is 'NOTICE'. +.TP +\-p +Writes data also to stdout (for piped logging). +.SH EXAMPLE + ErrorLog "|/usr/bin/qslogger \-t apache \-f local7" + +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qspng.1 b/tools/man1/qspng.1 new file mode 100644 index 0000000..d3ff0c4 --- /dev/null +++ b/tools/man1/qspng.1 @@ -0,0 +1,22 @@ +.TH QSPNG 1 "May 2023" "mod_qos utilities 11.74" "qspng man page" + +.SH NAME +qspng \- an utility to draw a png graph from qslog(1) output data. +.SH SYNOPSIS +qspng \-i <stat_log_file> \-p <parameter> \-o <out_file> [\-10] +.SH DESCRIPTION +qspng is a tool to generate png (portable network graphics) raster images files from semicolon separated data generated by the qslog utility. It reads up to the first 1440 entries (24 hours) and prints a graph using the values defined by the 'parameter' name. +.SH OPTIONS +.TP +\-i <stats_log_file> +Input file to read data from. +.TP +\-p <parameter> +Parameter name, e.g. r/s or usr. +.TP +\-o <out_file> +Output file name, e.g. stat.png. +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslogger(1), qslog(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsre.1 b/tools/man1/qsre.1 new file mode 100644 index 0000000..b011661 --- /dev/null +++ b/tools/man1/qsre.1 @@ -0,0 +1,19 @@ +.TH QSRE 1 "May 2023" "mod_qos utilities 11.74" "qsre man page" + +.SH NAME +qsre matches a regular expression against test strings. +.SH SYNOPSIS +qsre <string>|<path> <pcre>|<path> +.SH DESCRIPTION +Regular expression test tool. The provided regular expression (pcre, caseless matching, "." matches anything incl. newline) is appplied against the provided test strings to verify if the pattern matches. +.SH OPTIONS +.TP +<string>|<path> +The first argument either defines a single test string of a path to a file containing either multiple test strings or a test pattern with newline characters (text). +.TP +<pcre>|<path> +The second argument either defines a regular expression or a path to a file containing the expression. +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsrespeed(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsrespeed.1 b/tools/man1/qsrespeed.1 new file mode 100644 index 0000000..15207a8 --- /dev/null +++ b/tools/man1/qsrespeed.1 @@ -0,0 +1,16 @@ +.TH QSRESPEED 1 "May 2023" "mod_qos utilities 11.74" "qsrespeed man page" + +.SH NAME +Tool to compare / estimate the processing time for (Perl\-compatible) regular expressions (PCRE). +.SH SYNOPSIS +qsrespeed <path> +.SH DESCRIPTION +qsrespeed loads regular expressions from the provided file and matches them against a built\-in set of strings measuring the time needed to process them. It's a benchmark too to judge the expressions you have defined regarding the potential CPU consumption. +.SH OPTIONS +.TP +<path> +Defines the input file to process. The file consists a list of (separated by a newline character) regular expressions to test +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrotate(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qsrotate.1 b/tools/man1/qsrotate.1 new file mode 100644 index 0000000..754e8f4 --- /dev/null +++ b/tools/man1/qsrotate.1 @@ -0,0 +1,50 @@ +.TH QSROTATE 1 "May 2023" "mod_qos utilities 11.74" "qsrotate man page" + +.SH NAME +qsrotate \- a log rotation tool (similar to Apache's rotatelogs). +.SH SYNOPSIS +qsrotate \-o <file> [\-s <sec> [\-t <hours>]] [\-b <bytes>] [\-f] [\-z] [\-g <num>] [\-u <name>] [\-m <mask>] [\-p] [\-d] +.SH DESCRIPTION +qsrotate reads from stdin (piped log) and writes the data to the provided file rotating the file after the specified time. +.SH OPTIONS +.TP +\-o <file> +Output log file to write the data to (use an absolute path). +.TP +\-s <sec> +Rotation interval in seconds, default are 86400 seconds. +.TP +\-t <hours> +Offset to UTC (enables also DST support), default is 0. +.TP +\-b <bytes> +File size limitation (default/max. are 2147352576 bytes, min. are 1048576 bytes). +.TP +\-f +Forced log rotation at the specified interval even no data is written. +.TP +\-z +Compress (gzip) the rotated file. +.TP +\-g <num> +Generations (number of files to keep). +.TP +\-u <name> +Become another user, e.g. www\-data. \-m <mask> +File permission which is either 600, 640, 660 (default) or 664. +.TP +\-p +Writes data also to stdout (for piped logging). \-d +Line\-by\-line data reading prefixing every line with a timestamp. +.SH EXAMPLE + TransferLog "|/usr/bin/qsrotate \-f \-z \-g 3 \-o /var/log/apache/access.log \-s 86400" + +The name of the rotated file will be /dest/filee.YYYYmmddHHMMSS where YYYYmmddHHMMSS is the system time at which the data has been rotated. +.SH NOTE + \- Each qsrotate instance must use an individual file. + \- You may trigger a file rotation manually by sending the signal USR1 +to the process. +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qsre(1), qsrespeed(1), qspng(1), qssign(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qssign.1 b/tools/man1/qssign.1 new file mode 100644 index 0000000..ec3ed8d --- /dev/null +++ b/tools/man1/qssign.1 @@ -0,0 +1,44 @@ +.TH QSSIGN 1 "May 2023" "mod_qos utilities 11.74" "qssign man page" + +.SH NAME +qssign \- an utility to sign and verify the integrity of log data. +.SH SYNOPSIS +qssign \-s|S <secret> [\-e] [\-v] [\-u <name>] [\-f <regex>] [\-a 'sha1'|'sha256'] +.SH DESCRIPTION +qssign is a log data integrity check tool. It reads log data from stdin (pipe) and writes the data to stdout adding a sequence number and signature to ever log line. +.SH OPTIONS +.TP +\-s <secret> +Passphrase used to calculate signature. +.TP +\-S <program> +Specifies a program which writes the passphrase to stdout. +.TP +\-e +Writes start/end marker when starting/stopping data signing. +.TP +\-v +Verification mode checking the integrity of signed data. +.TP +\-u <name> +Becomes another user, e.g. www\-data. +.TP +\-f <regex> +Filter pattern (case sensitive regular expression) for messages which do not need to be signed. +.TP +\-a 'sha1'|'sha256' +Specifies the algorithm to use. Default is sha1. +.SH EXAMPLE +Sign: + + TransferLog "|/usr/bin/qssign \-s password \-e |/usr/bin/qsrotate \-o /var/log/apache/access.log" + + +Verify: + + cat access.log | qssign \-s password \-v + +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qstail(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ diff --git a/tools/man1/qstail.1 b/tools/man1/qstail.1 new file mode 100644 index 0000000..0755c0e --- /dev/null +++ b/tools/man1/qstail.1 @@ -0,0 +1,19 @@ +.TH QSTAIL 1 "May 2023" "mod_qos utilities 11.74" "qstail man page" + +.SH NAME +qstail \- an utility printing the end of a log file starting at the specified pattern. +.SH SYNOPSIS +qstail \-i <path> \-p <pattern> +.SH DESCRIPTION +qstail shows the end of a log file beginning with the line containing the specified pattern. This may be used to show all lines which has been written after a certain event (e.g., server restart) or time stamp. +.SH OPTIONS +.TP +\-i <path> +Input file to read the data from. +.TP +\-p <pattern> +Search pattern (literal string). +.SH SEE ALSO +qsdt(1), qsexec(1), qsfilter2(1), qsgeo(1), qsgrep(1), qshead(1), qslog(1), qslogger(1), qspng(1), qsre(1), qsrespeed(1), qsrotate(1), qssign(1) +.SH AUTHOR +Pascal Buchbinder, http://mod-qos.sourceforge.net/ |