To log VFS and track the communication between it and the User-Space API, you can enable logging in the VFS API for the censhare Client and censhare Render-Client.



This page is targeted towards macOS users. Windows users should check the official CBFS documentation to learn how to enable CBFS logging. CBFS logs will be generated like any other system logs on Windows.

Introduction

The VFS-related logging includes:

  • logs generated by the censhare Client itself;
  • logs generated by the censhare VFS native library.


How to enable VFS logging

See VFS Configuration: Enable logging for detailed instructions.


Log messages

Where to find logs

See VFS Configuration: Enable logging for information.

Log message structure

Below is an example of VFS logs generated by the censhare Client logging. We will focus on these messages first.

2023.08.22-14:36:47.247 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3028 VN_Getattr P_0 N_17
2023.08.22-14:36:47.247 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3028 VN_Getattr P_0 N_17
2023.08.22-14:36:47.248 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3028 VN_Getattr __OK______ N_17 drwxr-xr-x   1   uid(  0) gid(  0)     0bytes 22 Aug 2023, 14:36 file
2023.08.22-14:36:47.248 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3028 VN_Getattr __OK______ N_17 drwxr-xr-x   1   uid(  0) gid(  0)     0bytes 22 Aug 2023, 14:36 file
2023.08.22-14:36:47.258 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3029 VN_Lookup_ P_0 N_17 Screenshot 2023-08-18 at 08.07.51.png [0, 37, Screenshot 2023-08-18 at 08.07.51.png]
2023.08.22-14:36:47.258 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3029 VN_Lookup_ P_0 N_17 Screenshot 2023-08-18 at 08.07.51.png [0, 37, Screenshot 2023-08-18 at 08.07.51.png]
2023.08.22-14:36:47.260 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3029 VN_Lookup_ __OK______ N_17 -rw-r--r--   1   uid(  0) gid(  0)    53kB 22 Aug 2023, 14:35 Screenshot 2023-08-18 at 08.07.51.png
2023.08.22-14:36:47.260 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3029 VN_Lookup_ __OK______ N_17 -rw-r--r--   1   uid(  0) gid(  0)    53kB 22 Aug 2023, 14:35 Screenshot 2023-08-18 at 08.07.51.png
2023.08.22-14:36:47.268 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3030 VN_Open___ P_0 N_18 Mode:0x0000(r.w)
2023.08.22-14:36:47.268 [CsVfsKextHandler,56] INFO: censhareVFS: Rcv 3030 VN_Open___ P_0 N_18 Mode:0x0000(r.w)
2023.08.22-14:36:47.269 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3030 VN_Open___ __OK______
2023.08.22-14:36:47.269 [CsVfsKextHandler,56] INFO: censhareVFS: Snd 3030 VN_Open___ __OK______
YML

From left to the right, the positions are reserved for the following pieces of information:

  • At the beginning of each line, you see a timestamp, e.g. 2023.08.22-14:36:47.247
  • [CsVfsKextHandler,56] indicates that this log message is related to VFS. (The number shows the thread). 
  • INFO stands for the type of the message (see the log levels section below)
  • censhareVFS indicates that it is related to the VFS 
  • Rcv and Snd indicates the direction – received or sent respectively – followed by the sequence number. The same sequence number means that the messages belong to each other.
  • VN_Getattr/VN_Lookup_/VN_Open___ are requests. See the table below for a complete list of possible requests. They may contain additional parameters. See also below.
  • __OK______ is a response. See the table below for a complete list of possible responses. They may contain additional parameters. See also below.
  • P_x are the process IDs. They may or may not follow the reply. 
  • N_x are the file/folders IDs. They follow the process ID. 

Request and response types and parameters

Value

Description

Request parameters (Snd)

Response parameters (Rcv)

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.)

-

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___

Request of file/folder metadata by its unique id. (filename, size, modification date, etc.)

-

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_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.

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]

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_Open___

Processing instruction to open a file/folder for read and/or write access.

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_Close__

Processing instruction to close a file/folder.

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_Getattr

Request of file/folder metadata by its unique ID. (Filename, size, modification date, etc.) This is equivalent to FS_VGet___

-

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___

Read n bytes of a file up to a length of m.

[ 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]

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

Read the content of a directory. The reply is a list of file/folder names and its corresponding unique ID.

[ 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]

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}

___INVALID

Invalid requests

-

-

Success messages

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

Additional VFS logging

In addition to all above, the censhare native VFS library also generates the following logs upon start and shutdown of the censhare Client and the VFS. They are only available in the macOS Console.

<Startup of censhare-Client and VFS>
standard	14:20:07.009180+0200	censhare Client	CenshareFS: censhare VFS native lib initialized. Version: 3.0.0a3
standard	14:20:07.011112+0200	censhare Client	CenshareFS: mountNative called
standard	14:20:07.011173+0200	censhare Client	CenshareFS: FUSE arg[0]=-osubtype=censhare-vfs
standard	14:20:07.011305+0200	censhare Client	CenshareFS: FUSE arg[1]=-ordonly
standard	14:20:07.011364+0200	censhare Client	CenshareFS: mounting VFS (FUSE-T) at mount point: /Volumes/my-volume
standard	14:20:07.045905+0200	censhare Client	CenshareFS: VFS (FUSE-T) mount call succeeded
standard	14:20:07.046371+0200	censhare Client	CenshareFS: mountNative finished; mount point = /Volumes/my-volume

...
<File system calls like 
standard	14:20:07.159347+0200	censhare Client	CenshareFS: Rcv_1 VN_Getattr P_0 N_1
standard	14:20:07.162837+0200	censhare Client	CenshareFS: Snd_1 VN_Getattr __OK______ N_1 drwxr-xr-x  0 2095791887 2116441323          0 my-volume
>
...

<Shutdown of censhare-Client and VFS>
standard	14:22:26.127696+0200	censhare Client	CenshareFS: exitFuseSessionAndUnmount called
standard	14:22:26.127788+0200	censhare Client	CenshareFS: calling fuse_session_exit
standard	14:22:26.127830+0200	censhare Client	CenshareFS: calling fuse_unmount
standard	14:22:26.128002+0200	censhare Client	CenshareFS: exitFuseSessionAndUnmount finished
standard	14:22:26.418353+0200	censhare Client	CenshareFS: releaseNative called
standard	14:22:26.418425+0200	censhare Client	CenshareFS: exitFuseSessionAndUnmount called
standard	14:22:26.418466+0200	censhare Client	CenshareFS: exitFuseSessionAndUnmount finished
standard	14:22:26.418507+0200	censhare Client	CenshareFS: releaseNative finished
XML



Log Levels

There are 4 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 get, but not the severity of errors. 

As appears in the log messages

Log Level

(debug-level in

hosts.xml)

VFS-API (Java) Level

(in the censhare Client)

Description

-

0

OFF

Log is disabled

Client logging starts here

WARNING

1

ERRORS 

Only errors will be reported. This might be negative replies as well as operational errors, e.g.: "does file X exist?" -> "no".

censhare native VFS library logging starts here

INFO

2

FILES & DIRECTORIES 

Requests corresponding to files and folders (open, close, read, search):

  • VN_Open___
  • VN_Close__ 
  • VN_Read___
  • VN_Lookup_
  • VN_Readdir

CONFIG

3

FILE SYSTEM 

Requests corresponding to the file system itself (mount, unmount, filesystem attributes):

  • FS_Unmount
  • FS_Getattr
  • FS_VGet___

DEBUG

4

ALL

All VFS requests including some additional debug information.