dosh(1) Manual Page

NAME

dosh - run a user shell in a container with cwd bind mounted

SYNOPSIS

Typical shell commands:

dosh [(-|+)abefhmnuvxC] [(-|+)o shopt] [SCRIPT_FILE [ARGS…]]

dosh -c [(-|+)abefhmnuvxC] [(-|+)o shopt] COMMAND [NAME [ARGS…]]

dosh -i [(-|+)abefhmnuvxC] [(-|+)o shopt] [SCRIPT_FILE [ARGS…]]

dosh -s [(-|+)abefhmnuvxC] [(-|+)o shopt] [ARGS…]

Advanced dosh container commands:

dosh --detach [OPTIONS]

dosh --exec CONTAINER [OPTIONS] [ARGS…]

dosh --attach CONTAINER [OPTIONS]

Advanced dosh image management commands:

dosh --rmi [OPTIONS]

dosh --ls [OPTIONS]

dosh --gc [OPTIONS]

Extra docker frontend commands:

dosh --attach [OPTIONS] [DOCKER_OPTIONS] CONTAINER

dosh --kill [OPTIONS] [DOCKER_OPTIONS] CONTAINER [CONTAINER…]

dosh --rm [OPTIONS] [DOCKER_OPTIONS] CONTAINER [CONTAINER…]

DESCRIPTION

dosh is a sh-compatible frontend for docker(1) that executes commands read from the standard input or from a file.

It runs a shell process in a new container with its own file system, the current working directory bind mounted, and the current user/group privileges set.

When called without arguments, dosh defaults to running an interactive shell as current user.

When a container shell is started, dosh reads and executes commands from ~/.dosh_profile, if that file exists. This may be inhibited by using the option --no-doshprofile.

When a container shell is started, dosh reads and executes commands from ./doshrc, if that file exists. This may be inhibited by using the option --no-doshrc.

dosh has specific options to modify its behaviour; the option --dockerfile specifies the path to the Dockerfile(5) to use; the option --home bind mounts the user’s home directory instead of cwd; the option --root runs the container with the root privileges. Other options are specified in the section OPTIONS.

Under the hood, dosh builds and tags automatically a docker image using the Dockerfile(5) from the current working directory through docker-build(1). It appends extra RUN instructions to add the host $USER/$GROUPS through groupadd(8) and useradd(8) to the docker image. Once the image is built, dosh runs the $SHELL entry-point with the given arguments specified via the command-line through docker-run(1).

OPTIONS

POSIX Shell related options

-c: Read commands from command-line.
-i: Set interactive.
-s: Read commands from standard-input.
-abefhmnuvxC or -o shopt, +abefhmnuvxC or +o shopt: For a more thorough description of shopts, please refers to sh help.

Bash specific options:

-klprtBDEHIPT or -O shopt, +klprtBDEHIPT or +O shopt: For a more thorough description of shopts, please refers to bash help.

Dash specific options:

-pqEIV, +pqEIV: For a more thorough description of shopts, please refers to dash help.

Zsh specific options:

-0123456789dgklprtwyBDEFGHIJKLMNOPQRSTUVWXYZ, +0123456789dgklprtwyBDEFGHIJKLMNOPQRSTUVWXYZ: For a more thorough description of shopts, please refers to zsh help.

Docker related options

--dockerfile FILE: Path to the Dockerfile to use.
--context TAR: Path to the context to send to docker daemon.
--no-auto-context: Disable automatic context sent to docker daemon.
--no-extra-options: Disable extra options given to docker commands.
--no-doshprofile: Disable read of ~/.dosh_profile.
--no-doshrc: Disable read of ./doshrc.
--directory DIR: Change to directory before doing anything else.
--working-directory DIR: Working directory inside the container.
--root: Run as root.
--dind: Run dosh in dosh.
--home: Bind mount home directory.
--mount-options OPTIONS: Set bind mount volume options. For a more thorough description please refers to docker-run(1) manual.
--shell SHELL: Set shell interpretor. Equivalent to set DOSHELL=<SHELL>.
--ls: List images and exit.
--gc: Cleanup unused images and exit.
--build-only: Build image if needed and exit.
--build: Build image.
--rebuild: Build image again, verbosely. Equivalent to --build --verbose.
--rmi: Remove image and exit.
--detach: Detach container.
--exec CONTAINER: Execute in container.
--attach CONTAINER: Attach container.
--kill CONTAINER: Kill container.
--rm CONTAINER: Remove container.
--tag: Print docker tag and exit.
--dry-run: Do nothing; echo docker commands.

Miscellaneous options

--verbose: Turn on verbose mode.
--version: Print version.
--help: Print usage.

ENVIRONMENT VARIABLES

DOSHELL: The full pathname to the shell to run in docker image. Equivalent to --shell <SHELL>.
DOSHLVL: Incremented by one each time an instance of dosh is started.
DOSH_DOCKER: The docker executable.
DOSH_DOCKERFILE: The filename of the Dockerfile to use. Equivalent to --dockerfile <FILE>.
DOSH_DOCKER_RUN_EXTRA_OPTS: Set additionnal parameters to docker run command.
DOSH_DOCKER_EXEC_EXTRA_OPTS: Set additionnal parameters to docker exec command.
DOSH_DOCKER_ATTACH_EXTRA_OPTS: Set additionnal parameters to docker attach command.
DOSH_DOCKER_KILL_EXTRA_OPTS: Set additionnal parameters to docker kill command.
DOSH_DOCKER_RM_EXTRA_OPTS: Set additionnal parameters to docker rm command.
DOSH_DOCKER_BUILD_EXTRA_OPTS: Set additionnal parameters to docker build command.
DOSH_DOCKER_RMI_EXTRA_OPTS: Set additionnal parameters to docker rmi command.

EXAMPLES

Run an interactive shell in the latest Ubuntu container

$ echo FROM ubuntu >Dockerfile
$ cat Dockerfile
FROM ubuntu

$ dosh
sha256:777c682a9816
gportay@4c3fb2d195d8:~$

Check for the distribution

gportay@4c3fb2d195d8:~$ cat /etc/os-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=16.04
DISTRIB_CODENAME=xenial
DISTRIB_DESCRIPTION="Ubuntu 16.04.1 LTS"
NAME="Ubuntu"
VERSION="16.04.1 LTS (Xenial Xerus)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 16.04.1 LTS"
VERSION_ID="16.04"
HOME_URL="http://www.ubuntu.com/"
SUPPORT_URL="http://help.ubuntu.com/"
BUG_REPORT_URL="http://bugs.launchpad.net/ubuntu/"
VERSION_CODENAME=xenial
UBUNTU_CODENAME=xenial

Check for user

gportay@4c3fb2d195d8:~$ whoami
gportay

Exit from container

gportay@4c3fb2d195d8:~$ exit
logout

Run the commands above in the same container as a shell script

$ dosh "cat /etc/os-release && whoami"
NAME="Ubuntu"
VERSION="16.04.1 LTS (Xenial Xerus)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 16.04.1 LTS"
VERSION_ID="16.04"
HOME_URL="http://www.ubuntu.com/"
SUPPORT_URL="http://help.ubuntu.com/"
BUG_REPORT_URL="http://bugs.launchpad.net/ubuntu/"
VERSION_CODENAME=xenial
UBUNTU_CODENAME=xenial
gportay
logout

Check for PWD bind mountage ; write the distribution name to local file

$ dosh -c "grep '^NAME=' /etc/os-release >os-release"

Read the contents outside the container

$ cat os-release
NAME="Ubuntu"

Specify the Dockerfile(5) to use

$ dosh --dockerfile Dockerfile.fedora -c "grep '^NAME=' /etc/os-release"
sha256:44d9de323a55
NAME=Fedora

Change to another directory before doing anything else

$ cd /tmp
$ dosh --directory "$OLDPWD" -c "grep '^NAME=' /etc/os-release"
NAME="Ubuntu"
$ cd -

Run shell as root with --root to perform privileged user operations into container

$ dosh --root
root@4c3fb2d195d8:/# whoami
root
root@4c3fb2d195d8:/# apt-get install -y asciidoctor
Reading package lists... Done
Building dependency tree
Reading state information... Done
asciidoctor is already the newest version (1.5.4-1).
0 upgraded, 0 newly installed, 0 to remove and 6 not upgraded.

Rebuild image if Dockerfile(5) has changed

$ echo RUN apt-get update && apt-get install -y asciidoctor >>Dockerfile
$ cat Dockerfile
FROM ubuntu
RUN apt-get update && apt-get install -y asciidoctor
$ dosh --build
sha256:777c682a9816
gportay@31dd533203ea:~$ which asciidoctor
/usr/bin/asciidoctor
gportay@31dd533203ea:~$ exit
logout

$ dosh
gportay@0406c4779648:~$ exit
logout

Bind mount $HOME directory

$ echo $PWD
/home/gportay/src/dosh
$ echo $HOME
/home/gportay

$ dosh --home
gportay@098ac1e92f20 ~/src/dosh $ echo $PWD
/home/gportay/src/dosh
gportay@098ac1e92f20 ~/src/dosh $ echo $HOME
/home/gportay

Use /bin/sh as default $SHELL

$ echo $0
bash

$ dosh --shell /bin/sh
$ echo $0
/bin/sh

Detach container

$ dosh --detach
6b0e5f883ca5e176452bb234bccf70623a35b5d5f12ae56761a392a3e9f40125

$ docker ps -a
CONTAINER ID        IMAGE                                                                  COMMAND                  CREATED             STATUS              PORTS               NAMES
6b0e5f883ca5        dosh-dbc94874ef3f1be8f595c79fcaf36fd691dc2af3b7b29f291210cecc8f2beca2  "/bin/bash -c 'cd /ho"   7 seconds ago       Up 6 seconds                            determined_archimedes

Execute commands in it with --exec

$ dosh --exec determined_archimedes -c 'hostname'
6b0e5f883ca5

Attach to it using --attach

$ dosh --attach determined_archimedes
gportay@6b0e5f883ca5:~$ exit
exit

Kill it using --kill

$ dosh --kill determined_archimedes
determined_archimedes

And do not forget to remove it using --rm

$ dosh --rm determined_archimedes
determined_archimedes

$ docker ps -a
CONTAINER ID        IMAGE                                                                  COMMAND                  CREATED             STATUS              PORTS               NAMES

BUGS

Report bugs at https://github.com/gportay/dosh/issues

AUTHOR

Written by Gaël PORTAY gael.portay@gmail.com

COPYRIGHT

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 2.1 of the License, or (at your option) any later version.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

dosh.1.adoc

dosh.1.adoc

dosh(1) Manual Page

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

ENVIRONMENT VARIABLES

EXAMPLES

BUGS

AUTHOR

COPYRIGHT

SEE ALSO

Files

dosh.1.adoc

Latest commit

History

dosh.1.adoc

File metadata and controls

dosh(1) Manual Page

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

ENVIRONMENT VARIABLES

EXAMPLES

BUGS

AUTHOR

COPYRIGHT

SEE ALSO