eventlog

read, write, backup, enumerate, count, clear, and display an event log 

Command


SYNOPSIS

eventlog -r [-S hostname] [-s eventlog] [-p eventsource]... [-o offset] [-N recordcount] [-D initialdate] [-M daycount|finaldate] [-R eventtype] [-i eventid]... [-c eventcategory] ... [[-w [timeout]] [-a]] [-F formatoptions] [-m delimiter] [-b] [-L backupfile] [-timeout seconds] [-I]

eventlog -n [-S hostname] [-s eventlog] [-a] [-v] [-timeout seconds]

eventlog -C [-f] [-S hostname] [-s eventlog] [-timeout seconds]

eventlog -B backupfilenameprefix [-f] [-S hostname] [-s eventlog] [-timeout seconds]

eventlog -l [-S hostname] [-s eventlog] [-p eventsource]... [-a] [-timeout seconds]

eventlog -W [-t insertionstring]... [-d binarydatafile] [-S hostname] -p eventsource -R eventtype [-c eventcategory] -i eventid [-timeout seconds]

eventlog -T [-S hostname] -p eventsource [-P messagefiletype] [-timeout seconds]

eventlog -h


DESCRIPTION

The eventlog utility reads the specified log file from the specified host or a backup log file and dumps the records on the console on a one line per record basis. It also writes a specified event into the log file, creates backup, enumerates, clears, and counts the number of entries in the specified event log on the specified host. Additionally, it can dump the message strings associated with an application.

The user must have domain administration rights to view the Security event log or to clear any event log on a remote system.

Mode Selection Options

Each eventlog command line must include a mode selection option. Mode selection options are mutually exclusive, but may be combined with appropriate secondary options (see Secondary Options). The following mode selection options are available:

-B backupfilenameprefix 

backs up an event log. This option takes a prefix for the name of the backup file as an argument. The user is prompted if the backup file already exists. Specifying the -f option suppresses the prompt. The name of the event log and the host name whose log is being backed up are prefixed with the backupfilenameprefix in that order. Then a .evt extension is suffixed. If a .evt extension is already suffixed to the backupfilenameprefix, it is stripped off and suffixed to the resulting backup file name. If the -s option is not specified, the name of the log appended to the backup file name is application. If the -S option is not specified, the name of the local host is appended to the backup file name. The name of the local host is a fully qualified domain name if it can be found out.

For example, if backupfilenameprefix is bkp06-06-2001 and the system log is being backed up (specified by the -s option) from machine host_a (specified by the -S option), the name of the backed up file is bkp06-06-2001.system.host_a.evt. If the -S option had not been specified, the name of the backed up file would be bkp06-06-2001.system.host_b.evt (The system log of host_b, that is, the local host, has been backed up). If the -s option had not been specified, the name would have been bkp06-06-2001.application.host_a.evt (the application log of host host_a has been backed up). If neither -s nor -S had been specified, the name would have been bkp06-06-2001.application.host_b.evt (the application log of host_b, that is, the local host, has been backed up).

If -S is specified with -B and the backup file name is not a UNC name, it is converted to the UNC format for the local host.

The MKS KornShell and MKS C Shell use the backslash (\) as an escape sequence, so for one backslash, two have to be specified. Another way to deal with it is to specify forward slash (/) in place of backslash.

For example:

eventlog -B bkp06-06-2001 -s system

backs up the system log of the local host to bkp06-06-2001.system.host_b.evt (host_b is the local host) in the current directory.

eventlog -B \\host_b\backup\bkp06-06-2001 -S host_a -s system

backs up the system log of host host_a to bkp06-06-2001.system.host_a.evt in the network share \\host_b\backup. (See below for security related issues)

Log file backups are performed by the eventlog service running on the corresponding host whose log file is to be backed up. This service generally runs in the LocalSystem account which does not have credentials on a different host (if the backup file is specified on a different host by a UNC name). In such a case, taking recourse to the following may help:

LocalSystem accounts try to gain access to network resources with a NULL session, that is, a session having no security credentials. Normally such sessions do not have any access rights over the network, but the target machine (on which a backup file has to be written) can declare some share which is accessible by a NULL session. The name of the share being made accessible to a NULL session can be added to the NullSessionShares value under the registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters

This is a potential security hole; therefore, it is recommended that you create a share with a $ suffixed to hide it from browsing. A long and difficult name also helps.

Note also that write access to everyone for this null session share has to be enabled. For example, if you need to issue command lines on host_a like:

eventlog -S host_b -B bkp1 -s system     (with current directory D:\backup)
eventlog -S host_b -B D:\backup\bkp1 -s system

Share D:\backup on host_a, on which the eventlog utility is to run, as backup. Enable backup for access from null sessions then issue a command like:

eventlog -S host_b -B \\host_a\backup\bkp1 -s system

This backs up the system event log on host_b to bkp1.system.host_b.evt in the D:\backup folder on host_a.

-C 

clears an event log. The user is prompted before the log file is cleared. Specifying the -f option suppresses the prompt.

-h 

displays usage information.

-l 

enumerates all logs on a specified host. If an event log is specified with the -s option, all event sources registered under that event log are enumerated. If an event source is specified with -p option, all logs from that source are enumerated. If both -p and -s are specified, categories are enumerated. If the -a option is specified, all event sources under all event logs are enumerated. The -a option overrides -s and -p.

-n 

counts records in an event log. The -a option counts records of all event logs on the specified host and overrides the -s option. The -v option displays the name of the log whose records are being counted.

-r 

reads an event log and displays records on a one-line-per-record basis.

-T 

dumps message string table from a message file associated with an event source.

-W 

writes a record into a event log.

Secondary Options

In addition to the mode selection options listed in the previous section, you can also specify one or more of the following secondary options:

-a (valid with -l, -n, and -r

when specified with the -l option, enumerates all event sources registered under all logs on the specified host

When specified with the -n option, -a displays the total count of records in all logs on the specified host.

This option is only valid with the -r option when the -w option is specified and the -L option is not. In this case, -a waits for the full time out period specified by -w and displays all events logged by that time.

-b (valid with -r

displays records in chronologically decreasing order (that is, from the latest to the earliest). Normally, eventlog displays records in a chronologically increasing order (that is, earliest to latest).

-c eventcategory (valid with -r and -W

specifies the category that the source may have defined for its event IDs. With the -r option, the -p option is also necessary, because event categories are created relative to event sources. Also with the -r option, you can use multiple -c options to specify multiple categories as filters.

Event categories are numeric.

-D initialdate (valid with -r

specifies the starting date from which records are to be displayed. The initialdate argument is in the format [[[[cc]yy]mm]dd]hhmm[.ss] Dates of records are calculated based on local time. Normally, eventlog displays all records in the log file with a date of the starting date or later. With -b, it displays all records in the log file with a date of the starting date or earlier. When -M is specified with a days count, eventlog displays all records for the specified number of days from the starting date. When -M is specified with a final date, eventlog displays records from the starting date through the final date.

-d binarydatafile (valid with -W

specifies the event-specific binary data file for that particular event.

-F formatoptions (valid with -r

specifies the format of the output. The output of eventlog has one record per line. The format options are:

e - event log
p - event source
i - event ID (full 32-bit ID in hexadecimal)
r - event type
c - event category
d - date (MM/DD/YY)
t - time (HH:MM:SS - 24 hr. format)
u - user (Domain\User)
m - computer name
s - description string
b - binary data
C - replace comma with semicolon in description string
S - do not output description string in default format
    (The default format is epircdtum).
B - display binary data in default format (The default format
    is epircdtumsb).

The format option strings epircdtumsb and SB are mutually exclusive sets. formatoptions is a string of format options with no white space separating them The options are scanned left to right and for each letter, eventlog displays the requisite file on the line for the record, delimited with the specified delimiter (see -m). For example, the command:

eventlog -r -R -S test1 -s application p "NuTCracker 4" -F epdd

displays a record line like the following:

application	NutCracker 4	4/3/2001	4/3/2001

The default format string is epircdtums. When information is not available for a field, eventlog displays N/A.

-f (valid with -B and -C

suppresses the prompts generated by the -B and -C options.

-I (valid with -r

displays the lower word of the event ID in decimal instead of the whole double word in hex. This matches the output of the Administration Tool "Event Viewer" which just displays the decimal version of the lower word.

-i eventid (valid with -r and -W

specifies an event ID. The value given for eventid can be decimal, octal (when it begins with a 0), or hexadecimal (when it begins with x or X).

With -r, this event ID is used as a filter to select specific event log entries. You must also specify the -p option, because event IDs are created relative to event sources. Finally, you can use multiple -i options with -r to specify multiple event IDs as filters.

The TK_EVENTLOG_USE_FULL_EVENTID environment variable determines whether or not the full double word value of the specified event ID is used as the filter. When this variable is set, the full double word value is used; when it is unset (the default condition), only the lower 16-bit word is used as the filter.

With -W, the -i is always required and specifies the event ID to be logged into the event log. Consistency with the event source (-p) is the user's responsibility. The full double word value of the specified event ID is always written, regardless of the value of the TK_EVENTLOG_USE_FULL_EVENTID environment variable.

-L backupfile (valid with -r

read log entries from the specified backup file instead of the event log specified with the -s option. Neither -a nor -w are valid when you specify this option.

As described with the -B option, eventlog creates backup files with names of the form somename.eventlog.hostname.evt. The eventlog utility obtains the description strings for event IDs associated with log eventlog on host hostname. A log name specified with the -s option and a remote system specified with the -S option overrides eventlog and hostname respectively. When the name of the backup file does not contain the eventlog and the hostname components, the default eventlog and hostname are application and the local host, respectively.

-M daycount|finaldate (valid with -r

specifies the end of the date range for which eventlog displays records. When you specify daycount, the end of the date range is that many days from the beginning of the date range. When you specify finaldate, which is a date in the format [[[[cc]yy]mm]dd]hhmm[.ss], the end of the date range is that date.

The beginning of the date range is the initial date specified by the -D. When -D is not specified, the beginning of the date range is the date of the earliest record in the log file, or if -b is specified (reversing the order in which records are displayed), the date of the most recent record in the log file.

-m delimiter (valid with -r

specifies the delimiter to use between the output fields. The default is a tab. For example:

eventlog -s System -p Tcpip -i 4199 -F epircdtum

produces:

System	Tcpip	4199	Error	None	4/3/2001	11:36:27	N/A	DEV26A

and:

eventlog -s System -p Tcpip -i 4199 

produces:

System	Tcpip	4199	Error	None	4/3/2001	11:36:27	N/A	DEV26A	The system detected an address conflict for IP address 10.91.1.121 with the system having network hardware address 00:50:BA:48:AF:19. Network operations on this system may be disrupted as a result.

Finally:

eventlog  -s System -p Tcpip -i 4199 -v -m "$$$" -F epircdtumsb

produces:

System$$$Tcpip$$$4199$$$Error$$$None$$$4/3/2001$$$11:36:27$$$N/A$$$DEV26A$$$The system detected an address conflict for IP address 10.91.1.121 with the system having network hardware address 00:50:BA:48:AF:19. Network operations on this system may be disrupted as a result.$$$00 00 00 00 03 00 50 00 00 00 00 00 67 10 00 c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  
-N recordcount (valid with -r

specifies the number of records to be displayed from the offset specified by -o. When the -o option is not specified, eventlog displays recordcount records beginning with the earliest record in the log file (or the most recent record if -b is also specified).

If there are not enough records in the log file (or part of the file that is to be displayed) to meet the specified recordcount, all remaining records are displayed.

You cannot specify a value of zero for recordcount. If you also specify the -w option, -N has no effect.

-o offset (valid with -r

specifies the starting record number from which records are to be displayed. The offset starts with number 1 and is counted from the earliest record in the log file. Normally, eventlog displays the starting record and all later records; however, if -b is specified, it displays the starting record and all earlier records.

When -N recordcount is also specified, eventlog displays no more than recordcount records.

The offset value cannot be zero and it cannot be greater than the number of records in the specified log. If you also specify the -w option, -o has no effect.

-P messagefiletype (valid with -T

specifies the type of message file to be dumped. The valid arguments for this option are event for EventMessageFile, parameter for ParameterMessageFile and category for CategoryMessageFile. When -P is not specified with -T, the default is event.

-p eventsource (valid with -l, -r, -T, and -W

specifies the application which is generating (during writing, that is, -W) or has generated (during reading, that is, -r) the log entries. This option is also used with the -T option to specify the event source whose message strings are to be dumped. These application subkeys are under the log file subkeys in the registry.

This option is required with the -T and -W options, but is optional with -r and -l. With -r, you can specify multiple -p options to indicate multiple event sources as filters, but only when neither -i nor -c is specified.

-R eventtype (valid with -r and -W

specifies the type or priority of the event being logged. There are six types of valid events: success, error, warning, information, audit_success, and audit_failure.

This option is required with the -W option, but is optional with -r With -r, you can specify multiple -R options to indicate multiple event types as filters.

-S hostname (valid with -B, -C, -l. -n, -r, -T, and -W

specifies the name of the host whose log file is to be written to or read from. When this option is not specified, the log file of the local system is read or written as the default. Optionally, hostname may be preceded by \\ or //.

You cannot specify this option with -w.

-s eventlog (valid with -B, -C, -l. -n, -r, -T, and -W

specifies the name of the event log. When this option is not specified, the Application event log is taken to be the default.

-t insertionstring (valid with -W

defines a string which can be inserted into the description string of the specified event ID of the specified event source, as needed. You can specify this option multiple times. The first -t identifies the first insertion string, and so on. Consistency with the event ID specified with -i and the event source specified with -p is the user's responsibility; this includes the number of -t options which can be specified.

-timeout seconds 

specifies the number of seconds that eventlog has to complete the operation before timing out and issuing an error.

If both -timeout and -w are specified with -r, only -w applies; -timeout is ignored.

-v (valid with -n

displays the log name whose records are being counted.

-w [timeout] (valid with -r

waits up to a maximum of timeout seconds for an event to be logged into the specified event log. When you do not specify a value for timeout, eventlog waits forever for an event to be logged. Normally, eventlog exits after displaying the first event logged. When the -a option is specified, eventlog displays all events logged during the wait period; it only exits when the waiting period (timeout) is finished.

The -S option is not valid with this option because event notification cannot be done for remote hosts. The -b option has no effect when you specify this option. The -w option overrides both -o and -N.

If both -timeout and -w are specified with -r, only -w applies; -timeout is ignored.


EXAMPLES

This command displays all the event records in the Application event log of host dev30:

eventlog -r -S dev30 -s Application 

This command displays all event records caused by the "NuTCRACKER 4" application in the application event log of host dev30:

eventlog -r -S dev30 -s Application -p "NuTCRACKER 4"

This command displays event records starting from the record number 24 through the newest event record from the Application event log of host dev30:

eventlog -r -S dev30 -s Application -o 24

This command displays 24 records from record number 100 in chronologically increasing order from the system event log of host dev30:

eventlog -r -S dev30 -s System -o 100 -N 24

This command displays 100 records from system event log of host dev30, from oldest record:

eventlog -r -S dev30 -s System -N 100

This command displays event records starting from the record number 24 through the oldest record from the Application event log of host dev30:

eventlog -r -S dev30 -s Application -o 24 -b

This command displays 100 records from record number 24 in chronologically decreasing order from system event log of host dev30:

eventlog -r -S dev30 -s System -o 24 -N 100 -b

This command displays 24 records from record number 24 in chronologically decreasing order from system event log of host dev30:

eventlog -r -S dev30 -s System -o 24 -N 24 -b

This command displays 100 records from system event log of host dev30, from the newest record:

eventlog -r -S dev30 -s System -N 100 -b

This command displays records for 10 days starting from date 2/24/2001 and later from the system event log of host dev30:

eventlog -r -S dev30 -s system -D 200102140000 -M 10

This command displays records from the end of the day on 2/14/2001 through the beginning of 1/13/2001 in a chronologically decreasing order:

eventlog -r -S dev30 -s System -D 200102142359.59 -M 200101130000 -b

With the following command, the eventlog utility waits for 15 seconds for an event to be logged in the Application event log of the local host, displays it and exits:

eventlog -r -s Application -w 15

With the following command, the eventlog utility waits indefinitely from the time it is invoked for events to be logged in the Application event log of the local host, and displays them:

eventlog -r -s Application -w -a

This command displays the number of records in the Security event log:

eventlog -S dev30 -s Security -n

This command clears the Application event log after asking the user whether the user really wants to remove all records in the log:

eventlog -S dev30 -s Application -C

This next command takes the backup of the System event log of host dev30 into the file sys.system.dev30 in share backup of host dev30. If a file called sys.system.dev30 already exists, it silently overwrites (due to the extra -f option).

eventlog -S dev30 -s System -B \\dev30\backup\sys -f

This command enumerates all the logs available on dev30:

eventlog -S dev30 -l

This next command writes an event into the Application event log of dev30 with the priority - Error, category - 0, message id - 12055 (Failed to establish RPC connection to NuTCRACKER Service (error=1702). [%1 (xftconsole.cpp:919) PID=1312 TID=652]) with NiceTest for %1.

eventlog -W -S dev30 -p "NuTCRACKER 4" -R Error -c 0 -i 12055 -t "NiceTest"

This next command dumps the message table of the parameter message files associated with event source NuTCracker:

eventlog -T -p"NuTCracker 4" -P parameter

ENVIRONMENT VARIABLES

TK_EVENTLOG_USE_FULL_EVENTID 

determines whether or not the -r option uses the full double word value of the event ID specified with -i as a filter. When this variable is set, the full double word value is used; when it is unset (the default condition), only the lower 16-bit word is used as the filter.

This environment variable has no effect on the behavior of the -W option.


DIAGNOSTICS

Possible exit status values are:

0 

Successful completion.

1 

Failure.

2 

Failure due to problem with specified command line.


PORTABILITY

Windows 7. Windows Server 2008 R2. Windows 8. Windows Server 2012. Windows 10. Windows Server 2016.


AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


PTC MKS Toolkit 10.1 Documentation Build 15.