The Mako Server includes automatic installation of certificates by using the free Certificate Authority Let's Encrypt™. All you need to do is to create a configuration file, and the Mako Server will do the rest.
The Automatic Certificate Management Environment (ACME) defined in RFC-8555 is a protocol that enables automatic installation of certificates.
The Mako Server includes a programmable ACME plugin that may be activated by using the Mako Server's configuration file or activated programmatically by directly interacting with the Lua modules. The ACME protocol automates the CSR signing process, but just like any other CA, Let's Encrypt requires proof of ownership.
Proof of ownership can be provided by one of the two challenge options Let's Encrypt provides, http-01 and dns-01. The Mako Server supports both challenge options, in which the http-01 challenge option is used for public servers and the dns-01 challenge option is used for private servers.
See the Let's Encrypt How It Works tutorial if you are new to Let's Encrypt.
The following two examples show how to use the http-01 challenge option for a public server running on a VPS and the dns-01 challenge option for a private server running on a home/office computer.
For both examples, download the Mako Server to the target computer and unpack the server in any directory. Use an editor and create a mako.conf file in the same directory as the Mako Server.
The following example also works for a private (Intranet) server if you have configured port forwarding in your router, but note that the server must be accessible via non secure HTTP on port 80. Let's Encrypt communicates with your server using this port number.
Copy the following and paste the configuration data into your mako.conf file, but make sure to change the email address. Let's Encrypt requires a valid address. You must also set the domain name to a name you own. A DNS tutorial can be found further down in this tutorial.
Save the file and start the Mako Server. The command on line 1 below shows how to start the server on Linux as user root. We must start it this way since the server must listen on port 80. See the Getting Started Guide for more information.
Notice how the Mako Server initially loads an embedded certificate (line 5). This certificate is not trusted by your browser but is needed since we initially do not have a Let's Encrypt certificate.
Communicating with Let's Encrypt takes time and line 8 and 9 above are printed roughly 10 seconds after starting the server. The server has at this point installed a certificate that is valid for the requested domain name and you may navigate to https://your-domain-name. The following figure shows the Mako Server's default page and the Let's Encrypt signed certificate's chain of trust.
A much more detailed tutorial on using the many configuration options for the dns-01 option can be found further down in this tutorial and we will not go into the details for how the next example works. You can simply copy the configuration data below and paste the data into mako.conf, but make sure to change the email address to your own address and the sub-domain name "john-doe" (the 'domains' setting) to your own name.
Save the file and start the Mako Server. The Mako Server does not need to listen on port 80 and 443 when using the dns-01 challenge option, but it is much easier to use and understand the example if the server listens on the default ports. We use the same Linux command for starting the server. On Windows, you would just type: mako.
In Figure 3, when using the http-01 challenge option, line 8 and 9 were printed roughly 10 seconds after starting the server. When using the dns-01 challenge option, this takes much longer and it will take roughly 2.5 minutes before you see the two printouts.
In Figure 6, the private server is locally available on the LAN by navigating to: https://john-doe.local.makoserver.net.
As will be explained in detail later, there are many configuration options for using the dns-01 challenge option. The configuration options selected in Figure 5 uses the dns-01 challenge option with the testing domain https://local.makoserver.net. The Mako Server includes an integrated zone key for this testing domain and this testing domain is hosted by Real Time Logic's DNS testing service. You may create your own zone key using your own domain name and you may host your own DNS server. You may also use the dns-01 challenge option without the DNS service as will be explained further down in this tutorial.
One of the more common Mako Server and Barracuda App Server use cases is to integrate the server solution in devices designed to be run and operated on private networks or in environments with no network.
The rest of this tutorial explains in detail how to provide proof of ownership for private servers. We will explain in detail how to use the Let's Encrypt dns-01 challenge option, which is the only challenge option that may be used by servers not publicly available on the Internet.
This tutorial covers the following:
The traditional solution for dealing with SSL certificates for servers running on private networks has been to implement a custom Certificate Authority (CA) and its associated chain of trust by, for example, using Real Time Logic's free Certificate (PKI) Management Tool .
Setting up a custom CA has several drawbacks, including requiring a good understanding of certificate management by the end user and installation of the CA's root certificate in all client devices (browser) for the device(s) to be trusted.
Let's Encrypt's root certificate is pre-installed in all common client devices (e.g. browsers) and a server certificate signed by Let's Encrypt is automatically trusted by clients as long as the device can be reached by the domain name its SSL certificate is signed for.
Managing domain names for servers running on private networks or servers without a network requires minimal understanding by the end user when properly set up. This process can also be automated as we will show later in this tutorial. However, let's first start with a domain name tutorial to show the many options you have as a product designer when it comes to providing easy secure access to embedded web servers.
A private network is a network using privately assigned network addresses such as IP addresses in the range 192.168.x.x and where the IP addresses cannot be reached from the Internet. We will show how to use an online DNS server to provide DNS services for resolving private IP addresses. For devices with no network and when an Ethernet crossover cable is used, a DNS entry in the client computer's host file may be necessary.
Devices are typically assigned subdomain names and a fully qualified device name may for example be devicename.product.company.com, in which product.company.com is a subdomain of company.com with its own DNS service.
In this tutorial, we use the free domain name registrar freenom. The domain name we chose for this tutorial is realtimelogic.tk and we will add two sub domain names, one for device1 and one for device two. The two fully qualified domain names are:
You can follow along this tutorial by creating a freenom account and by registering your own domain name.
The following figure shows the freenom's DNS Management page for the domain name realtimelogic.tk. The screenshot shows we have added the public WAN IP address for the top domain realtimelogic.tk and the subdomain device1, just before adding a new record for device2.
The two private IP addresses are for two PCs running in our network. If you are following along this tutorial, set the IP address to your own local computer. Note that the purpose with adding the public WAN IP address for the top domain is to make sure Let's Encrypt accepts our DNS settings. The top domain realtimelogic.tk is the one in the above screenshot where the name field is blank. You do not need a web server at this address, but the address must be publicly available and can, for example, be set to your WAN IP address.
Your own PC is probably assigned a dynamic IP address by the DHCP server. We have set a short TTL for the DNS settings if we should need to change the IP settings, but usually, locally connected computers get the same IP address when restarted since the DHCP server remembers the client computer's MAC address. We will later show how Mako Server can dynamically update DNS settings by using a DNS service.
After adding the DNS settings, we can open a command window and check if the device domain names resolve. The following example shows how to check one of the domain names:
x:\>ping device1.realtimelogic.tk Pinging device1.realtimelogic.tk [192.168.1.100] with 32 bytes of data: Reply from 192.168.1.100: bytes=32 time<1ms TTL=128
After making sure the DNS works, we can start any web server on the PC with this IP address. The following screenshot shows the Mako Server accessible via the domain device1.realtimelogic.tk:
As you can see from the above screenshot, we are using an HTTP connection and the browser shows this as "Not secure". We get a certificate error if we change to https since we have thus far not installed a certificate for the domain name device1.realtimelogic.tk.
So now that we have covered DNS, it's time to create a certificate for our domain name and have Let's Encrypt sign our certificate with its publicly trusted root.
The Mako Server makes it possible to have Let's Encrypt sign certificates for non public servers by using what is known as the dns-01 challenge option. This option shows domain ownership proof by setting a DNS TXT record.
The Mako Server includes an option for automatically setting the DNS entry, but this requires using our online DNS service. We will discuss the automatic DNS option later. We can also configure the Mako Server for manual DNS TXT entry mode by having the Mako Server inform the user when it is time to set the DNS TXT record.
For the next tutorials, download the Mako Server and get familiar with running the server in console mode.
Open a console window in a directory suitable for creating some test files and directories. The Mako Server must be in the PATH environment variable or the Mako Server's full pathname must be provided when starting the server -- e.g. c:\installdir\mako.
Create the following directory and two files:
│──── mako.conf │ └─+──www │ └──── index.lsp
Use an editor and insert the following into mako.conf
Change the email address above to a valid address and change the domain name to your own registered domain.
Insert the following into www/index.lsp:
The 'acme' mako.conf configuration option enables the ACME plugin. See the Mako Server's online Let's Encrypt documentation for more information. The LSP file www/index.lsp calls acmedns.recordset(). The LSP page must be executed after setting the DNS TXT entry. This will be explained below.
Start Mako Server in the console window as follows:
x:\>mako -l::www Mako Server. Version 3.0 BAS lib 4402. Build date: Jul 2 2019 Copyright (c) Real Time Logic. Loading x:\\mako.conf. Trace file: mako.log Mounting mako.zip Server listening on IPv6 port 80 Server listening on IPv4 port 80 Loading certificate MakoServer SharkSSL server listening on IPv6 port 443 SharkSSL server listening on IPv4 port 443 Info: www/.preload not found Loading www as "root application" : ok Set ACME DNS TXT Record: Record name: _acme-challenge.device1.realtimelogic.tk Record data: UctRs7Sq51Y7_hSECQFBcBr_jCe5tjQXMqQPwWBP7Ro
The above command line option instructs Mako Server to load the 'www' application where we have the index.lsp page. Notice from the above printouts that Mako Server loads our configuration file. After a few seconds, you should see the text "Set ACME DNS TXT Record". Navigate to freenom (or any other domain name registrar you are using) and set the TXT record for your domain as shown below:
The default is to set the 'A' record so make sure to change the type to 'TXT' as shown above.
The Mako Server's ACME engine is, at this point, paused and we must resume the operation by calling function acmedns.recordset() . However, after setting the TXT record, give the DNS server at least two minutes to replicate the data before continuing. You may have to wait 10 minutes if using freenome. This is a good time to take a coffee break.
If you have 'dig' installed, you may check the record as follows:
dig +short _acme-challenge.device1.realtimelogic.tk TXT "xYTPUjSj4ArzEVNT0pG1dXrdRuFqmYOxQK4qXs15gBo"
After two or more minutes, open a browser and navigate to http://device.domain-name.tk as shown in the screenshot below.
Recall that the LSP page index.lsp calls acmedns.recordset() and prints the result from this function. The function returns true, meaning that the ACME engine was in a paused state and that calling the function resumed operation.
After a few seconds, you should see the following in the console window:
ACME: device1.realtimelogic.tk renewed Loading certificate "cert/device1.realtimelogic.tk.cert.pem"
The new certificate is now loaded, and we can simply change the URL from http:// to https:// as shown in the screenshot below:
Notice the error message from index.lsp above. Since we are re-executing index.lsp, function acmedns.recordset() returns 'nil, "error message"', letting the user know that the DNS challenge state is inactive.
Since the Mako Server is a tool and not a ready to use end product, you must design a supporting web application that, at a minimum, lets the user resume the ACME state machine by calling function acmedns.recordset() no sooner than two minutes after the DNS record has been set. You may also design a web application that programmatically controls the ACME plugin.
Staging environment v.s. Production environment
The certificate you get when using the mako.conf file created in figure 11 uses Let's Encrypt's staging environment and not the production environment. The certificate will, for this reason, not be trusted by the browser. Please make sure you can successfully use the staging environment prior to switching to the Let's encrypt production environment. When switching to the production environment, the account information saved in cert/account.json will be invalid. The Mako Server prints a nasty error message, but recovers and creates a new Let's Encrypt account using the production environment.
The Mako Server would typically not be run in a console window for deployed applications and the DNS text record printed would not be visible. For this reason, the log module must be enabled such that the user receives an email when it is time to renew the certificate. The Mako Server's ACME plugin checks if the certificate needs to be renewed one time every 24 hours and dispatches an email to the configured recipient with the DNS TXT record information when it is time to renew the certificate.
The options we have presented so far require a permanent Internet connection by either a direct connection via company router or company proxy. See the proxy options if the private network is behind a proxy.
Sometimes devices with embedded web servers are deployed in environments without a permanent Internet connection.
For example, maintenance personnel may connect a laptop directly to a device using an Ethernet crossover cable. For this setup to work, the laptop must be connected to the Internet by using, for example, a cellular modem and the laptop must be configured such that the device can connect to the Internet via the PC when the device is being managed.
With such a network setup, the Mako Server's ACME plugin should be used directly by a dedicated web application that lets the personnel renew the certificate when plugged in. The Mako Server documentation includes an example that shows how to programmatically control the acmedns module .
You may receive an error similar to the following if you have followed the above tutorial for the manual DNS challenge option and if using a freenom.com domain.
ACME: renewing device1.realtimelogic.tk failed: DNS problem: SERVFAIL looking up CAA for device1.realtimelogic.tk - the domain's nameservers may be malfunctioning.
The freenom name server sometimes appears to be overloaded and Let's Encrypt may have stringent requirements. You can simply try again later if you get this error or use a paid for domain name.
Note that the Automatic DNS Challenge Option works without a problem when using a freenom domain.
Using the automatic DNS option is by far the easiest option since the end user does not need to set DNS TXT records or update the DNS A record if the device IP address should change.
The automatic DNS option requires the use of Real Time Logic's DNS service, which is specifically designed to help Mako Server and Barracuda App Server deployments automatically maintain the "DNS A record" (IP address) and set the "ACME DNS TXT record" when it is time to renew.
The Mako Server initially registers the device with the online DNS service and authenticates by using the zone key received after signing up for the DNS service. The Mako Server also sends a message to the DNS service if its IP address should change. When it is time to renew, Mako Server starts the renewal process by communicating with Let's Encrypt and the DNS service when Let's Encrypt requests proof of ownership.
When using the automatic option, devices are assigned a subdomain either by using the mako.conf file or programmatically by directly controlling the ACME plugin.
The fully qualified device name may, for example, be devicename.product.company.com, in which product.company.com is a subdomain of company.com with its "product" subdomain managed by Real Time Logic's DNS service.
Navigate to your freenom.com account and click "Manage Domain". Click "Management Tools" -> Nameservers. Select custom nameservers and enter the two following for nameserver 1 and 2.
Click the save button and wait until the changes have replicated across the Internet's whois database. This may take up to 48 hours. One way to test if the settings are ready is to run the whois command line program for your domain name. Whois should list the above name servers.
When whois reports the correct name servers, navigate to https://acme.realtimelogic.com
Sign up for the DNS service and follow the signup process. The DNS service sends you an email with the zone account key when the registration is complete.
Open mako.conf (figure 11), remove 'url="manual"' and add 'key="the key from the email you received"'. The domain name entry should only include the device subdomain name -- e.g. "device". See the second example in the Mako Server's online Let's Encrypt documentation for more information.
Start Mako Server in the console window as follows:
x:\>mako Mako Server. Version 3.0 BAS lib 4402. Build date: Jul 2 2019 Copyright (c) Real Time Logic. Loading x:\mako.conf. Trace file: mako.log Mounting mako.zip Server listening on IPv6 port 80 Server listening on IPv4 port 80 Loading certificate MakoServer SharkSSL server listening on IPv6 port 443 SharkSSL server listening on IPv4 port 443 ACME: device.realtimelogic.tk renewed Loading certificate "cert/device.realtimelogic.tk.cert.pem"
It takes more than two minutes before the last two printouts in figure 18 are printed to the console. The Mako Server ACME plugin waits two minutes after requesting the online DNS service to set the records before it continues. This makes sure the Let's Encrypt service can successfully verify the DNS TXT record.
The automatic DNS mode makes sure the certificate is valid and automatically renews the certificate without any user interactions. The user is informed by email each time the certificate is renewed if the data logging option is enabled.
Real Time Logic's DNS service is primarily designed as an initial development aid, letting developers test the automatic DNS feature without having to set up their own DNS server. The software for the online service is a source code product provided by us, and you may use the software to host your own service either directly or with help from our consulting partners.The source code for Real Time Logic's DNS service is available on GitHub.
The free DNS testing service must not be used for production mode, and product manufacturers should consider setting up their own service. Real Time Logic's DNS service runs on one online VPS and uses bind for the DNS management. The bind service is controlled by a Lua powered application running on a Mako Server instance. Contact Real Time Logic for details on running your own DNS service if you need help with installing the DNS software available on GitHub.
When a company registers a domain, such as product.company.com, with Real Time Logic's DNS service, a dedicated online web interface is created for the registered domain name. All devices registered for the particular domain name get listed online and may be viewed by the registered administrator after authenticating. In addition, any person without authentication requirements may view the devices registered for the location from where the user is located. This construction makes it easy to find devices that get its IP address via DHCP. In other words, the typical static IP configuration needed for server devices is not needed. The online DNS service greatly simplifies device deployment since devices can be shipped and deployed without requiring any network configurations by the end user.