[
    {
        "Name"                  : "libfuse",
        "License"               : "LGPL V2.1",
        "License File"          : "LGPL2.txt",
        "Version Number"        : "3.16.1",
        "Owner"                 : "maojingjing1@huawei.com",
        "Upstream URL"          : "https://github.com/libfuse/libfuse/releases/tag/fuse-3.16.1",
        "Description"           : "libfuse provides the reference implementation for communicating with the FUSE kernel module."
    }
]

libfuse
=======

About
-----

FUSE (Filesystem in Userspace) is an interface for userspace programs
to export a filesystem to the Linux kernel. The FUSE project consists
of two components: the *fuse* kernel module (maintained in the regular
kernel repositories) and the *libfuse* userspace library (maintained
in this repository). libfuse provides the reference implementation
for communicating with the FUSE kernel module.

A FUSE file system is typically implemented as a standalone
application that links with libfuse. libfuse provides functions to
mount the file system, unmount it, read requests from the kernel, and
send responses back. libfuse offers two APIs: a "high-level",
synchronous API, and a "low-level" asynchronous API. In both cases,
incoming requests from the kernel are passed to the main program using
callbacks. When using the high-level API, the callbacks may work with
file names and paths instead of inodes, and processing of a request
finishes when the callback function returns. When using the low-level
API, the callbacks must work with inodes and responses must be sent
explicitly using a separate set of API functions.


Development Status
------------------

libfuse is shipped by all major Linux distributions and has been in
production use across a wide range of systems for many years. However,
at present libfuse does not have any active, regular contributors. The
current maintainer continues to apply pull requests and makes regular
releases, but unfortunately has no capacity to do any development
beyond addressing high-impact issues. When reporting bugs, please
understand that unless you are including a pull request or are
reporting a critical issue, you will probably not get a response. If
you are using libfuse, please consider contributing to the project.


Supported Platforms
-------------------

* Linux (fully)
* BSD (mostly/best-effort)
* For OS-X, please use [OSXFUSE](https://osxfuse.github.io/)


Installation
------------

You can download libfuse from https://github.com/libfuse/libfuse/releases. To build and
install, you must use [Meson](http://mesonbuild.com/) and
[Ninja](https://ninja-build.org).  After downloading the tarball and `.sig` file, verify
it using [signify](https://www.openbsd.org/papers/bsdcan-signify.html):

    signify -V -m fuse-X.Y.Z.tar.gz -p fuse-X.Y.pub

The `fuse-X.Y.pub` file contains the signing key and needs to be obtained from a
trustworthy source. Each libfuse release contains the signing key for the release after it
in the `signify` directory, so you only need to manually acquire this file once when you
install libfuse for the first time.

After you have validated the tarball, extract it, create a (temporary) build directory and
run Meson:

    $ tar xzf fuse-X.Y.Z.tar.gz; cd fuse-X.Y.Z
    $ mkdir build; cd build
    $ meson setup ..

Normally, the default build options will work fine. If you
nevertheless want to adjust them, you can do so with the
*meson configure* command:

    $ meson configure # list options
    $ meson configure -D disable-mtab=true # set an option

To build, test, and install libfuse, you then use Ninja:

    $ ninja
    $ sudo python3 -m pytest test/
    $ sudo ninja install

Running the tests requires the [py.test](http://www.pytest.org/)
Python module. Instead of running the tests as root, the majority of
tests can also be run as a regular user if *util/fusermount3* is made
setuid root first:

    $ sudo chown root:root util/fusermount3
    $ sudo chmod 4755 util/fusermount3
    $ python3 -m pytest test/

Security implications
---------------------

The *fusermount3* program is installed setuid root. This is done to
allow normal users to mount their own filesystem implementations.

To limit the harm that malicious users can do this way, *fusermount3*
enforces the following limitations:

  - The user can only mount on a mountpoint for which they have write
    permission

  - The mountpoint must not be a sticky directory which isn't owned by
    the user (like /tmp usually is)

  - No other user (including root) can access the contents of the
    mounted filesystem (though this can be relaxed by allowing the use
    of the *allow_other* and *allow_root* mount options in
    */etc/fuse.conf*)


If you intend to use the *allow_other* mount options, be aware that
FUSE has an unresolved [security
bug](https://github.com/libfuse/libfuse/issues/15): if the
*default_permissions* mount option is not used, the results of the
first permission check performed by the file system for a directory
entry will be re-used for subsequent accesses as long as the inode of
the accessed entry is present in the kernel cache - even if the
permissions have since changed, and even if the subsequent access is
made by a different user. This is of little concern if the filesystem
is accessible only to the mounting user (which has full access to the
filesystem anyway), but becomes a security issue when other users are
allowed to access the filesystem (since they can exploit this to
perform operations on the filesystem that they do not actually have
permissions for).

This bug needs to be fixed in the Linux kernel and has been known
since 2006 but unfortunately no fix has been applied yet. If you
depend on correct permission handling for FUSE file systems, the only
workaround is to use `default_permissions` (which does not currently
support ACLs), or to completely disable caching of directory entry
attributes.

Building your own filesystem
------------------------------

FUSE comes with several example file systems in the `example`
directory. For example, the *passthrough* examples mirror the contents
of the root directory under the mountpoint. Start from there and adapt
the code!

The documentation of the API functions and necessary callbacks is
mostly contained in the files `include/fuse.h` (for the high-level
API) and `include/fuse_lowlevel.h` (for the low-level API). An
autogenerated html version of the API is available in the `doc/html`
directory and at http://libfuse.github.io/doxygen.


Getting Help
------------

If you need help, please ask on the <fuse-devel@lists.sourceforge.net>
mailing list (subscribe at
https://lists.sourceforge.net/lists/listinfo/fuse-devel).

Please report any bugs on the GitHub issue tracker at
https://github.com/libfuse/libfuse/issues.

# libfuse

仓库包含第三方开源软件libfuse，libfuse是FUSE（用户态文件系统）框架的用户态程序接口。libfuse提供挂载、卸载文件系统、解析和传递内核的请求接口等功能。在OpenHarmony中，开发者可以通过注册回调函数的形式，实现特定的用户态文件系统功能，例如cloudfiledaemon（云端文件系统服务）等。

## 目录结构

```
doc/        文档
example/    样例代码
include/    libfuse库头文件
lib/        libfuse库源代码
test/       测试脚本代码
util/       fusermount等二进制工具
README      README说明
```

## OpenHarmony如何使用libfuse

OpenHarmony只编译使用libfuse仓库中lib/和include/目录下的源代码和头文件。libfuse作为cloudfiledaemon的依赖模块，来实现具体的云端文件系统功能。

## OpenHarmony如何集成libfuse

libfuse编译为动态链接库，打包到system分区镜像中。

### 1. libfuse的编译

libfuse的编译入口在其根目录下的BUILD.gn中。简单示意如下：

```
libfuse_source = [
    "//third_party/libfuse/lib/fuse.c",
    "//third_party/libfuse/lib/fuse_loop.c",
    "//third_party/libfuse/lib/fuse_loop_mt.c",
    "//third_party/libfuse/lib/fuse_lowlevel.c",
    "//third_party/libfuse/lib/fuse_opt.c",
    "//third_party/libfuse/lib/fuse_signals.c",
    "//third_party/libfuse/lib/buffer.c",
    "//third_party/libfuse/lib/compat.c",
    "//third_party/libfuse/lib/cuse_lowlevel.c",
    "//third_party/libfuse/lib/helper.c",
    "//third_party/libfuse/lib/modules/subdir.c",
    "//third_party/libfuse/lib/mount_util.c",
    "//third_party/libfuse/lib/fuse_log.c",
    "//third_party/libfuse/lib/mount.c",
    "//third_party/libfuse/lib/modules/iconv.c",
]

ohos_shared_library("libfuse") {
    configs = [ ":libfuse_config" ]
    sources = libfuse_source
    ldflags = [
        "-ldl",
        "-Wl,--version-script",
        rebase_path("//third_party/libfuse/lib/fuse_versionscript", root_build_dir),
        "-Wl,-soname,libfuse3.so.3",
        "-Wl,--no-undefined",
        "-Wl,--as-needed",
        "-shared",
        "-fPIC",
    ]
    external_deps = [ "c_utils:utils" ]
    subsystem_name = "thirdparty"
    part_name = "libfuse"
    output_name = "libfuse"
    install_enable = true
    install_images = [ "system" ]
}

```

### 2. 使用libfuse

在需要使用libfuse的模块构建配置中，增加对应依赖，示例如下：

```
ohos_shared_library("cloudfiledaemon") {

  sources = [
    ......
  ]

  include_dirs = [
    ......
    "//third_party/libfuse/include",
    "//third_party/libfuse/lib",
  ]

  external_deps = [
    "//third_party/libfuse:libfuse",
  ]

...
}
```

## libfuse相关内容

[libfuse主页](https://github.com/libfuse/libfuse)
[libfuse文档](https://libfuse.github.io/doxygen/index.html)

## License

- include/ 和 lib/ 目录下的源文件，使用LGPL2.1协议；
- 其他源文件，使用GPL2协议。

## 风险提示

**libfuse是LGPLV2和GPLV2协议类型的三方开源软件，OpenHarmony当前仅使用LGPLV2部分。使用时需履行相应的开源义务。**