{"id":21884088,"url":"https://github.com/leiless/bsd_kext_log","last_synced_at":"2025-07-18T17:36:01.733Z","repository":{"id":140254872,"uuid":"181263680","full_name":"leiless/bsd_kext_log","owner":"leiless","description":"Experimental kext logging propagation from kernel into user space","archived":false,"fork":false,"pushed_at":"2020-01-06T03:51:27.000Z","size":86,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-14T15:54:51.477Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leiless.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":"2019-04-14T05:17:43.000Z","updated_at":"2023-11-10T23:54:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"c0cafb8c-2912-4803-9618-239ce88e733f","html_url":"https://github.com/leiless/bsd_kext_log","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/leiless/bsd_kext_log","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2Fbsd_kext_log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2Fbsd_kext_log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2Fbsd_kext_log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2Fbsd_kext_log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leiless","download_url":"https://codeload.github.com/leiless/bsd_kext_log/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leiless%2Fbsd_kext_log/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265802053,"owners_count":23830508,"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-11-28T10:12:15.989Z","updated_at":"2025-07-18T17:36:01.701Z","avatar_url":"https://github.com/leiless.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"## bsd\\_kext\\_log\n\n`bsd_kext_log` is a macOS kernel extension used for experimental kext logging propagation from kernel into user space.\n\n### Rationale\n\nOne can use [log(1)](x-man-page://1/log)/[syslog(1)](x-man-page://1/syslog) to capture log from kernel, just as [kextlogd](https://github.com/lynnlx/kextlogd) do.  Yet due to kext cache mechanism, new logging system [log(1)](x-man-page://1/log) may capture nothing while the kext was indeed issued a log via [printf](http://xr.anadoxin.org/source/xref/macos-10.13.6-highsierra/xnu-4570.71.2/osfmk/kern/printf.c#853) or [IOLog](http://xr.anadoxin.org/source/xref/macos-10.13.6-highsierra/xnu-4570.71.2/iokit/Kernel/IOLib.cpp#1152).\n\nThusly this kernel extension tries to fix this flaw by introducing a simple in-kernel logging mechanism, which it uses [kernel control socket](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/NKEConceptual/control/control.html) to communicate with user space log-daemon client, and pushing messages to it(daemon).\n\nSo user space daemon can do bottom-half work like print the log, persist into disk, etc.\n\nThis logging technique inspired by Microsoft's [VFS for Git](https://github.com/Microsoft/VFSForGit)(ProjFS.Mac), yet they use [IOSharedDataQueue](http://xr.anadoxin.org/source/xref/macos-10.13.6-highsierra/xnu-4570.71.2/iokit/IOKit/IOSharedDataQueue.h#55) for messaging propagation, which is part of [`IOKit` environment](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/Architecture/Architecture.html#//apple_ref/doc/uid/TP30000905-CH1g-TPXREF102), unavailable for BSD portion.\n\n### Log interface\n\nThere're essentially five log levels:\n\n* TRACE - (Log call path, massive logs, logging persistence is optional)\n\n* DEBUG - (Used for debugging purpose, will print nothing in release build)\n\n* INFO - (Usual info, should always persist into disk)\n\n* WARNING - (Used for negligible errors)\n\n* ERROR - (For significant errors should be take care of)\n\nLogging function:\n\n```c\nvoid log_printf(uint32_t, const char *, ...) __printflike(2, 3);\n```\n\nwhich the first parameter indicates the log level, there're already candy wrappers for each levels:\n\n```c\nlog_trace(fmt, ...);\nlog_debug(fmt, ...)\nlog_info(fmt, ...);\nlog_warning(fmt, ...);\nlog_error(fmt, ...);\n```\n\n### Build\n\nYou must install Apple's [Command Line Tools](https://developer.apple.com/download/more) as a minimal build environment, or Xcode as a full build environment in App Store.\n\n#### Kernel extension\n\n```shell\n# cd into repository home\ncd bsd_kext_log\n\n# Default target is debug\nmake [release]\n```\n\n#### User space log daemon\n\n```shell\ncd bsd_kext_log/daemon\n\n# Default target is debug\nmake [release]\n```\n\n### Test\n\nAfter you compiled kext and daemon, you can load kext and run daemon to capture kernel messages.\n\nCurrently user space log daemon implementation is trivial, it only print logs directly into tty. Log persistence not yet implemented, we leave it to developers.\n\nSample way to test it:\n\n```shell\ncd bsd_kext_log\nmake\nsudo cp -r bsd_kext_log.kext /tmp\n\nsudo kextload -v 6 /tmp/bsd_kext_log.kext\n\ncd daemon\nmake\n./kextlog_daemon-debug\n```\n\nYou'll see massive logs from KAuth subsystem, this experimental kext listen to several [KAuth scopes](https://developer.apple.com/library/archive/technotes/tn2127/_index.html) and push their logs into user space.\n\nTo stop the test, you should firstly terminate the daemon, and [kextunload(8)](x-man-page://8/kextunload) the kext.\n\n### Caveats\n\n* User space read buffer should over commit to kctl's `ctl_recvsize` so it can handle massive logs from kernel at one time.\n\n* User space log handling should fast enough, since kernel messages will continue to push while user space not yet read.\n\n\tYou may alternatively use two threads, one for read, the other to handle.\n\n* The kctl accepts at most one client at a time, you need further effort to support multi-client(make nonsense?)\n\n* When `log_printf` cannot push messages into user space daemon(like no user space client, client's buffer is full, kernel malloc failed, etc.), it'll instead print the log directly into system message buffer via [printf](http://xr.anadoxin.org/source/xref/macos-10.13.6-highsierra/xnu-4570.71.2/osfmk/kern/printf.c#853)(last possible resort).\n\n### TODO\n\n* Add `sysctl` entries for logging diagnostic/statistic purposes.\n\n* Turn kctl's socket type into `SOCK_STREAM`, and test again.\n\n* Test on other macOS versions.\n\n### Contributing\n\nFeel free to contribute this repository in any fashion.\n\nCurrently this kext tested under macOS 10.13.6(17G65) in a heavy file system event load, yet no warranty, use as your own risk!\n\n### License\n\nSee [`LICENSE`](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleiless%2Fbsd_kext_log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleiless%2Fbsd_kext_log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleiless%2Fbsd_kext_log/lists"}