{"id":19168415,"url":"https://github.com/bloomberg/userchroot","last_synced_at":"2025-08-07T21:12:56.203Z","repository":{"id":66125214,"uuid":"46010451","full_name":"bloomberg/userchroot","owner":"bloomberg","description":"A tool to allow controlled access to 'chroot' functionality by users without root permissions","archived":false,"fork":false,"pushed_at":"2020-07-01T18:43:38.000Z","size":71,"stargazers_count":19,"open_issues_count":3,"forks_count":20,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-02T07:39:09.044Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.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":"2015-11-11T21:18:35.000Z","updated_at":"2025-03-07T01:29:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"67423f94-a41b-4831-8c5b-c84be4e0292a","html_url":"https://github.com/bloomberg/userchroot","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bloomberg/userchroot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fuserchroot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fuserchroot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fuserchroot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fuserchroot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/userchroot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fuserchroot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269324732,"owners_count":24398048,"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","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-09T09:42:35.746Z","updated_at":"2025-08-07T21:12:56.153Z","avatar_url":"https://github.com/bloomberg.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# userchroot - Allow regular users to invoke a chroot'd processes\n\n`userchroot` is used heavily by the\n[`buildbox`](https://buildgrid.gitlab.io/buildbox/buildbox-home/) ecosystem to\nprovide a simple and lightweight build sandbox.  Therefore, primary maintenance\nof `userchroot` now takes place over at\n[buildbox/userchroot](https://gitlab.com/BuildGrid/buildbox/userchroot). This\nrepo will soon be archived.\n\n## Purpose\n\nThe [chroot(2)](https://pubs.opengroup.org/onlinepubs/7908799/xsh/chroot.html) system call can be used to\nprovide a restricted or new view onto an existing filesystem and thus has\napplications in build sandboxing. Normally it can only be invoked by an\nappropriately privileged user possessing the necessary capabilities or\nprivileges. `userchroot` allows you to safely workaround that limitation,\nprovided it can be installed and configured by a user with the requisite\npower. `userchroot` allows you to create pre-defined chroot locations and allow\nunprivileged users to safely run processes within those predefined\nenvironments.\n\nWe use it at Bloomberg to allow non-privileged users to run builds on a\nchroot'd environment on Linux x86_64, Solaris sparc, and AIX powerpc. This\nprovides sandboxing and consistent repeatability to builds across those\nplatforms.\n\nIt is similar to [schroot](https://wiki.debian.org/Schroot) and\n[bubblewrap](https://github.com/containers/bubblewrap).\n\n## Fundamental Devices\n\nThere are some devices that so many processes expect to exist, that when\nprovisioning ephemeral chroot locations as a non-privileged user you may need\nto make available. Those devices are:\n\n * /dev/zero\n * /dev/random\n * /dev/urandom\n * /dev/null\n * /dev/poll (Solaris only)\n * /dev/shm (Linux only)\n\nThe userchroot command offers a \"--install-devices\" and \"--uninstall-devices\"\nthat will allow a non-privileged user to create and destroy those devices.\n\nThis allow us to run the entire build infrastructure as a non-privileged user.\n\n# How to build\n\nThere is very little build-time customization, so we provide a simple Makefile\nthat will use the implicit rules in order to build the executable.\n\n```\nmake\n```\n\n# Compile-time settings\n\n## PREFIX\n\nThis variables (defaults to `/usr/local`) controls the default base path to the\nCONFIGFILE.\n\n## CONFIGFILE\n\nThis variable (defaults to `/etc/userchroot.conf`) will set the path for the\nconfig file.\n\nThis tool will check for the config file in two places:\n* `$(PREFIX)/etc/userchroot.conf`\n* `/etc/userchroot.conf`\n\n`$(PREFIX)` defaults to `bldroot` in the Makefile.\n\nThe tool will verify that the file as well as the entire path leading to the\nfile is root owned, has limited permissions and is not a symbolic link.\n\n## VERSIONSTRING\n\nThis variable (defaults to an ident string created with `git describe\n--tags`). This will be stored in a static string in the executable for\nidentifying the version with `ident`.\n\n# Conditional compilations\n\n## `_HAVE_CLEARENV`\n\nWe include a compat implementation of clearenv for architectures where that\nsystem call is not available. This is evaluated by the makefile by using the\ntest-clearenv.sh script.\n\n## `_USE_MOUNT_LOFS_INSTEAD_OF_MKNOD`\n\nWhen running inside a Solaris zone, you will not be allowed to use mknod. As an\nalternative, the tool will allow you to use a lofs mount to the system location\nfor the fundamental devices.\n\n## `__linux__`\n\nOn Linux we also create /dev/shm and mount it as a tmpfs, since the GNU Libc\nwill not only expect that location to exist, but it will also check that it is\nactually a tmpfs location. Without this, named pipes do not work on Linux.\n\n## `__sun`\n\nOn Solaris, we mount the kernel poll device at /dev/poll. This is a\nSolaris-only replacement for `select` and `poll`.\n\n# How to install\n\nThe executable needs to be setuid root, but it must *not* be setgid root. In\nfact, it will validate that you haven't given too much permissions to it.\n\n# How to use\n\nThe config file must have the a path to a pre-approved chroot directory and the\nname of the user that owns that directory. In the format:\n\n```\nuser:/path/to/userchroot/base\n```\n\nThen any user will be able to run\n\n```\nuserchroot /path/to/userchroot/base/myimage some command\n```\n\nAs well as:\n\n```\nuserchroot /path/to/userchroot/base/myimage --install-devices\n```\n\nor\n\n```\nuserchroot /path/to/userchroot/base/myimage --uninstall-devices\n```\n\nAs long as:\n\n * The entire path leading to /path/to/userchroot is owned by root and\n   doesn't have open permissions.\n * The directory /path/to/userchroot/base is owned by the configured\n   user and doesn't have open permissions.\n * The directory /path/to/userchroot/base/myimage is owned by the\n   configured user and doesn't have open permissions.\n\nThis will result on ```some command``` being invoked after performing\nthe chroot to the location and dropping the privileges back to the\ncalling user.\n\n# Copyright statement\n\n\n```\n// ----------------------------------------------------------------------------\n// Copyright 2015 Bloomberg Finance L.P.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n// ----------------------------- END-OF-FILE ----------------------------------\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fuserchroot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fuserchroot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fuserchroot/lists"}