{"id":13647731,"url":"https://github.com/cbreak-black/ZetaWatch","last_synced_at":"2025-04-22T02:32:45.036Z","repository":{"id":47146609,"uuid":"48544399","full_name":"cbreak-black/ZetaWatch","owner":"cbreak-black","description":"ZFS OSX Menu Bar widget","archived":false,"fork":false,"pushed_at":"2025-01-05T10:48:20.000Z","size":3073,"stargazers_count":145,"open_issues_count":7,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-05T11:27:56.975Z","etag":null,"topics":["gui","mac","zfs","zfs-interaction"],"latest_commit_sha":null,"homepage":null,"language":"Objective-C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbreak-black.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2015-12-24T13:48:00.000Z","updated_at":"2025-01-05T10:48:24.000Z","dependencies_parsed_at":"2024-11-09T21:32:07.754Z","dependency_job_id":"1ceff642-3fbd-40b4-bcdc-70491844fd24","html_url":"https://github.com/cbreak-black/ZetaWatch","commit_stats":null,"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbreak-black%2FZetaWatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbreak-black%2FZetaWatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbreak-black%2FZetaWatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbreak-black%2FZetaWatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbreak-black","download_url":"https://codeload.github.com/cbreak-black/ZetaWatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250163782,"owners_count":21385314,"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":["gui","mac","zfs","zfs-interaction"],"created_at":"2024-08-02T01:03:44.849Z","updated_at":"2025-04-22T02:32:44.374Z","avatar_url":"https://github.com/cbreak-black.png","language":"Objective-C++","funding_links":[],"categories":["Objective-C++","System Status","How to Use OpenZFS on macOS (ZFS on Mac)"],"sub_categories":["Local System Status","ZFS other tools"],"readme":"ZetaWatch\n=========\n\n![ZetaWatch displaying pool status and filesystems][ZFSImage]\n\nZetaWatch is a small OS X program that displays the zfs status in the menu bar, similar to\nwhat iStat Menus does for other information. It is fairly well tested, but due to the\ncurrent state of libzfs and libzfs_core, changes will be required until the API\nstabilizes. ZetaWatch is usually compiled for the latest available [ZFS release for Mac\nOS](https://openzfsonosx.org/), and might not be compatible with other releases.\n\nCurrently supported features are:\n\n * Show pool, vdev, filesystem stats\n * Show pool / filesystem properties\n * Start, stop, pause scrubs, and monitor their progress.\n * Import and Export pools manually, or auto-import when they become available\n * Mount / unmount datasets manually or at pool import automatically\n * Load/Unload encryption keys for encrypted datasets manually or automatically\n * Optionally store pass phrases in the Mac OS X Keychain\n * Create, Display, Delete, Clone Snapshots or roll back to them\n * Report errors in notification center when they are discovered\n\n\nInstallation\n------------\n\nZetaWatch Releases can be downloaded from the [GitHub Releases Page](https://github.com/cbreak-black/ZetaWatch/releases).\nPlease verify that the Version of ZetaWatch matches your ZFS Version. Usually,\nonly the newest official Release is supported, since code changes are sometimes\nrequired to be fully compatible with the new library version.\n\nZetaWatch does not require manual installation. Simply copy it into /Application or where\never else it fits. The bundled helper tool gets installed automatically the first time the\nprogram is started. This requires user-authentication.\n\nZetaWatch supports auto updates, if enabled.\n\n\nFor Developers\n==============\n\nZFS Interaction\n---------------\n\nZetaWatch communicates with zfs using `libzfs.dylib`, `libzfs_core.dylib` ,\n`libzpool.dylib` and `libnvpair.dylib`, just like the command line tools do. This gives\nit all the flexibility of the command line tools, at the cost of having to reimplement\nfunctionality that is found in the tools and not the library. And since the libraries are\nexplicitly not meant to provide a stable ABI, ZetaWatch is also closely coupled to the\nZFS version it is built and written for.\n\nAll the ZFS interaction is wrapped in the ZFSWrapper library. This C++ library isolates\nthe issues mentioned above and provides a more convenient and safe API than the original\nC interface does. The library is used both by the helper tool and the frontend app. This\nis the most reusable part of ZetaWatch, and might be split out as separate project later.\n\n * *ZFSUtils* contains most of the advanced functionality, such as C++ Wrappers around the\nlibrary, pool, vdev or file system handles. Those classes also have functionality to query\nstate and iterate over members.\n * *ZFSNVList* provides a wrapper around the `nvpair_t` / `nvlist_t` data structure that\nis used in ZFS for a lot of userland / kernel communication. It manages resources in both\nowning and non-owning fashion, and allows for easier iteration over sequences.\n * *ZFSStrings* translate ZFS status enums into the user facing emoji or string\ndescription, optionally with localization. (Localization is not well tested or supported\nat the moment.)\n\n\nHelper Tool\n-----------\n\nThe implementation of the helper tool follows apple's [EvenBetterAuthorizationSample].\n\nThe helper tool communicates with the user application via `AuthorizationService` and\n`NSXPCConnection`. The application side of code for this is in `ZetaAuthorization.m`. The\nRPC protocol can be found in `ZetaAuthorizationHelperProtocol.h`, and is implemented in\n`ZetaAuthorizationHelper.mm`. The `CommonAuthorization.m` file contains the supported\ncommands and associated default permissions.\n\nThe helper tool can be uninstalled with the `uninstall-helper.sh` script. This is useful\nfor debugging the installation of the helper, or updating the helper without increasing\nthe bundle version.\n\n\nAuthorization\n-------------\n\nThe ZetaWatch helper tool uses the Security framework to authorize users before performing\nprivileged operations. It currently supports the following permissions.\n\n * `net.the-color-black.ZetaWatch.import`, allowed by default, required for importing a pool.\n * `net.the-color-black.ZetaWatch.export`, allowed by default, required for exporting a pool.\n * `net.the-color-black.ZetaWatch.mount`, allowed by default, required for mounting a dataset.\n * `net.the-color-black.ZetaWatch.unmount`, allowed by default, required for unmounting a\n dataset.\n * `net.the-color-black.ZetaWatch.snapshot`, allowed by default, required for creating a\n snapshot.\n * `net.the-color-black.ZetaWatch.rollback`, requires admin authentication by default,\nrequired for rolling back a filesystem.\n * `net.the-color-black.ZetaWatch.clone`, requires admin authentication by default,\nrequired for cloning a filesystem.\n * `net.the-color-black.ZetaWatch.create`, requires admin authentication by default,\nrequired for creating a new filesystem.\n * `net.the-color-black.ZetaWatch.destroy`, requires admin authentication by default,\nrequired for destroying a filesystem or snapshot.\n * `net.the-color-black.ZetaWatch.key`, allowed by default, required for loading or\nunloading a key for a dataset. This also includes the ability to auto mount / unmount them.\n * `net.the-color-black.ZetaWatch.scrub`, allowed by default, required for starting,\nstopping or pausing scrubs.\n\nThese permissions can be manipulated via the `security` command line program. To inspect\nthe current dataset creation permissions, and switching it to allow this to all users:\n\n```\nsecurity authorizationdb read net.the-color-black.ZetaWatch.create\nsecurity authorizationdb write net.the-color-black.ZetaWatch.create allow\n```\n\nPermissions include `allow`, `deny` or `authenticate-admin`.\n\nMore detailed information about this topic can be found in the article apples documentation\nabout [AuthorizationServices] and [Managing the Authorization Database in OS X Mavericks].\n\n\nSecurity \u0026 Code Signing\n-----------------------\n\nOfficial release builds are signed and notarized, and should run without issues even on\nnewer Mac OS X. But there are still issues with authentication reported with the program\nnot being recognized as signed. To verify security manually, the following commands can\nbe used:\n\n```bash\ncodesign -v -v -d ZetaWatch.app\nxcrun stapler validate -v ZetaWatch.app\n```\n\nBuilding ZetaWatch requires an apple developer account with DeveloperID signing\ncapabilities, since it uses [`SMJobBless`] to run a helper service as root. This service\nexecutes actions on behalf of the user, such as mounting, unmounting or loading a key.\n[Notarization] is required to create binaries that can be run without without warning on\nthe newest Mac OS X.\n\n\nSelf Updating\n-------------\n\nThe self-updating uses [SparkleFramework]. Since the newest released sparkle does not yet\nsupport hardened runtime, it needs to be compiled manually. Building the \"Distribution\"\ntarget in the Sparkle submodule in release mode is sufficient.\nThe sparkle submodule contains a version that is slimmed down by removing most languages,\nwhich saves space. Since ZetaWatch is not localized, this is not a problem.\nTo create a working fork, adjust the public key and update url in the Info.plist file.\n\n\nZFS Binary Compatibility\n------------------------\n\nSince ZetaWatch directly links to the zfs libraries, it only works if those are\ncompatible. And while Sparkle has built-in support for OS compatibility checking, it\ndoesn't have the same for other dependencies. There is support for custom appcast\nfiltering, to select a suitable version, but since the ZFS version and the ZetaWatch\nversion are kind of orthogonal, this didn't seem fitting.\n\nThe chosen solution was to have a ZFS version specific appcast URL, and make ZetaWatch\nquery the appropriate appcast. This allows updating ZetaWatch when the used ZFS version\nchanges, but also have several supported parallel builds. Currently, the only supported\nZFS version is 1.9.\n\n\nLicense\n=======\n\nThis program is copyrighted by me, because I wrote it.\nThis program is licensed under the \"3-clause BSD\" License. See the LICENSE.md file for\ndetails.\n\n[EvenBetterAuthorizationSample]: https://developer.apple.com/library/content/samplecode/EvenBetterAuthorizationSample/Introduction/Intro.html\n[`SMJobBless`]: https://developer.apple.com/documentation/servicemanagement/1431078-smjobbless?language=objc\n[Notarization]: https://developer.apple.com/documentation/security/notarizing_your_app_before_distribution?language=objc\n[ZFSImage]: https://raw.githubusercontent.com/cbreak-black/ZetaWatch/master/doc/ZetaWatch.jpg\n[SparkleFramework]: https://sparkle-project.org/\n[SparkleGithub]: https://github.com/sparkle-project/Sparkle\n[AuthorizationServices]: https://developer.apple.com/documentation/security/authorization_services?language=objc\n[Managing the Authorization Database in OS X Mavericks]: https://derflounder.wordpress.com/2014/02/16/managing-the-authorization-database-in-os-x-mavericks/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbreak-black%2FZetaWatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbreak-black%2FZetaWatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbreak-black%2FZetaWatch/lists"}