pam_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.
WARNING: pam_docker was mostly created for academic purposes, to get a better understanding how Docker actually works.
Here 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 & CentOS), build it from sources or try with minimal efforts (using Vagrant image). Enjoy!
Usage with OpenSSH and other services
pam_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.
Using PAM system makes a lot of things easy:
- 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.
- su / sudo. These services work with PAM, so using them will also bring user inside appropriate container.
- cron. Vixie cron supports PAM, so user's crontab tasks (from the host system) will be executed inside appropriate container.
- 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.
All 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.
1. Ubuntu & Debian
curl -s https://packagecloud.io/install/repositories/flant/pam_docker/script.deb.sh | sudo bash sudo apt-get install pam-docker
curl -s https://packagecloud.io/install/repositories/flant/pam_docker/script.rpm.sh | sudo bash sudo yum install pam_docker
1. Setup your PAM
1.1. Ubuntu и Debian
Do 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.
Please edit your /etc/pam.d/system-auth by adding to its end (just after the
session required pam_unix.so line):
session required pam_docker.so
Enable for sudo
Add this line to the end of /etc/pam.d/sudo (sudo in CentOS 7 doesn't use system-auth by default):
session include system-auth
Enable for ssh
Add this line to the end of /etc/pam.d/sshd (ssh in CentOS 7 doesn't use system-auth by default):
session include system-auth
2. Add system user
System 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).
3. Assign users to containers
To assign user username or group groupname to container docker_container_name just add a line into your /etc/security/docker.conf file:
- Assigning user:
- Assigning group:
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.
If 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:
1. Ubuntu / Debian
sudo apt-get install build-essential libpam0g-dev make DESTDIR=/lib/security/ sudo make install sudo make pam-auth-update
sudo yum install make gcc pam-devel make DESTDIR=/lib64/security/ sudo make install
Try it using Vagrant
To catch a glimpse of pam_docker, you can simply use Vagrant:
git clone https://github.com/flant/pam_docker.git vagrant up vagrant ssh sudo -i
This virtual machine is configured and ready for tests: it has some containers, users & groups. More details are available in Vagrantfile.
- 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.
- 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.
- 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.
Contacts & feedback
We encourage and welcome any feedback via issues and/or pull requests to pam_docker's upstream at https://github.com/flant/pam_docker