3. Managing Event
Information with the WEvtUtil Utility
The WEvtUtil utility helps
you monitor the event logs on a system. This utility replaces the other
utilities provided in earlier versions of Windows. You might wonder
about this change, until you begin looking at the Server Core event log
setup, which is very complex. (The new event logs are a significant
change from past versions of Windows that have contained the same few
logs.) The WEvtUtil utility has the flexibility required to work with
Server Core's complex event log setup. This utility uses the following
syntax:
WEvtUtil COMMAND [ARGUMENT [ARGUMENT] ...] [/OPTION:VALUE [/OPTION:VALUE] ...]
It helps to discuss
WEvtUtil command line arguments as commands and common options (with
associated arguments). The following list describes each of the commands
(the short name appears first, followed by the long name in
parentheses).
el (enum-logs)
Displays a list of
all of the logs on the system.
gl (get-log)
Logname
Obtains
configuration information about a specific log. You must provide the
fully qualified name of the log that you want to work with. For example,
if you want to know about the Backup log, you must provide the fully
qualified name of Microsoft-Windows-Backup. Use the el command to obtain a list of fully qualified
names.
sl (set-log)
Logname [/Option:Value [/Option:Value] ...] Changes the configuration of a log file. You can
supply option/value pairs or use an XML file to make the changes. The
WEvtUtil utility accepts either short or long option names. When using
an XML file, you must supply the /c
option. The following list describes the option/value pairs used to
configure a log (the long names appear in parentheses after the option).
/e:{True | False} (enabled)
Enables or
disables the log. The default value is true to enable the log.
/i:{System | Application | Custom} (isolation)
Defines the log
isolation mode: system, application, or custom. In addition, the mode
identifies the other logs with which the log shares a session, which
means these other logs have write permission for the target log. Use the
System mode when a log affects that system as a whole. The resulting
log shares a session with the System log. The Application mode is the
option to use with general applications. Logs in this class share a
session with the Application log. The Custom mode is for private logs
that you don't want to share a session with any other log. You must use
the /ca option to define security for custom logs.
/lfn:
Value
(logfilename)
Provides the full
path to the physical location of the log on the hard drive.
/rt:{True | False} (retention)
Determines
whether the log retains existing entries when the log becomes full. When
you set the log retention mode to True, the log retains earlier entries
when the log becomes full and discards all new entries. The default
value of false discards older entries in favor of new ones.
/ab:{True | False} (autobackup)
Performs an
automatic backup of the log when it reaches maximum size. You must set
the retention value to true using the /rt option when using
this feature.
/ms:
Value
(maxsize)
Specifies the
maximum log size in bytes. The maximum log size in Server Core is
1,048,576 bytes (1,024 KB). Log files are always multiples of 64 KB, so
Server Core rounds any value you provide to a multiple of 64 KB.
/l:
Value
(level)
Defines the log
level filter (normally critical, error, warning, information, or
verbose). You may use any valid level value. This feature is only
applicable to logs with a dedicated session (which means that the
isolation mode is normally custom). You can remove a level filter by
setting the value to 0.
/k:
Value
(keywords)
Defines the log
keyword filter (common keywords include Audit Failure, Audit Success,
Classic, Correlation Hint, Software Quality Monitoring (SQM), Windows
Diagnostics Infrastructure (WDI) Context, and WDI Diag). The value can
include any valid 64-bit keyword mask. This feature is only applicable
to logs with a dedicated session (which means that the isolation mode is
normally custom).
/ca:
Value
(channelaccess)
Defines the
access permission for an event log. You must provide a valid security
descriptor defined using the Security Descriptor Definition Language
(SDDL). You can learn more about SDDL at http://msdn2.microsoft.com/en-us/library/aa379567.aspx.
/c:
Value
(config)
Defines a path to a
configuration file. The configuration file contains log file settings in
the form of an XML file. When using this feature, you must not specify
the logname command line argument
because this value is ready as part of the configuration file. Here's a
typical example of a configuration file.
<?xml version="1.0" encoding="UTF-8"?>
<channel name="Application" isolation="Application"
xmlns="http://schemas.microsoft.com/win/2004/08/events">
<logging>
<retention>true</retention>
<autoBackup>true</autoBackup>
<maxSize>9000000</maxSize>
</logging>
<publishing>
</publishing>
</channel>
Notice that the <channel> element includes the log filename as Application
and an isolation level (/i) of Application.
The logging options appear as part of the <logging> element. Each child element name is the long name
for an option. For example, the <retention>
element corresponds to the /rt command
line argument. You can add other configuration options to the log, such
as the publishing options.
ep (enum-publishers)
Displays a list of
event publishers. The list can be quite long, so you'll normally want to
redirect the output to a text file.
gp (get-publisher)
PublisherName [/OPTION:VALUE
[/OPTION:VALUE] ...]
Obtains
specific event publisher configuration information. The output includes
such helpful information as a publisher help link and the name of the
DLL used to create event entries. This argument also supports the
following options (the long names appear in parentheses after the
option).
/ge:{True | False} (getevents)
Obtains
metadata for the events that this publisher will raise, in addition to
the standard data.
/gm:{True | False} (getmessage)
Obtains the
actual messages that the event entries will use instead of the message
ID.
/f:{XML | Text} (format)
Determines the
output format of the data. The default setting is Test. When you use
XML, the output appears as an XML file that you can view using any XML
viewer (making the output considerably easier to understand).
im (install-manifest)
Manifest
Installs an
event manifest. The manifest can contain multiple publishers and logs.
You can obtain an overview of event manifest instrumentation at http://msdn2.microsoft.com/en-gb/library/aa385227.aspx.
um (uninstall-manifest)
Manifest
Removes the specified event manifest from
the system.
qe (query-events)
Path [/OPTION:VALUE
[/OPTION:VALUE] ...]
Outputs event
information from a log or log file. The path argument normally contains
the name of the log. However, if you use the /lf option, then you must provide the physical path to the event
log file. This argument also supports the following options (the long
names appear in parentheses after the option).
/lf:{True | False} (logfile)
Specifies
that the path argument contains a physical path to a log file, rather
than a log filename.
/sq:{True | False} (structuredquery)
Specifies
that the path argument contains a path to a file that contains a
structure query.
/q:
Value
(query)
Provides an
XPath query to filter the events read from the log. The utility returns
all of the events when you don't provide this option. You can't use this
option with the /sq option.
/bm:
Value
(bookmark)
Specifies a
path to a file that contains a bookmark from a previous query. Using a
bookmark lets you continue a previous query.
/sbm:
Value
(savebookmark)
Specifies a path to a
file that the utility uses to store a bookmark for the current query.
The bookmark file extension should be XML.
/rd:{True | False} (reversedirection)
Defines the
direction in which the utility reads events. The default setting of true
returns the most current events first.
/f:{XML | Text} (format)
Determines the
output format of the data. The default setting is Test. When you use
XML, the output appears as an XML file that you can view using any XML
viewer (making the output considerably easier to understand).
/l:
LCID
(locale)
Provides a
locale string that defines the locale used to output text information.
This option is only available when you use the /f option to
print events in text format.
/c:
Number
(count)
Defines the
maximum number of events to read. If you combine this switch with the
bookmark feature, you can read a segment of the event log at a time.
/e:
RootElementName
(element)
Defines a root
element name to use to produce well-formed XML.
gli (get-log-info)
Path
Outputs
information about the specified log. The path argument normally contains
the name of the log. However, if you use the /lf option, then you must provide the physical path to the
event log file. This argument also supports the following options (the
long names appear in parentheses after the option).
/lf:{True | False} (logfile)
Specifies
that the path argument contains a physical path to a log file, rather
than a log filename.
epl (export-log)
Path TargetFile [/OPTION:VALUE
[/OPTION:VALUE] ...]
Exports a log to the
specified target file. The path argument normally contains the name of
the log. However, if you use the /lf
option, then you must provide the physical path to the event log file.
This argument also supports the following options (the long names appear
in parentheses after the option).
/lf:{True | False} (logfile)
Specifies
that the path argument contains a physical path to a log file, rather
than a log filename.
/sq:{True | False} (structuredquery)
Specifies
that the path argument contains a path to a file that contains a
structure query.
/q:
Value
(query)
Provides an
XPath query to filter the events read from the log. The utility returns
all of the events when you don't provide this option. You can't use this
option with the /sq option.
/ow:{True | False} (overwrite)
Overwrites
the contents in any existing target file without confirmation when set
to True. The default setting is False.
al (archive-log)
LogFile [/OPTION:VALUE
[/OPTION:VALUE] ...]
Archives an
exported log—the log entries remain in place, but the utility outputs a
copy of all existing log entries. You can create a log using either the export-log
or clear-log commands. This
argument also supports the following options (the long names appear in
parentheses after the option).
/l:
LCID
(locale)
Provides a
locale string that defines the locale used to output text information.
This option is only available when you use the /f option to print events in text format.
cl (clear-log)
LogName
[/
OPTION: VALUE]
Clears the
specified log. This command differs from archiving in that the utility
actually clears the log entries instead of leaving them in place. This
argument also supports the following option (the long names appear in
parentheses after the option).
/bu:
Filename
(backup)
Creates a backup
of the log before clearing it. You must specify a backup filename with
an EVTX extension. (Don't use the EVT extension used with previous
version of Windows because the file formats aren't compatible.)
Most of the commands
use common options. The options are in addition to the special options
discussed as part of the commands. The following list describes each of
the options.
NOTE
There are some
differences between the WEvtUtil options and the options used by other
utilities, even though many of them perform the same function. For
example, the familiar /S command line switch (for remote
system) is now the /r command line
switch. Be careful when making assumptions about the options for this
utility.
/r:
System
(remote)
Specifies a
remote system. You can use any connected system to store the event log
entries. Some administrators send event log entries to a central
location to ensure someone sees them. The remote system must allow the
required access.
/u:
[domain\]user
(username)
Defines the user
context for executing the command. The user context is important
because not every user has access to the event log. In addition, the
user context appears as part of the event log entry.
/p:
Password
(password)
Provides a password
for the user context. The utility prompts you for the password (when
necessary) if you don't include it on the command line. In most cases,
supplying the password when prompted is safer from a security
perspective than including this information on the command line or as
part of a batch file entry.
/a:{Default | Negotiate | Kerberos | NTLM} (authentication)
Specifies the kind
of authentication to use for the remote location. The default value is
Negotiate. Using a specific value can improve security when the remote
machine offers multiple authentication options.
/uni:{True | False} (unicode)
Specifies
that the utility should display all output in Unicode when set to True.
