makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: misc update

Browse source
This commit is contained in:
CismonX 2025-01-14 09:22:26 +08:00
parent 7b2942416b
commit 76d22c5bcc
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 57 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

91
doc/bookmarkfs.texi
View file

@ -133,7 +133,7 @@ if a vulnerability is discovered in BookmarkFS and/or its dependencies.
However, it only deals with untrusted input, However, it only deals with untrusted input,
and cannot help if the operating system has already been compromised. and cannot help if the operating system has already been compromised.
Example of what ``untrusted input'' may include: Examples of what ``untrusted input'' may include:
@itemize @bullet{} @itemize @bullet{}
@item Bookmark files that are @emph{not} created by the user using a @item Bookmark files that are @emph{not} created by the user using a
@ -169,17 +169,22 @@ that contains bookmark data.
The exact interpretation of this option is backend-defined. The exact interpretation of this option is backend-defined.
@item target @item target
Pathname to the directory where the filesystem shall be mounted on Pathname of the directory where the filesystem shall be mounted to
(i.e. the ``mountpoint''). (i.e. the ``mountpoint'').
@end table @end table
Files under the filesystem are assigned ownership according to
the effective user ID and group ID of the calling process.
On FreeBSD, you may wish to set the @samp{vfs.usermount}
@freebsdmanpage{sysctl, 8} to @t{1} for unprivileged mounts.
To unmount a BookmarkFS filesystem, run @linuxmanpage{fusermount3, 1} or To unmount a BookmarkFS filesystem, run @linuxmanpage{fusermount3, 1} or
@linuxmanpage{umount, 8} on @var{target}. @linuxmanpage{umount, 8} on @var{target}.
The daemon process will automatically dismount the filesystem upon The daemon process will automatically dismount the filesystem upon
@code{SIGINT} or @code{SIGTERM} receipt, however, it only works in @code{SIGINT} or @code{SIGTERM} receipt, however, it only works in
non-sandbox mode. non-sandbox mode.
Available options: Options:
@table @option @table @option
@item -o backend=@var{name} @item -o backend=@var{name}
@ -217,10 +222,10 @@ Since a bookmark has only one ``modification time'' attribute instead of two,
the user has to choose which one to maintain: the user has to choose which one to maintain:
@table @asis @table @asis
@item mtime @item modification time
ctime only updates when mtime does. ctime only updates when mtime does.
@item ctime @item change time
ctime updates normally; mtime always updates when ctime does, ctime updates normally; mtime always updates when ctime does,
even if the file content is not modified. even if the file content is not modified.
@ -271,23 +276,29 @@ Notable options:
@item -o rw @item -o rw
Mount the filesystem read/write. 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.
@quotation Warning @quotation Warning
Always backup the bookmarks before mounting it read/write, or risk losing Always backup the bookmark storage before mounting it read/write,
your data! or risk losing your data!
@end quotation @end quotation
By default, the filesystem is mounted read-only.
This behavior won't change in the future, due to the hackish nature of
most BookmarkFS backends.
When mounted read/write, other process must not write to the
underlying bookmark storage, otherwise data corruption may occur.
@item -o debug @item -o debug
Set libfuse log level to @code{FUSE_LOG_DEBUG}. Set libfuse log level to @code{FUSE_LOG_DEBUG}.
Log messages related to each FUSE request will be printed to standard error. Log messages related to each FUSE request will be printed to standard error.
@item -o fsname @item -o fsname=@var{name}
The name that appears as the @code{fs_spec} field in @linuxmanpage{fstab, 5}. Name for the filesystem.
Defaults to the backend name. Defaults to the backend name.
This name is equivalent to the @code{fs_spec} field in @linuxmanpage{fstab, 5},
and appears as the @samp{SOURCE} column in @linuxmanpage{findmnt, 8} output.
@item -o atime,diratime,relatime @item -o atime,diratime,relatime
These options (and other atime-related ones) are ignored. These options (and other atime-related ones) are ignored.
@ -316,7 +327,7 @@ Filesystem check on BookmarkFS has a different purpose compared to
on-disk filesystems. on-disk filesystems.
@xref{Filesystem Check}. @xref{Filesystem Check}.
Available options: Options:
@table @option @table @option
@item -o backend=@var{name} @item -o backend=@var{name}
@ -363,7 +374,7 @@ This option can be provided multiple times.
Attempt to repair errors found during fsck. Attempt to repair errors found during fsck.
@quotation Warning @quotation Warning
Always backup the bookmarks before repairing, or risk losing your data! Always backup the bookmark storage before repairing, or risk losing your data!
@end quotation @end quotation
@item -o rl_app=@var{name} @item -o rl_app=@var{name}
@ -416,7 +427,7 @@ This option is equivalent to the @var{src} argument for
@command{mount.bookmarkfs}. @command{mount.bookmarkfs}.
@end table @end table
Available options: Options:
@table @option @table @option
@item -o backend=@var{name} @item -o backend=@var{name}
@ -554,12 +565,13 @@ Currently all subsystem definitions are hard-coded within the
@node Bookmarks @node Bookmarks
@subsection Bookmarks @subsection Bookmarks
The ``bookmarks'' subsystem maintains the hierarchical structure, names, URLs
and other information of a bookmark storage.
@example @example
@var{$@{mountpoint@}}/bookmarks/@var{$@{bookmark_dir...@}}/@var{$@{bookmark@}} @var{$@{mountpoint@}}/bookmarks/@var{$@{bookmark_dir...@}}/@var{$@{bookmark@}}
@end example @end example
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 Each bookmark folder name appears as the filename for directory
@var{$@{bookmark_dir@}}, and each @var{$@{bookmark@}} is a regular file @var{$@{bookmark_dir@}}, and each @var{$@{bookmark@}} is a regular file
that refers to a bookmark. that refers to a bookmark.
@ -601,12 +613,13 @@ supports it (@pxref{Extended Attributes}).
@node Tags @node Tags
@subsection Tags @subsection Tags
The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and
their alternative names.
@example @example
@var{$@{mountpoint@}}/tags/@var{$@{tag_dir@}}/@var{$@{bookmark@}} @var{$@{mountpoint@}}/tags/@var{$@{tag_dir@}}/@var{$@{bookmark@}}
@end example @end example
The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and
their alternative names.
Each tag name appears as the filename for directory @var{$@{tag_dir@}}, Each tag name appears as the filename for directory @var{$@{tag_dir@}},
and @var{$@{bookmark@}} is a hard link to the bookmark file. and @var{$@{bookmark@}} is a hard link to the bookmark file.
A bookmark directory cannot be associated with a tag. A bookmark directory cannot be associated with a tag.
@ -639,12 +652,13 @@ fails with @code{EPERM}.
@node Keywords @node Keywords
@subsection Keywords @subsection Keywords
The ``keywords'' subsystem maintains a one-to-one mapping between bookmarks
and their alternative names, independent from tag names.
@example @example
@var{$@{mountpoint@}}/keywords/@var{$@{keyword_name@}} @var{$@{mountpoint@}}/keywords/@var{$@{keyword_name@}}
@end example @end example
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 Each keyword name appears as the filename for regular file
@var{$@{keyword_name@}}, which is a hard link to the bookmark file. @var{$@{keyword_name@}}, which is a hard link to the bookmark file.
A bookmark directory cannot be associated with a keyword. A bookmark directory cannot be associated with a keyword.
@ -991,10 +1005,10 @@ Typically, backends are built into shared libraries, and are installed as:
@var{$@{pkglibdir@}}/backend-@var{$@{name@}}@var{$@{shlib_suffix@}} @var{$@{pkglibdir@}}/backend-@var{$@{name@}}@var{$@{shlib_suffix@}}
@end example @end example
Where @var{$@{name@}} is the value given to the @option{-o handler=@var{name}} Where @var{$@{name@}} is the backend name, equivalent to value given to the
option of frontend programs, and @var{$@{shlib_suffix@}} is the common @option{-o backend=@var{name}} option of frontend programs,
filename extension for shared library files on the current platform and @var{$@{shlib_suffix@}} is the common filename extension for shared library
(e.g. @file{.so} on GNU/Linux and FreeBSD). files on the current platform (e.g. @file{.so} on GNU/Linux and FreeBSD).
@node Firefox @node Firefox
@ -1015,6 +1029,8 @@ When mounting the filesystem, this pathname shall be passed as the @var{src}
argument (@pxref{mount.bookmarkfs}). argument (@pxref{mount.bookmarkfs}).
Actual path for the profile directories may differ across distributions. Actual path for the profile directories may differ across distributions.
Backend name: @samp{firefox}.
Backend-specific options (@command{mount.bookmarkfs} only): Backend-specific options (@command{mount.bookmarkfs} only):
@table @option @table @option
@ -1103,6 +1119,8 @@ When mounting the filesystem, this pathname shall be passed as the @var{src}
argument (@pxref{mount.bookmarkfs}). argument (@pxref{mount.bookmarkfs}).
Actual path for the profile directories may differ across distributions. Actual path for the profile directories may differ across distributions.
Backend name: @samp{chromium}.
Backend-specific options (@command{mount.bookmarkfs} only): Backend-specific options (@command{mount.bookmarkfs} only):
@table @option @table @option
@ -1146,14 +1164,19 @@ Defaults to @samp{native} when the filesystem is mounted read-only,
@table @samp @table @samp
@item native @item native
Watch for file changes using platform-specific features. Watch for file changes using platform-specific features:
On Linux, @linuxmanpage{fanotify, 7} is used. @table @asis
@item Linux
@linuxmanpage{fanotify, 7} is used.
Requires kernel version 5.13 or later for unprivileged users. Requires kernel version 5.13 or later for unprivileged users.
@linuxmanpage{inotify, 7} does not have this limitation, however, @linuxmanpage{inotify, 7} does not have this limitation, however,
it is incompatible with our sandboxing design. it is incompatible with our sandboxing design.
On FreeBSD, @freebsdmanpage{kevent, 2} with @code{EVFILT_VNODE} is used. @item FreeBSD
@freebsdmanpage{kevent, 2} with @code{EVFILT_VNODE} is used.
@end table
@item fallback @item fallback
Watch for file changes by checking @code{st_ino} and @code{st_mtim} attributes Watch for file changes by checking @code{st_ino} and @code{st_mtim} attributes
@ -1211,16 +1234,16 @@ shared libraries, and are installed as:
@var{$@{pkglibdir@}}/fsck-handler-@var{$@{name@}}@var{$@{shlib_suffix@}} @var{$@{pkglibdir@}}/fsck-handler-@var{$@{name@}}@var{$@{shlib_suffix@}}
@end example @end example
Where @var{$@{name@}} is the value given to the @option{-o handler=@var{name}} Where @var{$@{name@}} is the handler name, equivalent to the value given to
option of @command{fsck.bookmarkfs}, and @var{$@{shlib_suffix@}} is the the @option{-o handler=@var{name}} option of @command{fsck.bookmarkfs},
common filename extension for shared library files on the current platform and @var{$@{shlib_suffix@}} is the common filename extension for shared library
(e.g. @file{.so} on GNU/Linux and FreeBSD). files on the current platform (e.g. @file{.so} on GNU/Linux and FreeBSD).
@node Built-in Filesystem-Check Handler @node Built-in Filesystem-Check Handler
@section Built-in Handler @section Built-in Handler
The built-in handler is shipped with the @command{fsck.bookmarkfs} program. The built-in handler is linked into the @command{fsck.bookmarkfs} program.
It has minimal functionalities, but is capable enough to handle most It has minimal functionalities, but is capable enough to handle most
common fsck scenarios. common fsck scenarios.