{"id":13446724,"url":"https://github.com/theAkito/sue","last_synced_at":"2025-03-21T16:32:46.185Z","repository":{"id":150541543,"uuid":"300993405","full_name":"theAkito/sue","owner":"theAkito","description":"As small and swift as su-exec, but as featureful and robust as gosu!","archived":false,"fork":false,"pushed_at":"2022-04-26T21:10:24.000Z","size":52,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-05T12:13:16.194Z","etag":null,"topics":["docker","linux","nim","permissions"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theAkito.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}},"created_at":"2020-10-03T22:29:17.000Z","updated_at":"2024-10-11T18:26:22.000Z","dependencies_parsed_at":"2023-04-19T05:18:16.620Z","dependency_job_id":null,"html_url":"https://github.com/theAkito/sue","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theAkito%2Fsue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theAkito%2Fsue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theAkito%2Fsue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theAkito%2Fsue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theAkito","download_url":"https://codeload.github.com/theAkito/sue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244829609,"owners_count":20517342,"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":["docker","linux","nim","permissions"],"created_at":"2024-07-31T05:00:58.169Z","updated_at":"2025-03-21T16:32:45.897Z","avatar_url":"https://github.com/theAkito.png","language":"Nim","readme":"[![nimble](https://raw.githubusercontent.com/yglukhov/nimble-tag/master/nimble.png)](https://nimble.directory/pkg/sue)\n\n[![Source](https://img.shields.io/badge/project-source-2a2f33?style=plastic)](https://github.com/theAkito/sue)\n[![Language](https://img.shields.io/badge/language-Nim-orange.svg?style=plastic)](https://nim-lang.org/)\n\n![Last Commit](https://img.shields.io/github/last-commit/theAkito/sue?style=plastic)\n\n[![GitHub](https://img.shields.io/badge/license-GPL--3.0-informational?style=plastic)](https://www.gnu.org/licenses/gpl-3.0.txt)\n[![Liberapay patrons](https://img.shields.io/liberapay/patrons/Akito?style=plastic)](https://liberapay.com/Akito/)\n\n## What\nExecutes a program as a user different from the user running `sue`. The target program is `exec`'ed which means, that it replaces the `sue` process you are using to run the target program. This simulates native tools like `su` and `sudo` and uses the same low-level POSIX tools to achieve that, but eliminates common issues that usually arise, when using those native tools.\n\n## Why\nAs small and swift as `su-exec`, but as featureful and robust as `gosu`!\n\nThis and its alternatives all exist for pretty much the same core reason:\n\n\u003eThis is a simple tool grown out of the simple fact that `su` and `sudo` have very strange and often annoying TTY and signal-forwarding behavior.  They're also somewhat complex to setup and use (especially in the case of `sudo`), which allows for a great deal of expressivity, but falls flat if all you need is \"run this specific application as this specific user and get out of the pipeline\".\n\n[Source](https://github.com/tianon/gosu/blob/master/README.md)\n\n### Why use `sue` instead of `su-exec`, `gosu` or other alternatives?\nAn opinionated comparison!\n\n**Better than `gosu` in these ways:**\n\n`gosu` is written in Go, which is comparatively slow and bloated compared to other systems programming languages. `sue` is written in [Nim](https://nim-lang.org/), which is comparable to C in terms of performance and size, while being actually maintainable \u0026 readable.\n\n**Better than `su-exec` in these ways:**\n\n`su-exec` is supposed to be a far more lightweight alternative to `gosu`. As an example, the official Debian-based `postgres` images use `gosu` while the Alpine-based images use `su-exec`.\nThe latter is written in C, meaning that the level of maintainability is kept pretty low. It also is focused entirely on size and less on providing every feature of `gosu` in a more compact fashion. `gosu` has a stricter and much more robust behaviour, than `su-exec`.\n\n`sue` is on the other hand covering all `gosu` test cases, meaning that it provides precisely the same feature set as `gosu` while being only half the size and most likely being also more performant overall.\n\n**Better than `chroot` in these ways:**\n\n`chroot` is a bit clunky and not as straight-forward to use. For the use-case of the specific privilege management in Docker environments, this tool is not well suited, as it has originally a different overall purpose.\n\n**Better than `setpriv` in these ways:**\n\nSimilar to `chroot`, `setpriv` feels very clunky and you have to provide so much information explicitly, when it could be so much more straight-forward and easy to use, as is `gosu`, `su-exec` or `sue`.\n\n## How\nFirst, make sure you are running `sue` as the `root` user, to avoid permission issues.\n\nGet the project and prepare it:\n```\ngit clone https://github.com/theAkito/sue.git\ncd sue\nnimble configure\n```\nTo build the project use one of the predefined tasks:\n```\nnimble fbuild\n```\nfor the release build or\n```\nnimble dbuild\n```\nfor the debug/development build.\n\nYou can also make a quick test if `sue` works, as it should:\n```\nnimble test\n```\nRun the fully fledged test suite, covering a large amount of edge cases and possible flukes:\n```\nnimble xtest\n```\nThis test suite covers all original [`gosu` test cases](https://github.com/tianon/gosu/blob/master/Dockerfile.test-alpine). Since all are passed successfully, we achieve full compatability with `gosu`'s behaviour.\n____\n\nThe first argument passed to `sue` is the *user-spec* with either the username or its `id`. Appending a `group` to the *user-spec* is optional.\n\nThe following examples assume a user named *dunwall*, belonging to a group of the same name and `id`.\n\nExample 1:\n```bash\n./sue dunwall src/test\n```\nExample 2:\n```bash\n./sue dunwall:dunwall src/test\n```\nExample 3:\n```bash\n./sue 1000:dunwall src/test\n```\n\n## Where\nThis tool is meant to be used in a Docker environment, as a way to execute a program while temporarily switching the user just for running that process, as some need to be run as a specific user or need a designated user for taking over a user role in that program.\n\n### Real world example\n\nThe following example is taken from the official `postgres:13-alpine` Docker image's `docker-entrypoint.sh` script, where `su-exec` is used to execute this startup script as the `postgres` user, since PostgreSQL should be operated by the `postgres` user.\n\n```bash\n\tif [ \"$1\" = 'postgres' ] \u0026\u0026 ! _pg_want_help \"$@\"; then\n\t\tdocker_setup_env\n\t\t# setup data directories and permissions (when run as root)\n\t\tdocker_create_db_directories\n\t\tif [ \"$(id -u)\" = '0' ]; then\n\t\t\t# then restart script as postgres user\n\t\t\texec su-exec postgres \"$BASH_SOURCE\" \"$@\"\n\t\tfi\n```\n\n[Source](https://github.com/docker-library/postgres/blob/b80fcb5ac7f6dde712e70d2d53a88bf880700fde/13/docker-entrypoint.sh#L281)\n\nNote that use-cases like this one are the primary target of `sue`. Using this program outside of a Docker container usually means that this tool is misused, as it is specifically designed for the type of purpose shown in the example above.\n\n## Goals\n* Performance\n* Size\n* Maintainability\n\n## Project Status\nAll [`gosu` test cases](https://github.com/tianon/gosu/blob/master/Dockerfile.test-alpine) are covered, achieving full compatability with `gosu`'s behaviour. Therefore, this alternative is just as stable as the widely popular `gosu`.\n\n## TODO\n* ~~Implement test suite~~\n* ~~Include `gosu` test cases~~\n* ~~Better error handling~~\n* Add base Docker image\n* Add CI\n* Separate inlined script from Dockerfile\n* Optimize\n\n## License\nCopyright © 2020-2022  Akito \u003cthe@akito.ooo\u003e\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.","funding_links":["https://liberapay.com/Akito/"],"categories":["Docker Images"],"sub_categories":["Base Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FtheAkito%2Fsue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FtheAkito%2Fsue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FtheAkito%2Fsue/lists"}