NaviServer - programmable web server

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

# ns_accesslog(n) 4.99.8 nslog "NaviServer Module Commands"

## Name

ns_accesslog - Query and control access log parameters

## Table Of Contents

## Synopsis

- ns_accesslog file ?new-path?
- ns_accesslog roll ?new-path?
- ns_accesslog rollfmt ?time-format?
- ns_accesslog maxbackup ?keep?
- ns_accesslog flags ?flags?
- ns_accesslog extendedheaders ?new-headers?
- ns_accesslog maxbuffer ?lines?

## Description

This command controls and configures the access log. It can change settings at run-time.

## COMMANDS

ns_accesslog file ?new-path?

  Returns the path of the access log for the current virtual server.

  If ?new-path? is given then the old log is closed and the log re-opened at the new location. All the components of ?new-path? must exist. If an error occurs logging will be disabled.

ns_accesslog roll ?new-path?

  Roll the access log (see ns_rollfile for details). Keep maxbackup old log files around. If ?new-path? is given then it overrides the configuration parameter 'file' as the new log file.

ns_accesslog rollfmt ?time-format?

  Get the ?time-format? which is appended to the log file name when rolling. The format string is as understood by the Tcl clock command. If ?time-format? is given then it replaces any existing value.

ns_accesslog maxbackup ?keep?

  Get the number of backup files which will be kept when log rolling is enabled. If ?keep? is given it replaces any existing value.

ns_accesslog flags ?flags?

  Return a list of the enabled logging options, or reset the list if a new set of flags is given. Valid flags are: logcombined, formattedtime, logpartialtimes, logreqtime, checkforproxy, and suppressquery. They have the same meaning as the similarly named configuration parameters.

ns_accesslog extendedheaders ?new-headers?

  Return a list of the HTTP headers which will be appended to each entry in the access log. If ?new-headers? is given it replaces the existing setting.

ns_accesslog maxbuffer ?lines?

  Set or get the maximum number of lines to buffer before being flushed to the log file.

## CONFIGURATION

The nslog module is loaded per-server.

    ns_section "ns/server/server1/modules"
    ns_param   nslog   nslog.so
    ns_section "ns/server/server1/module/nslog"
    ns_param   ...

The following are valid configuration parameters:

file

  String: path to the log file.

formattedtime

  If true, log the time in common-log-format. Otherwise log seconds since the epoch. Default: true.

logcombined

  If true, log the referer and user-agent HTTP headers (NCSA combined format). Default: true.

maxbuffer

  The number of log entries to buffer before flushing to the log file. Default: 0.

rolllog

  If true then the log file will be rolled. Default: true.

rollhour

  The hour of the day (0-23) to roll the log file if log rolling is enabled. Default: 0 (midnight).

maxbackup

  Number of old log files to keep when log rolling is enabled. Default: 100.

rollonsignal

  If true then the log file will be rolled when the serve receives a SIGHUP signal. Default: false.

suppressquery

  If true then the query (everything after the ? in the URL) is not logged. Default: false.

checkforproxy

  If true then the value of the X-Forwarded-For HTTP header is logged as the IP address of the client. Otherwise, the TCP peer address is logged. Only enable this if you run your own, trusted proxy server. Default: false.

logpartialtimes

  If true then include the high-resolution start time of the request together with partial request durations (accept, queue, filter, run) in the access log. Default: false.

logreqtime

  If true then log the total amount of time the request took to run in seconds and milliseconds. Default: false.

extendedheaders

  A space separated list of additional HTTP headers whos value should be logged. Default: no extra headers are logged.

## EXAMPLES

The path of the active access log.

    nscp:1> ns_accesslog file
    /home/ns/servers/server1/modules/nslog/access.log
    nscp:2> ns_modulepath server1 nslog access.log
    /home/ns/servers/server1/modules/nslog/access.log

The access log can be rolled manually.

    nscp:1> ns_accesslog roll

Extended logging options can be configured at run-time.

    nscp:1> ns_accesslog flags
    logCombined formattedTime
    nscp:2> ns_accesslog flags {logcombined formattedtime checkforproxy}
    logcombined formattedtime checkforproxy
    nscp:3> ns_accesslog extendedheaders
    nscp:4> ns_accesslog extendedheaders {Cookie Accept}
    Cookie Accept

## See Also

ns_log, ns_rollfile

## Keywords

ipaddress, log, path, proxy