toccofs - FUSE-Based Network FS for Tocco DMS

Introduction

A network filesystem allowing to mount Tocco DMS locally via Tocco's REST API and accessing it via filesystem. It's implemented using FUSE (Filesystem in Userspace).

This is a personal project, this software is not provided by Tocco AG, although it interfaces with their software, Tocco. This is a fun project and is unlikely to be maintained long-term. More features may get added, or bugs fixed but don't count on it.

Prerequisites

• An operating system with FUSE support (e.g. Linux or FreeBSD).
• An API key. (You may not have permissions to create one.)

Quick Guide

toccofs mount --user-name <user_name> --api-key-file <path_to_key_file> <hostname> <mount_dir>

Example:

mkdir mnt  # empty folder
toccofs --user-name pgerber --api-key-file ~/tocco-api-key master.tocco.ch mnt/

Then access the FS:

ls -lh mnt/
drwxr-xr-x 1 root root 0 Apr 16  2024 Documents
drwxr-xr-x 1 root root 0 Apr 16  2024 Internal
drwxr-xr-x 1 root root 0 Apr 16  2024 Temp
...

And ultimately, unmount it again:

fusermount -u mnt/

Options

--user-name and --api-key-file

Use it to make sure you have access to restricted files and folders. If omitted, publicly visible files and folders will still show up.

--business-unit

If you have access to multiple Business Units, this allows to restrict what folders are visible. Use this when, across Business Units, root folder names (AKA domain names) aren't unique and multiple folders with the same name appear.

RUST_LOG= env. var.

Enable debug or trace logging:

RUST_LOG=debug toccofs mount ...

See also env_logger documention.

Default is equal to RUST_LOG=toccofs=info.

Extended Attributes (xattr)

Extended attributes can be used to retrieve the corresponding URLs on the API and admin interface.

$ getfattr -d path/to/file
# file: path/to/file
user.admin_url="https://master.tocco.ch/tocco/docs/doc/22723/detail"
user.entity_api_url="https://master.tocco.ch/nice2/rest/entities/2.0/Resource/22723"

or:

$ xattr -l path/to/file
user.admin_url: https://master.tocco.ch/tocco/docs/doc/22723/detail
user.entity_api_url: https://master.tocco.ch/nice2/rest/entities/2.0/Resource/22723

File Names (vs Tocco Labels)

Some file / folder / domain names (AKA labels) used by Tocco cannot be used in a filesystem. They are simply not valid file names. Such names are encoded in a reversible manner to allow accessing all files in Tocco via toccofs.

The most notable encoding is the one of '/', a character not allowed in a file name. This character is encoded as '⫽'.

Features

Supported

• list folders (readdir)
• get file attributes (fstat)
• read files (read)
• rename and move (rename)
• remove files and directories (unlink, rmdir)
• create directories / domains (mkdir)

Unsupported

• sync files (fsync)
• write files (write)

Caveats

• Performance

  Very little has been done to optimize performance. In particular, reads will be very slow. All downloads are currently synchronous with no other read-ahead than that provided by the OS.

• Lost and found:

  In Tocco, it's possible for a folder/file to be visible but not it's parent directory. Such orphaned entries are visible in the hidden .lost+found directory:

  ls -lha mnt/
  ...
  drwxr-xr-x 1 root root   0 Jan  1  1970 .lost+found
  ...
  

  Names will have their type and ID prefixed to avoid name collisions.