From 73f4f2911090575ae7a63265afdeaac58df6f98d Mon Sep 17 00:00:00 2001 From: Harshavardhana Date: Sat, 28 Jan 2017 19:45:30 -0800 Subject: [PATCH] docs: Restructure docs, move the files to their relevant location. (#3648) Also combines windows TLS docs with single doc with Linux. --- .../{management-api.md => README.md} | 0 docs/configure-minio-with-gnutls-windows.md | 68 ---------- docs/configure-minio-with-tls.md | 49 ------- docs/service/linux/README.md | 44 +++++++ .../windows/README.md} | 1 - docs/tls/README.md | 122 ++++++++++++++++++ 6 files changed, 166 insertions(+), 118 deletions(-) rename docs/admin-api/{management-api.md => README.md} (100%) delete mode 100644 docs/configure-minio-with-gnutls-windows.md delete mode 100644 docs/configure-minio-with-tls.md create mode 100644 docs/service/linux/README.md rename docs/{running-minio-as-a-service-on-windows.md => service/windows/README.md} (99%) create mode 100644 docs/tls/README.md diff --git a/docs/admin-api/management-api.md b/docs/admin-api/README.md similarity index 100% rename from docs/admin-api/management-api.md rename to docs/admin-api/README.md diff --git a/docs/configure-minio-with-gnutls-windows.md b/docs/configure-minio-with-gnutls-windows.md deleted file mode 100644 index b397e30d8..000000000 --- a/docs/configure-minio-with-gnutls-windows.md +++ /dev/null @@ -1,68 +0,0 @@ - -# Generate self signed certificate with GnuTLS under Windows - - -## 1. Install GnuTLS - -Download and decompress the Windows version of GnuTLS from [here](http://www.gnutls.org/download.html) - -Add the directory `gnutls-3.4.9-w64/bin` to your PATH environment and restart your console - -## 2. Generate private.key - -Run the following command to create `private.key` -``` -certtool.exe --generate-privkey --outfile private.key -``` - -## 3. Generate public.crt - -The easiest way is to generate certificate is to specify its information under a file. You can find an example below. We'll call that file `cert.cnf`. - -``` -# X.509 Certificate options -# -# DN options - -# The organization of the subject. -organization = "Example Inc." - -# The organizational unit of the subject. -#unit = "sleeping dept." - -# The state of the certificate owner. -state = "Example" - -# The country of the subject. Two letter code. -country = "EX" - -# The common name of the certificate owner. -cn = "Sally Certowner" - -# In how many days, counting from today, this certificate will expire. -expiration_days = 365 - -# X.509 v3 extensions - -# DNS name(s) of the server -dns_name = "localhost" - -# (Optional) Server IP address -ip_address = "127.0.0.1" - -# Whether this certificate will be used for a TLS server -tls_www_server - -# Whether this certificate will be used to encrypt data (needed -# in TLS RSA ciphersuites). Note that it is preferred to use different -# keys for encryption and signing. -encryption_key -``` - -Now, it is time to generate the public certificate using this command: - -```sh -certtool.exe --generate-self-signed --load-privkey private.key --template cert.cnf --outfile public.crt -``` - -That's it. diff --git a/docs/configure-minio-with-tls.md b/docs/configure-minio-with-tls.md deleted file mode 100644 index 840f5628c..000000000 --- a/docs/configure-minio-with-tls.md +++ /dev/null @@ -1,49 +0,0 @@ -# How to secure access to your Minio server with TLS [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) - -In this document, we will show how to configure your Minio servers with TLS certificates. Steps for Windows could be found [here](https://github.com/minio/minio/blob/master/docs/configure-minio-with-gnutls-windows.md). - -## 1. Prerequisites - -* Download Minio server from [here](https://docs.minio.io/docs/minio) - -## 2. Generate TLS certificate - -Minio supports only key/certificate in PEM format. - -### With Letsencrypt - -Please explore [here](https://docs.minio.io/docs/generate-let-s-encypt-certificate-using-concert-for-minio) - -### With generate_cert.go (self-signed certificate) - -You need to download [generate_cert.go](https://golang.org/src/crypto/tls/generate_cert.go?m=text) which is a simple go tool for generating self-signed certificates but works for the most of cases. - -`generate_cert.go` already provides SAN certificates with DNS and IP entries: - -```sh - go run generate_cert.go -ca --host "10.10.0.3" -``` - -### With OpenSSL: - -Generate the private key: -```sh -openssl genrsa -out private.key 1024 -``` - -Generate the self-signed certificate: -```sh -openssl req -new -x509 -days 3650 -key private.key -out public.crt -subj "/C=country/ST=state/L=location/O=organization/CN=domain" -``` - -## 3. Configure Minio with the generated certificate - -To make Minio aware about your generated key and certificate, you will need to put them under `certs` directory in your Minio config path (usually ~/.minio) using the names of `private.key` and `public.crt` for key and certificate files respectively. - -## 4. Install third parties CAs - -Minio can be configured to connect to other servers, whether Minio nodes or servers like NATs, Redis. If these servers use certificates that are not registered in one of the known certificates authorities, you can make Minio server trust these CAs by dropping these certificates under `~/.minio/certs/CAs/` in your Minio config path. - -# Explore Further -* [Minio Quickstart Guide](https://docs.minio.io/docs/minio-quickstart-guide) -* [Minio Client Complete Guide](https://docs.minio.io/docs/minio-client-complete-guide) diff --git a/docs/service/linux/README.md b/docs/service/linux/README.md new file mode 100644 index 000000000..84780b329 --- /dev/null +++ b/docs/service/linux/README.md @@ -0,0 +1,44 @@ +# Running Minio as a service on Linux + +## Install Minio service + +Systemctl is a controller for systemd system and service manager. This document assumes operating system to be Ubuntu 16.04 (LTS) with `systemctl`. + +Create a default minio startup config file at `/etc/default/minio`. `MINIO_VOLUMES` should be updated with the correct path. +``` +cat <> /etc/default/minio +# Local export path. +MINIO_VOLUMES="/mnt/export" +# Use if you want to run Minio on a custom port. +# MINIO_OPTS="--address :9001" + +EOT +``` + +Optionally you can also override your Minio access credentials as shown below. +``` +cat <> /etc/default/minio +# Access key of the server. +MINIO_ACCESS_KEY=YOUR-ACCESSKEY +# Secret key of the server. +MINIO_SECRET_KEY=YOUR-SECRETKEY + +EOT +``` + +Download `minio.service` into `/etc/systemd/system/` +``` +( cd /etc/systemd/system/; curl -O https://raw.githubusercontent.com/minio/minio-systemd/master/minio.service ) +``` + +## Enable Minio service + +Once we have successfully copied the `minio.service` we will enable it to start on boot. +``` +systemctl enable minio.service +``` + +## Disable Minio service +``` +systemctl disable minio.service +``` diff --git a/docs/running-minio-as-a-service-on-windows.md b/docs/service/windows/README.md similarity index 99% rename from docs/running-minio-as-a-service-on-windows.md rename to docs/service/windows/README.md index f459d6afe..3c10628bf 100644 --- a/docs/running-minio-as-a-service-on-windows.md +++ b/docs/service/windows/README.md @@ -23,7 +23,6 @@ It is a good (and secure) practice to create a new user, assign rights to the da ![Configure user](https://raw.githubusercontent.com/minio/minio/master/docs/screenshots/windows-configure-user.png) ## Delete Minio service - ``` c:\nssm.exe remove Minio ``` diff --git a/docs/tls/README.md b/docs/tls/README.md new file mode 100644 index 000000000..c879798d7 --- /dev/null +++ b/docs/tls/README.md @@ -0,0 +1,122 @@ +# How to secure access to Minio server with TLS [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) + +In this document, we will configure Minio servers with TLS certificates. Steps for Windows could be found [here](https://github.com/minio/minio/blob/master/docs/configure-minio-with-gnutls-windows.md). + +## 1. Prerequisites + +* Download Minio server from [here](https://docs.minio.io/docs/minio) + +## 2. Generate TLS certificate + +### Linux + +Minio supports only key/certificate in PEM format on Linux. + +#### With Let's Encrypt + +Please explore [here](https://docs.minio.io/docs/generate-let-s-encypt-certificate-using-concert-for-minio) + +#### With generate_cert.go (self-signed certificate) + +You need to download [generate_cert.go](https://golang.org/src/crypto/tls/generate_cert.go?m=text) which is a simple go tool for generating self-signed certificates but works for the most of cases. + +`generate_cert.go` already provides SAN certificates with DNS and IP entries: + +```sh + go run generate_cert.go -ca --host "10.10.0.3" +``` + +#### With OpenSSL: + +Generate the private key: +```sh +openssl genrsa -out private.key 1024 +``` + +Generate the self-signed certificate: +```sh +openssl req -new -x509 -days 3650 -key private.key -out public.crt -subj "/C=country/ST=state/L=location/O=organization/CN=domain" +``` + +### Windows + +Minio only supports key/certificate in PEM format on Windows. Currently we do not yet support PFX certificates. + +#### Install GnuTLS + +Download and decompress the Windows version of GnuTLS from [here](http://www.gnutls.org/download.html) + +Make sure to add extracted GnuTLS binary path to your system path. +``` +setx path "%path%;C:\Users\MyUser\Downloads\gnutls-3.4.9-w64\bin" +``` + +You may need to restart your powershell console for this to take affect. + +#### Generate private.key + +Run the following command to create `private.key` +``` +certtool.exe --generate-privkey --outfile private.key +``` + +#### Generate public.crt + +Create a file `cert.cnf` with all the necessary information to generate a certificate. + +``` +# X.509 Certificate options +# +# DN options + +# The organization of the subject. +organization = "Example Inc." + +# The organizational unit of the subject. +#unit = "sleeping dept." + +# The state of the certificate owner. +state = "Example" + +# The country of the subject. Two letter code. +country = "EX" + +# The common name of the certificate owner. +cn = "Sally Certowner" + +# In how many days, counting from today, this certificate will expire. +expiration_days = 365 + +# X.509 v3 extensions + +# DNS name(s) of the server +dns_name = "localhost" + +# (Optional) Server IP address +ip_address = "127.0.0.1" + +# Whether this certificate will be used for a TLS server +tls_www_server + +# Whether this certificate will be used to encrypt data (needed +# in TLS RSA ciphersuites). Note that it is preferred to use different +# keys for encryption and signing. +encryption_key +``` + +Generate public certificate +``` +certtool.exe --generate-self-signed --load-privkey private.key --template cert.cnf --outfile public.crt +``` + +## 3. Configure Minio with the generated certificate + +Copy the generated key and certificate under `certs` in your Minio config path (by default in your HOME directory `~/.minio` on Linux or `C:\Users\\.minio` on Windows) using the names `private.key` and `public.crt` for key and certificate files respectively. + +## 4. Install third-party CAs + +Minio can be configured to connect to other servers, whether Minio nodes or servers like NATs, Redis. If these servers use certificates that are not registered in one of the known certificates authorities, you can make Minio server trust these CAs by dropping these certificates under Minio config path (`~/.minio/certs/CAs/` on Linux or `C:\Users\\.minio\certs\CAs` on Windows). + +# Explore Further +* [Minio Quickstart Guide](https://docs.minio.io/docs/minio-quickstart-guide) +* [Minio Client Complete Guide](https://docs.minio.io/docs/minio-client-complete-guide)