     [file version.texi not included]

BookmarkFS User Manual
**********************

This manual is for BookmarkFS, version VERSION.

     Copyright © 2024  CismonX <admin@cismon.net>

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

BookmarkFS is a FUSE-based pseudo-filesystem which provides an interface to the bookmark data of web browsers.

Currently, the following browsers (and their derivatives) are supported:

  * Firefox

  * Chromium

BookmarkFS is free software, distributed under the terms of the GNU General Public License, either version 3, or any later version of the license. You should have received a copy of the GNU General Public License along with BookmarkFS.  If not, see https://www.gnu.org/licenses/.

Porting BookmarkFS
==================

Currently, BookmarkFS only runs on GNU/Linux and FreeBSD.

Although BookmarkFS sticks hard to POSIX and avoids using platform-specific features, porting it to other operating systems is not trivial.

The major pitfall is the FUSE (https://docs.kernel.org/filesystems/fuse.html) dependency. Generally speaking, FUSE is Linux-only. FreeBSD partially implements the FUSE protocol in its kernel, to the extent that BookmarkFS is mostly usable. However, that's not the case for other operating systems.

For example, OpenBSD implements its own FUSE protocol, which is incompatible with the Linux one. While OpenBSD does provide a libfuse-compatible library, however, it only covers the high-level API, and BookmarkFS uses the low-level API (https://libfuse.github.io/doxygen/fuse__lowlevel_8h.html). For a similar reason, WinFsp (https://github.com/winfsp/winfsp) won't work if you're trying to port BookmarkFS to Microsoft Windows.

Sandboxing
==========

A BookmarkFS backend can be instructed to enter a sandboxed state, where it irrevocably relinquishes most access to the system resources that it's not supposed to touch. For example, it can only access the directory that contains the bookmark file; it cannot establish socket connections; it cannot execute other files; ...

This mechanism reduces the attack surface for exploit, if a vulnerability is discovered in BookmarkFS and/or its dependencies. However, it only deals with untrusted input, and cannot help if the operating system has already been compromised.

Example of what ``untrusted input'' may include:

  * Bookmark files that are not created by the user using a trusted program (e.g. a file obtained from some random person on the internet).

  * Filesystem calls from untrusted programs. The program itself may be isolated, but it has a chance to escape the isolated environment if it can exploit BookmarkFS.

On Linux, sandboxing is achieved using seccomp(2) and landlock(7). On FreeBSD, capsicum(4) is used.

Contributing to BookmarkFS
==========================

BookmarkFS is hosted on Savannah. Write to the mailing lists (https://savannah.nongnu.org/mail/?group=bookmarkfs) for bug reports, feature requests, and other discussions.

BookmarkFS is a personal hobby project, and is currently in experimental stage. Thus, it it not yet ready for open collaboration, which means patches are generally rejected unless trivial (e.g. typo fix).

Programs
********

mount.bookmarkfs
================

     mount.bookmarkfs [OPTIONS] SRC TARGET

The mount.bookmarkfs program mounts a BookmarkFS filesystem to the location specified by TARGET.

The SRC argument is presumably the pathname of a file that stores bookmark data. Its exact interpretation is backend-defined.

To unmount a BookmarkFS filesystem, use fusermount3(1) or umount(8) on TARGET.

Available options:

-o backend=NAME
     The backend used by the filesystem (see Backends). This option is mandatory.

-o @KEY[=VALUE]
     A backend-specific option. This option can be provided multiple times.

-o accmode=MODE
     File access mode. Defaults to 0700.

     This option applies to both directories and regular files. Execution bits on regular files are masked off.

     Should be used in combination with -o allow_other for other users to access the files.

-o ctime
     Maintain file change time, while modification time follows change time. If this option is not provided, maintain file modification time instead.

     Usually, a bookmark's ``modification time'' attribute behaves differently from both mtime and ctime. In Chromium, for instance, when a bookmark is renamed, neither itself nor the parent directory changes timestamp accordingly.

     BookmarkFS do not follow browser behavior here, and instead try to stay compatible with POSIX. Since a bookmark has only one ``modification time'' attribute instead of two, the user has to choose which one to maintain. If choosing mtime, ctime only updates when mtime does. Otherwise, mtime may change when the file content is not modified -- inefficient but makes applications that depend on ctime less fragile.

     The kernel may cache file attributes, making ctime appear more ``correct'' than what we claim. However, this behavior should not be relied upon.

-o eol
     Add a newline (ASCII LF character) to the end of each file.

     Before writing the file content back to the backend, a trailing newline is automatically removed (if one exists).

-o file_max=BYTES
     Max file size limit. Defaults to 32768.

-o no_sandbox
     Do not enable sandboxing features (see Sandboxing).

-o no_landlock
     Do not use Landlock for sandboxing. This option is ignored on non-Linux platforms.

     Without Landlock, sandboxing offers less security. However, Landlock is a rather new feature (requires kernel version 5.13 or later), thus we provide an option to disable it separately.

-F
     Stay in the foreground, do not daemonize.

-h
     Print help text, and then exit.

-V
     Print version and feature information, and then exit.

Unrecognized options specified with -o are passed to libfuse (and subsequently to the kernel, if applicable) as-is. Notable options:

-o rw
     Mount the filesystem read/write.

     By default, the filesystem is mounted read-only. This behavior won't change in the future, since the hackish nature of BookmarkFS makes it forever unstable.

          Always backup the bookmarks before mounting it read/write, or risk losing your data!

-o debug
     Set libfuse log level to FUSE_LOG_DEBUG. Log messages related to each FUSE request will be printed to standard error.

-o fsname
     The name that appears as the fs_spec field in fstab(5). Defaults to the backend name.

-o atime,diratime,relatime
     These options (and other atime-related ones) are ignored.

     BookmarkFS only supports noatime mounts, since the ``access time'' attribute of a bookmark necessarily means ``the last time it was accessed from the browser''. As a bookmark management tool independent from the browser, BookmarkFS should never update that time automatically.

     Nonetheless, the user can still update atime explicitly (e.g. with futimens(3p)).

fsck.bookmarkfs
===============

     fsck.bookmarkfs [OPTIONS] PATHNAME

The fsck.bookmarkfs program checks and optionally repairs a BookmarkFS filesystem.

Unlike fsck on general-purpose filesystems (e.g. ext4), this program does not check the integrity or validity of a bookmark file -- the underlying filesystem containing the bookmark storage is responsible for that. Instead, it checks for bookmark names that are not valid as filename (e.g. contains slash characters). See Filesystem Check.

Available options:

-o backend=NAME
     The backend used by the filesystem (see Backends).

     If this option is not provided, or NAME is empty, performs online fsck.

-o @KEY[=VALUE]
     A backend-specific option. This option can be provided multiple times.

-o handler=NAME
     The handler for resolving errors found during fsck (see Filesystem-Check Handlers).

     If this option is not provided, or NAME is empty, a built-in handler will be used. See Built-in Filesystem-Check Handler.

-o %KEY[=VALUE]
     A handler-specific option. This option can be provided multiple times.

-o repair
     Attempt to repair errors found during fsck.

          Always backup the bookmarks before repairing, or risk losing your data!

-o rl_app=NAME
     Readline application name in interactive mode. Defaults to ``fsck.bookmarkfs''.

-o type=bookmark|tag|keyword
     Subsystem type (see Hierarchy). Defaults to ``bookmark''.

     This option is ignored when performing online fsck.

-i
     Enable interactive mode.

-R
     Perform fsck on subdirectories recursively.

     This option is ignored when performing fsck on tags or keywords.

-o no_sandbox
     Do not enable sandboxing features (see Sandboxing).

-o no_landlock
     Do not use Landlock for sandboxing. This option is ignored on non-Linux platforms.

     Also see Disabling Landlock.

-h
     Print help text, and then exit.

-V
     Print version and feature information, and then exit.

mkfs.bookmarkfs
===============

     mkfs.bookmarkfs [OPTIONS] PATHNAME

The mkfs.bookmarkfs program creates a BookmarkFS filesystem on the file specified by PATHNAME.

Available options:

-o backend=NAME
     The backend used by the filesystem (see Backends). This option is mandatory.

-o @KEY[=VALUE]
     A backend-specific option. This option can be provided multiple times.

-o force
     Overwrite existing files when creating the filesystem.

-h
     Print help text, and then exit.

-V
     Print version and feature information, and then exit.

bookmarkctl
===========

     bookmarkctl SUBCMD [ARGS]

The bookmarkctl program is a command-line wrapper for various I/O controls of a BookmarkFS filesystem.

     bookmarkctl permd PATHNAME OP NAME1 NAME2

The permd sub-command re-arranges the order of the directory entries returned from readdir() calls. See Permute Directory Entries.

The PATHNAME argument is the path to the directory. The NAME1 and NAME2 arguments are filenames under that directory.

The OP argument is the operation to perform on the directory:

  * swap -- BOOKMARKFS_PERMD_OP_SWAP

  * move-before -- BOOKMARKFS_PERMD_OP_MOVE_BEFORE

  * move-after -- BOOKMARKFS_PERMD_OP_MOVE_AFTER

     bookmarkctl fsck PATHNAME OP

The fsck sub-command checks for errors within a BookmarkFS filesystem. See Filesystem Check.

The pathname argument is the path to the directory to perform checks on.

The op argument is the operation to perform on the directory:

  * list -- Display a list of errors found under the given directory. Will not recurse into subdirectories.

For the full fsck functionalities, see fsck.bookmarkfs.

     bookmarkctl help

Print help text, and then exit.

     bookmarkctl version

Print version information, and then exit.

The Filesystem
**************

When a BookmarkFS filesystem is mounted using the mount.bookmarkfs program, a daemon process acts as a proxy between the kernel (which relays filesystem requests to FUSE requests) and the backend (which manipulates actual bookmark data, see Backends), thus providing POSIX (and platform-specific) filesystem API access to bookmarks.

BookmarkFS is designed in the hope that web browser bookmarks can be managed flexibly using a combination of existing software, without having to reinvent the wheel. However, like most other pseudo-filesystems, it cannot be considered fully POSIX-compliant. Users should be aware of the limitations when using BookmarkFS.

Filesystem Hierarchy
====================

BookmarkFS has multiple subsystems. Each one appears as a directory under the mountpoint:

     ${MOUNTPOINT}/bookmarks
     ${MOUNTPOINT}/tags
     ${MOUNTPOINT}/keywords

If the backend does not support a subsystem, the corresponding directory does not exist.

Currently all subsystem definitions are hard-coded within the mount.bookmarkfs program, and cannot be extended by the backend.

Bookmarks
---------

     ${MOUNTPOINT}/bookmarks/${BOOKMARK_DIR...}/${BOOKMARK}

The ``bookmarks'' subsystem maintains the hierarchical structure, names, URLs and other information of a bookmark storage. Each bookmark folder name appears as the filename for directory ${BOOKMARK_DIR}, and each ${BOOKMARK} is a regular file that refers to a bookmark.

The name of a bookmark file is usually the ``bookmark title'', which is the name that appears in the browser's bookmark manager. The content of a bookmark file is usually the URL associated with the bookmark.

Not all bookmark names can be represented as a filename (e.g. contains slash character; longer than NAME_MAX; ...). For a bookmark or bookmark folder with an invalid name, the corresponding file does not exist on the filesystem. To deal with such bookmarks, see Filesystem Check; or you can instruct the backend to identify bookmarks using GUIDs instead of titles (and then access the titles via extended attributes).

Some file attributes are used to represent bookmark metadata:

st_ino
     ID of the bookmark (stored as lower bits).

st_size
     Length of the bookmark URL in bytes. Always 0 for directories.

st_atim
     Last access time of the bookmark.

st_mtim
     Last modification time of the bookmark. See File Modification/Change Time.

Additional information of a bookmark or bookmark folder can be accessed via the extended attributes of the corresponding file, for backends that supports it (see Extended Attributes).

Tags
----

     ${MOUNTPOINT}/tags/${TAG_DIR}/${BOOKMARK}

The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and their alternative names. Each tag name appears as the filename for directory ${TAG_DIR}, and ${BOOKMARK} is a hard link to the bookmark file. A bookmark directory cannot be associated with a tag.

If multiple bookmark files with identical names are both associated with a tag, it is unspecified which one appears as an entry for the tag directory. However, consecutive lookups and readdir()s should produce consistent results for that file, provided that it is not renamed or deleted.

Tag files behave differently from traditional hard links. If the original bookmark file is renamed or deleted, it may also change accordingly. It may even link to another file that was previously shadowed. Applications should tread lightly if they wish to cache tag directory entries.

To associate a bookmark with a tag, use link(3p):

     fd = open("tags/gnu/readline", O_CREAT | O_WRONLY, 0600);
     // Oops, fd == -1, errno == EPERM

     fd = link("bookmarks/other/readline", "tags/gnu/readline", 0);
     // OK!

Make sure that the two files have identical names, otherwise link() fails with EPERM.

Keywords
--------

     ${MOUNTPOINT}/keywords/${KEYWORD_NAME}

The ``keywords'' subsystem maintains a one-to-one mapping between bookmarks and their alternative names, independent from tag names. Each keyword name appears as the filename for regular file ${KEYWORD_NAME}, which is a hard link to the bookmark file. A bookmark directory cannot be associated with a keyword.

To associate a bookmark with a keyword, use link() like we do with tags. If the original file is already associated with another keyword, link() fails with EEXIST.

Error Codes
===========

When a filesystem operation fails, the kernel returns an error code for the system call. In addition to common error codes, there's few more in BookmarkFS:

EPERM
     Attempting to perform an unsupported operation. For example:

       * chmod(), chown(), and other operations that makes no sense for web browser bookmarks.

       * Moving a file across subsystems.

       * Creating a bookmark file with a name that is not valid UTF-8 (on Chromium backend).

EIO
     An unexpected internal error occurred, likely due to a bug in BookmarkFS, or a corruption in the bookmark storage.

     When this error occurs, a log message describing the situation may be printed to the standard error of the daemon process. Sometimes this error comes from the kernel-side FUSE implementation, and there's no error message.

     Once this error occurs, behavior of any further operations on the filesystem is undefined.

ESTALE
     The file associated with the file descriptor no longer exists.

     The error may occur when the underlying bookmark storage has been modified by another process (e.g. a web browser) after opening a file.

     If the filesystem is mounted in exclusive mode, this error should not occur.

Other BookmarkFS-specific errors may occur. See the corresponding manual section for details.

Extended Attributes
===================

BookmarkFS uses extended attributes to manage additional information associated with a bookmark.

Extended attributes is a platform-specific feature. On Linux, see xattr(7). On FreeBSD, see extattr(2).

All BookmarkFS extended attributes fall under the ``user'' namespace, which means they have a user. name prefix on Linux, and should be accessed with EXTATTR_NAMESPACE_USER on FreeBSD. All attributes have a bookmarkfs. name prefix.

For example, to get the GUID of a bookmark file (Firefox backend):

     // Linux
     len = fgetxattr(fd, "user.bookmarkfs.guid", buf, sizeof(buf));

     // FreeBSD
     len = extattr_get_fd(fd, EXTATTR_NAMESPACE_USER, "bookmarkfs.guid",
             buf, sizeof(buf));

BookmarkFS does not define any common attributes, neither can users create arbitrary ones. The backend decides which attributes are available during initialization, and all bookmark files share the same set of attributes.

Directory Entry Ordering
========================

POSIX does not specify the ordering of the directory entries retrieved from the directory stream using readdir(3p). It only guarantees that if an entry is not added or removed from the directory after the most recent call to opendir(3p) or rewinddir(3p), that entry is returned once and only once.

This allows filesystem implementations to organize directory entries in a more relaxed manner. There could be extra overhead to maintain a predictable ordering of directory entries, since they may not have a linear structure on modern on-disk filesystems (e.g. ext4 uses htree (https://docs.kernel.org/filesystems/ext4/dynamic.html#hash-tree-directories) for large directories).

As for users of a filesystem, the order of directory entries generally does not matter. If they care, they can add a prefix to the filename, and let the application do the sorting.

However, the order of which a bookmark entry appears in the web browser sometimes does matter. In BookmarkFS, it is guaranteed to be equivalent to the directory traversal order. New entries are appended to the end; removed entries do not affect the order of other entries.

Permute Directory Entries
-------------------------

BookmarkFS provides an I/O control for rearranging directory entries:

     #include <bookmarkfs/ioctl.h>

     int ioctl (int dirfd, BOOKMARKFS_IOC_PERMD,
             struct bookmarkfs_permd_data const *argp);

The bookmarkfs_permd_data structure is defined as:

     struct bookmarkfs_permd_data {
         enum bookmarkfs_permd_op op;

         char name1[NAME_MAX + 1];
         char name2[NAME_MAX + 1];
     };

The op field denotes the operation to perform on the directory:

BOOKMARKFS_PERMD_OP_SWAP
     Exchange the positions of the directory entries represented by name1 and name2.

BOOKMARKFS_PERMD_OP_MOVE_BEFORE
     Move the directory entry represented by name1 to the position just before the one represented by name2.

BOOKMARKFS_PERMD_OP_MOVE_AFTER
     Move the directory entry represented by name1 to the position just after the one represented by name2.

On success, ioctl() returns 0. Otherwise, it returns -1 and sets errno:

EACCES
     Write or search permission is denied for the directory.

EINVAL
     op is not one of the values defined in enum bookmarkfs_permd_op.

EINVAL
     name1 or name2 is not a valid filename (e.g. empty string; contains slash character, ...).

ENOENT
     The directory does not contain name1 or name2.

EPERM
     The backend does not support rearranging entries for this directory.

To ensure that the order change is visible to further readdir() calls, fsync() or close() the directory.

Filesystem Check
================

Backends
********

In BookmarkFS, each backend provides a way to manipulate a certain kind of application bookmarks.

Typically, backends are built into shared libraries, and are installed as:

     ${PKGLIBDIR}/backend-${SHORT_NAME}${SHLIB_SUFFIX}

Where ${SHORT_NAME} is the name passed to the frontend program, and ${SHLIB_SUFFIX} is the common filename extension for shared library files on the current platform (e.g. .so on GNU/Linux and FreeBSD).

Currently, BookmarkFS ships with two backends. One for Firefox, the other for Chromium. If you which to add support for more backends, you may submit a feature request or implement one using the Backend API.

Firefox Backend
===============

Chromium Backend
================

Backend API
===========

Filesystem-Check Handlers
*************************

Built-in Handler
================

Tcl-Based Handler
=================

Handler API
===========

GNU Free Documentation License
******************************

     [file fdl.texi not included]