VFS Logging
To track the communication between the kernel extension and the User-Space API, you can enable logging in the KEXT as well as in the VFS API.
Kernel Extension Logging
The VFS-Logging within the Kernel-Extension can be enabled by adding an entry to the configuration file "hosts.xml". You need to add the attribute debug-level to the XML-Element <censhare-vfs>, below of the corresponding <host> element:
<host name="hostname"
url="//some/where/corpus.RMIServer">
<censhare-vfs use="1" debug-level="0" />
</host>
The value for debug-level specifies the log granularity in a range of 0 to 6. A value of 0 disables the logging.
For macOS, the log messages are written into "/var/log/system.log" or "/var/log/kernel.log".
Windows stores the log messages, up to level 3, within the client protocol. From debug-level="4" the messages will be stored in a dedicated file: "%HOMEPATH%censharevfs_logyyyy-MM-dd_HH-mm-ss_cbfs.log".
For censhare Client on Microsoft Windows, starting with the versions 4.7.37, 4.8.26, 4.9.19, 4.10.21, 5.1.14, 5.2.10, 5.3.10, 5.4.7, 5.5.4, and 5.6.0 the configuration within the hosts.xml file is deprecated and will be ignored. The KEXT logging is replaced by the VFS-API logging in this case.
VFS - Configuration
VFS-API Logging (censhare Client / censhare Render-Client)
Starting with censhare versions 4.7.37, 4.8.26, 4.9.19, 4.10.21, 5.1.14, 5.2.10, 5.3.10, 5.4.7, 5.5.4 and 5.6.0 the additional logging within the VFS-API can be enabled / disabled in the client. The log messages are written into the censhare Client protocol.
To enable the logging, open the censhare Client in admin mode and open the Log-Dialog window File -> Preferences -> Logs...:
In the drop-down, select the log level for the VFS. Select the required granularity for the log messages. The output channel at the end of the dialog specifies where those log messages will be displayed/stored.
If the drop-down isn't visible, then the dialog definition on the server has to be patched. But as a workaround you can enable the logging anyway:
1) Select a Log-Level for "Client" (e.g. Info) and confirm the dialog with "OK".
2) Open the dialog for "Detailed logs" by selecting the menu entry "File -> Preferences -> Detailed Logs..."
3) Select the corresponding log-level for the entry "com.censhare.vfs." and confirm with "OK".
Log Level
There are 6 log levels available. A higher log level includes all messages from the previous levels as well. That means, the higher the level the more messages you'll get. The log level for the Kernel logging are equal to the levels for the VFS-API logging and described in the following table.
Log Level | Description | VFS-API (Java) Level |
---|---|---|
0 | Log is disabled | OFF |
1 | Only errors will be reported. This might be negative replies as well as operational errors. e.g.: "does file X exist?" -> "no". | ERRORS (WARNING) |
2 | Requests corresponding to files and folders (open, close, read, search). The following VFS requests will be included (VN_Open___, VN_Close__, VN_Read___, VN_Lookup_, VN_Readdir) | FILES & DIRECTORIES (INFO) |
3 | Requests corresponding to the file system itself (Unmount, Filesystem-attributes). The following VFS requests will be included (FS_Unmount, FS_Getattr, FS_VGet___) | FILE SYSTEM (CONFIG) |
6 | Internal control commands of the VFS. e.g. keep-alive The following VFS requests will be included (FS_IsAlive) | CONTROLLER (FINEST) |
7 | All VFS requests including some additional debug information. | ALL |
Log levels that are not listed in the table can be set for KEXT logging. Depending on the level, they contain additional debug messages. The higher the value the higher the amount of logged messages.
Structure of the log messages
The structure of the log messages, coming from the KEXT compared to the messages coming from the VFS-API logging, are nearly the same. The content of those messages depends on the kind of request.
Log Output
As you can see in the image, each log message can be clustered into four main parts.
Group A contains the message direction (Snd = sent, Rcv = received) as well as the sequence counter. The same sequence number on messages means that those messages belong to each other.
In the example, the KEXT sends a request with sequence number 296 to the VFS-API (Snd_296), which receives (Rcv 296) it, processes it, and replies accordingly to the KEXT (Snd 296). The KEXT receives (Rcv_296) the reply and forwards it to the OS.
Group B contains the type of the request/reply:
Value
Description
FS_Unmount
Hint for the VFS-API that the VFS will be unmounted now.
FS_Getattr
Request for file system metadata (number of files/folders, used storage space, etc.)
FS_VGet___
Request of file/folder metadata by its unique id. (filename, size, modification date, etc.)
VN_Lookup_
Request if a specified file/folder name exists within a given folder. If it exists, the VFS-API replies with the metadata of the file/folder.
VN_Open___
Processing instruction to open a file/folder for read and/or write access.
VN_Close__
Processing instruction to close a file/folder.
VN_Getattr
Request of file/folder metadata by its unique ID. (Filename, size, modification date, etc.) This is equivalent to FS_VGet___
VN_Read___
Read n bytes of a file up to a length of m.
VN_Readdir
Read the content of a directory. The reply is a list of file/folder names and its corresponding unique ID.
FS_IsAlive
Test if the connection between the KEXT and the censhare Client is still alive. After several failing tests, the VFS will be unmounted automatically.
___INVALID
Invalid requests
Group C contains for requests the process-ID (P_xxx) of the requesting application as well as the unique ID of a file/folder (N_xxx), the request belongs to. In the example, the application with PID=929 requests a VN_Lookup on the folder with ID=1 ( P_929 N_1 ).
For replies, group C contains information about the success of the request:Value
Description
__OK______
Request was executed successfully. No error
E_NOENT___
Error: No such file or directory
E_IO______
Error: Input/output error
E_EXIST___
Error: File exists
E_ACCES___
Error: Permission denied
E_BUSY____
Error: Device / Resource busy
E_FBIG____
Error: File too large
E_NOTDIR__
Error: Not a directory
E_EISDIR__
Error: Is a directory
E_NOTEMPTY
Error: Directory not empty
E_MFILE___
Error: Too many open files
E_MLINK___
Error: Too many links
E_PERM____
Error: Operation not permitted
E_INVAL___
Error: Invalid argument
E_NOMEM___
Error: Cannot allocate memory
E_NOSPC___
Error: No space left on device
E_ROFS____
Error: Read-only file system
E_DQUOT___
Error: Disc quota exceeded
E_NOSYS___
Error: Function not implemented
E_xxxx
Error: Other errors and its error number
Group D contains the request/reply parameters and differs from type to type (Group B). In the image, the KEXT searches for example a file/folder of name "service" within the folder of ID "1". As a reply, the client returns the metadata of that folder (access rights, User-ID, Group-ID, size, modification date, name). Group D will be empty in case of an error.
Request-Type
Request parameters
FS_Unmount
FS_Getattr
FS_VGet___
VN_Getattr
FS_IsAlive
--
No request parameters. The requested object is specified by its Objekt-ID (N_xxx) in group C.
VN_Lookup_
name [idx, len, path]
name: name of a file/folder, to be searched below of folder with ID N_xxx (Group C).
path: Complete path of the request (if available)
idx: Index position, of the name within the path.
len: length of the searched name within the path
Example: service [19, 7, /Volumes/localhost/service]
VN_Open___
VN_Close__
Mode:hex (r.w)
hex: Processing mode in HEX to open the file/directory.
r.w.: text representation of the processing mode:
r = read mode disabled or R = read-mode enabled
w = write-mode disabled or W = write-mode enabled.
Example: Mode:0x0001 (R.w)
VN_Read___
VN_Readdir
[offset, len]
offset: start offset for read requests (n-th. byte or n-th. directory entry).
len: maximum number of expected bytes (or directory entries).
Example: [0, 330792]
Reply-Type
Reply parameters
FS_Unmount
FS_IsAlive
VN_Open___
VN_Close__
--
No reply parameters. The reply is specified by the processing info from group C.
FS_Getattr
capacity(usedBytes/sizeVfs) nodes(files/dirs/max) date
usedBytes: Used bytes on the storage
sizeVfs: Capacity of the storage (total size)
files: Total number of files on the storage
dirs: Total number of directories on the storage
max: Maximum number of files/folders
date: Last modification date
Example: capacity(0/123432) nodes(1/4/432523423)
FS_VGet___
VN_Lookup_
VN_Getattr
N_xxx perm refCnt uid gid size date
N_xxx: unique ID of file/folder
perm: access rights, using Unix notation (d=directory, r=read, w=write, x=execute - 1. rwx = user, 2. rwx = group, 3. rwx = others).
refCnt: Number of files in a directory
uid: User-ID (Owner of a file/folder)
gid: Group-ID (group of the owner)
size: file size
date: Last modification date of file/folder
Example: N_1 drwxr-xr-x 1 uid(0) gid(0) 0 bytes 06 Jul 2016, 08:19 service
VN_Read___
size bytes [hex]
size: Number of returned bytes
hex: Extract of the first 8 as well as the last 8 read bytes in HEX.
Example: 330792 bytes [255044462d312e35 ... 320d2525454f460d]
VN_Readdir
num entries eof {id dir name}
num: Number of directory entries processed in this result
eof: EOF if the end of the directory is reached or eof if there are some additional entries to be processed.
id: unique ID of the file/folder
dir: d if the entry is a directory or - if it is a file.
name: Name of the file/folder
Example: 1 entry EOF {28 - foo.png}