Difference between revisions of "Administration Console and CLI Certificate Tools"

Line 63: Line 63:
=ZCS Certificate CLI=
=ZCS Certificate CLI=
The ZCS Certificate CLI commands for 7.0.x, 6.0.x and 5.0.x differ from 4.5.x. The following sections discuss the CLI tools for each version.
The ZCS Certificate CLI commands for 8.x, 8.0.x, 7.0.x, 6.0.x and 5.0.x differ from 4.5.x. The following sections discuss the CLI tools for each version.
==ZCS 8.x, 8.0.x, 7.0.x, 6.0.x, and 5.0.x==
==ZCS 8.x, 8.0.x, 7.0.x, 6.0.x, and 5.0.x==
Line 471: Line 471:
   tomcat start
   tomcat start
{{Article Footer|ZCS 4.5.x & 5.0.x|9/10/2008}}
{{Article Footer|ZCS 8.x, 8.0.x, 7.0.x, 6.0.x |9/10/2008}}

Revision as of 14:32, 3 October 2014

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.5 Article ZCS 8.5ZCS 8.0 Article ZCS 8.0 ZCS 7.0 Article ZCS 7.0

Note: For information about iPhone SSL certificates, see http://wiki.zimbra.com/wiki/IPhone

ZCS allows administrators to manage their certificates using either the Administration Console or the Command Line Interface (CLI). This article discusses the ZCS 8.5, 8.0.x, 7.0.x, 6.0.x, and 5.0.x Administration Console, and the CLI tools for ZCS 7.0.x, 6.0.x, 5.0.x and 4.5.x.

ZCS Administration Console Certificates Tools

The ZCS Certificates tools are located in the Navigation pane, under Tools>Certificates. Once you have selected Certificates from this menu, the Manage Certificates tab opens in the Content pane. From here, you can view your deployed certificates or install a new certificate.


In Zimbra 8.0.x and above we will find the ZCS Certificates in the Navigation pane, under Configure>Certificates SSL Install Web 001.png SSL Install Web 002.png

Viewing Certificates

Using the Administration Console, you can view the details of certificates currently deployed. Details include the certificate subject, issuer, validation days, and subject alternative name.

To view a certificate, select a service host name, either under Certificates in the Navigation pane or by selecting a Service host name in the Manage Certificates tab and clicking View Certificate. A Certificates tab for the service host name you selected opens in the Content Pane.

SSL Install Web 003.png

Information about the certificate: SSL Install Web 004.png

You can refresh the currently displayed details by clicking Refresh at the top of the tab.

Installing Certificates

Clicking Install Certificate from either the Manage Certificates tab or a Certificates tab opens the Certificate Installation Wizard. The Certificate Installation Wizard is a tool that will help you quickly create and deploy a certificate.

Generating & Installing a Self-Signed Certificate

Sometimes we want to regenerate the Self-Signed Certificate, we can do it in the Administration Console. We need to click in the Cog>Select Install Certificate and follow the steps:

The first step is select Install the self-signed certificate SSL Install Web 005.png

Next, we need to mark the checkbox Replace the existing CSR SSL Install Web 006.png

We need to be sure of select the Key Length at 2048, the rest of the fields, is not necessary to change it, because are hard-coded and it will be included automatically. SSL Install Web 007.png

We can select also the time that we want to have this SSL validated, remember that is Self-Signed, if we are not planning any future change, we can select more than a year. And then press Install. SSL Install Web 008.png

The SSL Certificate Self-Signed are now installing in our Zimbra Collaboration Server. SSL Install Web 009.png

Once the installation has finish, the system request us a restar of the ZCS services. SSL Install Web 010.png

Trough console by user zimbra we need to execute the next command, and wait until all services are up again:

zmcontrol restart

If we will go again to our https://mail.domain.com we will have the known problem with SSL Certificate in our Web Browser: SSL Install Web 011.png

Generating Multiple CSRs using the Administration Console

Currently the Administration Console only supports having one Certificate Signing Request (CSR) and private key at a time. Generating a new CSR overrides the existing one and generates a new private key. To generate more than one CSR, move both the CSR and key from the directory it is generated in (E.g. /opt/zimbra/ssl/zimbra/commercial directory/) before generating another CSR.

Maintaining Valid Certificates

It is important to keep your SSL certificates valid to ensure clients and environments work properly, as the ZCS system can become non-functional if certificates are allowed to expire. You can view deployed SSL certificates from the ZCS administrator console, including their validation days. It is suggested that certificates are checked periodically, so you know when they expire and to maintain their validity.

ZCS Certificate CLI

The ZCS Certificate CLI commands for 8.x, 8.0.x, 7.0.x, 6.0.x and 5.0.x differ from 4.5.x. The following sections discuss the CLI tools for each version.

ZCS 8.x, 8.0.x, 7.0.x, 6.0.x, and 5.0.x


This command allows you to manage certificates.

General Guidelines

Follow these guidelines when using this command.

  • This tool must be run as root
Commercial Certificate Guidelines

Follow these guidelines when using this command to generate a commercial certificate.

  • The private key must exist in the /opt/zimbra/ssl/zimbra/commercial directory, and must be named commercial.key with its permission set to 740
  • The server certificate and the chain certificate files must exist in a temp directory. (E.g. /root/certs/)
  • The chain certificate files must be concatenated into one file called commercial_ca.crt


zmcertmgr [options]


Name Description
General Options
-help Displays usage options for zmcertmgr
Self-Signed Certificate Options
createca [-new] [-keysize keysize] [-digest digest] [-subject subject] Generates a Certificate Authority (CA). The -new option forces the generation of a new CA.
deployca Deploys a CA.
createcsr <self|comm> [-new] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"] Creates a certificate signing request (CSR) for either a self or commercially signed certificate authority. The -new option forces the generation of a new CSR. The -keysize option allows you to set the keysize, for example "-keysize 2048". Recommended keysize is 2048 - in 8.0.7, it will be the default: https://bugzilla.zimbra.com/show_bug.cgi?id=85023. The -subject option allows you to specify the path in which the certificate is valid. The -subjectAltNames option allows you to specify additional hosts that may use the certificate other than the one listed in the subject. The default subject is "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}".
createcrt [-new] [-days validation days] [-keysize keysize] [-digest digest] [-subject subject] [-subjectAltNames "host1,host2"] Creates a self-signed certificate based on the CSR generated using createcsr. The -new option forces the generation of a new certificate. The -days option assigns a number of days for which the certificate is valid. The -subject option allows you to specify the path in which the certificate is valid. The -subjectAltNames allows you to specify additional hosts that may use the certificate other than the one listed in the subject. The default subject is "/C=US/ST=N\/A/L=N\/A/O=Zimbra Collaboration Suite/OU=Zimbra Collaboration Suite/CN=${zimbra_server_hostname}".
deploycrt <self> Deploys a self-signed certificate.
Self-Signed and Commercial Certificate Options
deploycrt <comm> [certfile] [ca_chain_file] Deploys a commercial certificate. Specify the certificate file and the certificate authority (CA) chain file.
savecrt Saves a certificate
viewcsr <self|comm> [csr_file] Shows a certificate signing request (CSR). Specify self if the CSR is self-signed. Specify comm if the certificate is commercial. Specify the CSR file to view.
viewdeployedcrt [all|ldap|mta|proxy|mailboxd] Shows a deployed certificate. This option only works for the local server.
viewstagedcrt <self|comm> [certfile] Shows a staged certificate. A staged certificate is placed in a staging file, where all files that will be deployed with the certificate are kept. You can use the staging area to verify that you are ready to deploy a certificate. Specify self if the certificate is self-signed. Specify comm if the certificate is commercial. Specify the certificate file to view.
verifycrt <self|comm> [priv_key] [certfile] Verifies a certificate. Specify self if the certificate is self-signed. Specify comm if the certificate is commercial. Specify the certificate key. Specify the certificate file.
verifycrtchain <ca_file> <certfile> Verifies a certificate chain. Specify self if the certificate is self-signed. Specify comm if the certificate is commercial. Specify the certificate key. Specify the certificate file.


The following are examples of using the above options for different installation scenarios.

Single-Node Self-Signed Certificate

1. Begin by generating a new Certificate Authority (CA).

 /opt/zimbra/bin/zmcertmgr createca -new

2. Then generate a certificate signed by the CA that expires in 365 days.

 /opt/zimbra/bin/zmcertmgr createcrt -new -days 365

3. Next deploy the certificate.

 /opt/zimbra/bin/zmcertmgr deploycrt self

4. Next deploy the CA.

 /opt/zimbra/bin/zmcertmgr deployca

5. To finish, verify the certificate was deployed to all the services.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt
Multi-Node Self-Signed Certificate

1. Begin by generating a new Certificate Authority (CA).

 /opt/zimbra/bin/zmcertmgr createca -new
 /opt/zimbra/bin/zmcertmgr deployca

2. Then generate a certificate signed by the CA that expires in 365 days with either wild-card or subject altnames.

 /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "*.example.com"
 /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subject "/C=US/ST=CA/L=NVA/O=ZCS/OU=ZCS/CN=*.example.com"
 /opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "host1.example.com,host2.example.come"

3. Next, deploy the certificate to all nodes in the deployment.

 /opt/zimbra/bin/zmcertmgr deploycrt self -allserver

4. To finish, verify the certificate was deployed.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Note: The option viewdeployedcrt only works for the local server.

Alternate Method

The "-allserver" command above doesn't always work as expected, depending on whether the ssh keys are current and working properly. One can also create the new ca first on an LDAP Master node, and then manually deploy the ca and create the self-signed certs on all the other nodes:

On an LDAP Master:

/opt/zimbra/bin/zmcertmgr createca -new
/opt/zimbra/bin/zmcertmgr deployca
/opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subject "/C=US/ST=CA/L=NVA/O=ZCS/OU=ZCS/CN=*.example.com"
/opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "host1.example.com,host2.example.com"
/opt/zimbra/bin/zmcertmgr createcrt -new -days 1825 -subjectAltNames "*.example.com"
/opt/zimbra/bin/zmcertmgr deploycrt self

On all other systems:

/opt/zimbra/bin/zmcertmgr createca
/opt/zimbra/bin/zmcertmgr deployca -localonly
/opt/zimbra/bin/zmcertmgr getcrt self
/opt/zimbra/bin/zmcertmgr deploycrt self
Single-Node Commercial Certificate

Some theory about SSL Certificates and words that we will use in this tutorial:

  • CSR (Certificate Signing Request): A CSR or also Certificate Signing request is a encrypted file with information about the company. This file is generated in our server, the Information that contains inside we discussed in a previous article. A Certificate authority uses this CSR for take the information and create the SSL Certificate.
  • Private Key: We told before that CSR is a encrypted file, we used for encrypt it a Private Key, that is unique. The CSR and the SSL certificate will only works if we have the Private key. So the best practice is do a Backup of the Private Key and the CSR just in case we can have any problem. But keep in a secure place.

We will moving us to the correct folder inside our Server for generate the files that we will need:

cd /opt/zimbra/ssl/zimbra/commercial/
Generating a Private key

We will use at least 2048-bit key, is the minimum for all Certificate Authorities:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# openssl genrsa -des3 -out zimbrahelp.key 2048
e is 65537 (0x10001)
Enter pass phrase for zimbrahelp.key: zimbrahelp123
Verifying - Enter pass phrase for zimbrahelp.key: zimbrahelp123

Now, we need to remove the password from the Private Key, Zimbra can have problems later importing the Certificate, so is better to remove the password now, it will ask for the password one more time:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# openssl rsa -in zimbrahelp.key -out zimbraprivate.key

And if you want, we can delete the old private key with password, because we will not use it anymore:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# rm zimbrahelp.key
Generating the CSR

Note: We need to take care with the next fields, it's necessary let them blank.

  • Email address
  • Optional Password
  • Optional Company Name
zimbra@help:/opt/zimbra/ssl/zimbra/commercial# openssl req -new -key zimbraprivate.key -out zimbracsr.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code):US
State or Province Name (full name) [Some-State]:Texas
Locality Name (eg, city) []:Frisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Zimbra
Organizational Unit Name (eg, section) []:Documentation
Common Name (e.g. server FQDN or YOUR name) []:help.zimbra.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Checking the content of the SSL Certificate

Now, is time to check if everything was good, we need to run this command:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# openssl req -noout -text -in zimbracsr.csr

Other good method to check if everything is allright is using external websites, the only thing that we need to do is paste our CSR content, we can view it doing a more command:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# more zimbracsr.csr

We recommend one of this three:

  • [1]Comodo DecodeCSR
  • [2] Symantec CSR Check
  • [3] SSLShoper CSR Decoder

Use this web pages is quite easy, we just copy the CSR content and paste into this pages, take a look of this example in Symantec Website:


Buying the Commercial SSL Certificate

The next step is buy a valid commercial SSL certificate. Have tons of webpages around the World that you can use. This Companies will ask us about the CSR and our Business Information. And once the verification has a success they will send to us a file with the SSL Certificate (usually is a file with .crt extension)

Installing the Commercial SSL Certificate

When we have everything from our SSL Certificate authority, is time to put it in the correct folder.

Creating the commercial.crt

This file is easy to create, we only need to create that and paste inside the content of the file that the Certificate authority gave it to us:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# vi commercial.crt
Creating the commercial_ca.crt

The file called commercial_ca.crt needs to be created with the correct information, we need to mix the Root Certificate and also The Intermediate Certificate, the order matters, so the file need to include CA INTERMEDIATE or INTERMEDIATES, CA ROOT one in the end of other with only one Backspace:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# vi commercial_ca.crt

For example, this is how looks the file commercial_ca.crt with date September 2014 with a Geotrust QuickSSL Premium Certificate:

Checking if every file is OK

Also with all of these steps, we could do something wrong, we could check if everything is alright before deploy the SSL Certificate, for test all files we will execute the next:

zimbra@help:/opt/zimbra/bin/zmcertmgr verifycrt comm zimbraprivate.key commercial.crt commercial_ca.crt

If everything is allright, the result of the command will be:

** Verifying commercial.crt against zimbraprivate.key
Certificate (commercial.crt) and private key (zimbraprivate.key) match.
Valid Certificate: commercial.crt: OK
Launching the last two command

If we don't have any issue in the previous step, is time to launch the last two command here:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# /opt/zimbra/bin/zmcertmgr deploycrt comm commercial.crt commercial_ca.crt

The Logfile will be like this:

** Verifying commercial.crt against /opt/zimbra/ssl/zimbra/commercial/zimbraprivate.key
Certificate (commercial.crt) and private key (/opt/zimbra/ssl/zimbra/commercial/zimbraprivate.key) match.
Valid Certificate: commercial.crt: OK
** Copying commercial.crt to /opt/zimbra/ssl/zimbra/commercial/commercial.crt
** Appending ca chain commercial_ca.crt to /opt/zimbra/ssl/zimbra/commercial/commercial.crt
** Importing certificate /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt to CACERTS as zcs-user-commercial_ca...done.
** NOTE: mailboxd must be restarted in order to use the imported certificate.
** Saving server config key zimbraSSLCertificate...done.
** Saving server config key zimbraSSLPrivateKey...done.
** Installing mta certificate and key...done.
** Installing slapd certificate and key...done.
** Installing proxy certificate and key...done.
** Creating pkcs12 file /opt/zimbra/ssl/zimbra/jetty.pkcs12...done.
** Creating keystore file /opt/zimbra/mailboxd/etc/keystore...done.
** Installing CA to /opt/zimbra/conf/ca...done.

The last step is import the SSL Certificate into JAVA security, for this work we will do the follow commands:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# /opt/zimbra/java/bin/keytool -import -alias new -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/ssl/zimbra/commercial/commercial.crt

And then is much better do a complete reboot:

zimbra@help:/opt/zimbra/ssl/zimbra/commercial# sudo reboot
Forcing the Server to use only HTTPS

Now that we have a valid SSL, the best option is force to our server that only use SSL for our Web Client Access. For do it we will use zmtlsctl command, let's take a look of all of the options here:

  • http - http only, the user can access to our Zimbra Web Client trough http://webmail.zimbra.com
  • https – https only, the user can access to our Zimbra Web Client trough https://webmail.zimbra.com
  • both – The user can access trough both protocols http:// or https:// and it will keep in the same protocol during all session.
  • mixed – With this option, the user will come in trought http:// and will be redirect to https:// only for the login form, after that will be redirect to http:// again. If the user come directly trough https:// the user will be under https:// all the time.
  • redirect - If the user came trough http, it will be automatically redirect to https:// and it will keep on it during all session.
Possible Errors during the process

If we obtain the next error, it that means we introduced bad password:

zimbra@help:~/ssl/zimbra/commercial$ openssl rsa -in zimbrahelp.key -out zimbraprivate.key

Enter pass phrase for zimbrahelp.key:
unable to load Private Key
140530213516960:error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt:evp_enc.c:539:
140530213516960:error:0906A065:PEM routines:PEM_do_header:bad decrypt:pem_lib.c:483:

Multi-Node Commercial Certificate

1. We'll start by assuming you have your Commercial Certificate. If you don't, please see above. 2. Store the certificate and CA Chain on one of your systems:

  • Signed Certificate: /tmp/commercial.crt
  • Certificate Key (Private): /tmp/commercial.key
  • Root Certificate Authority (CA Root): /tmp/ca.crt
  • Any Intermediate CA Certs: /tmp/ca_intermediary.crt

3. Combine root and intermediary CAs into a temporary file.

 # cat /tmp/ca_intermediary.crt /tmp/ca.crt > /tmp/ca_chain.crt

4. [Optional Step] If you previously had an earlier Commercial Certificate on this platform, it may help - make this easier and more consistent - to remove the old ones:

 # mv /opt/zimbra/ssl/zimbra /opt/zimbra/ssl/zimbra.old

Then recreate the directories:

 # mkdir /opt/zimbra/ssl/zimbra
 # mkdir /opt/zimbra/ssl/zimbra/ca
 # mkdir /opt/zimbra/ssl/zimbra/commercial
 # mkdir /opt/zimbra/ssl/zimbra/server
 # chmod 740 /opt/zimbra/ssl/zimbra
 # chmod 740 /opt/zimbra/ssl/zimbra/*

5. Copy the commercial.key to /opt/zimbra/ssl/zimbra/commercial

 # cp /tmp/commercial.key /opt/zimbra/ssl/zimbra/commercial/
 # chmod 640 /opt/zimbra/ssl/zimbra/commercial/commercial.key

5. Verify your commercial certificate. (as root):

 # /opt/zimbra/bin/zmcertmgr verifycrt comm /opt/zimbra/ssl/zimbra/commercial/commercial.key /tmp/commercial.crt /tmp/ca_chain.crt

6. Deploy your commercial certificate.

 /opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt

7. To finish, verify the certificate was deployed.

 /opt/zimbra/bin/zmcertmgr viewdeployedcrt

8. In case of any issues in the Java keystore, check that the Intermediate CA was added to the keystore:

 /opt/zimbra/java/bin/keytool -list -keystore \
 /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit

If necessary, import the CA into the keystore:

 /opt/zimbra/java/bin/keytool -import -alias root -keystore \
 /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit -file /opt/zimbra/conf/ca/commercial_ca.pem

9. Copy these files to each of your other nodes, and repeat steps 4-8 on each node:

  • Signed Certificate: /tmp/commercial.crt
  • Certificate Key (Private): /tmp/commercial.key
  • Certificate Chain: /tmp/ca_chain.crt

ZCS 4.5.x

In ZCS 4.5.x, the task of creating a Certificate Authority, creating a self-signed certificate, and then installing the certificate is handled by three CLI commands. When you are installing a certificate, remember to stop and then restart Tomcat once the certificate has been installed.


This command creates a Certificate Authority (CA).




This command creates a new self-signed certificate.




This command installs a certificate.

Note: Tomcat must be stopped and restarted after you have installed a certificate.




The follow example shows how to install a self-signed certificate on a ZCS 4.5.x server.

1. As root, type the follow commands.

 rm -rf /opt/zimbra/ssl
 mkdir /opt/zimbra/ssl
 chown zimbra:zimbra /opt/zimbra/ssl

2. Switch to the Zimbra User.

 su -zimbra

3. Type the following command.

 keytool -delete -alias my_ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit

4. Create the Certificate Authority.


5. Create the self-signed certificate.


Note: You may need to type zmcreatecert host.domain.com if your host uses multiple names or aliases. (For example, if you have the hostname bingo.insidedomain.com, which is aliased to mail.truedomain.com, you will want to include the host and domain name for your certificate.) When typing your domain, be sure that the hostname is the one used in the certificate.

6. Install your certificate.

 zmcertinstall mailbox

7. Stop Tomcat.

 tomcat stop

8. Restart Tomcat.

 tomcat start
Verified Against: ZCS 8.x, 8.0.x, 7.0.x, 6.0.x Date Created: 9/10/2008
Article ID: https://wiki.zimbra.com/index.php?title=Administration_Console_and_CLI_Certificate_Tools Date Modified: 2014-10-03

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search