1SMB_TRAFFIC_ANALYZER(8) System Administration tools SMB_TRAFFIC_ANALYZER(8)
2
6 vfs_smb_traffic_analyzer - log Samba VFS read and write operations
7 through a socket to a helper application
8
10 vfs objects = smb_traffic_analyzer
11
13 This VFS module is part of the samba(7) suite.
14 The vfs_smb_traffic_analyzer VFS module logs client file operations on
16 a Samba server and sends this data over a socket to a helper program
17 (in the following the "Receiver"), which feeds a SQL database. More
18 information on the helper programs can be obtained from the homepage of
19 the project at: http://holger123.wordpress.com/smb-traffic-analyzer/
20 Since the VFS module depends on a receiver that is doing something with
21 the data, it is evolving in it's development. Therefore, the module
22 works with different protocol versions, and the receiver has to be able
23 to decode the protocol that is used. The protocol version 1 was
24 introduced to Samba at September 25, 2008. It was a very simple
25 protocol, supporting only a small list of VFS operations, and had
26 several drawbacks. The protocol version 2 is a try to solve the
27 problems version 1 had while at the same time adding new features. With
28 the release of Samba 3.6.0, the module will run protocol version 2 by
29 default.
30
32 vfs_smb_traffic_analyzer protocol version 1 is aware of the following
33 VFS operations:
34 write
35 pwrite
36 read
37 pread
38 vfs_smb_traffic_analyzer sends the following data in a fixed format
40 separated by a comma through either an internet or a unix domain
41 socket:
42 BYTES|USER|DOMAIN|READ/WRITE|SHARE|FILENAME|TIMESTAMP
44 Description of the records:
47 · BYTES - the length in bytes of the VFS operation
49 · USER - the user who initiated the operation
51 · DOMAIN - the domain of the user
53 · READ/WRITE - either "W" for a write operation or "R" for read
55 · SHARE - the name of the share on which the VFS operation occurred
57 · FILENAME - the name of the file that was used by the VFS operation
59 · TIMESTAMP - a timestamp, formatted as "yyyy-mm-dd hh-mm-ss.ms"
61 indicating when the VFS operation occurred
62 · IP - The IP Address (v4 or v6) of the client machine that initiated
64 the VFS operation.
65 This module is stackable.
68
70 Several drawbacks have been seen with protocol version 1 over time.
71 · Problematic parsing - Protocol version 1 uses hyphen and comma to
73 seperate blocks of data. Once there is a filename with a hyphen,
74 you will run into problems because the receiver decodes the data in
75 a wrong way.
76 · Insecure network transfer - Protocol version 1 sends all it's data
78 as plaintext over the network.
79 · Limited set of supported VFS operations - Protocol version 1
81 supports only four VFS operations.
82 · No subreleases of the protocol - Protocol version 1 is fixed on
84 it's version, making it unable to introduce new features or
85 bugfixes through compatible sub-releases.
86
88 Protocol version 2 is an approach to solve the problems introduced with
89 protcol v1. From the users perspective, the following changes are most
90 prominent among other enhancements:
91 · The data from the module may be send encrypted, with a key stored
93 in secrets.tdb. The Receiver then has to use the same key. The
94 module does AES block encryption over the data to send.
95 · The module now can identify itself against the receiver with a
97 sub-release number, where the receiver may run with a different
98 sub-release number than the module. However, as long as both run on
99 the V2.x protocol, the receiver will not crash, even if the module
100 uses features only implemented in the newer subrelease. If the
101 module uses a new feature from a newer subrelease, and the receiver
102 runs an older protocol, it is just ignoring the functionality. Of
103 course it is best to have both the receiver and the module running
104 the same subrelease of the protocol.
105 · The parsing problems of protocol V1 can no longer happen, because
107 V2 is marshalling the data packages in a proper way.
108 · The module now potientially has the ability to create data on every
110 VFS function. As of protocol V2.0, there is support for 8 VFS
111 functions, namely write,read,pread,pwrite, rename,chdir,mkdir and
112 rmdir. Supporting more VFS functions is one of the targets for the
113 upcoming sub-releases.
114 To enable protocol V2, the protocol_version vfs option has to be used
117 (see OPTIONS).
118
120 smb_traffic_analyzer:mode = STRING
121 If STRING matches to "unix_domain_socket", the module will use a
122 unix domain socket located at /var/tmp/stadsocket, if STRING
123 contains an different string or is not defined, the module will use
124 an internet domain socket for data transfer.
125 smb_traffic_analyzer:host = STRING
127 The module will send the data to the system named with the hostname
128 STRING.
129 smb_traffic_analyzer:port = STRING
131 The module will send the data using the TCP port given in STRING.
132 smb_traffic_analyzer:anonymize_prefix = STRING
134 The module will replace the user names with a prefix given by
135 STRING and a simple hash number. In version 2.x of the protocol,
136 the users SID will also be anonymized.
137 smb_traffic_analyzer:total_anonymization = STRING
139 If STRING matches to 'yes', the module will replace any user name
140 with the string given by the option
141 smb_traffic_analyzer:anonymize_prefix, without generating an
142 additional hash number. This means that any transfer data will be
143 mapped to a single user, leading to a total anonymization of user
144 related data. In version 2.x of the protocol, the users SID will
145 also be anonymized.
146 smb_traffic_analyzer:protocol_version = STRING
148 If STRING matches to V1, the module will use version 1 of the
149 protocol. If STRING is not given, the module will use version 2 of
150 the protocol, which is the default.
151
153 Running protocol V2 on share "example_share", using an internet socket.
154 [example_share]
156 path = /data/example
157 vfs_objects = smb_traffic_analyzer
158 smb_traffic_analyzer:host = examplehost
159 smb_traffic_analyzer:port = 3491
160 The module running on share "example_share", using a unix domain socket
163 [example_share]
165 path = /data/example
166 vfs objects = smb_traffic_analyzer
167 smb_traffic_analyzer:mode = unix_domain_socket
168 The module running on share "example_share", using an internet socket,
171 connecting to host "examplehost" on port 3491.
172 [example_share]
174 path = /data/example
175 vfs objects = smb_traffic_analyzer
176 smb_traffic_analyzer:host = examplehost
177 smb_traffic_analyzer:port = 3491
178 The module running on share "example_share", using an internet socket,
181 connecting to host "examplehost" on port 3491, anonymizing user names
182 with the prefix "User".
183 [example_share]
185 path = /data/example
186 vfs objects = smb_traffic_analyzer
187 smb_traffic_analyzer:host = examplehost
188 smb_traffic_analyzer:port = 3491
189 smb_traffic_analyzer:anonymize_prefix = User
190
193 This man page is correct for version 3.3 of the Samba suite.
194
196 The original Samba software and related utilities were created by
197 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
198 Source project similar to the way the Linux kernel is developed.
199 The original version of the VFS module and the helper tools were
201 created by Holger Hetterich.
202Samba 3.6 04/11/2016 SMB_TRAFFIC_ANALYZER(8)