Contents x
    Using the dcs.cfg File
    • 16 Apr 2020
    • 28 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Contents

    Using the dcs.cfg File

    • Updated on 16 Apr 2020
    • 28 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    • PDF
    Article Summary

    If you installed SmartSource Data Collector (SDC) with your WebTrends Analytics software, you can use this article to configure the SmartSource Data Collector. SDC consists of a suite of Web server plug-ins. The plug-ins place instrumented hits in log files and generate visitor-identifying cookies based on these hits. You can configure the SDC plug-ins using the dcs.cfg configuration file that resides in the SDC installation directory/cfg directory. When the Web server loads an SDC plug-in, the configuration file is loaded into memory and determines the behavior of the SDC components.

    This article provides a detailed reference to the settings in dcs.cfg, also known as the SDC configuration file. It also provides information about configuring the SDC web server as well as suggestions for making SDC P3P-compliant.

    For information about installing or upgrading SDC, creating DCSIDs, and configuring the SDC site map file, see “SmartSource Data Collector Installation” in the SmartSource Data Collector User’s Guide.

    Using the dcs.cfg configuration file

    As the configuration file, dcs.cfg determines the behavior of SDC. The dcs.cfg file contains the following subsections:

    • auditlog
    • cookieserver
    • logserver
    • logrotation
    • logfields
    • logelementmap#
    • servicemodel
    Note

    For Linux-specific instructions for configuring the dcs.cfg file, refer to “Using dcs.cfg and Audit Log Rotation in Linux,” below.

    auditlog Section

    The auditlog section controls aspects of the SmartSource Data Collector (SDC) that apply to the audit log portion of the SDC server. For more information about the SDC audit log, see “Operating and Monitoring SDC" in the WebTrends SmartSource Data Collector User’s Guide.

    The following table describes the parameters used in the auditlog section.

    auditlog Parameters:

    Parameter NameDescriptionDefault Value
    typeSpecifies the type of logging and the location where SDC writes error and warning information. Valid values are:
    dcs – Write to SDC audit log
    system – Write to operating system audit log. In Windows 2003/XP, this can be viewed using the Event Viewer. In Linux, this is syslog.
    both – Write to SDC audit log and operating system audit log.

    Note: When SDC is installed on the Linux operating systems, the SDC audit log requires more system resources than the system syslog utility requires. Setting type to system can improve performance and is recommended for high-volume SDC installations.    		both
    debuglevelSpecifies the level of information SDC writes to the SDC audit log.
    Valid values are:
    0 – Errors only
    1 – Warnings and errors    		1
    systemdebuglevelSpecifies the type of information SDC writes to the operating system audit log. Valid values are:
    0 – Errors only
    1 – Warnings and errors    		0
    systemlogfacilitySpecifies the location where SDC messages are logged for the operating system audit log and not for the SDC audit log.
    Valid values are:
    log_daemon – By default, systemlogfacility is set to log_daemon, which causes the system and SDC messages to be logged to the default log file for daemon messages.
    User-specified – The user can specify a valid local log facility (LOG_LOCAL0 – LOG_LOCAL7).

    Note: The systemlogfacility option applies only to Linux operating systems.    		log_daemon
    auditlimitbysizemethodSpecifies the method used to limit the size of the audit log.
    Valid values are:
    rotate - Roll over and save under a new file name. Applies only to IIS-based SDC. For more information on audit log rotation using Linux, see “Using dcs.cfg and Audit Log Rotation in Linux,” below.
    truncate - Truncate in place.    		rotate
    auditlimitbysizeSpecifies whether to rotate based on size or truncate in place.
    This parameter is valid only for type=dcs or type=both.    		true
    auditmaxsizeSpecifies the maximum size (in kilobytes) of the audit log file.
    Valid values are between 10 and 2000000 inclusive.
    If auditlimitbysizemethod is set to rotate and the audit log file grows to the value specified, the audit log is rotated.
    If auditlimitbysizemethod is set to truncate and the audit log file grows to the value specified, the audit log is truncated. A portion of the audit log file is retained after truncation. This portion contains the most recently written records. The amount retained is controlled by the audittrimsize parameter.    		1000
    audittrimsizeSpecifies the portion (in kilobytes) of the audit log file to retain after truncation.
    Valid values are between 1 and 1000 inclusive.
    Note that audittrimsize must be less than auditmaxsize. Ideally, audittrimsize should be some small percentage (10% or less) of auditmaxsize.
    Otherwise, you will potentially truncate the file too often and incur a performance penalty associated with disk I/O.
    This is valid only for type=dcs or type=both.
    This is valid only for auditlimitbysizemethod=truncate.    		10
    auditfilenameprefixSpecifies the prefix for the audit log.dcs
    auditfilenameextSpecifies the file extension of the audit log. (Default file name is dcs.audit.).audit
    auditfiledirSpecifies the directory in which the audit log will be created. If you change the default directory, you must make sure SDC has permission to write to the new directory.%WT_ROOT%/log
    Note

    The SDC does not attempt to determine the maximum file size that your system supports. If you choose not to limit by size or choose a very large auditmaxsize, be careful not to exceed the maximum system file size. Loss of data may occur if you attempt to exceed the maximum system file size.

    In Linux, WebTrends recommends that you configure the audit log settings to either truncate or rotate the audit log so it does not ever reach the limit, which varies depending upon your file system.

    cookieserver Section

    The cookieserver section controls aspects of the SmartSource Data Collector that apply to the SDC-based Cookie Server plug-in. The following table describes the parameters used in this section.

    The Default Value column in the following table contains values that are used in the absence of the respective setting in the configuration file.

    cookieserver Parameters:

    Parameter NameDescriptionDefault Value
    cookieversionIdentifies the format of the cookie to be generated by the cookie server. If you are using a previous version of the WebTrends cookie plug-in and want to continue to generate cookies of the same name and same format, set the cookieversion to 1.
    cookieversion=1

    Otherwise, set the cookieversion to 2.
    cookieversion=2
    2 is recommend if you do not have an existing WebTrends Cookie plug-in on the same domain used for the SDC.
    To use cookie validation, you must set the cookieversion to 2. Otherwise, validation is disabled.    		1
    cookienameSpecifies the name of the SDC-based cookie.WEBTRENDS_ID
    enabledSpecifies whether the SDC-based cookie server is enabled.True
    expirationtypeSpecifies whether cookies expire and, if so, what type of cookie expiration is in effect. Valid values are:
    seconds – Sets the expiration equal to the current time plus the number of seconds identified by the expirationseconds setting.
    date – Sets the expiration to the time identified by the expirationdate setting.
    none – Does not set to the cookie expiration. This is interpreted by most browsers as a session-only cookie.    		seconds
    expirationsecondsIf seconds is specified for expirationtype, specifies the time (in seconds) between cookie generation and cookie expiration.315360000 (10 years)
    expirationdateIf a date was specified for expirationtype, this setting indicates the date when all generated cookies expire. The format of this string is MM-DD-YYYY where:
    MM – Month of the year (1-12)
    DD – Day of the month (1-31)
    YYYY – Year    		12-31-2010
    pathSpecifies the subset of URLs in a Web site for which the cookie is valid./ (The entire Web site)
    includepathThis parameter specifies whether the path attribute is included in the Set-Cookie directive created by SDC. If set to true, the value of the path setting is included in the Set-Cookie directive. If set to false, no path attribute is included in the Set-Cookie directive. For the Hosted Model SDC, you should set this value to false. By not including the path attribute in the Set-Cookie directive, the cookie (by default) uses the path of the resource associated with the directive. With the hosted-model SDC, the DCSID is included in the request to the SDC. By not including the path attribute, each DCSID has its own tracking SDC cookie.True
    domainUsed by Web clients to determine if a cookie should be sent with an HTTP request to a targeted domain. With a Set-Cookie directive, if this value is not present, the domain name of the server that generated the cookie response is used.
    We recommend leaving this value disabled.    		Disabled by default
    secure (not currently supported with Apache Windows installations)Specifies whether the secure attribute of the Set-Cookie directive is set. This attribute is used to determine if the cookie is transmitted only over secure connections.False
    magiccodeSecret key used for the cookie validation process. During cookie generation, this string is appended to the base component of the cookie and the resulting compound string is run through a hash algorithm. The hash value (checksum) is then appended to the base component of the cookie set using the Set-Cookie directive.
    On subsequent requests, the hash value of the string (consisting of the base cookie component plus the magiccode) is recreated and compared with the hash value associated with the sent cookie. If the hash values do not match, the cookie is marked as invalid.

    Warning: After a magiccode is established, it should never be changed. Changing the magiccode while validation is enabled causes all existing cookies to become invalid.
    If you are using redundant Web servers, this value should be matched across all servers. This value is case-sensitive.    		Set during installation
    validatecookieIndicates if cookie validation is performed. This is valid for cookieversion=2 only.True
    reissuebadcookieIndicates if new cookies are issued for hits containing invalid cookies. This is valid for cookieversion=2 only.True
    useoptoutcookieIndicates whether the opt-out cookie (WTLOPTOUT) should be honored. If you implemented the opt-out cookie for SDC, this value should be set to True. For more information, see "Using Cookies to Track Visitor Sessions" in the SmartSource Data Collector User’s Guide.True
    sitewidecookieThis setting enables the account rollup cookie which allows you to track multiple DCSIDs across domains and track email campaigns that use the WebTrends JavaScript tag.True

    logserver Section

    The logserver section controls aspects of the SmartSource Data Collector that apply to the logging portion of SDC. The following table describes the parameters used in this section.

    The Default Value column in the following table contains values that are used in the absence of the respective setting in the configuration file.

    logserver Parameters:

    Parameter NameDescriptionDefault Value
    loginvalidhitsIndicates whether hits with invalid cookies are logged in the SDC log file.False
    logtruncatedhitsIndicates whether hits that were truncated are logged in the SDC log file. For more information, see "Query Parameter Reference."False
    loggingfilenameSpecifies the name of a valid SDC uri-stem. This is a GIF resource that is the target for valid hits to the SDC server. Do not modify this value. If you want to specify an alternate resource, use the altloggingfilename parameter./dcs.gif
    noscriptfilenameSpecifies the file name of a valid SDC uri-stem. This is the GIF resource that is the target for hits from browsers that do not support the scripting language JavaScript. Do not modify this value. If you want to specify an alternate resource, use the altnoscriptfilename parameter./njs.gif
    contentfilenameSpecifies the file name to which the resources specified in the loggingfilename and the noscriptfilename parameters are mapped. This is the file name that is returned to the client from the SDC server./wt_dcs.gif
    javascriptfilenameSpecifies the file name of the WebTrends JavaScript tag. As a best practice, you should not modify this value./wtid.js
    altjavascriptfilenameSpecifies an alternative file name if you don’t want SDC to use the javascriptfilename value. If you change this value, you must also replace references to wtid.js in the WebTrends JavaScript tag./wtid.wt
    altloggingfilenameSpecifies an alternative file name if you don’t want SDC to use the javascriptfilename value. If you change this value, you must also replace references to dcs.gif in the WebTrends JavaScript tag./dcs.xtp
    altnoscriptfilenameSpecifies an alternative file name if you don’t want SDC to use the noscriptfilename value. If you change this value, you must also replace references to njs.gif in the WebTrends JavaScript tag./njs.xtp
    altcontentfilenameSpecifies an alternative file name if you don’t want to SDC to use the contentfilename value./wt_dcs.xtp
    logelementcountDetermines the number of logelement entries listed in the logelementmap# sections.Set by the installation. Do not modify.
    logelementFixed identifier of a component of a log file entry. Valid values include:
    DCS_URI – cs-uri-stem
    DCS_QUERY – cs-uri-query
    DCS_REFERRER – cs(Referer)
    DCS_AUTHUSER – cs-username
    DCS_METHOD – cs-method
    DCS_STATUS – sc-status
    DCS_SERVERIP – s-ip
    DCS_PROTOCOL – request protocol
    DCS_BYTES – sc-bytes
    DCS_DATE – date
    DCS_CLIENTIP - For more information, refer to the tables in the “logelementmap# Sections,” below.    		Fixed list. Do not modify.
    parameterName of the parameter in the instrumented hit that SDC searches for during the parsing process. The log entry component represented by the parameter is determined by the associated log element value. For more information, refer to the tables in the “logelementmap# Sections,” below.DCS_URI ->dcsuri
    DCS_QUERY ->dcsqry
    DCS_REFERRER ->dcsref
    DCS_AUTHUSER->dcsaut
    DCS_METHOD ->dcsmet
    DCS_STATUS ->dcssta
    DCS_SERVERIP ->dcssip
    DCS_PROTOCOL ->dcspro
    DCS_BYTES ->dcsbyt
    DCS_DATE ->dcsdat
    DCS_P3P ->dcsp3p
    DCS_CFG ->dcscfg
    DCS_CLIENTIP ->dcscip
    Changing these values is not recommended.
    requiredBoolean used to indicate if the logelement is required in the instrumented hit. If set to required and the associated parameter is not found in a particular instrumented hit, the hit is marked invalid. These invalid hits are discarded.The DCS_URI logelement is always required. All others default to false.
    issuep3pBoolean used to indicate if a P3P header will be included in the SDC HTTP response.True
    p3pfromIndicates where the P3P header comes from. Applies only when issuep3p=true.
    The following values are valid:
    global – use value from p3p parameter.
    hit – use value from instrumented hit.
    hitorglobal – First attempt to use P3P value from instrumented hit. If not present, fall back to using value from p3p parameter. For more information, see the article “P3P and SDC.”    		Global
    p3pSpecifies the string to include as the global P3P HTTP header. Only included when issuep3p=true. The exact value of this string is appended to “P3P:” and included in the HTTP response. For more information, see the article “P3P and SDC.”No default
    hostedmodelThis setting should be set to true to enable Hosted Model SDC. With Hosted Model, requests to SDC must include a valid DCSID in the path to the SDC logging file name. With a hosted SDC, the request must be in the following form:
    /valid DCSID/dcs.gif

    The format of a valid DCSID is:
    dcsnnnnnnnnnnnnnnnnnnnnnn_xxxx where nnnnnnnnnnnnnnnnnnnn is the globally unique component of the DCSID. This is a twenty-two (22) alphanumeric-character string.

    xxxx is the string’s checksum used for validation. This is a four (4) character string.
    The following examples illustrate some valid DCSIDs:

    dcsfl0pjmbuwblk29hgmbrmpd_7h9x
    dcsrtxsdlauwbl8lj4on9d5v9_9e3v    		True
    maxhandlecountNumber representing the maximum number of concurrently open Web data files.
    Applies only when hostedmodel=true and splitlogs=true. For Windows installations the maximum value is 2000. For IIS-based SDC only.    		2000
    splitlogsEnables log file splitting based on the DCSID associated with each hit to the SDC. If splitlogs is set to true, the log files are split based on the DCSID. Each new file name begins with the DCSID. If splitlogs is set to false, hits are written to a single file. Normal file rotation applies to both cases.
    Applies only when hostedmodel=true. For IIS-based SDC only.    		False
    writebuffersizeThis parameter specifies the size (in KB) of the internal buffer used for each SDC log file controller. If the log files are being split based on the DCSID, a separate log file controller is created for each active DCSID. For each active log file controller, an internal write buffer is created to cache incoming hits. The size of the write buffer is dictated by the writebuffersize setting. You should adjust the writebuffersize according to your system resources and the number of active DCSIDs your SDC is supporting. The default value is 64 KB (65536).
    You can disable the buffer by setting the value to 0 (zero).
    For IIS-based SDC only.    		65,535
    heartbeatrateNumber representing the number of seconds that elapse between heart beats.
    For IIS-based SDC only.    		60
    bufferflushrateNumber representing the number of seconds that elapse between buffered writes.
    For IIS-based SDC only.    		60
    filecheckrateNumber representing the number of seconds that elapse between checks for inactive file handles.
    For IIS-based SDC only.    		900
    cfgbyhit​Used to enable configuration using the SDC tag.
    For more information, see “Tagging Web Pages for SDC” in the SmartSource Data Collector User’s Guide.    		False
    trackfirsttimecookiesUsed to enable WebTrends to accurately tie together a new visit with subsequent return visits. When a new visit hit arrives, SDC inserts a WebTrends query parameter into the query string, WT.co_d, that contains the cookie value. To identify return visits, this value is matched against the cs(Cookie) field.
    Additionally, the WebTrends query parameter (WT.co) is inserted in the query string on every hit. This value indicates whether or not the client accepts SDC cookies.    		true
    trackhitcountBoolean used to enable hit count tracking.
    For IIS-based SDC only.
    For more information, see “Operating and Monitoring SDC” in the SmartSource Data Collector User’s Guide.    		False
    hitcountflushrateThe number of minutes to elapse between hit count log file writes. Applies only if trackhitcount is true.
    Valid values are 2, 3, 5, 6, 10, 12, 20, 30    		20
    hitcountlogfiledirSpecifies the directory to create HCLF.%WT_root% /log
    hitcountlogfileextSpecifies the HCLF file extension..hclf
    hitcountrotatebyflushBoolean used to indicate if flush-based rotation is enabled. Only applies if trackhitcount is true.False
    hitcountflushesperrotationInteger that determines the number of flushes that occur before an HCLF is rotated. Only applies if hitcountrotatebyflush is true. Valid values are between 1 and 60 inclusive.3
    hitcountlimitbysizeBoolean used to indicate if size-based rotation is enabled. Only applies if trackhitcount is true.False
    hitcountmaxsizeInteger that determines the maximum size (in megabytes) of the HCLF. Only applies if hitcountlimitbysize is true.1
    usememmappedfileBoolean used to indicate if log files should be memory mapped (IIS-only).False
    enableheaderparamsIndicates whether HTTP headers on incoming requests should be emitted as WebTrends query parameters.False
    headerparamslistComma-delimited list of HTTP headers to be emitted as WebTrends query parameters. You can also have the value of the header logged to the field specified by the logelementvalue instead of as a query parameter. The format is:
    header[:logelement] where header is the HTTP header name and logelementis a valid SDC logelement name. For more information, see “logelementmap# Sections,” below.
    For example, specifying Host,Accept,x-Forwarded-For:DCS_CLIENTIP logs the value of the HTTP header "x-Forwarded-For" to the c-ip field. This configuration is useful if you have load-balanced SDC servers, and the load balancer overwrites the value of the actual client IP with the IP of the load balancer.
    This setting only applies if enableheaderparams is set to true. Refer to “WebTrends Query Parameters” in the SmartSource Data Collector User’s Guide for more information.    		Host,Accept
    dcsidbacktoversionNumber representing the earliest version DCSID that is deemed valid by SDC. Valid values are 1, 2, and 3.1

    logrotation Section

    The logrotation section controls SmartSource Data Collector (SDC) log file rotation settings when SDC is configured for Hosted Model or Standard Model.

    Note

    The rotationratestandardlag setting determines the log file rotation for Service Model SDC. For more information, see “servicemodel Section,” below.

    The following table describes the settings in the logrotation section. The Default Value column specifies the values that SDC uses when the respective setting is missing in the configuration file.

    logrotation Parameters:

    Parameter NameDescriptionDefault Value
    rotationperiodThe time period that specifies the rotation of the log file. Rotation is based on local time or on GMT (see gmtrotation parameter).
    Valid values are:
    YEARLY
    QUARTERLY
    MONTHLY
    WEEKLY
    DAILY
    HOURLY
    HOURS
    MINUTES
    NONE (rotates based on maxlogfilesize only)
    or
    number of days (0-30)    		DAILY
    weekstartThe starting day of the week. This only applies if the rotationperiod is set to WEEKLY.
    Valid values are:
    MONDAY
    TUESDAY
    WEDNESDAY
    THURSDAY
    FRIDAY
    SATURDAY
    SUNDAY    		MONDAY
    hoursintervalThe number of hours to elapse between rotation. This applies only if the rotationperiod is set to HOURS. Valid values are 2, 4, 6, 8, and 12.2
    maxlogfilesizeMaximum size (in kilobytes) of the log file. If the file size grows to this value, the file is rotated. If set to 0, this feature is effectively disabled.
    The SDC does not attempt to determine the maximum file size that your system supports. If you choose not to limit by size or choose a very large maxlogfilesize, be careful not to exceed the maximum system file size. Loss of data may occur if you attempt to exceed the maximum system file size.    		200000
    limitbysizeBoolean used to indicate if size-based rotation is enabled.True
    logfileprefixSpecifies the prefix for log file namessdc
    logfiledirSpecifies the directory to create the SDC files.%WT_ROOT%\weblog\
    gmtrotationBoolean used to indicate that the log file rotation should be based on GMT. By default, GMT time is used.True
    minutesintervalThe number of minutes to elapse between rotation. This applies only if the rotation period is set to MINUTES. Valid values are 1, 2, 3, 4, 5, 6, 10, 2, 15, 20, 30.30
    usenumericmonthBoolean used to indicate that log file names contain two-digit month specifiers (with zero prefill).False
    Note

    SDC does not attempt to determine the maximum file size that your system supports. If you choose not to limit by size or choose a very large auditmaxsize, be careful not to exceed the maximum system file size. Loss of data may occur if you attempt to exceed the maximum system file size.

    In Linux, WebTrends recommends that you configure the audit log settings to either truncate or rotate the audit log so it does not ever reach the limit, which varies depending upon your file system.

    The generated file names depend on the rotationperiod and the logfileprefix specified in the configuration file. The following are some examples of file names:

    By minute: server1_min30_hr01_apr_10_2005.log
    If minutes is specified, the file name refers to the first minute of the period.

    Hourly: server1_hr01_apr_10_2005.log
    If hours is specified, the file name uses the same format as the hourly file name and refers to the first hour of the period.

    Daily: server1_apr_10_2005.log
    If weekly or an exact number of days is specified, the file name uses the same format as the daily file name and refers to the first day of the period.

    Weekly: server1_wk_apr_08_2005.log
    Monthly: server1_apr_2005.log
    Quarterly: server1_qtr2_2005.log
    Yearly: server1_2005.log

    The weekstart configuration setting works in conjunction with the WEEKLY rotationperiod and specifies on which day of the week the logging begins.

    The minutesinterval configuration setting works in conjunction with the MINUTES rotationperiod and specifies the number of minutes to elapse between rotations.

    The hoursinterval configuration setting works in conjunction with the HOURS rotationperiod and specifies the number of hours to elapse between rotations.

    The logfileprefix configuration setting specifies the beginning of the file name.

    The maxlogfilesize configuration setting specifies the maximum size of a log file. If the maximum size is reached while logging server activity, a new file is created. The new file has the same name as the current file, except that (2) appears before the period. For example, if server1_2005.log reaches its limit, the new file is called server1_2005(2).log.

    If the current file name already has a (2) before the period and that file has reached its limit, the new file name will contain (3) before the period, as in the following example: server1_2005(3).log.

    logfields Section

    The logfields section controls which elements are written to the SDC log file. Note that the date and time elements are always written to the log file.

    The following table describes the parameters used in the logfields section.

    logfields Parameters:

    Parameter NameDescriptionDefault Value
    logclientipEnables c-ip logging.True
    logusernameEnables cs-username logging.True
    logserveripEnables cs-host logging.True
    logmethodEnables cs-method logging.True
    loguristemEnables cs-uri-stem logging.True
    loguriqueryEnables cs-uri-query logging.True
    loghttpstatusEnables sc-status logging.True
    logbytessentEnables sc-bytes logging.True
    logprotocolversionEnables cs-version logging.True
    loguseragentEnables cs(User-Agent) logging.True
    logcookieEnables cs(Cookie) logging.True
    logrefererEnables cs(Referer) logging.True
    logdcsidEnables DCSID logging. This parameter specifies whether the DCSID associated with the hit is included as a column in the log file generated by SDC. We recommend you set this to true. (Valid only if hostedmodel is set to true).True

    logelementmap# Sections

    The logelementmap# sections define SmartSource Data Collector (SDC)-specific query parameters (also known as logelements). These parameters are present in the instrumented hit. SDC searches these parameters when parsing incoming hits. SDC either writes the parameter value to the log file or uses it internally.

    The number of SDC-specific parameters is determined by logelementcount setting in the [logserver]section. There is one [logelement#] section for each SDC-specific parameter.

    The following table describes the parameters in the [logelement#] sections.

    logelement# Parameters:

    Parameter NameDescriptionDefault Value
    logelementFixed identifier of a component of a SDC log file entry. Valid values include:
    DCS_URIDCS_QUERY
    DCS_REFERRER
    DCS_AUTHUSER
    DCS_METHOD
    DCS_STATUS
    DCS_SERVERIP
    DCS_PROTOCOL
    DCS_BYTES
    DCS_DATE
    DCS_P3P
    DCS_CFG
    DCS_REDIRECT
    DCS_CLIENTIP    		Fixed list. Do not modify.
    parameterName of the parameter that SDC searches for during the parsing process. What SDC does with the parameter is determined by the associated element value. For more information, see the next section.Fixed list. Do not modify
    requiresIndicates whether the logelement is required in the instrumented hit. If set to true and the associated parameter is not found in a particular instrumented hit, the hit is marked invalid. These invalid hits are discarded.The DCS_URI logelement is always true. All others default to false.

    The following table identifies the log file field where SDC writes the value for the logelement identifier. For example, when SDC identifies dcsuri parameter in the hit, it writes the value to the cs-uri-stemfield.

    logelement Identifier Fields:

    Logelement IdentifierParameterLog File Entry
    DCS_URIdcsurics-uri-stem
    DCS_QUERYdcsqrycs-uri-query
    DCS_REFERRERdcsrefcs(Referer)
    DCS_AUTHUSERdcsautcs-username
    DCS_METHODdcsmetcs-method
    DCS_STATUSdcsstasc-status
    DCS_SERVERIPdcssipcs-host
    DCS_PROTOCOLdcsprocs-version
    DCS_BYTESdcsbytsc-bytes
    DCS_DATEdcsdatn/a(used internally)
    DCS_P3Pdcsp3pn/a (used internally)
    DCS_CFGdcscfgn/a (used internally)
    DCS_REDIRECTdcsredirectn/a (used internally)
    DCS_CLIENTIPdcscipc-ip

    To log anything other than – to the cs-username field, the hit to SDC must contain the dcsaut as a query parameter, as shown in the following example:

    http://1.2.3.4/dcs.gif?dcsuri=/xxx.htm&dcsaut=xavier&WT.ti=...

    SDC logs xavier in the cs-username field. The &dcsaut=xavier is not written to cs-uri-query.

    SDC recognizes dcsaut as a special SDC-specific parameter. Note all of the SDC-specific parameters:
    dcsuri, dcsqry, dcsref, dcsaut, dcsmet, dcssta, dcssip, dcspro, dcsbyt, dcsdat, dcsp3p, dcscfg, dcsredirect, dcscip.

    These parameters are consumed by SDC and are not logged to the cs-uri-query field.

    DCS_AUTHUSER is simply a mnemonic used in the SDC configuration file.

    The following example illustrates three SDC-specific parameters: dcssip, dcsuri, dcsaut.

    A hit like this:
    http://pdx03.us.yourcompany.corp/dcs0wswclz6ttwqct9rn4cmt9_6f2j/dcs.gif? &dcsdat=1083602642984&dcssip=hostname&dcsuri=/params.htm&dcsaut= someuser&WT.tz=-7&WT.bh=9&WT.ul=en-us&WT.cd=16&WT.sr=1152x864&WT.jo=Yes &WT.js=Yes&WT.jv=1.3

    produces a record like this:
    #Fields: date time c-ip cs-username cs-host cs-method cs-uri-stem cs-uri-query sc-status sc-bytes cs-version cs(User-Agent) cs(Cookie) cs(Referer) dcs-id 2004-05-03 16:44:03 192.168.100.40 someuser pdx03 GET /params.htm WT.tz=-7&WT.bh=9&WT.ul=en-us&WT.cd=16&WT.sr=1152x864&WT.jo=Yes&WT.js=Yes &WT.jv=1.3&WT.cg_n=XecureWeb%20Control%20%3F%3F\xc4\xa1%3F\xc8\xb3%3F.&WT.co=Yes 200 - - Mozilla4.0+(compatible;+MSIE+6.0;+Windows+NT+5.0;+.NET+CLR +1.0.3705) WEBTRENDS_ID=192.11.11.11-3101421440.29634860::070617466FD2 06AAE91FAD5E983925B5 - dcs0wswclz6ttwqct9rn4cmt9_6f2j

    Notice that some of the SDC-specific parameters are written as a field in the SDC log file, and do not appear in the cs-uri-query field.

    servicemodel Section

    The servicemodel setting is enabled by default in SDC v7.5a and higher. The servicemodel settings are required to configure SDC for Express Analysis, to collect Web data traffic for multiple DCSIDs, and to enable the account rollup data source. To use SDC with servicemodel enabled, you need to create a site map identifying any DCSIDs you use on your web site. For more information about creating a site map, see “Configuring the Site Map File.” For more information about Express Analysis, see “Express Analysis” in the WebTrends Administration User’s Guide.

    servicemodel Parameters:

    Parameter NameDescriptionDefault Value
    servicemodelSpecifies whether to enable servicemodel for SDC (supported for IIS only).true
    sitemapfullpathWhen servicemodel is enabled, specifies the file name for a required site map.%WTROOT%\cfg\webtrendssites.lst
    rotationratestandardlagSpecifies how often (in minutes) SDC rotates standard logs when servicemodel is enabled. Valid values are 60, 120, 240, 360, 720, and 1440.60
    rotationraterealtimeSpecifies how often (in minutes) SDC rotates Express Analysis or real-time logs when servicemodel is enabled. Valid values are 1-6, 10, 12, 15, 20, 30, and 60.5
    uselogfilenameversionSpecifies whether to include the version of SDC as part of the log file name. Enabling this setting allows troubleshooting of SDC compatibility issues without opening the log.false

    Creating a Log for SDC Messages in Linux

    In the auditlog section of the dcs.cfg file, the auditfiledir setting specifies the directory where SDC writes its audit log file. The default directory, SDC Installation Directory/log/, is created during SDC installation. The system variable for this directory is %WT_ROOT%/log.

    To use a different directory:

    1. Create the directory manually by entering the following at a command prompt:
      mkdir /logdir

    2. To change the owner of the directory so that Apache is able to write to it, enter:
      chown apache:apache /logdir/

    3. If SDC is installed on a Secure Linux operating system, change the security context to apache log files for the new directory. This determines the directory access restrictions. Enter:
      chcon -t httpd_log_t /logdir/

    4. To change the auditfiledir setting to reflect the directory you want to use, go to the auditlog section of the dcs.cfg file and enter:
      /logdir

    5. Restart the SDC Apache service. SDC automatically creates a new audit log file in the directory you have specified.

    Using dcs.cfg and Audit Log Rotation in Linux

    In audit log rotation, a new log is automatically created when certain criteria are met. On Linux, this function is only supported through use of the System Logs (syslog).

    You need to configure the dcs.cfg file to use syslog. The dcs.cfg file is loaded into the installation directory when SDC is installed and it contains configuration information that determines the behavior of SDC.

    Note

    Log truncation is still supported without using syslog.

    To use audit log rotation:

    1. Configure SDC to use syslog.
    2. Isolate SDC syslog messages.
    3. Enable syslog rotation.
    4. Optionally, create a cron job for logrotate.

    Configuring SDC to use syslog

    To enable the use of syslog:

    1. Using a text editor, open the dcs.cfg file, which is located in SDC Installation Directory/cfg.
    2. Proceed to the auditlog section of dcs.cfg file.
    3. Change the type setting to system.
    4. Change the systemdebuglevel setting to 1.
    5. If you want syslog to log a location other than the default location, change systemlogfacility to the preferred syslog facility. For more information, see “Isolating SDC syslog Messages,” below.

    Isolating SDC syslog Messages

    By default, systemlogfacility is set to log_daemon, which causes the system and SDC messages to be logged to the default log file for daemon messages. The location of the default log file varies depending on what specific Operating System (OS) and distribution of that OS you are using. Common locations include /var/log/messages or /var/log/syslog.

    Since other processes routinely send messages to the default syslog, it is recommended that SDC messages be isolated into a separate log file.

    To isolate SDC messages from other syslog messages:

    1. Open /etc/syslog.conf in a text editor. This file specifies the location of the log file for all syslog facilities.

    2. Find a local log facility that is not already defined. Possible values are LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, and LOG_LOCAL7.

      Note

      LOG_LOCAL7 is often used for boot messages.

    3. At the end of the file, create an entry for the undefined local log facility in the following format:
      log facility.* desired log file location
      For example, type:
      local1.* /usr/local/webtrends/sdc/log/dcs.audit

      Note

    We recommend setting type to system in the dcs.cfg file, but if type is set to both, make sure the directory you are specifying as the syslog destination differs from the one specified in the auditlog section of the dcs.cfg file, which by default is set to SDC installation directory/log. The system variable for this directory is %WT_ROOT%/log.
    :::

    1. Save the syslog.conf file.

    2. In a Terminal window, terminate the current syslog process by entering:
      killall –HUP syslogd

    3. In the auditlog section of the dcs.cfg file, set systemlogfacility to the facility that you used in Step 3.

    4. Enter the following command to restart Apache:
      /Apache bin directory/apachectl restart

      Note

      The default Apache bin directory is /usr/sbin/apachect1.

    Enabling Log Rotation

    After you activate syslog, you need to enable log rotation.

    To enable log rotation:

    1. In a text editor, open the /etc/logrotate.conf file for editing.
    2. At the end of the file, add an entry to match the log file you specified in /etc/syslog.conf.
    Notes

    * Logs can be rotated based on size or date. Refer to the logrotate man page, or on-line reference manuals, for examples. These can be accessed by typing man logrotate at a command prompt.
    * logrotate is usually set to run as a daily cron job, but if you are rotating based on size, you might want to have logrotate run more often. For more information, see “Creating a cron Job for logrotate,” below.
    * Logs will not be rotated when logrotate is not running.

    Creating a cron Job for logrotate

    A cron job or cron script is a method of scheduling one or more tasks.

    Note

    By default, logrotate runs once a day. If you rotate logs by date, you do not need to create another cron job. If you rotate logs by audit log size, you should create another cron job so you can control the maximum size that the log files reach.

    To create a cron job that runs logrotate when logs reach a certain size:

    1. Edit the cron file using crontab -e.
    2. Add logrotate path_to_conf_file to the cron file, with the desired interval at which to run logrotate. For more information, see the man pages for cron (man cron) and crontab (man crontab).
    3. Save the cron file.
    Note

    If you do not want to rotate all logs listed in /etc/logrotate.conf, create a second configuration file that only rotates the SDC logs and use that for your new cron job.

    Was this article helpful?
    What's Next