'\" t .\" Title: smb_traffic_analyzer .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 02/24/2015 .\" Manual: System Administration tools .\" Source: Samba 4.0 .\" Language: English .\" .TH "SMB_TRAFFIC_ANALYZER" "8" "02/24/2015" "Samba 4\&.0" "System Administration tools" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" vfs_smb_traffic_analyzer \- log Samba VFS read and write operations through a socket to a helper application .SH "SYNOPSIS" .HP \w'\ 'u vfs objects = smb_traffic_analyzer .SH "DESCRIPTION" .PP This VFS module is part of the \fBsamba\fR(7) suite\&. .PP The vfs_smb_traffic_analyzer VFS module logs client file operations on a Samba server and sends this data over a socket to a helper program (in the following the "Receiver"), which feeds a SQL database\&. More information on the helper programs can be obtained from the homepage of the project at: http://holger123\&.wordpress\&.com/smb\-traffic\-analyzer/ Since the VFS module depends on a receiver that is doing something with the data, it is evolving in it\*(Aqs development\&. Therefore, the module works with different protocol versions, and the receiver has to be able to decode the protocol that is used\&. The protocol version 1 was introduced to Samba at September 25, 2008\&. It was a very simple protocol, supporting only a small list of VFS operations, and had several drawbacks\&. The protocol version 2 is a try to solve the problems version 1 had while at the same time adding new features\&. With the release of Samba 4\&.0\&.0, the module will run protocol version 2 by default\&. .SH "PROTOCOL VERSION 1 DOCUMENTATION" .PP vfs_smb_traffic_analyzer protocol version 1 is aware of the following VFS operations: .RS 4 write .RE .RS 4 pwrite .RE .RS 4 read .RE .RS 4 pread .RE .PP vfs_smb_traffic_analyzer sends the following data in a fixed format separated by a comma through either an internet or a unix domain socket: .sp .if n \{\ .RS 4 .\} .nf BYTES|USER|DOMAIN|READ/WRITE|SHARE|FILENAME|TIMESTAMP .fi .if n \{\ .RE .\} .PP Description of the records: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} BYTES \- the length in bytes of the VFS operation .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} USER \- the user who initiated the operation .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} DOMAIN \- the domain of the user .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} READ/WRITE \- either "W" for a write operation or "R" for read .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} SHARE \- the name of the share on which the VFS operation occurred .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} FILENAME \- the name of the file that was used by the VFS operation .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} TIMESTAMP \- a timestamp, formatted as "yyyy\-mm\-dd hh\-mm\-ss\&.ms" indicating when the VFS operation occurred .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} IP \- The IP Address (v4 or v6) of the client machine that initiated the VFS operation\&. .RE .sp .RE .PP This module is stackable\&. .SH "DRAWBACKS OF PROTOCOL VERSION 1" .PP Several drawbacks have been seen with protocol version 1 over time\&. .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Problematic parsing \- Protocol version 1 uses hyphen and comma to separate blocks of data\&. Once there is a filename with a hyphen, you will run into problems because the receiver decodes the data in a wrong way\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Insecure network transfer \- Protocol version 1 sends all it\*(Aqs data as plaintext over the network\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Limited set of supported VFS operations \- Protocol version 1 supports only four VFS operations\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} No subreleases of the protocol \- Protocol version 1 is fixed on it\*(Aqs version, making it unable to introduce new features or bugfixes through compatible sub\-releases\&. .RE .SH "VERSION 2 OF THE PROTOCOL" .PP Protocol version 2 is an approach to solve the problems introduced with protcol v1\&. From the users perspective, the following changes are most prominent among other enhancements: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The data from the module may be send encrypted, with a key stored in secrets\&.tdb (or secrets\&.ntdb)\&. The Receiver then has to use the same key\&. The module does AES block encryption over the data to send\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The module now can identify itself against the receiver with a sub\-release number, where the receiver may run with a different sub\-release number than the module\&. However, as long as both run on the V2\&.x protocol, the receiver will not crash, even if the module uses features only implemented in the newer subrelease\&. Ultimately, if the module uses a new feature from a newer subrelease, and the receiver runs an older protocol, it is just ignoring the functionality\&. Of course it is best to have both the receiver and the module running the same subrelease of the protocol\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The parsing problems of protocol V1 can no longer happen, because V2 is marshalling the data packages in a proper way\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The module now potentially has the ability to create data on every VFS function\&. As of protocol V2\&.0, there is support for 8 VFS functions, namely write,read,pread,pwrite, rename,chdir,mkdir and rmdir\&. Supporting more VFS functions is one of the targets for the upcoming sub\-releases\&. .RE .sp .RE .PP To enable protocol V2, the protocol_version vfs option has to be used (see OPTIONS)\&. .SH "OPTIONS WITH PROTOCOL V1 AND V2.X" .PP smb_traffic_analyzer:mode = STRING .RS 4 If STRING matches to "unix_domain_socket", the module will use a unix domain socket located at /var/tmp/stadsocket, if STRING contains an different string or is not defined, the module will use an internet domain socket for data transfer\&. .RE .PP smb_traffic_analyzer:host = STRING .RS 4 The module will send the data to the system named with the hostname STRING\&. .RE .PP smb_traffic_analyzer:port = STRING .RS 4 The module will send the data using the TCP port given in STRING\&. .RE .PP smb_traffic_analyzer:anonymize_prefix = STRING .RS 4 The module will replace the user names with a prefix given by STRING and a simple hash number\&. In version 2\&.x of the protocol, the users SID will also be anonymized\&. .RE .PP smb_traffic_analyzer:total_anonymization = STRING .RS 4 If STRING matches to \*(Aqyes\*(Aq, the module will replace any user name with the string given by the option smb_traffic_analyzer:anonymize_prefix, without generating an additional hash number\&. This means that any transfer data will be mapped to a single user, leading to a total anonymization of user related data\&. In version 2\&.x of the protocol, the users SID will also be anonymized\&. .RE .PP smb_traffic_analyzer:protocol_version = STRING .RS 4 If STRING matches to V1, the module will use version 1 of the protocol\&. If STRING is not given, the module will use version 2 of the protocol, which is the default\&. .RE .SH "EXAMPLES" .PP Running protocol V2 on share "example_share", using an internet socket\&. .sp .if n \{\ .RS 4 .\} .nf \fI[example_share]\fR \m[blue]\fBpath = /data/example\fR\m[] \m[blue]\fBvfs_objects = smb_traffic_analyzer\fR\m[] \m[blue]\fBsmb_traffic_analyzer:host = examplehost\fR\m[] \m[blue]\fBsmb_traffic_analyzer:port = 3491\fR\m[] .fi .if n \{\ .RE .\} .PP The module running on share "example_share", using a unix domain socket .sp .if n \{\ .RS 4 .\} .nf \fI[example_share]\fR \m[blue]\fBpath = /data/example\fR\m[] \m[blue]\fBvfs objects = smb_traffic_analyzer\fR\m[] \m[blue]\fBsmb_traffic_analyzer:mode = unix_domain_socket\fR\m[] .fi .if n \{\ .RE .\} .PP The module running on share "example_share", using an internet socket, connecting to host "examplehost" on port 3491\&. .sp .if n \{\ .RS 4 .\} .nf \fI[example_share]\fR \m[blue]\fBpath = /data/example\fR\m[] \m[blue]\fBvfs objects = smb_traffic_analyzer\fR\m[] \m[blue]\fBsmb_traffic_analyzer:host = examplehost\fR\m[] \m[blue]\fBsmb_traffic_analyzer:port = 3491\fR\m[] .fi .if n \{\ .RE .\} .PP The module running on share "example_share", using an internet socket, connecting to host "examplehost" on port 3491, anonymizing user names with the prefix "User"\&. .sp .if n \{\ .RS 4 .\} .nf \fI[example_share]\fR \m[blue]\fBpath = /data/example\fR\m[] \m[blue]\fBvfs objects = smb_traffic_analyzer\fR\m[] \m[blue]\fBsmb_traffic_analyzer:host = examplehost\fR\m[] \m[blue]\fBsmb_traffic_analyzer:port = 3491\fR\m[] \m[blue]\fBsmb_traffic_analyzer:anonymize_prefix = User\fR\m[] .fi .if n \{\ .RE .\} .SH "VERSION" .PP This man page is correct for version 3\&.3 of the Samba suite\&. .SH "AUTHOR" .PP The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&. .PP The original version of the VFS module and the helper tools were created by Holger Hetterich\&.