{"id":13509850,"url":"https://github.com/winfsp/objfs","last_synced_at":"2025-04-09T04:33:24.704Z","repository":{"id":57572416,"uuid":"127462770","full_name":"winfsp/objfs","owner":"winfsp","description":"Object Storage File System","archived":false,"fork":false,"pushed_at":"2021-02-19T23:44:39.000Z","size":125,"stargazers_count":31,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T23:33:30.831Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/winfsp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-30T18:57:10.000Z","updated_at":"2025-03-19T08:22:03.000Z","dependencies_parsed_at":"2022-08-24T08:40:44.506Z","dependency_job_id":null,"html_url":"https://github.com/winfsp/objfs","commit_stats":null,"previous_names":["billziss-gh/objfs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fobjfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fobjfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fobjfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fobjfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/winfsp","download_url":"https://codeload.github.com/winfsp/objfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980833,"owners_count":21027803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:01:14.548Z","updated_at":"2025-04-09T04:33:24.130Z","avatar_url":"https://github.com/winfsp.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"# objfs - Object Storage File System\n\nThe [objfs](https://github.com/billziss-gh/objfs) repository and its companion repository [objfs.pkg](https://github.com/billziss-gh/objfs.pkg) contain the implementation of objfs, the \"object storage file system\".\n\nObjfs exposes objects from an object storage, such as a cloud drive, etc. as files in a file system that is fully integrated with the operating system. Programs that run on the operating system are able to access these files as if they are stored in a local \"drive\" (perhaps with some delay due to network operations).\n\n- Supported operating systems: Windows, macOS, and Linux.\n- Supported object storages: OneDrive\n\n## How to use\n\nObjfs is implemented as a command-line program that accepts commands such as `auth` and `mount`, but also shell-like commands, such as `ls`, `stat`, etc.\n\n```\n$ ./objfs help\nusage: objfs [-options] command args...\n\ncommands:\n  version\n    \tget current version information\n  config\n    \tget or set configuration options\n  keyring\n    \tget or set keys\n  auth\n    \tperform authentication/authorization\n  mount\n    \tmount file system\n  statfs\n    \tget storage information\n  ls\n    \tlist files\n  stat\n    \tdisplay file information\n  mkdir\n    \tmake directories\n  rmdir\n    \tremove directories\n  rm\n    \tremove files\n  mv\n    \tmove (rename) files\n  get\n    \tget (download) files\n  put\n    \tput (upload) files\n  cache-pending\n    \tlist pending cache files\n  cache-reset\n    \treset cache (upload and evict files)\n\noptions:\n  -accept-tls-cert\n    \taccept any TLS certificate presented by the server (insecure)\n  -auth name\n    \tauth name to use\n  -config path\n    \tpath to configuration file\n  -credentials path\n    \tauth credentials path (keyring:service/user or /file/path)\n  -datadir path\n    \tpath to supporting data and caches\n  -keyring string\n    \tkeyring type to use: system, private (default \"private\")\n  -storage name\n    \tstorage name to access (default \"onedrive\")\n  -storage-uri uri\n    \tstorage uri to access\n  -v\tverbose\n```\n\n### Default Storage\n\nObjfs uses defaults to simplify command line invocation. In the default build of objfs, the default storage is `onedrive`.\n\n### Auth\n\nObjfs supports multiple \"auth\" (authentication or authorization) mechanisms through the `-credentials path` option and the `auth` command.\n\nIn general before an object storage service can be used it requires auth. The specific auth mechanism used depends on the service and it ranges from no auth, to username/password, to Oauth2, etc. Auth mechanisms require credentials, which can be supplied using the `-credentials path` option.\n\nIn some cases the object storage service cannot readily accept the supplied credentials, they must be converted to other credentials first. As an authentication example, a particular service may require username/password credentials to be converted to some form of service-level token before they can be used. As an authorization example Oauth2 requires application-level credentials together with user consent to form a service-level token that can be used to access the service.\n\nThe `auth` command can be used for this purpose. It takes user-level or application-level credentials and converts them to service-level credentials.\n\nCredentials can be stored in the local file system or the system keyring. The syntax `/file/path` is used to name credentials stored in the file system. The syntax `keyring:service/user` is used to name credentials stored in the system keyring.\n\n#### Example - Oauth2 Flow\n\n- Prepare the Oauth2 `client_secret` credentials in a file or the system keyring:\n    ```\n    client_id=\"XXXXXXXX\"\n    client_secret=\"XXXXXXXX\"\n    redirect_uri=\"http://localhost:xxxxx\"\n    scope=\"files.readwrite.all offline_access\"\n    ```\n- Issue the command:\n    ```\n    $ ./objfs -credentials=CLIENT_SECRET_PATH auth TOKEN_PATH\n    ```\n- This will launch your browser and ask for authorization. If the access is authorized the Oauth2 `access_token` and `refresh_token` will be stored in the specified path.\n- The object storage can now be mounted using the command:\n    ```\n    $ ./objfs -credentials=TOKEN_PATH mount MOUNTPOINT\n    ```\n\n### Mount\n\nThe objfs `mount` command is used to mount an object storage as a file system on a mountpoint. On Windows the mount point must be a non-existing drive or directory; it is recommended that an object storage is only mounted as a drive when the object storage is case-sensitive. On macOS and Linux the mount point must be an existing directory.\n\nTo mount on Windows:\n\n```\n\u003e objfs -credentials=TOKEN_PATH mount -o uid=-1,gid=-1 mount X:\n```\n\nTo mount on macOS and Linux:\n\n```\n$ ./objfs -credentials=TOKEN_PATH mount MOUNTPOINT\n```\n\nObjfs uses a local file cache to speed up file system operations. This caches files locally when they are first opened; subsequent I/O operations will be performed against the local file and are therefore fast. Modified files will be uploaded to the object storage when they are closed. File system operations such as creating and deleting files and listing directories are sent directly to the object storage and are therefore slow (although some of their results are cached).\n\nThe Objfs cache was inspired by an early version of the Andrew File System (AFS). For more information see this [paper](http://pages.cs.wisc.edu/~remzi/OSTEP/dist-afs.pdf).\n\n### Diagnostics\n\nObjfs includes a tracing facility that can be used to troubleshoot problems, to gain insights into its internal workings, etc. This facility is enabled when the `-v` option is used.\n\nThe environment variable `GOLIB_TRACE` controls which traces are enabled. This variable accepts a comma separated list of file-style patterns containing wildcards such as `*` and `?`.\n\n```\n$ export GOLIB_TRACE=pattern1,...,patternN\n```\n\nExamples:\n\n```\n$ export GOLIB_TRACE=github.com/billziss-gh/objfs/fs.*      # file system traces\n$ export GOLIB_TRACE=github.com/billziss-gh/objfs/objio.*   # object storage traces\n$ export GOLIB_TRACE=github.com/billziss-gh/objfs/fs.*,github.com/billziss-gh/objfs/objio.*\n$ ./objfs -v -credentials=TOKEN_PATH mount MOUNTPOINT\n```\n\n## How to build\n\nObjfs is written in Go and uses [cgofuse](https://github.com/billziss-gh/cgofuse) to interface with the operating system. It requires the relevant FUSE drivers/libraries for each operating system.\n\nPrerequisites:\n- Windows: [WinFsp](https://github.com/billziss-gh/winfsp), gcc (e.g. from [Mingw-builds](http://mingw-w64.org/doku.php/download))\n- macOS: [FUSE for macOS](https://osxfuse.github.io), [command line tools](https://developer.apple.com/library/content/technotes/tn2339/_index.html)\n- Linux: libfuse-dev, gcc\n\nTo build the following is usually sufficient:\n\n```\n$ go get -d github.com/billziss-gh/objfs\n$ make      # on windows you may have to update the PATH in make.cmd\n```\n\nThis will include all supported storages. Objfs storage and auth mechanisms are maintained in the separate repository objfs.pkg. You can customize the supported storages for licensing or other reasons by modifying the [`Makefile Packages`](Makefile) variable.\n\n## License\n\nThe objfs and objfs.pkg repositories are available under the [AGPLv3](License.txt) license.\n\nThe project has the following dependencies and their licensing:\n\n- [cgofuse](https://github.com/billziss-gh/cgofuse) - Cross-platform FUSE library for Go.\n    - License: MIT\n- [boltdb](https://github.com/boltdb/bolt) - An embedded key/value database for Go.\n    - License: MIT\n- [golib](https://github.com/billziss-gh/golib) - Collection of Go libraries.\n    - License: MIT\n- [oauth2-helper](https://github.com/billziss-gh/oauth2-helper) - OAuth 2.0 for Native Apps\n    - License: MIT\n- [WinFsp](https://github.com/billziss-gh/winfsp) - Windows File System Proxy - FUSE for Windows.\n    - License: GPLv3 w/ FLOSS exception\n- [FUSE for macOS](https://osxfuse.github.io) - File system integration made easy.\n    - License: BSD-style\n- [libfuse](https://github.com/libfuse/libfuse) - The reference implementation of the Linux FUSE (Filesystem in Userspace) interface.\n    - License: LGPLv2.1\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinfsp%2Fobjfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwinfsp%2Fobjfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinfsp%2Fobjfs/lists"}