{"id":13632686,"url":"https://github.com/Hexilee/tifs","last_synced_at":"2025-04-18T05:32:50.538Z","repository":{"id":49799678,"uuid":"316410724","full_name":"Hexilee/tifs","owner":"Hexilee","description":"A distributed POSIX filesystem based on TiKV, with partition tolerance and strict consistency.","archived":false,"fork":false,"pushed_at":"2024-07-10T07:37:14.000Z","size":335,"stargazers_count":361,"open_issues_count":3,"forks_count":23,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-05T13:09:48.067Z","etag":null,"topics":["distributed-file-system","distributed-systems","filesystem","fuse","posix-compatible","tifs","tikv"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hexilee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-27T05:44:10.000Z","updated_at":"2025-04-02T06:29:51.000Z","dependencies_parsed_at":"2024-06-11T17:04:50.253Z","dependency_job_id":"9b94bffd-382b-4c6d-91cf-c55cd1be164b","html_url":"https://github.com/Hexilee/tifs","commit_stats":{"total_commits":268,"total_committers":7,"mean_commits":"38.285714285714285","dds":"0.19029850746268662","last_synced_commit":"e52c072e9ebb770bbf637495bcc05cb1e1b49407"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexilee%2Ftifs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexilee%2Ftifs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexilee%2Ftifs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hexilee%2Ftifs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hexilee","download_url":"https://codeload.github.com/Hexilee/tifs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249436936,"owners_count":21271968,"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":["distributed-file-system","distributed-systems","filesystem","fuse","posix-compatible","tifs","tikv"],"created_at":"2024-08-01T22:03:10.985Z","updated_at":"2025-04-18T05:32:50.152Z","avatar_url":"https://github.com/Hexilee.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# TiFS\n\nA distributed POSIX filesystem based on TiKV, with partition tolerance and strict consistency.\n\n[![pjdfstest](https://github.com/Hexilee/tifs/workflows/pjdfstest/badge.svg)](https://github.com/Hexilee/tifs/actions)\n\n## Environment\n\n### Build \n\n- Linux\n`libfuse` and `build-essential` are required, in ubuntu/debian:\n\n```\nsudo apt install -y libfuse-dev libfuse3-dev build-essential\n```\n\n- macOS\n```\nbrew install --cask osxfuse\n```\n\n### Runtime\n- Linux\n`fuse3` and `openssl` are required, in ubuntu/debian:\n\n```\nsudo apt-get install -y libfuse3-dev fuse3 libssl-dev\n```\n\n- macOS\n\n```\nbrew install --cask osxfuse\n```\n\nIn Catalina or former version, you need to load osxfuse into the kernel:\n\n```\n/Library/Filesystems/osxfuse.fs/Contents/Resources/load_osxfuse\n```\n\n## Installation\n\n### Container\nYou can use the image on [docker hub](https://hub.docker.com/repository/docker/hexilee/tifs) or build from the [Dockerfile](Dockerfile).\n\n### Binary(linux-amd64 or darwin-amd64)\n\n```bash\nmkdir tmp\ncd tmp\nwget https://github.com/Hexilee/tifs/releases/download/v0.2.1/tifs-linux-amd64.tar.gz\ntar -xvf tifs-linux-amd64.tar.gz\nsudo ./install.sh\n```\n\n\u003e The `install.sh` may fail in macOS Catalina or Big Sur because of the \n\u003e [SIP](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection). \n\u003e \n\u003e You can just use the `target/release/tifs` to mount tifs.\n\u003e ### Example\n\u003e ```\n\u003e target/release/tifs tifs:127.0.0.1:2379 ~/mnt\n\u003e ```\n\n### Source code\n\n```bash\ngit clone https://github.com/Hexilee/tifs.git\ncd tifs\nsudo make install\n```\n\n## Usage\nYou need a tikv cluster to run tifs. [tiup](https://github.com/pingcap/tiup) is convenient to deploy one, just install it and run `tiup playground`.\n\n### Container\n\n```bash\ndocker run -d --device /dev/fuse \\\n    --cap-add SYS_ADMIN \\\n    -v \u003cmount point\u003e:/mnt:shared \\\n    hexilee/tifs:0.2.2 --mount-point /mnt --pd-endpoints \u003cendpoints\u003e\n```\n\n#### TLS\nYou need ca.crt, client.crt and client.key to access TiKV cluster on TLS. \n\n\u003e It will be convenient to get self-signed certificates by [sign-cert.sh](sign-cert.sh)(based on the [easy-rsa](https://github.com/OpenVPN/easy-rsa)).\n\nYou should place them into a directory \u003ccert dir\u003e and execute following docker command.\n\n```bash\ndocker run -d --device /dev/fuse \\\n    --cap-add SYS_ADMIN \\\n    -v \u003ccert dir\u003e:/root/.tifs/tls \\\n    -v \u003cmount point\u003e:/mnt:shared \\\n    hexilee/tifs:0.3.1 --mount-point /mnt --pd-endpoints \u003cendpoints\u003e\n```\n\n### Binary\n\n```bash\nmkdir \u003cmount point\u003e\nmount -t tifs tifs:\u003cpd endpoints\u003e \u003cmount point\u003e\n```\n\n#### TLS\n\n```bash\nmount -t tifs -o tls=\u003ctls config file\u003e tifs:\u003cpd endpoints\u003e \u003cmount point\u003e\n```\n\nBy default, the tls-config should be located in `~/.tifs/tls.toml`, refer to the [tls.toml](config-examples/tls.toml) for detailed configuration.\n\n## Other Custom Mount Options\n\n### `direct_io`\n\nEnable global direct io, to avoid page cache.\n\n```bash\nmount -t tifs -o direct_io tifs:\u003cpd endpoints\u003e \u003cmount point\u003e\n```\n### `blksize`\n\nThe block size, 64KiB by default, could be human-readable.\n\n```bash\nmount -t tifs -o blksize=512 tifs:\u003cpd endpoints\u003e \u003cmount point\u003e\n```\n\n### `maxsize`\n\nThe quota of fs capacity, could be human-readable.\n\n```bash\nmount -t tifs -o maxsize=1GiB tifs:\u003cpd endpoints\u003e \u003cmount point\u003e\n```\n\n## Development\n\n```bash\ncargo build\nmkdir ~/mnt\nRUST_LOG=debug target/debug/tifs --mount-point ~/mnt\n```\n\nThen you can open another shell and play with tifs in `~/mnt`.\n\nMaybe you should enable `user_allow_other` in `/etc/fuse.conf`.\n\nfor developing under `FreeBSD`, make sure the following dependencies are met.\n\n```bash\npkg install llvm protobuf pkgconf fusefs-libs3 cmake\n```\n\nfor now, `user_allow_other` and `auto unmount` does not work for `FreeBSD`, using as `root` and manually `umount` is needed.\n\n## Contribution\n\n### Design\n\nPlease refer to the [design.md](contribution/design.md)\n\n### FUSE\nThere are little docs about FUSE, refer to the [example](https://github.com/cberner/fuser/blob/master/examples/simple.rs) for the meaning of FUSE API.\n\n### Deploy TiKV\nPlease refer to the [tikv-deploy.md](contribution/tikv-deploy.md).\n\n## TODO\n\n- [x] FUSE API\n    - [x] init\n    - [x] lookup\n    - [x] getattr\n    - [x] setattr\n    - [x] readlink\n    - [x] readdir\n    - [x] open\n    - [x] release\n    - [x] read\n    - [x] write\n    - [x] mkdir\n    - [x] rmdir\n    - [x] mknod\n    - [x] lseek\n    - [x] unlink\n    - [x] symlink\n    - [x] rename\n    - [x] link\n    - [x] statfs\n    - [x] create\n    - [x] fallocate\n    - [x] getlk\n    - [x] setlk\n\n- [x] Testing and Benchmarking\n    - [x] pjdfstest\n    - [x] fio\n\n- [x] Real-world usage\n    - [x] vim\n    - [x] emacs\n    - [x] git\n    - [x] gcc\n    - [x] rustc\n    - [x] cargo build\n    - [x] npm install\n    - [x] sqlite\n    - [x] tikv on tifs\n    - [x] client runs on FreeBSD: simple case works\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHexilee%2Ftifs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHexilee%2Ftifs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHexilee%2Ftifs/lists"}