Samba VFS internal API is really unstable, so it takes a bit more :effort: to support multiple version at once. Current version is tested with samba 3.6.14.

VFSX is a transparent Samba Virtual File System (VFS) module which forwards operations to a process on the same machine for handing outside of the Samba daemon process (smbd). The external handler can be implemented in any language with support for Unix domain sockets (Python, Ruby, Perl, Java with Jtux) which is how VFSX and its external process communicates.

The advantage of using VFSX over a pure VFS module is that any programming language can be used to implement the transparent operations. VFS modules linked directly into the Samba daemon must be written in C or C++. while VFSX lets the developer implement a transparent module in his favorite higher-level language, with all the advantages of that language, outside of the smbd process.

The following figure illustrates a typical file server configuration with VFSX:

For Samba shares configured with VFSX as a VFS module, all client requests to manipulate files and directories will first be sent to the external handler process. For every VFS operation invoked by the Samba daemon, VFSX sends to the handler the name of the operation, the local directory path of the shared SMB service, the ID of the calling user, and any additional arguments required for the operation. The handler may respond to any operation for which it is designed. Note that since VFSX is a transparent module, file contents may not be passed between the VFSX module and its handler; The Samba daemon must still handle the file system I/O directly. However, the external handler may choose to reject an operation and return an error code which will be passed on to the client.

Included with VFSX is an external handler written in Python. Developers can extend this implementation to provide custom operation handling.

VFSX requires Samba 3.6.x. All directory and file paths described in the following instructions are based on Ubuntu 13.04 substitute paths as appropriate for your Linux distribution.

1. Install Samba 3.6.14, including the source distribution.
2. Download the VFSX source distribution: git clone https://github.com/fudanchii/vfsx.
3. cd vfsx/module
4. ./configure --prefix=<samba installation path> --with-samba-source=<samba source3 location>
5. Build the VFSX shared library: make
6. Install with make install
7. Attach VFSX to a Samba shared directory by adding the VFSX module name to the share's configuration parameters. For example:
   [myshare]
comment = VFSX-Aware Shared Directory
path = /home/myuser/shared/
valid users = myuser
read only = No
vfs objects = vfsx
8. Restart Samba
9. Run the Python external event handler:
   python vfsx/python/vfsx.py
10. Access the share using smbclient or from a Windows system. By default the Python handler prints debug activity messages to the console. If the module has problems communicating with the external handler, error messages are written to syslog.

1. Extend
2. Run

• VFSX
• Original VFSX Project Page at SourceForge
• Samba Home Page
• Samba VFS Module Configuration
• Samba VFS Module Developers Guide
• Python Home Page

VFSX is distributed under the open source Mozilla Public License. The file vfsx/LICENSE contains the license terms.

Copyright (C) 2004 Steven R. Farley. All rights reserved.
Copyright (C) 2009 Alexander Duscheleit.
Copyright (C) 2013 Nurahmadie.