3.1.4.22 EvtRpcPutChannelConfig (Opnum 21)

  • Article

The EvtRpcPutChannelConfig (Opnum 21) method is used by a client to update the configuration for a channel.

 error_status_t EvtRpcPutChannelConfig(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, range(1, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR channelPath,
   [in] DWORD flags,
   [in] EvtRpcVariantList* props,
   [out] RpcInfo* error
 );

binding: An RPC binding handle as specified in section 2.2.21.

channelPath: A pointer to a string that contains a channel name (this is not a file path as the parameter name might suggest).

flags: A 32-bit unsigned integer that indicates what to do depending on the existence of the channel. This MUST be set to one of the following, and the server SHOULD return ERROR_INVALID_PARAMETER (0x00000057) if the flag is not one of the following values.<40>

Value

Meaning

0x00000000

The server MUST open the existing channel entry in its channel table or create a new entry if the specified channel is not in the table.

0x00000001

The server MUST open the existing channel entry in its channel table.

0x00000002

Always create a new channel entry in the server's channel table and delete the existing entry.

0x00000003

Only create a new channel entry in the server's channel table.

props: A pointer to an EvtRpcVariantList (section 2.2.9) structure containing channel properties, as defined in the following table.

Index

Type

Meaning

0

EvtRpcVarTypeBoolean

Enabled. If true, the channel can accept new events. If false, any attempts to write events into this channel are automatically dropped.

1

EvtRpcVarTypeUInt32

Channel Isolation. It defines the default access permissions for the channel. Three values are allowed:

  • 0: Application.

  • 1: System.

  • 2: Custom.

The default isolation is Application. The default permissions for Application are (shown using SDDL):

  • L"O:BAG:SYD:"

  • L"(A;;0xf0007;;;SY)" // local system (read, write, clear)

  • L"(A;;0x7;;;BA)" // built-in admins (read, write, clear)

  • L"(A;;0x7;;;SO)" // server operators (read, write, clear)

  • L"(A;;0x3;;;IU)" // INTERACTIVE LOGON (read, write)

  • L"(A;;0x3;;;SU)" // SERVICES LOGON (read, write)

  • L"(A;;0x3;;;S-1-5-3)" // BATCH LOGON (read, write)

  • L"(A;;0x3;;;S-1-5-33)" // write restricted service (read,write)

  • L"(A;;0x1;;;S-1-5-32-573)"; // event log readers (read)

The default permissions for System are (shown using SDDL):

  • L"O:BAG:SYD:"

  • L"(A;;0xf0007;;;SY)" // local system (read, write, clear)

  • L"(A;;0x7;;;BA)" // built-in admins (read, write, clear)

  • L"(A;;0x3;;;BO)" // backup operators (read, write)

  • L"(A;;0x5;;;SO)" // server operators (read, clear)

  • L"(A;;0x1;;;IU)" // INTERACTIVE LOGON (read)

  • L"(A;;0x3;;;SU)" // SERVICES LOGON (read, write)

  • L"(A;;0x1;;;S-1-5-3)" // BATCH LOGON (read)

  • L"(A;;0x2;;;S-1-5-33)" // write restricted service (write)

  • L"(A;;0x1;;;S-1-5-32-573)"; // event log readers (read)

When the Custom value is used, the Access property will contain the defined SDDL.

2

EvtRpcVarTypeUInt32

Channel Type. One of four values:

  • 0: Admin

  • 1: Operational.

  • 2: Analytic

  • 3: Debug

For more information, see [MSDN-EVTLGCHWINEVTLG].

3

EvtRpcVarTypeString

OwningPublisher. The name of the publisher that defines and registers the channel with the system.

4

EvtRpcVarTypeBoolean

ClassicEventlog. If true, the channel represents an event log created according to the EventLog Remoting Protocol, not this protocol (EventLog Remoting Protocol Version 6.0).

5

EvtRpcVarTypeString

Access. A Security Descriptor Description Language (SDDL) string, as specified in [MS-DTYP], that represents access permissions to the channels. If the isolation attribute is set to Application or System, the access descriptor controls read access to the file (the write permissions are ignored). If the isolation attribute is set to Custom, the access descriptor controls write access to the channel and read access to the file.

6

EvtRpcVarTypeBoolean

Retention. If set to true, events can never be overwritten unless explicitly cleared. This is the way to configure the logs to be circular. If set to false, events are overwritten as needed when the event log is full.

7

EvtRpcVarTypeBoolean

AutoBackup. When set to true, the event log file associated with the channel is closed as soon as it reaches the maximum size specified by the MaxSize property, and a new file is opened to accept new events. If the new file reaches maximum size, another new file will be generated and the previous new file will be backed up. The events in backed up files cannot be queried from this channel in the server unless the client specifies the backup log file names in a separate query.

8

EvtRpcVarTypeUInt64

MaxSize. The value that indicates at which point the size (in bytes) of the event log file stops increasing. When the size is greater than or equal to this value, the file growth stops.

9

EvtRpcVarTypeString

LogFilePath. The server changes the file path to the event log file for the channel.

10

EvtRpcVarTypeUInt32

Level. Events with a level property less than or equal to this specified value are logged to the channel.

11

EvtRpcVarTypeUInt64

Keywords. Events with a keyword bit contained in the keywords bitmask set are logged to the channel.

12

EvtRpcVarTypeGuid

ControlGuid. A GUID value. The server SHOULD ignore this value.<41>

19

EvtRpcVarTypeStringArray

PublisherList. A list of publishers that can raise events into the channel.

20

EvtRpcVarTypeUInt32

FileMax. The maximum number of log files associated with an analytic or debug channel. When the number of logs reaches the specified maximum, the system begins to overwrite the logs, beginning with the oldest. A FileMax value of 0 or 1 indicates that only one file is associated with this channel. A MaxFile of 0 is the default.

error: A pointer to an RpcInfo (section 2.2.1) structure in which to place error information in the case of a failure. The RpcInfo (section 2.2.1) structure fields MUST be set to nonzero values if the error is related to a particular property. All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all of the values in the structure to 0.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success; otherwise, it MUST return an implementation-specific nonzero value as specified in [MS-ERREF].<42>

In response to this request from the client, the server MUST verify that the channelPath parameter specifies a valid channel name. The server MUST fail the method if the parameter is invalid with the error ERROR_INVALID_PARAMETER (0x00000057). The server checks if a channel name is valid by searching the given name in its channel table.

Next, the server MUST verify that the caller has write access to the information and MUST fail the method with the error ERROR_ACCESS_DENIED (0x00000005) if the caller does not have write access. To perform the access check, the server SHOULD first determine the identity of the caller. Information determining the identity of the caller for the purpose of performing an access check is specified in [MS-RPCE] section 3.2.3.4.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 3.1.4.21) as the security descriptor string. Next, the server SHOULD be able to perform the write and clear access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2).

If the client specifies 0x00000000 for the flags value, the server MUST try to find the channel entry specified by the channelPath parameter in its channel table. If the server does not find the channel entry in the table, it creates a new entry with the parameter channelPath as the new channel name. The creation of a new channel table entry SHOULD only fail when there is inadequate memory. The server SHOULD return ERROR_OUTOFMEMORY (0x0000000E) in that case. When a new channel is created, the server SHOULD assign the default property values to the channel as in the following table.

Property

Default Value

Enabled

true

Isolation

0

ChannelType

0

OwningPublisher

null

Classic

false

Access

"O:BAG:SYD:(A;;0xf0007;;;SY)(A;;0x7;;;BA)(A;;0x7;;;SO)"(A;;0x3;;;IU)(A;;0x3;;;SU)(A;;0x3;;;S-1-5-3)(A;;0x3;;;S-1-5-33)(A;;0x1;;;S-1-5-32-573)"

Retention

false

Autobackup

false

maxSize

20 * 1024 * 1024

LogFilePath

%systemfolder%\winevt\<channelname>.evtx

Level

0

Keywords

0xFFFFFFFFFFFFFFFF

ControlGuid

{00000000-0000-0000-0000-000000000000}

BufferSize

64K

MinBuffers

2 * Number of the CPUs.

MaxBuffers

22 + MinBuffers

Latency

1

ClockType

0

SidType

1

PublisherList

null

FileMax

0

If the client specifies 0x00000001 for the flags value and the specified channel entry is not found in the channel table, the server MUST return ERROR_NOT_FOUND (0x00000490).

If the client specifies 0x00000002 for the flags value, the processing rule is similar to processing rule 1 except that when the server finds the exiting channel entry, it SHOULD delete it first before creating a new one. Delete an existing entry SHOULD never fail.

If the client specifies the 0x00000003 for the flags value, the server MUST fail the method if the specified channel is already in the channel table with the error code ERROR_ALREADY_EXISTS (0x000000B7).

The server SHOULD check if the publisher specified has already registered in its publisher table when the client tries to update the owning publisher property. If not, the server SHOULD fail the method with ERROR_INVALID_PARAMETER (0x00000057).<43>

Note The configuration properties for BufferSize, MinBuffers, MaxBuffers, Latency, ClockType, and SIDType can't be updated by the client. These properties are maintained by the server administrator on the physical machine only and cannot be updated through the remote protocol methods. The server administrator can specify these properties with any allowable values.<44> The server SHOULD make sure the client does not update these properties. The server SHOULD fail the method with the error ERROR_INVALID_OPERATION (0x000010DD) in this case.

If the previous checks succeed, the server MUST attempt to update the channel's properties using the value specified in the props parameter. The server SHOULD proceed in the following manner to update the data for each channel property:

The server SHOULD allocate a memory block with the same size as the EvtRpcVariantList (section 2.2.9) pointed to by the props parameter. If the memory allocation fails, the server SHOULD return ERROR_OUTOFMEMORY (0x0000000E). The server then copies all the data in the props parameter into the new allocated memory block. Before copying the data, the server SHOULD validate the data as follows:

  • The Isolation property SHOULD be either 0, 1, or 2, if the client has specified that property.

  • The Channel type property SHOULD be either 0, 1, 2, or 3, if the client has specified that property.

  • The Access property string SHOULD be a valid security descriptor as specified in section [MS-DTYP], if the client specifies that property. Note that the only access permissions defined for channels are read, write, and clear; if a client attempts to specify any other access permissions in the security descriptor, the server SHOULD ignore them.

  • The LogFilePath property MUST be a valid file path string for the server's file system, if the client specifies that property.

  • The server SHOULD verify that the publishers specified in the PublisherList property exist in the server's publisher table. If so, the server SHOULD add the current channel to the publisher entries in the server's publisher table for every publisher specified by the PublisherList property so that as soon as the new settings are applied, the server is prepared for those publishers to publish events to this channel.

If any of the validation checks fail, the server SHOULD return ERROR_INVALID_DATA. After copying the data, the server SHOULD return to the client with ERROR_SUCCESS (0x00000000), but SHOULD NOT apply the new channel properties until EvtRpcAssertConfig is called or the server restarts. EvtRpcAssertConfig causes the server to apply an in-memory copy of the channel configuration, whereas when the server restarts, it loads channel configuration data from persistent storage as specified in section 3.1.1.5. Before applying the properties, all the server's behaviors are still the same as they were originally, even after the method has successfully returned to the client. For information on the server saving the configuration and then applying the changes with the EvtRpcAssertConfig method, see the processing rules in EvtRpcAssertConfig (section 3.1.4.29). The server SHOULD check if the value passed by the client is within the allowed range. If not, the server SHOULD return ERROR_INVALID_PARAMETER (0x00000057). The server will not fail the method if all the previous checks are passed.

The server MUST return a value indicating success or failure for this operation.