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 4.0.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 separate 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 (or secrets.ntdb). The Receiver then has to use the
94 same key. The module does AES block encryption over the data to
95 send.
96 · The module now can identify itself against the receiver with a
98 sub-release number, where the receiver may run with a different
99 sub-release number than the module. However, as long as both run on
100 the V2.x protocol, the receiver will not crash, even if the module
101 uses features only implemented in the newer subrelease. Ultimately,
102 if the module uses a new feature from a newer subrelease, and the
103 receiver runs an older protocol, it is just ignoring the
104 functionality. Of course it is best to have both the receiver and
105 the module running the same subrelease of the protocol.
106 · The parsing problems of protocol V1 can no longer happen, because
108 V2 is marshalling the data packages in a proper way.
109 · The module now potentially has the ability to create data on every
111 VFS function. As of protocol V2.0, there is support for 8 VFS
112 functions, namely write,read,pread,pwrite, rename,chdir,mkdir and
113 rmdir. Supporting more VFS functions is one of the targets for the
114 upcoming sub-releases.
115 To enable protocol V2, the protocol_version vfs option has to be used
118 (see OPTIONS).
119
121 smb_traffic_analyzer:mode = STRING
122 If STRING matches to "unix_domain_socket", the module will use a
123 unix domain socket located at /var/tmp/stadsocket, if STRING
124 contains an different string or is not defined, the module will use
125 an internet domain socket for data transfer.
126 smb_traffic_analyzer:host = STRING
128 The module will send the data to the system named with the hostname
129 STRING.
130 smb_traffic_analyzer:port = STRING
132 The module will send the data using the TCP port given in STRING.
133 smb_traffic_analyzer:anonymize_prefix = STRING
135 The module will replace the user names with a prefix given by
136 STRING and a simple hash number. In version 2.x of the protocol,
137 the users SID will also be anonymized.
138 smb_traffic_analyzer:total_anonymization = STRING
140 If STRING matches to ´yes´, the module will replace any user name
141 with the string given by the option
142 smb_traffic_analyzer:anonymize_prefix, without generating an
143 additional hash number. This means that any transfer data will be
144 mapped to a single user, leading to a total anonymization of user
145 related data. In version 2.x of the protocol, the users SID will
146 also be anonymized.
147 smb_traffic_analyzer:protocol_version = STRING
149 If STRING matches to V1, the module will use version 1 of the
150 protocol. If STRING is not given, the module will use version 2 of
151 the protocol, which is the default.
152
154 Running protocol V2 on share "example_share", using an internet socket.
155 [example_share]
157 path = /data/example
158 vfs_objects = smb_traffic_analyzer
159 smb_traffic_analyzer:host = examplehost
160 smb_traffic_analyzer:port = 3491
161 The module running on share "example_share", using a unix domain socket
164 [example_share]
166 path = /data/example
167 vfs objects = smb_traffic_analyzer
168 smb_traffic_analyzer:mode = unix_domain_socket
169 The module running on share "example_share", using an internet socket,
172 connecting to host "examplehost" on port 3491.
173 [example_share]
175 path = /data/example
176 vfs objects = smb_traffic_analyzer
177 smb_traffic_analyzer:host = examplehost
178 smb_traffic_analyzer:port = 3491
179 The module running on share "example_share", using an internet socket,
182 connecting to host "examplehost" on port 3491, anonymizing user names
183 with the prefix "User".
184 [example_share]
186 path = /data/example
187 vfs objects = smb_traffic_analyzer
188 smb_traffic_analyzer:host = examplehost
189 smb_traffic_analyzer:port = 3491
190 smb_traffic_analyzer:anonymize_prefix = User
191
194 This man page is correct for version 3.3 of the Samba suite.
195
197 The original Samba software and related utilities were created by
198 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
199 Source project similar to the way the Linux kernel is developed.
200 The original version of the VFS module and the helper tools were
202 created by Holger Hetterich.
203Samba 4.2 06/19/2018 SMB_TRAFFIC_ANALYZER(8)