github.com/drud/ddev@v1.21.5-alpha1.0.20230226034409-94fcc4b94453/containers/ddev-ssh-agent/README.md (about)

     1  # ddev-ssh-agent
     2  
     3  originally forked from <https://github.com/nardeas/docker-ssh-agent>
     4  at `fb6822d0003d1c0a795e183f5d257c2540fa74a4`.
     5  
     6  # Docker SSH Agent
     7  
     8  [![Pulls](https://img.shields.io/docker/pulls/nardeas/ssh-agent.svg)](https://img.shields.io/docker/pulls/nardeas/ssh-agent.svg?style=flat-square)
     9  [![Size](https://images.microbadger.com/badges/image/nardeas/ssh-agent.svg)](https://microbadger.com/images/nardeas/ssh-agent "Get your own image badge on microbadger.com")
    10  
    11  Lets you store your SSH authentication keys in a dockerized ssh-agent that can provide the SSH authentication socket for other containers. Works in macOS and Linux environments.
    12  
    13  ## Why?
    14  
    15  On macOS you cannot simply forward your authentication socket to a Docker container to be able to e.g clone private repositories that you have access to. You don't want to copy your private key to all containers either. The solution is to add your keys only once to a long-lived ssh-agent container that can be used by other containers and stopped when not needed anymore.
    16  
    17  ## hub.docker.com
    18  
    19  You can pull the image from [DockerHub](https://hub.docker.com/r/nardeas/ssh-agent/) via
    20  
    21  ```
    22  docker pull nardeas/ssh-agent
    23  ```
    24  
    25  ## How to use
    26  
    27  ### Quickstart
    28  
    29  If you don't want to build your own images, here's a 3-step guide:
    30  
    31  1\. Run agent
    32  
    33  ```
    34  docker run -d --name=ssh-agent nardeas/ssh-agent
    35  ```
    36  
    37  2\. Add your keys
    38  
    39  ```
    40  docker run --rm --volumes-from=ssh-agent -v ~/.ssh:/.ssh -it nardeas/ssh-agent ssh-add /root/.ssh/id_rsa
    41  ```
    42  
    43  3\. Now run your actual container:
    44  
    45  ```
    46  docker run -it --volumes-from=ssh-agent -e SSH_AUTH_SOCK=/.ssh-agent/socket ubuntu:latest /bin/bash
    47  ```
    48  
    49  **Run script**
    50  
    51  You can run the `run.sh` script which will build the images for you, launch the ssh-agent and add your keys. If your keys are password protected (hopefully) you will just need to input your passphrase.
    52  
    53  Launch everything:
    54  
    55  ```
    56  ./run.sh
    57  ```
    58  
    59  Remove your keys from ssh-agent and stop container:
    60  
    61  ```
    62  ./run.sh -s
    63  ```
    64  
    65  ### Step by step
    66  
    67  #### 0. Build
    68  
    69  Navigate to the project directory and launch the following command to build the image:
    70  
    71  ```
    72  docker build -t docker-ssh-agent:latest -f Dockerfile .
    73  ```
    74  
    75  #### 1. Run a long-lived container
    76  
    77  ```
    78  docker run -d --name=ssh-agent docker-ssh-agent:latest
    79  ```
    80  
    81  #### 2. Add your ssh keys
    82  
    83  Run a temporary container with volume mounted from host that includes your SSH keys. SSH key id_rsa will be added to ssh-agent (you can replace id_rsa with your key name):
    84  
    85  ```
    86  docker run --rm --volumes-from=ssh-agent -v ~/.ssh:/.ssh -it docker-ssh-agent:latest ssh-add /root/.ssh/id_rsa
    87  ```
    88  
    89  The ssh-agent container is now ready to use.
    90  
    91  #### 3. Add ssh-agent socket to other container
    92  
    93  If you're using `docker-compose` this is how you forward the socket to a container:
    94  
    95  ```
    96    volumes_from:
    97      - ssh-agent
    98    environment:
    99      - SSH_AUTH_SOCK=/.ssh-agent/socket
   100  ```
   101  
   102  ##### For non-root users
   103  
   104  The above only works for root. ssh-agent socket is accessible only to the user which started this agent or for root user. So other users don't have access to `/.ssh-agent/socket`. If you have another user in your container you should do the following:
   105  
   106  1. Install `socat` utility in your container
   107  2. Make proxy-socket in your container:
   108  
   109  ```
   110  sudo socat UNIX-LISTEN:~/.ssh/socket,fork UNIX-CONNECT:/.ssh-agent/socket &
   111  ```
   112  
   113  3. Change the owner of this proxy-socket
   114  
   115  ```
   116  sudo chown $(id -u) ~/.ssh/socket
   117  ```
   118  
   119  4. You will need to use different SSH_AUTH_SOCK for this user:
   120  
   121  ```
   122  SSH_AUTH_SOCK=~/.ssh/socket
   123  ```
   124  
   125  ##### Without docker-compose
   126  
   127  Here's an example how to run a Ubuntu container that uses the ssh authentication socket:
   128  
   129  ```
   130  docker run -it --volumes-from=ssh-agent -e SSH_AUTH_SOCK=/.ssh-agent/socket ubuntu:latest /bin/bash
   131  ```
   132  
   133  ### Deleting keys from the container
   134  
   135  Run a temporary container and delete all known keys from ssh-agent:
   136  
   137  ```
   138  docker run --rm --volumes-from=ssh-agent -it docker-ssh-agent:latest ssh-add -D
   139  ```