{"id":24995318,"url":"https://github.com/launchplatform/oci-hooks-mount-chown","last_synced_at":"2025-03-29T14:43:51.459Z","repository":{"id":176407961,"uuid":"657766035","full_name":"LaunchPlatform/oci-hooks-mount-chown","owner":"LaunchPlatform","description":"An OCI hook for changing owner for a mount point","archived":false,"fork":false,"pushed_at":"2023-06-24T23:08:33.000Z","size":83,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-04T15:47:27.016Z","etag":null,"topics":["containers","oci-hook"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LaunchPlatform.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":"2023-06-23T19:57:13.000Z","updated_at":"2023-08-23T07:59:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"7947dd08-3bf9-4329-b8c6-cc164a0aa07b","html_url":"https://github.com/LaunchPlatform/oci-hooks-mount-chown","commit_stats":null,"previous_names":["launchplatform/oci-hooks-mount-chown"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-mount-chown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-mount-chown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-mount-chown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-mount-chown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LaunchPlatform","download_url":"https://codeload.github.com/LaunchPlatform/oci-hooks-mount-chown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246200300,"owners_count":20739563,"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":["containers","oci-hook"],"created_at":"2025-02-04T15:35:10.524Z","updated_at":"2025-03-29T14:43:51.446Z","avatar_url":"https://github.com/LaunchPlatform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oci-hooks-mount-chown\nAn OCI hook for changing owner for a mount point\n\n# Why\n\nSome container runtime tools like podman allows you to mount image but it doesn't provide an option to change the owner of the mounted file system.\nAs a result, this limits what you can do with the mounted volume.\nA podman issue ([#18986](https://github.com/containers/podman/issues/18986)) has been opened for this particular need.\nBefore that issue is closed, or say if one needs to chown for any mount point inside a container, this hook comes hady.\n\n# How\n\nTo use this hook for changing the own of a mount point, there are a few special annotations you can add to the container:\n\n- com.launchplatform.oci-hooks.mount-chown.**\u0026lt;NAME\u0026gt;**.path\n- com.launchplatform.oci-hooks.mount-chown.**\u0026lt;NAME\u0026gt;**.owner\n- com.launchplatform.oci-hooks.mount-chown.**\u0026lt;NAME\u0026gt;**.policy\n- com.launchplatform.oci-hooks.mount-chown.**\u0026lt;NAME\u0026gt;**.mode\n\nThe `NAME` can be any valid annotation string without a dot in it.\nThe `path` and `owner` annotations with the same name need to appear in pairs, otherwise it will be ignored.\nThe owner value can be a single uid integer value or uid plus gid, with a format like `UID[:GID]`.\nPlease note that username is not supported, only integer value works.\nThe `policy` annoation is optional, there are two available options:\n\n- `recursive` - chown recursively (default)\n- `root-only` - chown only for the root folder of mount-pooint\n\nIf the policy value is not provided, `recursive` will be used by default.\nWith these annotations, to change owner of a path, here's an example of podman command you can run:\n\n```bash\npodman run \\\n    --user 2000:2000 \\\n    --annotation=com.launchplatform.oci-hooks.mount-chown.data.path=/data \\\n    --annotation=com.launchplatform.oci-hooks.mount-chown.data.owner=2000:2000 \\\n    --annotation=com.launchplatform.oci-hooks.mount-chown.data.policy=root-only \\\n    --mount type=image,source=my-data-image,destination=/data,rw=true \\\n    -it alpine\n# Now you can write to the root folder of the image mount\ntouch /data/my-data.lock\n```\n\nThe `mode` option can also be used. However, please note that it only changes the mode of root path, it doesn't apply recursively regardless what the `policy` says.\nEither one of `owner` or `mode` needs to be provided.\nFor now podman's image mount comes with `0555` as the root folder, without changing the owner, changing the mode to `0777` might help.\nHere's an example:\n\n```bash\npodman run \\\n    --user 2000:2000 \\\n    --annotation=com.launchplatform.oci-hooks.mount-chown.data.path=/data \\\n    --annotation=com.launchplatform.oci-hooks.mount-chown.data.mode=777 \\\n    --mount type=image,source=my-data-image,destination=/data,rw=true \\\n    -it alpine\n# Now you can write to the root folder of the image mount\ntouch /data/my-data.lock\n```\n\n## Add createContainer hook directly in the OCI spec\n\nThere are different ways of running a container, if you are generating OCI spec yourself and running OCI runtimes such as [crun](https://github.com/containers/crun) yourself, you can add the `createContainer` hook directly into the spec file like this:\n\n```json\n{\n  \"//\": \"... other OCI spec content ...\",\n  \"hooks\": {\n    \"createContainer\": [\n      {\n        \"path\": \"/usr/bin/mount_chown\"\n      }\n    ]\n  }\n}\n```\n\nFor more information about the OCI spec schema, please see the [document here](https://github.com/opencontainers/runtime-spec/blob/48415de180cf7d5168ca53a5aa27b6fcec8e4d81/config.md#posix-platform-hooks).\n\n## Add OCI hook config\n\nAnother way to add the OCI hook is to create a OCI hook config file.\nHere's an example:\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"hook\": {\n    \"path\": \"/usr/bin/mount_chown\"\n  },\n  \"when\": {\n    \"annotations\": {\n        \"com\\\\.launchplatform\\\\.oci-hooks\\\\.mount-chown\\\\.([^.]+)\\\\.path\": \"(.+)\"\n    }\n  },\n  \"stages\": [\"createContainer\"]\n}\n```\n\nFor more information about the OCI hooks schema, please see the [document here](https://github.com/containers/podman/blob/v3.4.7/pkg/hooks/docs/oci-hooks.5.md).\n\n# Debug\n\nTo debug the hook, you can add `--log-level=debug` (or `trace` if you need more details) argument for the `archive_overlay` executable, it will print debug information.\nWith OCI runtimes like [crun](https://github.com/containers/crun), you can also add an annotation like this:\n\n```\nrun.oci.hooks.stderr=/path/to/stderr\n```\n\nto make the runtime redirect the stderr from the hook executable to specific file.\nPlease note that podman invokes poststop hook instead of delegating it to crun, so the annotation won't work for podman.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchplatform%2Foci-hooks-mount-chown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchplatform%2Foci-hooks-mount-chown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchplatform%2Foci-hooks-mount-chown/lists"}