From 195cdd664aa8ba1f53b3e90d6f76c0b234868dfe Mon Sep 17 00:00:00 2001 From: Miclain K Keffeler Date: Wed, 3 Jun 2020 08:57:35 -0500 Subject: [PATCH 1/2] RHEL/CentOS Example --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/README.md b/README.md index f9169da6..1be5c9de 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,89 @@ We are using the [Arch User Repository](https://aur.archlinux.org) to distribute You can use [pacman](https://www.archlinux.org/pacman/) to install the packages. +#### RHEL/CentOS + +There are a few subtle yet important things to getting this setup, at the time of this writing the package cannot be installed via yum (its a feature request). So this is how we setup this on RHEL following some best practices. + +1. [Required] Install `step`. + + Download the latest Linux package from + [`step` releases](https://github.com/smallstep/cli/releases): + + ``` + $ wget -O step-cert.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz + ``` + + Install the Package by unzipping in bin: + + ``` + $ tar -xf step.tar.gz + $ cd step-_X.Y.Z/bin/ + $ mv step /usr/bin + ``` + +2. Install `step-ca`. + + Download the latest Linux package from [releases](https://github.com/smallstep/certificates/releases): + + ``` + $ wget -O step-ca.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz + ``` + + Install the Package by unzipping in bin: + + ``` + $ tar -xf step-ca.tar.gz + $ cd step-certificates_X.Y.Z/bin/ + $ mv step-ca /usr/bin + ``` + +3. Now your users can call the step and step-ca commands, create a 'smallstep' user that doesn't have login permitted and will only be used as a service user for systemctl to manage this service. + + ``` + $ useradd smallstep + $ passwd -l smallstep + ``` + + This creates a home directory for smallstep, as root sudo to the smallstep user, and perform the getting-started steps to setup the CA on this box as that user, we chose to put the password in a file in this example but you can mess with other solutions, we then made this systemctl service file + + ``` + [Unit] + Description=Smallstep + After=syslog.target network.target + + [Service] + + User=smallstep + Group=smallstep + ExecStart=/bin/sh -c '/bin/step-ca /home/smallstep/.step/config/ca.json --password-file=/home/smallstep/.step/pwd >> /var/log/smallstep/output.log 2>&1' + Type=simple + Restart=on-failure + RestartSec=10 + + + [Install] + WantedBy=multi-user.target + ``` + This also assumes you want logs going to a log file (we don't have a log rotation strategy at this time, perhaps the community can contribute :) + + To setup this, perform the following + ``` + $ mkdir /var/log/smallstep + $ chown -R smallstep:smallstep /var/log/smallstep + ``` + + + + Then do the following to startup the service. + ``` + $ systemctl status smallstep + $ systemctl enable smallstep (startup on reboot automatically) + $ systemctl start smallstep + ``` +If you have issues, you can debug by grabbing the execStart command from systemctl, sudo to smallstep, and start seeing what it is complaining about. + + ### Kubernetes We publish [helm charts](https://hub.helm.sh/charts/smallstep/step-certificates) for easy installation on kubernetes: From aaec9931f46c84f46e500b4fec19042ce976abe3 Mon Sep 17 00:00:00 2001 From: max furman Date: Mon, 15 Jun 2020 20:19:44 -0700 Subject: [PATCH 2/2] Add RHEL/Centos install docs and a section on systemctl config --- README.md | 68 +++++++---------------------------------- docs/GETTING_STARTED.md | 47 +++++++++++++++++++++++++++- 2 files changed, 57 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 1be5c9de..832bc881 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ Certificate: > Note: If you have installed `step` previously through the `smallstep/smallstep` > tap you will need to run the following commands before installing: -> +> > ``` > $ brew untap smallstep/smallstep > $ brew uninstall step @@ -177,23 +177,20 @@ You can use [pacman](https://www.archlinux.org/pacman/) to install the packages. #### RHEL/CentOS -There are a few subtle yet important things to getting this setup, at the time of this writing the package cannot be installed via yum (its a feature request). So this is how we setup this on RHEL following some best practices. +1. [Optional] Install `step`. -1. [Required] Install `step`. - - Download the latest Linux package from + Download the latest Linux tarball from [`step` releases](https://github.com/smallstep/cli/releases): ``` - $ wget -O step-cert.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz + $ wget -O step-cli.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz ``` - Install the Package by unzipping in bin: + Install `step` by unzipping and copying the executable over to `/usr/bin`: ``` - $ tar -xf step.tar.gz - $ cd step-_X.Y.Z/bin/ - $ mv step /usr/bin + $ tar -xf step-cli.tar.gz + $ sudo cp step_X.Y.Z/bin/step /usr/bin ``` 2. Install `step-ca`. @@ -204,60 +201,17 @@ There are a few subtle yet important things to getting this setup, at the time o $ wget -O step-ca.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz ``` - Install the Package by unzipping in bin: + Install `step-ca` by unzipping and copying the executable over to `/usr/bin`: ``` $ tar -xf step-ca.tar.gz - $ cd step-certificates_X.Y.Z/bin/ - $ mv step-ca /usr/bin + $ sudo cp step-certificates_X.Y.Z/bin/step-ca /usr/bin ``` -3. Now your users can call the step and step-ca commands, create a 'smallstep' user that doesn't have login permitted and will only be used as a service user for systemctl to manage this service. - - ``` - $ useradd smallstep - $ passwd -l smallstep - ``` - - This creates a home directory for smallstep, as root sudo to the smallstep user, and perform the getting-started steps to setup the CA on this box as that user, we chose to put the password in a file in this example but you can mess with other solutions, we then made this systemctl service file - - ``` - [Unit] - Description=Smallstep - After=syslog.target network.target - - [Service] - - User=smallstep - Group=smallstep - ExecStart=/bin/sh -c '/bin/step-ca /home/smallstep/.step/config/ca.json --password-file=/home/smallstep/.step/pwd >> /var/log/smallstep/output.log 2>&1' - Type=simple - Restart=on-failure - RestartSec=10 +See the [`systemctl` setup section](./docs/GETTING_STARTED.md#systemctl) for a +guide on configuring `step-ca` as a daemon. - [Install] - WantedBy=multi-user.target - ``` - This also assumes you want logs going to a log file (we don't have a log rotation strategy at this time, perhaps the community can contribute :) - - To setup this, perform the following - ``` - $ mkdir /var/log/smallstep - $ chown -R smallstep:smallstep /var/log/smallstep - ``` - - - - Then do the following to startup the service. - ``` - $ systemctl status smallstep - $ systemctl enable smallstep (startup on reboot automatically) - $ systemctl start smallstep - ``` -If you have issues, you can debug by grabbing the execStart command from systemctl, sudo to smallstep, and start seeing what it is complaining about. - - ### Kubernetes We publish [helm charts](https://hub.helm.sh/charts/smallstep/step-certificates) for easy installation on kubernetes: diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 44bd8876..156defd3 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -203,6 +203,49 @@ export STEPPATH=$(step path) step-ca $STEPPATH/config/ca.json ``` +### Systemctl + +Consider adding a service user that will only be used by `systemctl` to manage +the service. + +``` +$ useradd step +$ passwd -l step +``` + +Use the following example as a base for your `systemctl` service file: + +``` +[Unit] +Description=step-ca +After=syslog.target network.target + +[Service] + +User=smallstep +Group=smallstep +ExecStart=/bin/sh -c '/bin/step-ca /home/smallstep/.step/config/ca.json --password-file=/home/smallstep/.step/pwd >> /var/log/smallstep/output.log 2>&1' +Type=simple +Restart=on-failure +RestartSec=10 + + +[Install] +WantedBy=multi-user.target +``` + +The following are a few example commands you can use to check the status, +enable on restart, and start your `systemctl` service. + +``` +# Check the current status of the `step-ca` service +$ systemctl status step-ca +# Configure the `step-ca` process to startup on reboot automatically +$ systemctl enable step-ca +# Start the `step-ca` service. +$ systemctl start smallstep +``` + ## Configure Your Environment **Note**: Configuring your environment is only necessary for remote servers @@ -442,7 +485,9 @@ types of certs. Each of these provisioners must have unique keys. ## Use Custom Claims for Provisioners to Control Certificate Validity etc -It's possible to configure provisioners on the CA to issue certs using properties specific to their target environments. Most commonly different validity periods and disabling renewals for certs. Here's how: +It's possible to configure provisioners on the CA to issue certs using +properties specific to their target environments. Most commonly different +validity periods and disabling renewals for certs. Here's how: ```bash $ step ca init