github-personal/matchbox
1
0
Fork 0
mirror of https://github.com/outbackdingo/matchbox.git synced 2026-01-27 02:19:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

scripts: Move examples/etc/matchbox to scripts/tls

Browse Source 
* Use the same TLS cert-gen location in source as in releases
This commit is contained in:
Dalton Hubble
2017-05-24 10:58:13 -07:00
parent d437167ebf
commit 314a317271
7 changed files with 91 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/deployment.md
View File

@@ -127,31 +127,39 @@ $ sudo firewall-cmd --zone=MYZONE --add-port=8080/tcp --permanent
$ sudo firewall-cmd --zone=MYZONE --add-port=8081/tcp --permanent
```
## Generate TLS credentials
## Generate TLS Certificates
*Skip this unless you need to enable the gRPC API*
The Matchbox gRPC API allows clients (terraform-provider-matchbox) to create and update Matchbox resources. TLS credentials are needed for client authentication and to establish a secure communication channel. Client machines (those PXE booting) read from the HTTP endpoints and do not require this setup.
The `matchbox` gRPC API allows client apps (terraform-provider-matchbox, Tectonic Installer, etc.) to update how machines are provisioned. TLS credentials are needed for client authentication and to establish a secure communication channel. Client machines (those PXE booting) read from the HTTP endpoints and do not require this setup.
The `cert-gen` helper script generates a self-signed CA, server certificate, and client certificate. **Prefer your organization's PKI, if possible**
If your organization manages public key infrastructure and a certificate authority, create a server certificate and key for the `matchbox` service and a client certificate and key for each client tool.
Otherwise, generate a self-signed `ca.crt`, a server certificate (`server.crt`, `server.key`), and client credentials (`client.crt`, `client.key`) with the `examples/etc/matchbox/cert-gen` script. Export the DNS name or IP (discouraged) of the provisioner host.
Navigate to the `scripts/tls` directory.
```sh
$ cd scripts/tls
```
Export `SAN` to set the Subject Alt Names which should be used in certificates. Provide the fully qualified domain name or IP (discouraged) where Matchbox will be installed.
```sh
# DNS or IP Subject Alt Names where matchbox runs
$ export SAN=DNS.1:matchbox.example.com,IP.1:172.18.0.2
```
Generate a `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`.
```sh
$ cd examples/etc/matchbox
# DNS or IP Subject Alt Names where matchbox can be reached
$ export SAN=DNS.1:matchbox.example.com,IP.1:192.168.1.42
$ ./cert-gen
```
Place the TLS credentials in the default location:
Move TLS credentials to the matchbox server's default location.
```sh
$ sudo mkdir -p /etc/matchbox
$ sudo cp ca.crt server.crt server.key /etc/matchbox/
$ sudo cp ca.crt server.crt server.key /etc/matchbox
```
Save `client.crt`, `client.key`, and `ca.crt` to use with a client tool later.
Save `client.crt`, `client.key`, and `ca.crt` for later use (e.g. `~/.matchbox`).
## Start matchbox

44
examples/etc/matchbox/README.md
View File

@@ -1,44 +0,0 @@
## gRPC API Credentials
Create FAKE TLS credentials for running the `matchbox` gRPC API examples.
**DO NOT** use these certificates for anything other than running `matchbox` examples. Use your organization's production PKI for production deployments.
Navigate to the example directory which will be mounted as `/etc/matchbox` in examples:
cd matchbox/examples/etc/matchbox
Set certificate subject alt names which should be used by exporting `SAN`. Use the DNS name or IP at which `matchbox` is hosted.
# for examples on metal0 or docker0 bridges
export SAN=IP.1:127.0.0.1,IP.2:172.18.0.2
# production example
export SAN=DNS.1:matchbox.example.com
Create a fake `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`. Type 'Y' when prompted.
$ ./cert-gen
Creating FAKE CA, server cert/key, and client cert/key...
...
...
...
******************************************************************
WARNING: Generated TLS credentials are ONLY SUITABLE FOR EXAMPLES!
Use your organization's production PKI for production deployments!
## Inpsect
Inspect the generated FAKE certificates if desired.
openssl x509 -noout -text -in ca.crt
openssl x509 -noout -text -in server.crt
openssl x509 -noout -text -in client.crt
## Verify
Verify that the FAKE server and client certificates were signed by the fake CA.
openssl verify -CAfile ca.crt server.crt
openssl verify -CAfile ca.crt client.crt

6
scripts/dev/release-files
View File

@@ -18,9 +18,9 @@ cp README.md $DEST
# scripts
mkdir -p $SCRIPTS/tls
cp scripts/get-coreos $SCRIPTS
cp examples/etc/matchbox/README.md $SCRIPTS/tls
cp examples/etc/matchbox/cert-gen $SCRIPTS/tls
cp examples/etc/matchbox/openssl.conf $SCRIPTS/tls
cp scripts/tls/README.md $SCRIPTS/tls
cp scripts/tls/cert-gen $SCRIPTS/tls
cp scripts/tls/openssl.conf $SCRIPTS/tls
# systemd
mkdir -p $CONTRIB/systemd

5
scripts/tls/.gitignore vendored Normal file
View File

@@ -0,0 +1,5 @@
*
!.gitignore
!README.md
!cert-gen
!openssl.conf

61
scripts/tls/README.md Normal file
View File

@@ -0,0 +1,61 @@
## gRPC TLS Generation
The Matchbox gRPC API allows clients (`terraform-provider-matchbox`) to create and update Matchbox resources. TLS credentials are used for client authentication and to establish a secure communication channel. When the gRPC API is [enabled](../../Documentation/deployment.md#customization), the server requires a TLS server certificate, key, and CA certificate ([locations](../../Documentation/config.md#files-and-directories)).
The `cert-gen` helper script generates a self-signed CA, server certificate, and client certificate. **Prefer your organization's PKI, if possible**
Navigate to the `scripts/tls` directory.
```sh
$ cd scripts/tls
```
Export `SAN` to set the Subject Alt Names which should be used in certificates. Provide the fully qualified domain name or IP (discouraged) where Matchbox will be installed.
```sh
# DNS or IP Subject Alt Names where matchbox runs
$ export SAN=DNS.1:matchbox.example.com,IP.1:172.18.0.2
```
Generate a `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`.
```sh
$ ./cert-gen
Creating FAKE CA, server cert/key, and client cert/key...
...
...
...
******************************************************************
WARNING: Generated credentials are self-signed. Prefer your
organization's PKI for production deployments.
```
Move TLS credentials to the matchbox server's default location.
```sh
$ sudo mkdir -p /etc/matchbox
$ sudo cp ca.crt server.crt server.key /etc/matchbox
```
Save `client.crt`, `client.key`, and `ca.crt` for later use (e.g. `~/.matchbox`).
*If you are using the local Matchbox [development environment](../../Documentation/getting-started-rkt.md), move server credentials to `examples/etc/matchbox`.*
## Inpsect
Inspect the generated certificates if desired.
```sh
openssl x509 -noout -text -in ca.crt
openssl x509 -noout -text -in server.crt
openssl x509 -noout -text -in client.crt
```
## Verify
Verify that the server and client certificates were signed by the self-signed CA.
```sh
openssl verify -CAfile ca.crt server.crt
openssl verify -CAfile ca.crt client.crt
```

4
examples/etc/matchbox/cert-gen → scripts/tls/cert-gen
View File

@@ -41,5 +41,5 @@ openssl ca -batch -config openssl.conf -extensions usr_cert -days 365 -notext -m
rm *.csr
echo "*******************************************************************"
echo "WARNING: Generating self-signed TLS-credentials. Its recommended to"
echo "use your own organization's public key infrastructure"
echo "WARNING: Generated credentials are self-signed. Prefer your"
echo "organization's PKI for production deployments."

0
examples/etc/matchbox/openssl.conf → scripts/tls/openssl.conf
View File