vfs_fruit: fix a typo
[sfrench/samba-autobuild/.git] / docs-xml / Samba-EventLog-HOWTO.txt
1 ##
2 ## Samba-EventLog-HOWTO.txt
3 ## Brian Moran <bmoran@centeris.com>
4 ##
5 ## Feature Introduced in Samba 3.0.21
6 ##
7
8 Samba and Eventlogs
9 ===================
10
11 Samba servers now support event logs -- this means that if 
12 Samba is configured correctly, the usual administration tools 
13 like event viewer will work against a Samba server. 
14
15 To minimally configure Samba to publish event logs, the
16 eventlogs to list must be specified in smb.conf, and 
17 eventlog entries must be written to those eventlogs. 
18
19 Optionally, a message file can be registered for each 
20 of the eventlog 'sources' to pretty-print the eventlog 
21 messages in the eventlog viewer. 
22
23 Configuring smb.conf
24 ====================
25
26 To specify the list of eventlogs the eventlog list 
27 command is used. An example which will show four 
28 eventlogs is 
29
30         eventlog list = Application System Security  SyslogLinux
31
32 When Samba initially starts, it looks to see if the 
33 eventlog directory, and a particular log exists; if not, 
34 the  directory and file are created under LOCK_DIR 
35
36 Writing EventLog Records
37 ========================
38
39 The eventlogadm command is used to write records 
40 into a particular eventlog. Eventlogadm expects records 
41 to be on STDIN in the following format
42
43         LEN: 0
44         RS1: 1699505740
45         RCN: 0
46         TMG: 1128631322
47         TMW: 1128631322
48         EID: 1000
49         ETP: INFO
50         ECT: 0
51         RS2: 0
52         CRN: 0
53         USL: 0
54         SRC: cron
55         SRN: dmlinux
56         STR: (root) CMD ( rm -f /var/spool/cron/lastrun/cron.hourly)
57         DAT: 
58
59 These fields closely mirror the eventlog structures 
60 used by the APIs.  The definitions of the fields are 
61
62 - LEN: <integer>  The length field is calculated by the
63   eventlogadm program based on the rest of the information 
64   in the record.  Zero works well here.
65 - RS1: 1699505740 A "magic number", the primary purpose of
66   which seems to be to be able to find eventlog records in a 
67   sea of binary data 
68 - TMG: <integer>  The time the eventlog record was generated;
69   format is the number of seconds since 00:00:00 January 1, 
70   1970, UTC
71 - TMW: <integer>  The time the eventlog record was written;
72   format is the number of seconds since 00:00:00 January 1, 
73   1970, UTC
74 - EID: <integer>  The eventlog ID -- used as a index to a
75   message string in a message DLSamba and Eventlogs
76 - ETP: <string>   The event type -- one of INFO, ERROR,
77   WARNING, AUDIT SUCCESS, AUDIT FAILURE
78 - ECT: <integer>  The event category; this depends on the
79   message file -- primarily used as a means of filtering in 
80   the eventlog viewer
81 - RS2: 0 Another reserved field
82 - CRN: 0 Yet another reserved field
83 - USL: <integer>  Typically would contain the length of the
84   SID of the user object associated with this event. This is 
85   not supported now, so leave this zero.
86 - SRC: <string>   The source name associated with the event
87   log, e.g. "cron" or "smbd". If a message file is used with an 
88   event log, there will be a registry entry for associating 
89   this source name with a message file DLL
90 - SRN: <string>   The name of the machine on which the
91   eventlog was generated. This is typically the host name
92 - STR: <string>   The text associated with the eventlog. Note
93   that there may be more than one strings in a record
94 - DAT: <string>   Eventlog records can have binary information
95   associated with them. DAT only supports ASCII strings however
96
97 Typically, one would set up a program to gather events, format 
98 them into records, and pipe them into eventlogadm for a 
99 particular eventlog:
100
101 # tail -f /var/log/messages |\
102         my_program_to_parse_into_eventlog_records |\
103         eventlogadm SyslogLinux
104
105 Note that individual records are separated on the input by one 
106 or more blank lines. In this manner, eventlogadm will just wait 
107 for more input, writing to the underlying log files as necessary.
108
109
110 Deciphering EventLog entries on the Client
111 ==========================================
112
113 To set up an eventlog source (which is used by the eventlog viewer
114 program to pretty-print eventlog records), create a message file 
115 DLL,  then use the eventlogadm program to write the appropriate 
116 eventlog registry entries:
117
118 # eventlogadm -o addsource Application MyApplication \
119         %SystemRoot%/system32/MyApplication.dll
120
121 This will add the key
122 [HKLM/System/CurrentControlSet/services/Eventlog/Application/MyApplication]
123 and to that key add value "MyApplication/EventLogMessageFile" 
124 with a string of %SystemRoot%/system32/MyApplication.dll
125
126 If there happens to be a share called [C$] on your samba server, 
127 and in that share there's a Windows/system32/MyApplication.dll 
128 file, it will be read by the eventlog viewer application when 
129 displaying eventlog records to pretty-print your eventlog entries.
130