WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Setting up

  1. install certbot on your server
  2. install openssl on your server if it is not already
  3. determine a HTTP fulcrum to use, usually the urn:org:netkernel:fulcrum:frontend is a good choice
  4. expand fulcrum jar to a filesystem directory if it is currently deployed as jar
  5. uncomment sslHttpConfig, sslContextFactory, and sslConnector in /etc/HTTPServerConfig.xml as described in Configuring SSL.
  6. create a letsencrypt.xml file in the install/etc/ directory of your NetKernel installation with the form described below.
  7. click deploybutton on control panel Extras > Let's Encrypt.

<config>
  <fulcrum>urn:org:netkernel:fulcrum:frontend</fulcrum>
  <hostingImportHook>HTTPFulcrumInsecure</hostingImportHook>
  <domains>mydomain.com,www.mydomain.com</domains>
  <contactEmail>webmaster@mydomain.com</contactEmail>
</config>

Other steps/considerations

  1. HTTPS certificates require a domain name and DNS entry. This can be tricky on a development machine though you can do it an entry in /etc/hosts in Linux/MacOS.
  2. Best practice is to use a firewall to map 80 to 8080 and 443 to 8443. This avoids NetKernel running as root but does require some setup.

Config fields

  • fulcrum - the URI of the module hosting the HTTP server (the fulcrum)
  • hostingImportHook - your fulcrum should contain a dynamic import and this field must match the configured type. This is used to allow the HTTP server to host the transient secrets used in the certificate negotiation.
  • domains - a comma separated list of the hosted domains to provide obtain certificates for
  • contactEmail - a condition of using the Let's encrypt service is that you agree to it's terms of service, by providing your email you are agreeing.

If you change the domains field to support more, or less, or different domains then it is best to delete the [ install ]/letsencrypt/ directory and start fresh - otherwise LetsEncrypt gets confused about the conflict and fails.

How it works

This module creates a space that makes your web server host a directory containing secrets files that Let's Encrypt creates. Let's Encrypt's server look for these files on port 80 of your hosted domain and uses them to verify that you actually own and control the contents on it's server.

Once Let's Encrypt trusts your server to be who you say it is, it will generate an X509 certificate for you. This tool uses openssl to convert that certificate into a java keystore with a random password. The keystore is then registered in the fulcrums HTTPServerConfig.xml. After updating the configuration the HTTP server is restarted to pick up the new certificate.

Because Let's Encrypt certificates only last for 90 days they must be renewed frequently. This module provides a CRON job which runs every day to see if a new certificate needs generating. When it does it will be automatically deployed.

Certbot runs not as root; because of this it requires some filesystem directories as working space. These are located inside the netkernel install directory [ install ]/letsencrypt/. Deleting this directory will reset Let's Encrypt back to factory state.