This document explains how to obtain a Let's Encrypt certificate and install it on Cisco Business Dashboard using the Command Line Interface (CLI). If you want general information on managing certificates, check out the article Manage Certificates on the Cisco Business Dashboard.
Let’s Encrypt is a Certificate Authority that provides free, Domain Validation (DV) SSL certificates to the public using an automated process. Let's Encrypt provides an easily accessible mechanism for obtaining signed certificates for web servers, giving the end-user confidence that they are accessing the correct service. For more information on Let's Encrypt, visit the Let’s Encrypt website.
Using Let's Encrypt certificates with Cisco Business Dashboard is reasonably straightforward. Although Cisco Business Dashboard has some special requirements for certificate installation beyond just making the certificate available to the webserver, it is still feasible to automate the issuing and installation of the certificate using the command line tools provided.
To issue and renew certificates automatically, the Dashboard web server must be reachable from the Internet. If this is not the case, a certificate can be easily obtained using a manual process and then installed using the command line tools. The remainder of this document walks through the process of issuing a certificate and installing it in the Dashboard.
If the Dashboard web server is reachable from the Internet on standard ports TCP/80 and TCP/443, it is possible to automate the certificate management and install process. Check out Let’s Encrypt for Cisco Business Dashboard for details.
The first step is to obtain software that uses the ACME protocol certificate. In this example, we are using the certbot client, but there are many other options available.
To obtain the certbot client, use the Dashboard or another host running a Unix-like OS (e.g. Linux, macOS) and follow the instructions on certbot client to install the client. In the dropdown menus on this page, select None of the Above for Software and your preferred OS for System.
It is important to note that in this article, blue sections are prompts and output from CLI. The white text lists commands. Green colored commands, including dashboard.example.com, pnpserver.example.com, and user@example.com should be replaced with DNS names that are appropriate for your environment.
To install the certbot client on the Cisco Business Dashboard server, use the following commands:
cbd:~$sudo apt update cbd:~$sudo apt install software-properties-common cbd:~$sudo add-apt-repository ppa:certbot/certbot cbd:~$sudo apt update cbd:~$sudo apt install certbotCreate a working directory to contain all the files associated with the certificate. Note that these files include sensitive information such as the private key for the certificate and account details for the Let's Encrypt service. While the certbot client will create files with appropriately restrictive permissions, you should ensure that the host and the account being used are restricted for access to only authorized staff.
To create the directory on the Dashboard, Enter the following commands:
cbd:~$mkdir certbot cbd:~/certbot $cd certbotRequest a certificate using the following command:
cbd:~/certbot$certbot certonly --manual --preferred-challenges dns -d dashboard.example.com -d pnpserver.example.comThis command instructs the Let's Encrypt service to validate ownership of the hostnames provided by prompting you to create DNS TXT records for each of the names listed. Once the TXT records have been created, the Let's Encrypt service confirms the records exist and then issues the certificate. Finally, the certificate is applied to the dashboard using the cisco-business-dashboard utility.
The parameters on the command are required for the following reasons:
| certonly | Request a certificate and download the files. Do not attempt to install them. In the case of Cisco Business Dashboard, the certificate is not only used by the web server, but also by the PnP service and other functions. As a result, the certbot client is not able to install the certificate automatically. |
| --manual | Do not attempt to automatically authenticate with the Let's Encrypt service. Work interactively with the user to authenticate. |
| --preferred-challenges dns | Authenticate using DNS TXT records. |
-d dashboard.example.com -d pnpserver.example.com |
The FQDNs that should be included in the certificate. The first name listed will be included in the Common Name field of the certificate, and all names will be listed in the Subject-Alt-Name field. The pnpserver.<domain> name is a special name used by the Network Plug and Play feature when performing DNS discovery. Consult the Cisco Business Dashboard Administration Guide for more details. |
--logs-dir . --config-dir . --work-dir . |
Use the current directory for all the working files created during the process. |
| --deploy-hook “…” | Use the cisco-business-dashboard command line utility to take the private key and the certificate chain received from the Let's Encrypt service and load them into the dashboard application in the same way as if the files were uploaded through the Dashboard User Interface (UI). The root certificate that anchors the certificate chain is also added to the certificate file here. This is required by certain platforms being deployed using Network Plug and Play. |
-cat <fullchain certificate file> /etc/ssl/certs/DST_Root_CA_X3.pem >/tmp/cbdchain.pem
cisco-business-dashboard importcert -t pem -k <private key file> -c /tmp/cbdchain.pem
Go through the process of creating the certificate by following the instructions generated by the certbot client:
cbd:~/certbot$certbot certonly --manual --preferred-challenges dns -d dashboard.example.com -d pnpserver.example.comEnter the email address or C to Cancel.
Enter email address (used for urgent renewal and security notices) (Enter 'c' to cancel): user@example.comEnter A to agree or C to cancel.
Please read the Terms of Service atEnter Y for Yes or N for No.
Would you be willing to share your email address with the Electronic FrontierEnter Y for Yes or N for No.
NOTE: The IP of this machine will be publicly logged as having requested thisA DNS TXT record to validate the ownership of the dashboard.example.com hostname must be created in the DNS infrastructure. The steps required to do this are outside the scope of this document and will depend on the DNS provider being used. Once created, validate that the record is available using a DNS query tool such as Dig.
The DNS challenge process may be automated for certain DNS providers. See DNS Plugins for more details.
Press Enter on your keyboard.
Before continuing, verify the record is deployed.You will receive a similar CLI output. Create and verify additional TXT records for each name to be included in the certificate. Repeat Step 9 for each name specified in the certbot command.
Press Enter on your keyboard.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -The certificate has been issued and may be found in the live subdirectory in the filesystem:
Waiting for verification...Enter the following commands:
cbd:~/certbot$cd live/dashboard.example.com/ cbd:~/certbot/live/dashboard.example.com$lsThe directory containing the certificates has restricted permissions so only the cisco user can view the files. The privkey.pem file, in particular, is sensitive and access to this file should be restricted to authorized personnel only.
The Dashboard should now be running with the new certificate. If you open the Dashboard User Interface (UI) in a web browser by entering any of the names specified when creating the certificate in the address bar, the web browser should indicate that the connection is trusted and secure.
Please note that certificates issued by Let's Encrypt have relatively short lifetimes – currently 90 days. To ensure the certificate remains valid, you will need to repeat the process described above before the 90 days are up.
For more information about the use of the certbot client, consult the certbot documentation page.