VFS - Logging
The virtual filesystem is divided into two main parts. The kernel extension (KEXT), that is loaded into the operating system, and a User-Space API (VFS-API) as connection between the censhare Client and the KEXT.
The KEXT receives request from other applications and forwards them to the VFS-API, within the censhare Client. The client processes the request and replies accordingly.
VFS - Basic Architecture
To trace the whole communication between the kernel extension and the User-Space API, it is possible to enable a fine grane logging mechanism 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 Mac OS X 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".
Note: 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 sowie 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 by menu entries: "File -> Preferences -> Logs...".
You'll find a Drop-Down to 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.
Note: 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 informations. | ALL |
Log levels, not listed in the table can be set for KEXT logging anyway. Depending on the level, they will contain additional debug messages. The higher the value the higher the amount of logged messsages.
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 sequence counter. 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 repiles 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.
Possible values and their meaning:
Value | Description |
FS_Unmount | Hint for the VFS-API that the VFS will be unmounted now. |
FS_Getattr | Request for file system meta data (number of files/folders, used storage space, etc.) |
FS_VGet___ | Request of file/folder meta data 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 meta data 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 meta data 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 an information about the success of the request.
Possible values and their meaning:
VAlue | Description |
__OK______ | Request was executed successful. 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 meta data of that folder (access rights, User-ID, Group-ID, size, modification date, name).
Group D will be empty in case of an error.
Possible values and their meaning:
Request-Type | Request parameters |
Description | |
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 |
Description | |
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. Exampe: 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 eofif 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 entries EOF {28 - foo.png} |