Eventlog HOWTO - temporary copy,

(This used to be commit 5f55944ee5)

docs/Samba-EventLog-HOWTO.txt

@@ -0,0 +1,130 @@
+##
+## Samba-EventLog-HOWTO.txt
+## Brian Moran <bmoran@centeris.com>
+##
+## Feature Introduced in Samba 3.0.21
+##
+
+Samba and Eventlogs
+===================
+
+Samba servers now support event logs -- this means that if 
+Samba is configured correctly, the usual administration tools 
+like event viewer will work against a Samba server. 
+
+To minimally configure Samba to publish event logs, the
+eventlogs to list must be specified in smb.conf, and 
+eventlog entries must be written to those eventlogs. 
+
+Optionally, a message file can be registered for each 
+of the eventlog 'sources' to pretty-print the eventlog 
+messages in the eventlog viewer. 
+
+Configuring smb.conf
+====================
+
+To specify the list of eventlogs the eventlog list 
+command is used. An example which will show four 
+eventlogs is 
+
+	eventlog list = Application System Security  SyslogLinux
+
+When Samba initially starts, it looks to see if the 
+eventlog directory, and a particular log exists; if not, 
+the  directory and file are created under LOCK_DIR 
+
+Writing EventLog Records
+========================
+
+The eventlogadm command is used to write records 
+into a particular eventlog. Eventlogadm expects records 
+to be on STDIN in the following format
+
+	LEN: 0
+	RS1: 1699505740
+	RCN: 0
+	TMG: 1128631322
+	TMW: 1128631322
+	EID: 1000
+	ETP: INFO
+	ECT: 0
+	RS2: 0
+	CRN: 0
+	USL: 0
+	SRC: cron
+	SRN: dmlinux
+	STR: (root) CMD ( rm -f /var/spool/cron/lastrun/cron.hourly)
+	DAT: 
+
+These fields closely mirror the eventlog structures 
+used by the APIs.  The definitions of the fields are 
+
+- LEN: <integer>  The length field is calculated by the
+  eventlogadm program based on the rest of the information 
+  in the record.  Zero works well here.
+- RS1: 1699505740 A "magic number", the primary purpose of
+  which seems to be to be able to find eventlog records in a 
+  sea of binary data 
+- TMG: <integer>  The time the eventlog record was generated;
+  format is the number of seconds since 00:00:00 January 1, 
+  1970, UTC
+- TMW: <integer>  The time the eventlog record was written;
+  format is the number of seconds since 00:00:00 January 1, 
+  1970, UTC
+- EID: <integer>  The eventlog ID -- used as a index to a
+  message string in a message DLSamba and Eventlogs
+- ETP: <string>   The event type -- one of INFO, ERROR,
+  WARNING, AUDIT SUCCESS, AUDIT FAILURE
+- ECT: <integer>  The event category; this depends on the
+  message file -- primarily used as a means of filtering in 
+  the eventlog viewer
+- RS2: 0 Another reserved field
+- CRN: 0 Yet another reserved field
+- USL: <integer>  Typically would contain the length of the
+  SID of the user object associated with this event. This is 
+  not supported now, so leave this zero.
+- SRC: <string>   The source name associated with the event
+  log, e.g. "cron" or "smbd". If a message file is used with an 
+  event log, there will be a registry entry for associating 
+  this source name with a message file DLL
+- SRN: <string>   The name of the machine on which the
+  eventlog was generated. This is typically the host name
+- STR: <string>   The text associated with the eventlog. Note
+  that there may be more than one strings in a record
+- DAT: <string>   Eventlog records can have binary information
+  associated with them. DAT only supports ASCII strings however
+
+Typically, one would set up a program to gather events, format 
+them into records, and pipe them into eventlogadm for a 
+particular eventlog:
+
+# tail -f /var/log/messages |\
+	my_program_to_parse_into_eventlog_records |\
+	eventlogadm SyslogLinux
+
+Note that individual records are separated on the input by one 
+or more blank lines. In this manner, eventlogadm will just wait 
+for more input, writing to the underlying log files as necessary.
+
+
+Deciphering EventLog entries on the Client
+==========================================
+
+To set up an eventlog source (which is used by the eventlog viewer
+program to pretty-print eventlog records), create a message file 
+DLL,  then use the eventlogadm program to write the appropriate 
+eventlog registry entries:
+
+# eventlogadm -o addsource Application MyApplication \
+	%SystemRoot%/system32/MyApplication.dll
+
+This will add the key
+[HKLM/System/CurrentControlSet/services/Eventlog/Application/MyApplication]
+and to that key add value "MyApplication/EventLogMessageFile" 
+with a string of %SystemRoot%/system32/MyApplication.dll
+
+If there happens to be a share called [C$] on your samba server, 
+and in that share there's a Windows/system32/MyApplication.dll 
+file, it will be read by the eventlog viewer application when 
+displaying eventlog records to pretty-print your eventlog entries.
+