{"id":13676255,"url":"https://github.com/flant/pam_docker","last_synced_at":"2025-07-31T10:32:27.695Z","repository":{"id":110074826,"uuid":"51847972","full_name":"flant/pam_docker","owner":"flant","description":null,"archived":false,"fork":false,"pushed_at":"2016-10-05T12:46:36.000Z","size":77,"stargazers_count":61,"open_issues_count":1,"forks_count":7,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-11-11T17:45:58.478Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/flant.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}},"created_at":"2016-02-16T15:50:34.000Z","updated_at":"2024-05-10T01:03:13.000Z","dependencies_parsed_at":"2023-05-21T01:45:25.726Z","dependency_job_id":null,"html_url":"https://github.com/flant/pam_docker","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fpam_docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fpam_docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fpam_docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fpam_docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flant","download_url":"https://codeload.github.com/flant/pam_docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228236605,"owners_count":17889563,"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-08-02T13:00:20.976Z","updated_at":"2024-12-05T05:08:50.787Z","avatar_url":"https://github.com/flant.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# Description\npam_docker is an experimental module for putting host's users inside Docker containers via PAM. It is an easy way of providing SSH access to containers' users and simplifying a lot of other things.\n\nWARNING: pam_docker was mostly created for academic purposes, to get a better understanding how Docker actually works.\n\nHere you can find a brief documentation for its features and limitations as well as instructions on how to use it, install it (we have packages for Ubuntu/Debian \u0026 CentOS), build it from sources or try with minimal efforts (using Vagrant image). Enjoy!\n\n# Usage with OpenSSH and other services\npam_docker is a PAM (Pluggable Authentication Modules for UNIX-like systems) module that allows you to assign system users (or groups) to Docker containers. As a user is assigned to container, (s)he will enter the corresponding container just after logging in to the system. Other important thing is that all of user's processes will start inside this container.\n\nUsing PAM system makes a lot of things easy:\n* **SSH / login**. Thanks to OpenSSH supporting PAM by default (check *UsePAM* in *man sshd_config* for details), assigning user to container will bring this user into container's isolated environment by means of regular SSH login.\n* **su / sudo**. These services work with PAM, so using them will also bring user inside appropriate container.\n* **cron**. Vixie cron supports PAM, so user's crontab tasks (from the host system) will be executed inside appropriate container.\n* **FTP**. ProfFTPD (as well as other FTP servers) also supports PAM (it is enabled by default, check *AuthPAM* in *proftpd.conf* for details). User's FTP connections will start inside container as well.\n\n# Install\nAll you need in Ubuntu / Debian or CentOS is to add a repository and install the *pam_docker* package. Other Linux distributions lovers are very welcome to build it from sources (look for the \"Building\" section below) and/or to make their own packages.\n\n## 1. Ubuntu \u0026 Debian\n```\ncurl -s https://packagecloud.io/install/repositories/flant/pam_docker/script.deb.sh | sudo bash\nsudo apt-get install pam-docker\n```\n\n## 2. CentOS\n```\ncurl -s https://packagecloud.io/install/repositories/flant/pam_docker/script.rpm.sh | sudo bash\nsudo yum install pam_docker\n```\n\n# Configuration\n## 1. Setup your PAM\n### 1.1. Ubuntu и Debian\nDo nothing and enjoy: PAM module will be enabled automatically when the package is installed. Of course, it will be disabled when the package is uninstalled.\n\n### 1.2. CentOS\nPlease edit your */etc/pam.d/system-auth* by adding to its end (just after the ```session     required      pam_unix.so``` line):\n```\nsession    required    pam_docker.so\n```\n#### Enable for sudo\nAdd this line to the end of */etc/pam.d/sudo* (sudo in CentOS 7 doesn't use system-auth by default):\n```\nsession     include     system-auth\n```\n#### Enable for ssh\nAdd this line to the end of */etc/pam.d/sshd* (ssh in CentOS 7 doesn't use system-auth by default):\n```\nsession     include     system-auth\n```\n\n## 2. Add system user\nSystem user and all of user's groups should be added **both to host and container**. UIDs and GIDs should be the same (at the host and the container).\n\n## 3. Assign users to containers\nTo assign user *username* or group *groupname* to container *docker_container_name* just add a line into your */etc/security/docker.conf* file:\n* Assigning user:\n```\nusername docker_container_name\n```\n* Assigning group:\n```\n@groupname docker_container_name\n```\n**Warning!** *pam_docker* will parse this file from top to the bottom until it finds the first matching user/group. Each user/group can be assigned to one container only.\n\n# Building\nIf you use another distribution or don't want to use our repository, you are welcome to build *pam_docker* on your own. Here are brief instructions for different systems:\n\n## 1. Ubuntu / Debian\n```\nsudo apt-get install build-essential libpam0g-dev\nmake\nDESTDIR=/lib/security/ sudo make install\nsudo make pam-auth-update\n```\n\n## 2. CentOS\n```\nsudo yum install make gcc pam-devel\nmake\nDESTDIR=/lib64/security/ sudo make install\n```\n\n# Try it using Vagrant\nTo catch a glimpse of *pam_docker*, you can simply use Vagrant:\n```\ngit clone https://github.com/flant/pam_docker.git\nvagrant up\nvagrant ssh\nsudo -i\n```\n\nThis virtual machine is configured and ready for tests: it has some containers, users \u0026 groups. More details are available in *Vagrantfile*.\n\n# Technical limitations\n1. Currently, *pam_docker* doesn't use *runc* (previously it was known as *libcontainer*) to enter Docker containers. The actions required for that are done \"manually\": adding process to cgroups with following *setns* system calls. That's why it can be broken (i.e. should be modified) if Docker changes the steps required to enter container.\n2. To get Docker container's ID and its root process' PID, *pam_docker* uses Docker's UNIX socket in the *PAM_DOCKER_SOCK* path (this constant is defined at the compilation stage). Changing the socket's path (after pam_docker is compiled) and working with Docker via TCP (HTTP) is not supported.\n3. Docker's API uses JSON. However, our effort to make pam_docker's dependencies minimal led to its own, very simple JSON parser used to find *Id* and *Pid* keywords in the JSON data returned by Docker.\n\n# Contacts \u0026 feedback\n*pam_docker* was originally made by [Dmitry Stolyarov](https://github.com/distol) \u0026 [Timofey Kirillov](https://github.com/distorhead) from [Flant](http://flant.com/).\n\nWe encourage and welcome any feedback via issues and/or pull requests to pam_docker's upstream at https://github.com/flant/pam_docker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflant%2Fpam_docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflant%2Fpam_docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflant%2Fpam_docker/lists"}