From 90c484f7bb3b6f0c4cfab67176856449649827d8 Mon Sep 17 00:00:00 2001 From: James Deathe Date: Thu, 19 Sep 2019 22:33:49 +0100 Subject: [PATCH] #865: Adds docs directory and simplify README.md --- .dockerignore | 23 +-- .gitignore | 5 +- CHANGELOG.md | 1 + README.md | 236 ++++++------------------ command-keys.md => docs/command-keys.md | 0 docs/scmi.md | 141 ++++++++++++++ testing.md => docs/testing.md | 0 7 files changed, 215 insertions(+), 191 deletions(-) rename command-keys.md => docs/command-keys.md (100%) create mode 100644 docs/scmi.md rename testing.md => docs/testing.md (100%) diff --git a/.dockerignore b/.dockerignore index 58065fe..be8d7d0 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,13 +1,14 @@ -.env -.env.example -.git -.gitignore -dist -test -docker-compose.yml -LICENSE -README-short.txt -*.md +/.env +/.env.example +/.git +/.gitignore +/dist +/docs +/test +/docker-compose.yml +/LICENSE +/README-short.txt +/*.md !README.md **/*.mk -**/Makefile \ No newline at end of file +**/Makefile diff --git a/.gitignore b/.gitignore index 01faf4b..3bd889e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,2 @@ -.env -packages -dist \ No newline at end of file +/.env +/dist diff --git a/CHANGELOG.md b/CHANGELOG.md index b9d962b..bdab406 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ Summary of release changes. - Adds Makefile target `logsdef` to handle deferred logs output within a target chain. - Adds exec proxy function to `sshd-wrapper` used to pass through nice. - Adds double quotes around value containing spaces. +- Adds `/docs` directory for supplementary documentation and simplify README. - Fixes build error due to supervisord dependency resolution for `meld3`; pin to `1.0.2`. - Fixes validation failure of 0 second --timeout value in `test/health_status`. - Removes `ENABLE_SSHD_BOOTSTRAP` from docker-compose example configuration. diff --git a/README.md b/README.md index 9265301..0ac905a 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,10 @@ SSH access is by public key authentication and, by default, the [Vagrant](http:/ SSH is not required in order to access a terminal for the running container. The simplest method is to use the docker exec command to run bash (or sh) as follows: ``` -$ docker exec -it {container-name-or-id} bash +$ docker exec -it {{container-name-or-id}} bash ``` -For cases where access to docker exec is not possible the preferred method is to use Command Keys and the nsenter command. See [command-keys.md](https://github.com/jdeathe/centos-ssh/blob/centos-6/command-keys.md) for details on how to set this up. +For cases where access to docker exec is not possible the preferred method is to use Command Keys and the nsenter command. See [docs/command-keys.md](https://github.com/jdeathe/centos-ssh/blob/centos-7/docs/command-keys.md) for details on how to set this up. ## Quick Example @@ -42,7 +42,7 @@ Run up an SSH container named 'ssh.1' from the docker image 'jdeathe/centos-ssh' $ docker run -d \ --name ssh.1 \ -p 2020:22 \ - jdeathe/centos-ssh:1.11.0 + jdeathe/centos-ssh:2.6.0 ``` Check the logs for the password (required for sudo). @@ -51,20 +51,28 @@ Check the logs for the password (required for sudo). $ docker logs ssh.1 ``` -Download the [insecure private key](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant) and set permissions to 600. +#### Private key setup + +Download the [insecure private key](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant). ``` $ curl -LSs \ https://raw.githubusercontent.com/mitchellh/vagrant/master/keys/vagrant \ > id_rsa_insecure +``` + +Set restrictive permissions on the private key. + +``` $ chmod 600 id_rsa_insecure ``` +#### Connecting Connect using the `ssh` command line client with the [insecure private key](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant). ``` $ ssh -p 2020 -i id_rsa_insecure \ - app-admin@{docker-host-ip} + app-admin@{{docker-host-ip}} ``` ### SFTP Mode @@ -76,9 +84,11 @@ $ docker run -d \ --name sftp.1 \ -p 2021:22 \ -e SSH_USER_FORCE_SFTP=true \ - jdeathe/centos-ssh:1.11.0 + jdeathe/centos-ssh:2.6.0 ``` +#### Connecting + Connect using the `sftp` command line client with the [insecure private key](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant). ``` @@ -86,172 +96,44 @@ $ sftp \ -o Port=2021 \ -o StrictHostKeyChecking=no \ -i id_rsa_insecure \ - app-admin@{docker-host-ip} + app-admin@{{docker-host-ip}} ``` ## Instructions ### Running -To run the a docker container from this image you can use the standard docker commands. Alternatively, you can use the embedded (Service Container Manager Interface) [scmi](https://github.com/jdeathe/centos-ssh/blob/centos-7/src/usr/sbin/scmi) that is included in the image since `1.7.2` / `2.1.2` or, if you have a checkout of the [source repository](https://github.com/jdeathe/centos-ssh), and have make installed the Makefile provides targets to build, install, start, stop etc. where environment variables can be used to configure the container options and set custom docker run parameters. - -#### SCMI Installation Examples +To run the a docker container from this image you can use the standard docker commands. Alternatively, there's a [docker-compose.yml](https://github.com/jdeathe/centos-ssh/blob/centos-7/docker-compose.yml) example. -The following example uses docker to run the SCMI install command to create and start a container named `ssh.1`. To use SCMI it requires the use of the `--privileged` docker run parameter and the docker host's root directory mounted as a volume with the container's mount directory also being set in the `scmi` `--chroot` option. The `--setopt` option is used to add extra parameters to the default docker run command template; in the following example a named configuration volume is added which allows the SSH host keys to persist after the first container initialisation. Not that the placeholder `{{NAME}}` can be used in this option and is replaced with the container's name. +#### Using scmi -##### SCMI Install +For advanced use-cases, there's an embedded installer (Service Container Manager Interface) [scmi](https://github.com/jdeathe/centos-ssh/blob/centos-7/docs/scmi.md). -``` -$ docker run \ - --rm \ - --privileged \ - --volume /:/media/root \ - jdeathe/centos-ssh:1.11.0 \ - /usr/sbin/scmi install \ - --chroot=/media/root \ - --tag=1.11.0 \ - --name=ssh.1 \ - --setopt="--volume {{NAME}}.config-ssh:/etc/ssh" -``` - -##### SCMI Uninstall - -To uninstall the previous example simply run the same docker run command with the scmi `uninstall` command. - -``` -$ docker run \ - --rm \ - --privileged \ - --volume /:/media/root \ - jdeathe/centos-ssh:1.11.0 \ - /usr/sbin/scmi uninstall \ - --chroot=/media/root \ - --tag=1.11.0 \ - --name=ssh.1 \ - --setopt="--volume {{NAME}}.config-ssh:/etc/ssh" -``` - -##### SCMI Systemd Support - -If your docker host has systemd (and optionally etcd) installed then `scmi` provides a method to install the container as a systemd service unit. This provides some additional features for managing a group of instances on a single docker host and has the option to use an etcd backed service registry. Using a systemd unit file allows the System Administrator to use a Drop-In to override the settings of a unit-file template used to create service instances. To use the systemd method of installation use the `-m` or `--manager` option of `scmi` and to include the optional etcd register companion unit use the `--register` option. - -``` -$ docker run \ - --rm \ - --privileged \ - --volume /:/media/root \ - jdeathe/centos-ssh:1.11.0 \ - /usr/sbin/scmi install \ - --chroot=/media/root \ - --tag=1.11.0 \ - --name=ssh.1 \ - --manager=systemd \ - --register \ - --env='SSH_SUDO="ALL=(ALL) NOPASSWD:ALL"' \ - --env='SSH_USER="centos"' \ - --setopt='--volume {{NAME}}.config-ssh:/etc/ssh' -``` - -##### SCMI Image Information - -Since release tags `1.7.2` / `2.1.2` the install template has been added to the image metadata. Using docker inspect you can access `scmi` to simplify install/uninstall tasks. - -_NOTE:_ A prerequisite of the following examples is that the image has been pulled (or loaded from the release package). - -``` -$ docker pull jdeathe/centos-ssh:1.11.0 -``` +#### Using make -To see detailed information about the image run `scmi` with the `--info` option. To see all available `scmi` options run with the `--help` option. - -``` -$ eval "sudo -E $( - docker inspect \ - -f "{{.ContainerConfig.Labels.install}}" \ - jdeathe/centos-ssh:1.11.0 - ) --info" -``` - -To perform an installation using the docker name `ssh.2` simply use the `--name` or `-n` option. - -``` -$ eval "sudo -E $( - docker inspect \ - -f "{{.ContainerConfig.Labels.install}}" \ - jdeathe/centos-ssh:1.11.0 - ) --name=ssh.2" -``` - -To uninstall use the *same command* that was used to install but with the `uninstall` Label. - -``` -$ eval "sudo -E $( - docker inspect \ - -f "{{.ContainerConfig.Labels.uninstall}}" \ - jdeathe/centos-ssh:1.11.0 - ) --name=ssh.2" -``` - -##### SCMI on Atomic Host - -With the addition of install/uninstall image labels it is possible to use [Project Atomic's](http://www.projectatomic.io/) `atomic install` command to simplify install/uninstall tasks on [CentOS Atomic](https://wiki.centos.org/SpecialInterestGroup/Atomic) Hosts. - -To see detailed information about the image run `scmi` with the `--info` option. To see all available `scmi` options run with the `--help` option. - -``` -$ sudo -E atomic install \ - -n ssh.3 \ - jdeathe/centos-ssh:1.11.0 \ - --info -``` - -To perform an installation using the docker name `ssh.3` simply use the `-n` option of the `atomic install` command. - -``` -$ sudo -E atomic install \ - -n ssh.3 \ - jdeathe/centos-ssh:1.11.0 -``` - -Alternatively, you could use the `scmi` options `--name` or `-n` for naming the container. - -``` -$ sudo -E atomic install \ - jdeathe/centos-ssh:1.11.0 \ - --name ssh.3 -``` - -To uninstall use the *same command* that was used to install but with the `uninstall` Label. - -``` -$ sudo -E atomic uninstall \ - -n ssh.3 \ - jdeathe/centos-ssh:1.11.0 -``` +If you have a checkout of the [source repository](https://github.com/jdeathe/centos-ssh), and have `make` installed the Makefile provides targets to build, install, start, stop etc; run `make help` for instructions. #### Using environment variables The following example overrides the default "app-admin" SSH username, (and corresponding home directory path), with "centos" and "/home/centos" respectively via the `SSH_USER` environment variable. -*Note:* Settings applied by environment variables will override those set within configuration volumes from release 1.3.1. Existing installations that use the sshd-bootstrap.conf saved on a configuration "data" volume will not allow override by the environment variables. Also users can update sshd-bootstrap.conf to prevent the value being replaced by that set using the environment variable. - ``` -$ docker stop ssh.1 \ - && docker rm ssh.1 \ - ; docker run -d \ +$ docker stop ssh.1 && \ + docker rm ssh.1; \ + docker run -d \ --name ssh.1 \ -p :22 \ - --env "SSH_USER=app-user" \ - jdeathe/centos-ssh:1.11.0 + --env "SSH_USER=centos" \ + jdeathe/centos-ssh:2.6.0 ``` -Now you can find out the app-admin, (sudoer), user's password by inspecting the container's logs +To identify the `SSH_USER` user's sudoer password, inspect the container's logs as follows: ``` $ docker logs ssh.1 ``` -The output of the logs should show the auto-generated password for the app-admin and root users, (if not try again after a few seconds). +The output of the logs will show the auto-generated password for the user specified by `SSH_USER` on first run. ``` 2019-06-20 00:10:35,306 WARN No file matches via include "/etc/supervisord.d/*.ini" @@ -304,7 +186,7 @@ Server listening on :: port 22. 2019-06-20 00:10:41,872 INFO success: sshd-wrapper entered RUNNING state, process has stayed up for > than 5 seconds (startsecs) ``` -#### Environment Variables +#### Environment variables There are several environmental variables defined at runtime these allow the operator to customise the running container. @@ -336,7 +218,7 @@ ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAqmLedI2mEJimvIm1OzT1EYJCMwegL/jfsXARLnYkZvJl ... ``` -*Note:* The `base64` command on Mac OSX will encode a file without line breaks by default but if using the command on Linux you need to include use the `-w` option to prevent wrapping lines at 80 characters. i.e. `base64 -w 0 -i {key-path}`. +> **Note:** The `base64` command on Mac OSX will encode a file without line breaks by default but if using the command on Linux you need to include use the `-w` option to prevent wrapping lines at 80 characters. i.e. `base64 -w 0 -i {{key-path}}`. ``` ... @@ -453,11 +335,21 @@ If setting a password for the SSH user you might not want to store the plain tex ... ``` +###### Generating a crypt SHA-512 password hash + +To generate a hashed password string for the password `Passw0rd!`, use the following method. + +``` +$ docker run --rm jdeathe/centos-ssh \ + env PASSWORD=Passw0rd! \ + python -c "import crypt,os; print crypt.crypt(os.environ.get('PASSWORD'))" +``` + ##### SSH_USER_PRIVATE_KEY Use `SSH_USER_PRIVATE_KEY` to set an RSA private key for `SSH_USER`. It is recommended to use a container file path in combination with a secrets feature of your orchestration system e.g. Docker Swarm secrets. Alternatively, a container file path in combination with a bind mounted file or base64 encode the value (without line-breaks). -*Note:* Setting a value has no effect if `SSH_USER_FORCE_SFTP` is set to "true" (i.e. running in SFTP mode). +> **Note:** Setting a value has no effect if `SSH_USER_FORCE_SFTP` is set to "true" (i.e. running in SFTP mode). If set to a valid container file path the value will be read from the file - this allows for setting the value securely when combined with an orchestration feature such as Docker Swarm secrets. @@ -467,7 +359,7 @@ If set to a valid container file path the value will be read from the file - thi ... ``` -*Note:* The `base64` command on Mac OSX will encode a file without line breaks by default but if using the command on Linux you need to include use the `-w` option to prevent wrapping lines at 80 characters. i.e. `base64 -w 0 -i {key-path}`. +> **Note:** The `base64` command on Mac OSX will encode a file without line breaks by default but if using the command on Linux you need to include use the `-w` option to prevent wrapping lines at 80 characters. i.e. `base64 -w 0 -i {{key-path}}`. ``` ... @@ -477,26 +369,6 @@ If set to a valid container file path the value will be read from the file - thi ... ``` -##### SYSTEM_TIMEZONE - -If you require a locale based system time zone `SYSTEM_TIMEZONE` can be used when running the container. - -``` -... - --env "SYSTEM_TIMEZONE=Europe/London" \ -... -``` - -###### Generating a crypt SHA-512 password hash - -To generate a hashed password string for the password `Passw0rd!`, use the following method. - -``` -$ docker run --rm jdeathe/centos-ssh \ - env PASSWORD=Passw0rd! \ - python -c "import crypt,os; print crypt.crypt(os.environ.get('PASSWORD'))" -``` - ##### SSH_USER_SHELL On first run the SSH user is created with a default shell of "/bin/bash". If you require a specific shell `SSH_USER_SHELL` can be used when running the container. You could use "/sbin/nologin" to prevent login with the user account. @@ -519,11 +391,21 @@ This may be useful when running an SFTP container and mounting data volumes from ... ``` +##### SYSTEM_TIMEZONE + +If you require a locale based system time zone `SYSTEM_TIMEZONE` can be used when running the container. + +``` +... + --env "SYSTEM_TIMEZONE=Europe/London" \ +... +``` + ### Connect to the running container using SSH #### PasswordAuthentication disabled (default) -*NOTE:* This documents the process of connecting with a known private key which is insecure but the default. It is recommended that an alternative private/public key pair is created and used in place of the default value if running a container outside of a local test environment. +> **Note:** This documents the process of connecting with a known private key which is **insecure by default**. It is recommended that an alternative private/public key pair is created and used in place of the default value if running a container outside of a local test environment. Create the .ssh directory in your home directory with the permissions required by SSH. @@ -551,10 +433,10 @@ To connect to the running container use the following, where "app-admin" is the ``` $ ssh \ - -o Port={container-port} \ + -o Port={{container-port}} \ -o StrictHostKeyChecking=no \ -i ~/.ssh/id_rsa_insecure \ - app-admin@{docker-host-ip} + app-admin@{{docker-host-ip}} ``` #### PasswordAuthentication enabled @@ -563,8 +445,8 @@ If connecting to a container running with `SSH_PASSWORD_AUTHENTICATION` set to " ``` $ ssh \ - -o Port={container-port} \ + -o Port={{container-port}} \ -o StrictHostKeyChecking=no \ -o UserKnownHostsFile=/dev/null \ - app-admin@{docker-host-ip} -``` + app-admin@{{docker-host-ip}} +``` \ No newline at end of file diff --git a/command-keys.md b/docs/command-keys.md similarity index 100% rename from command-keys.md rename to docs/command-keys.md diff --git a/docs/scmi.md b/docs/scmi.md new file mode 100644 index 0000000..d21f175 --- /dev/null +++ b/docs/scmi.md @@ -0,0 +1,141 @@ +# SCMI + +Service Container Manager Interface (SCMI) is an [embedded installer](https://github.com/jdeathe/centos-ssh/blob/centos-7/src/usr/sbin/scmi) that has been included in the image since release tags `1.7.2` and `2.1.2`. + +## SCMI installation examples + +The following example uses docker to run the `scmi install` command to create and start a container named `ssh.1`. To use SCMI it requires the use of the `--privileged` docker run parameter and the docker host's root directory mounted as a volume with the container's mount directory also being set in the `scmi` `--chroot` option. The `--setopt` option is used to add extra parameters to the default docker run command template; in the following example a named configuration volume is added which allows the SSH host keys to persist after the first container initialisation. + +> **Note:** The placeholder `{{NAME}}` can be used in options and is replaced with the container's name. + +> **Note:** In the following examples replace `{{latest-release-tag}}` with the [latest release tag](https://github.com/jdeathe/centos-ssh/releases/latest) + +### SCMI install + +``` +$ docker run \ + --rm \ + --privileged \ + --volume /:/media/root \ + jdeathe/centos-ssh:{{latest-release-tag}} \ + /usr/sbin/scmi install \ + --chroot=/media/root \ + --tag={{latest-release-tag}} \ + --name=ssh.1 \ + --setopt="--volume {{NAME}}.config-ssh:/etc/ssh" +``` + +### SCMI uninstall + +To uninstall the previous example simply run the same docker run command with the scmi `uninstall` command. + +``` +$ docker run \ + --rm \ + --privileged \ + --volume /:/media/root \ + jdeathe/centos-ssh:{{latest-release-tag}} \ + /usr/sbin/scmi uninstall \ + --chroot=/media/root \ + --tag={{latest-release-tag}} \ + --name=ssh.1 \ + --setopt="--volume {{NAME}}.config-ssh:/etc/ssh" +``` + +### SCMI systemd support + +If your docker host has systemd (and optionally etcd) installed then `scmi` provides a method to install the container as a systemd service unit. This provides some additional features for managing a group of instances on a single docker host and has the option to use an etcd backed service registry. Using a systemd unit file allows the System Administrator to use a Drop-In to override the settings of a unit-file template used to create service instances. To use the systemd method of installation use the `-m` or `--manager` option of `scmi` and to include the optional etcd register companion unit use the `--register` option. + +``` +$ docker run \ + --rm \ + --privileged \ + --volume /:/media/root \ + jdeathe/centos-ssh:{{latest-release-tag}} \ + /usr/sbin/scmi install \ + --chroot=/media/root \ + --tag={{latest-release-tag}} \ + --name=ssh.1 \ + --manager=systemd \ + --register \ + --env='SSH_SUDO="ALL=(ALL) NOPASSWD:ALL"' \ + --env='SSH_USER="centos"' \ + --setopt='--volume {{NAME}}.config-ssh:/etc/ssh' +``` + +### SCMI image information + +Since release tags `1.7.2` and `2.1.2` the install template has been added to the image metadata. Using docker inspect, you can access `scmi` to perform install/uninstall tasks. + +> **Note:** A prerequisite of the following examples is that the image has been pulled (or loaded from the release package). + +``` +$ docker pull jdeathe/centos-ssh:{{latest-release-tag}} +``` + +To see detailed information about the image run `scmi` with the `--info` option. To see all available `scmi` options run with the `--help` option. + +``` +$ eval "sudo -E $( + docker inspect \ + -f "{{.ContainerConfig.Labels.install}}" \ + jdeathe/centos-ssh:{{latest-release-tag}} + ) --info" +``` + +To perform an installation using the docker name `ssh.2` simply use the `--name` or `-n` option. + +``` +$ eval "sudo -E $( + docker inspect \ + -f "{{.ContainerConfig.Labels.install}}" \ + jdeathe/centos-ssh:{{latest-release-tag}} + ) --name=ssh.2" +``` + +To uninstall use the *same command* that was used to install but with the `uninstall` Label. + +``` +$ eval "sudo -E $( + docker inspect \ + -f "{{.ContainerConfig.Labels.uninstall}}" \ + jdeathe/centos-ssh:{{latest-release-tag}} + ) --name=ssh.2" +``` + +### SCMI on Atomic Host + +With the addition of install/uninstall image labels it is possible to use [Project Atomic's](http://www.projectatomic.io/) `atomic install` command to simplify install/uninstall tasks on [CentOS Atomic](https://wiki.centos.org/SpecialInterestGroup/Atomic) Hosts. + +To see detailed information about the image run `scmi` with the `--info` option. To see all available `scmi` options run with the `--help` option. + +``` +$ sudo -E atomic install \ + -n ssh.3 \ + jdeathe/centos-ssh:{{latest-release-tag}} \ + --info +``` + +To perform an installation using the docker name `ssh.3` simply use the `-n` option of the `atomic install` command. + +``` +$ sudo -E atomic install \ + -n ssh.3 \ + jdeathe/centos-ssh:{{latest-release-tag}} +``` + +Alternatively, you could use the `scmi` options `--name` or `-n` for naming the container. + +``` +$ sudo -E atomic install \ + jdeathe/centos-ssh:{{latest-release-tag}} \ + --name ssh.3 +``` + +To uninstall use the *same command* that was used to install but with the `uninstall` Label. + +``` +$ sudo -E atomic uninstall \ + -n ssh.3 \ + jdeathe/centos-ssh:{{latest-release-tag}} +``` \ No newline at end of file diff --git a/testing.md b/docs/testing.md similarity index 100% rename from testing.md rename to docs/testing.md