Skip to main content
Skip table of contents

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:

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


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.