VFS 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 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}