diff --git a/docs/kernelcare-enterprise/README.md b/docs/kernelcare-enterprise/README.md index 146654b3..5afa71a9 100644 --- a/docs/kernelcare-enterprise/README.md +++ b/docs/kernelcare-enterprise/README.md @@ -1222,21 +1222,38 @@ This can be called during machine tear down to properly remove the server from e ## How to setup ePortal to use HTTPS -Some assumptions for a server where e-portal is deployed: +### Prerequisites -### Terminate TLS on ePortal public nginx web server +There are some prerequisites for a server where ePortal is deployed, that should be satisfied at first. + +1. A firewall should allow connections to the 443 port +2. Private and public keys should be downloaded to the server -1. A firewall allows connections to 443 port. -2. Private and public keys are downloaded on the server. +### Terminate TLS on ePortal public nginx web server -* Edit SSL configuration template according to your certificates: +* Use ePortal SSL template `/etc/nginx/eportal.ssl.conf.example` and modify it accordingly your domains and certificates. ``` mv /etc/nginx/eportal.ssl.conf.example /etc/nginx/eportal.ssl.conf vi /etc/nginx/eportal.ssl.conf ``` -* Include this configuration into the main one: +There are three main parameters: + + * `server_name` defines domain name(s) accordingly to your SSL certificate + * `ssl_certificate` is a path to your SSL certificate + * `ssl_certificate_key` is a path to your certificate's private key + +- Add `include` instruction to the main configuration file `/etc/nginx/conf.d/eportal.conf` that will include all SSL-specific parameters into it: + +``` +server { + listen 80; + include eportal.ssl.conf; + ... +``` + +or use a shell script, that will do the same: ``` sed -e '3iinclude eportal.ssl.conf;' -i /etc/nginx/conf.d/eportal.conf @@ -1248,46 +1265,34 @@ sed -e '3iinclude eportal.ssl.conf;' -i /etc/nginx/conf.d/eportal.conf service nginx restart ``` -### Terminate TLS on external balancer +### Terminate TLS on an external balancer -You can use any reverse proxy server of choice to terminate TLS traffic and -forward requests to ePortal instance. The only requirement is to provide correct +You can use any reverse proxy server of your choice to terminate TLS traffic and +forward requests to the ePortal instance. The only requirement is to provide the correct `Host` and `X-Forwarded-Proto` headers. For example balancer nginx config: ``` server { - listen 443 ssl; - server_name your-eportal-domain; - - # ssl stuff ... - # ssl_certificate ... - # ssl_certificate_key ... - - location / { - proxy_pass http://eportal-instance-address; - proxy_set_header Host $http_host; - proxy_set_header X-Forwarded-Proto https; - } + listen 443 ssl; + server_name your-eportal-domain; + # ssl stuff ... + # ssl_certificate ... + # ssl_certificate_key ... + location / { + proxy_pass http://eportal-instance-address; + proxy_set_header Host $http_host; + proxy_set_header X-Forwarded-Proto https; + } } ``` ### Update agent configuration -In order to communicate with e-portal, updated to https, you need to modify -KernelCare configuration file on all the servers if they have IPs hard coded servers -settings. +To communicate with ePortal, updated to https, you need to modify KernelCare configuration file on all the servers where KernelCare was already installed. All clients installed after will be configured automatically. -To do that, update `PATCH_SERVER` and `REGISTRATION_URL` options: - -``` -vi /etc/sysconfig/kcare/kcare.conf -``` - -So, after editing your `/etc/sysconfig/kcare/kcare.conf` should contain updated -`PATCH_SERVER` and `REGISTRATION_URL` environment variables like in the example -below: +You can migrate agents to a new endpoint manually, by updating `PATCH_SERVER` and `REGISTRATION_URL` options in `/etc/sysconfig/kcare/kcare.conf` file: ``` PATCH_SERVER=https://eportal_domain_name/ @@ -1300,6 +1305,39 @@ As an alternative you can use ePortal's special endpoint to update patch server curl -s https://eportal_domain_name/set-patch-server | bash ``` +### How to use Let's Encrypt with ePortal + +First of all you should install [certbot](https://eff-certbot.readthedocs.io/en/stable/install.html) and assuming that you have an A-record pointing to `example.com` you can run the following command to generate a new certificate: + +``` +sudo certbot --nginx -d example.com -d www.example.com +``` + +That will provide public and private key to use in ePortal's SSL configuration: + +``` +ls /etc/letsencrypt/live/example.com/ +cert.pem chain.pem fullchain.pem privkey.pem README +``` + +Now you should update your nginx configuration (depends on which SSL termination option you selected): update path to you keys and a server name: + +``` +server_name example.com; +ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; +ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; +``` + +Now apply changes by nginx restart + +``` +service nginx restart +``` + +After that you can check your certificate with following link: + + https://www.ssllabs.com/ssltest/analyze.html?d=example.com + ## High availability