[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-151":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":28,"readmeContent":29,"aiSummary":30,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":31,"discoverSource":32},151,"nfsdiag","lsferreira42\u002Fnfsdiag","lsferreira42","A nfs diagnostic application","",null,"C",146,4,1,0,2,19,3,2.1,false,"main",true,[24,25,26,27],"nfs","nfs-client","nfs-server","rpcbind","2026-06-12 02:00:09","# nfs-doctor\n\n`nfs-doctor` is a small command line tool written in C to help debug NFS servers from the client side.\n\nThe idea is simple: you give one IP or hostname, and the tool checks the things that usually break in NFS: network, rpcbind, NFS versions, mountd, exports, permissions, root squash, locking, stale handles and some basic performance.\n\nIt is not magic, and it will not replace a good server side analysis. But it helps a lot to understand if the problem is network, NFS config, permissions, UID\u002FGID mapping, or something more strange.\n\n---\n\n## What this tool does\n\nToday `nfs-doctor` can do these checks:\n\n- test if `rpcbind` TCP port `111` is reachable\n- test if NFS TCP port `2049` is reachable\n- query the RPC service map from rpcbind (supports IPv6 fallback)\n- detect registered NFS, mountd, lockd\u002FNLM and statd\u002FNSM services\n- test NFS v2, v3 and v4 with RPC `NULLPROC` (including v4.1 and v4.2 hints)\n- test mountd v1, v2 and v3\n- optionally test RPC over UDP with `--udp`\n- enumerate exports using mountd\n- check client prerequisite daemons (nfs-client.target, rpc.gssd, nfs-idmapd)\n- detect Kerberos tickets and configuration with `--krb5`\n- mount exports automatically under `\u002Ftmp\u002Fnfsdoctor-*`\n- try NFS v4.2 first, then fallback to v4.1, v4, and v3\n- parse and verify effective mount options from `\u002Fproc\u002Fself\u002Fmountinfo`\n- capture RPC stats (retransmissions, auth refreshes) before and after tests\n- extract deep latency metrics from `\u002Fproc\u002Fself\u002Fmountstats`\n- run filesystem checks after mount (close-to-open consistency, special files, quotas)\n- test read\u002Ftraverse permission\n- test directory listing\n- test POSIX ACLs, NFSv4 ACLs, generic xattrs, and SELinux contexts\n- test create\u002Fwrite\u002Fread\u002Ffsync when allowed (with configurable timeouts)\n- test advanced I\u002FO operations: `copy_file_range`, `fallocate`, and `O_DIRECT`\n- test advisory locks with `fcntl`\n- detect practical `root_squash` behavior\n- simulate UID\u002FGID access with `prctl` termination safety\n- simulate supplemental groups with `--groups`\n- run metadata latency test with create\u002Frename\u002Funlink\n- run stale file handle loop looking for `ESTALE`\n- check for pNFS layouts and NFSoRDMA connectivity\n- run external `fio` benchmarks alongside internal smoke tests\n- safely handle temporary files, mounts and folders using `O_NOFOLLOW`\n- perform safe audits with `--dry-run` and rate limiting (`--delay-ms`)\n- generate hierarchical JSON reports for automation\n- generate standalone HTML reports with inline CSS and Base64 (`--html`)\n- output colored text and progress bars on interactive terminals\n- run Docker fixture tests for regression checks\n\nBy default the output is compact. If you want all details, use `--verbose`.\n\n---\n\n## Important note\n\nNFS problems are very environment dependent. The result can change because of:\n\n- firewall rules\n- server export options\n- NFS version\n- kernel client state\n- UID\u002FGID mapping\n- root squash\n- ACLs\n- SELinux\u002FAppArmor on server\n- server load\n- stale file handles that only happen during real use\n\nSo, if the tool says no `ESTALE` happened, it means only that the tool did not reproduce it during the test window. It does not mean the problem can never happen.\n\n---\n\n## Build requirements\n\nOn Debian or Ubuntu:\n\n```sh\nsudo apt-get update\nsudo apt-get install -y build-essential pkg-config libtirpc-dev\n```\n\nOn Fedora\u002FRHEL style distros:\n\n```sh\nsudo dnf install -y gcc make pkgconf-pkg-config libtirpc-devel\n```\n\nFor live mount tests you also need NFS client tools.\n\nDebian or Ubuntu:\n\n```sh\nsudo apt-get install -y nfs-common\n```\n\nFedora\u002FRHEL style distros:\n\n```sh\nsudo dnf install -y nfs-utils\n```\n\n---\n\n## Build\n\nNormal build:\n\n```sh\nmake\n```\n\nClean and rebuild:\n\n```sh\nmake rebuild\n```\n\nSmall self-check:\n\n```sh\nmake check\n```\n\nInstall:\n\n```sh\nsudo make install\n```\n\nInstall in another prefix:\n\n```sh\nmake PREFIX=\u002Fopt\u002Fnfs-doctor install\n```\n\nUninstall:\n\n```sh\nsudo make uninstall\n```\n\nManual compile, if you want:\n\n```sh\ngcc -O2 -Wall -Wextra -I\u002Fusr\u002Finclude\u002Ftirpc nfsdiag.c -ltirpc -o nfsdiag\n```\n\n---\n\n## Basic usage\n\nFull diagnostic:\n\n```sh\nsudo .\u002Fnfsdiag 192.168.1.10\n```\n\nVerbose mode:\n\n```sh\nsudo .\u002Fnfsdiag --verbose 192.168.1.10\n```\n\nOnly network and RPC checks, without mounting anything:\n\n```sh\n.\u002Fnfsdiag --no-mount 192.168.1.10\n```\n\nTest only one export:\n\n```sh\nsudo .\u002Fnfsdiag --export \u002Fdata 192.168.1.10\n```\n\nPass mount options:\n\n```sh\nsudo .\u002Fnfsdiag --mount-options soft,timeo=30,retrans=2 192.168.1.10\n```\n\nDo not create\u002Fwrite test files:\n\n```sh\nsudo .\u002Fnfsdiag --read-only 192.168.1.10\n```\n\nKeep the temp folder for manual inspection:\n\n```sh\nsudo .\u002Fnfsdiag --keep-temp 192.168.1.10\n```\n\n---\n\n## Output style\n\nDefault output is clean and short. For example, in a healthy server it can be something like:\n\n```text\nnfsdiag: 192.168.0.21\n[OK] 1 export(s) discovered\nsummary: ok=13 warn=0 fail=0\n```\n\nIf you want to see all probe steps, use:\n\n```sh\n.\u002Fnfsdiag --verbose 192.168.0.21\n```\n\nWarnings and failures always appear in normal mode. Informational and low-level OK messages only appear in verbose mode.\n\n---\n\n## JSON output\n\nFor automation, use JSON.\n\nJSON to stdout, without human text mixed together:\n\n```sh\n.\u002Fnfsdiag --json 192.168.1.10\n```\n\nJSON to file, keeping stdout empty:\n\n```sh\n.\u002Fnfsdiag --json=report.json 192.168.1.10\n```\n\nThe JSON includes:\n\n- tool name\n- host\n- timestamp\n- system information (kernel, hostname, arch)\n- summary (ok, warn, fail)\n- options used\n- exports (hierarchical list of mount tests with performance metrics, ACLs, etc)\n- global events\n- recommendations\n\n---\n\n## HTML output\n\nFor human-readable reports that can be easily shared or attached to tickets, use HTML:\n\n```sh\n.\u002Fnfsdiag --html=report.html 192.168.1.10\n```\n\nThe generated HTML file is fully standalone.\n\n---\n\n## UID\u002FGID and permission tests\n\nSimulate one UID\u002FGID:\n\n```sh\nsudo .\u002Fnfsdiag --uid 1000 --gid 1000 192.168.1.10\n```\n\nSimulate more than one identity:\n\n```sh\nsudo .\u002Fnfsdiag --uid 1000 --gid 1000 --uid 65534 --gid 65534 192.168.1.10\n```\n\nSimulate supplemental groups:\n\n```sh\nsudo .\u002Fnfsdiag --uid 1000 --gid 1000 --groups 10,20,30 192.168.1.10\n```\n\nThis is useful because many NFS problems are not really NFS protocol problems. Many times it is UID, GID, groups, ACL, or root squash.\n\n---\n\n## Performance and stale handle tests\n\nChange write\u002Fread test size:\n\n```sh\nsudo .\u002Fnfsdiag --bench-bytes 167772160 192.168.1.10\n```\n\nChange metadata latency iterations:\n\n```sh\nsudo .\u002Fnfsdiag --bench-iterations 500 192.168.1.10\n```\n\nChange stale handle loop:\n\n```sh\nsudo .\u002Fnfsdiag --stale-iterations 1000 192.168.1.10\n```\n\nRun benchmarks using `fio` instead of the internal C loop (requires `fio` installed):\n\n```sh\nsudo .\u002Fnfsdiag --bench-type=fio 192.168.1.10\n```\n\nThe performance test is only a smoke test. It is not a replacement for full benchmarking, though enabling `fio` provides more accurate storage baseline metrics.\n\n---\n\n## Safety options\n\nTimeout for external commands like `mount` and `umount`:\n\n```sh\nsudo .\u002Fnfsdiag --command-timeout 15 192.168.1.10\n```\n\nDelay between testing each export (rate limiting):\n\n```sh\nsudo .\u002Fnfsdiag --delay-ms 500 192.168.1.10\n```\n\nSimulate the tool execution without actually mounting or modifying anything:\n\n```sh\n.\u002Fnfsdiag --dry-run 192.168.1.10\n```\n\nTry to isolate live mounts in a private mount namespace:\n\n```sh\nsudo .\u002Fnfsdiag --mount-namespace 192.168.1.10\n```\n\nThis needs root or `CAP_SYS_ADMIN`.\n\n---\n\n## Network\u002Fprotocol options\n\nProbe UDP RPC too:\n\n```sh\n.\u002Fnfsdiag --no-mount --udp 192.168.1.10\n```\n\nForce IPv4 direct TCP checks:\n\n```sh\n.\u002Fnfsdiag --ipv4-only --no-mount 192.168.1.10\n```\n\nForce IPv6 direct TCP checks:\n\n```sh\n.\u002Fnfsdiag --ipv6-only --no-mount nfs-server.example.com\n```\n\nDisable NFSv4 pseudo-root fallback:\n\n```sh\nsudo .\u002Fnfsdiag --no-nfs4-discovery 192.168.1.10\n```\n\nThe NFSv4 fallback is useful when the server is NFSv4-only and mountd is not available.\n\n---\n\n## Command line reference\n\n```text\nUsage: .\u002Fnfsdiag [OPTIONS] \u003Cserver-ip-or-hostname>\n\nOptions:\n  -e, --export PATH          Test only this export\n  -o, --mount-options OPTS   Extra mount options\n      --no-mount             Run network\u002FRPC checks only\n      --keep-temp            Do not remove \u002Ftmp\u002Fnfsdoctor-* after tests\n      --read-only            Do not create\u002Fwrite test files\n      --uid UID              Simulate access as UID\n      --gid GID              GID paired with last --uid\n      --groups G1,G2         Supplemental groups for simulation\n      --timeout SEC          Network\u002FRPC timeout\n      --command-timeout SEC  Timeout for mount\u002Fumount commands\n      --fs-timeout SEC       Timeout for filesystem operations in benchmarks\n      --mount-namespace      Use private mount namespace when possible\n      --json[=PATH]          Write JSON report\n      --udp                  Probe RPC over UDP too\n      --ipv4-only            Force IPv4 direct TCP checks\n      --ipv6-only            Force IPv6 direct TCP checks\n      --no-nfs4-discovery    Disable NFSv4 pseudo-root fallback\n      --krb5                 Check Kerberos prerequisites (ticket, gssd)\n      --bench-iterations N   Metadata latency iterations\n      --stale-iterations N   ESTALE loop iterations\n      --bench-bytes BYTES    Bytes used in read\u002Fwrite smoke test\n  -v, --verbose              Show detailed output\n  -h, --help                 Show help\n```\n\n---\n\n## Exit codes\n\n- `0`: no warnings or failures\n- `1`: warning or failure found\n- `2`: usage error or local runtime error\n\nWarnings return `1` because in automation they usually need attention.\n\n---\n\n## Docker fixtures\n\nThe project has Docker fixtures to reproduce bad NFS situations.\n\nList fixtures:\n\n```sh\nmake docker-list\n```\n\nBuild all fixtures:\n\n```sh\nmake docker-build-all\n```\n\nBuild one fixture:\n\n```sh\nmake docker-build-read-only-export\n```\n\nRun automated fixture tests:\n\n```sh\nmake test-fixtures\n```\n\nRun only one test:\n\n```sh\nmake test-fixture-rpcbind-unreachable\n```\n\nSome tests need root because they do real NFS mounts from the host. If the host cannot run kernel NFS inside Docker, the test runner skips those cases instead of failing everything.\n\nThe current fixture set includes:\n\n- `rpcbind-unreachable`\n- `nfs-port-unreachable`\n- `rpc-map-missing-nfs`\n- `mountd-unavailable`\n- `empty-exports`\n- `mount-denied`\n- `permission-denied`\n- `acl-unsupported`\n- `identity-denied`\n- `read-only-export`\n- `root-squash`\n- `locking-missing`\n- `stale-handle`\n- `slow-performance`\n\n---\n\n## What was added in the last big update\n\nThis version has these improvements:\n\n1. fully modular C architecture\n2. hierarchical per-export JSON output\n3. timeouts for filesystem operations (`--fs-timeout`)\n4. robust FD leak prevention and `poll()` migration\n5. deep metrics via `\u002Fproc\u002Fself\u002Fmountstats` and `mountinfo`\n6. RPC stats monitoring (`\u002Fproc\u002Fnet\u002Frpc\u002Fnfs`) for retransmissions\n7. client daemon prerequisite checks (`rpcbind`, `nfs-client.target`, `idmapd`)\n8. Kerberos detection and support (`--krb5`, `gssd` checks)\n9. NFSv4 ACL detection (`system.nfs4_acl`)\n10. NFSv4.1 and NFSv4.2 cascading mount support\n11. real IPv6 RPC support\n\n---\n\n## Security notes\n\nBe careful when running against production exports.\n\nBy default the tool may create hidden `.nfsdoctor-*` files to test write\u002Fread behavior. If you do not want this, use:\n\n```sh\n--read-only\n```\n\nAlso, UID\u002FGID simulation requires root because the tool uses `setgid`, `setgroups`, and `setuid` in child processes.\n\n---\n\n## Limitations\n\nSome things are impossible to guarantee from the client side:\n\n- `ESTALE` only appears if the handle becomes stale during the test\n- SELinux\u002FAppArmor problems can look only like generic permission denied\n- ACL info depends on what the NFS client exposes\n- performance numbers are only smoke-test values\n- Docker NFS fixtures depend on host kernel and Docker privileges\n\nSo use this tool as a fast diagnostic helper, not as the only source of truth.\n","nfs-doctor 是一个用 C 语言编写的命令行工具，旨在从客户端角度帮助调试 NFS 服务器问题。其核心功能包括检测 rpcbind 和 NFS 端口可达性、查询 RPC 服务映射、测试不同版本的 NFS 和 mountd、验证权限与 UID\u002FGID 映射、以及执行一系列文件系统操作如读写权限、POSIX ACLs、NFSv4 ACLs 等，并支持生成 JSON 或 HTML 格式的报告。该工具适用于当遇到 NFS 挂载或访问问题时，快速定位故障原因是否在于网络连接、NFS 配置错误、权限设置不当或其他更复杂的情况，但请注意它不能替代全面的服务器端分析。","2026-06-11 02:31:06","CREATED_QUERY"]