sslmate [OPTIONS] COMMAND [ARGS...]

sslmate buy HOSTNAME...

sslmate renew HOSTNAME

sslmate reissue HOSTNAME

sslmate rekey HOSTNAME

sslmate revoke [--all] HOSTNAME

sslmate download HOSTNAME...

sslmate download --all

sslmate list

sslmate show HOSTNAME

sslmate edit OPTIONS... HOSTNAME

sslmate test HOSTNAME

sslmate mkconfig TEMPLATE HOSTNAME

sslmate retry-approval HOSTNAME

sslmate link

buy [OPTIONS] HOSTNAME...

Generate a private key and purchase a certificate for the given hostname(s).

If only one hostname is specified, a single-hostname certificate is issued. The hostname is placed in the certificate's common name (CN) field as well as a subjectAltName field. If the hostname starts with "www.", a second subjectAltName is added, free of charge, for the base domain (formed by removing the "www." prefix). If the hostname does not start with "www.", a second subjectAltName is added, free of charge, for the www subdomain (formed by adding the "www." prefix). To disable the automatic addition of the second subjectAltName, specify the --no-auto-san option.

If the hostname starts with "*.", then a wildcard certificate is issued which is valid for the wildcard domain itself and all hostnames directly below the wildcard domain. The certificate is not valid for hostnames two or more levels below the wildcard domain. For example, "*.example.com" matches "example.com", "www.example.com", and "subdomain.example.com", but not "www.subdomain.example.com").

If more than one hostname is specified, a multi-hostname certificate is issued. The first hostname is the primary name of the certificate and is placed in the certificate's common name field, as well as a subjectAltName field. The remaining hostnames are placed in subjectAltNames. The certificate is referred to by its primary name when downloading, renewing, reissuing, etc. The primary name cannot be changed without purchasing a new certificate, but alternative names can be added and removed after the certificate is issued by running sslmate edit.

The following options are understood:

--auto-renew, --no-auto-renew

Enable or disable automatic renewal for this certificate. If neither option is specified, your account's default auto-renewal setting is used.

The auto-renewal setting of an already-purchased certificate can be changed from the SSLMate website.

--approval=email|dns|http

Use the given method to prove ownership of your domain.

When "email" is used (the default), you must respond to an email sent to one of the administrative addresses for your domain. You will be prompted for the email address when running sslmate buy, or you can specify it on the command line with the --email=ADDRESS option.

When "dns" is used, you must add a specific DNS record under your domain. If you have configured your SSLMate account to integrate with a supported DNS provider (see https://sslmate.com/account/integrations), then the DNS record will be added automatically. Otherwise, the DNS record will be displayed and you will need to add it manually.

When "http" is used, you must configure the web server for your domain to proxy certain URLs to an SSLMate approval server, as described at https://sslmate.com/help/approval/http. Once your web server is configured, certificates using HTTP approval will be approved and issued automatically.

When purchasing a multi-hostname certificate, each hostname must be approved separately. The approval method specified by this option applies to every hostname. To use a different method for a hostname, specify an option of the form --approval=HOSTNAME=METHOD.

--email=ADDRESS

Send the approval email to the given email address. This address must be one of the addresses that is listed when you run sslmate buy interactively. Only applicable if email approval is used.

When purchasing a multi-hostname certificate, this email address is used for every hostname. To use a different email address for a hostname, specify an option of the form --email=HOSTNAME=ADDRESS.

--timeout=SECONDS

Wait up to SECONDS seconds for the certificate to be issued. If the certificate is not issued before the timeout elapses, sslmate exits without downloading any certificate files. Instead, the certificate must be downloaded later with the sslmate download command.

--no-wait

Return immediately after placing the order instead of waiting for the certificate to be issued. If this option is used, no certificate files are downloaded; instead the certificate must be downloaded separately with the sslmate download command.

This option is equivalent to --timeout 0.

--temp

Instead of waiting for the certificate to be issued, install a temporary, self-signed, certificate and return immediately. The temporary certificate will not be trusted by clients, but it can be used to configure your server software while waiting for the real certificate to be issued.

When the real certificate is issued, it can be downloaded with the sslmate download command.

--invoice-note=NOTE

Include the given note with the invoice for this purchase.

--email-invoice-to=ADDRESS

Email the invoice for this purchase to the given address.

By default, invoices are not emailed, but can be downloaded from your online SSLMate dashboard.

-f, --force

Buy the certificate even if there are existing key and certificate files, or if an active certificate with this name already exists in your SSLMate account. Existing key and certificate files will be overwritten.

--key-type=rsa|ecdsa

Specify the type of key to generate: RSA (the default), or ECDSA (elliptic curve). The certificate will be signed with a signature of the same type.

RSA provides the best compatibility with clients. ECDSA provides better performance during the TLS handshake, but is not supported by older web browsers (such as IE 8 on Windows XP, Android 2.3, and Java 6). If in doubt, use RSA.

The default key type can be changed by setting the key_type configuration option (see the CONFIGURATION section for details).

--no-auto-san

Disable the addition of the automatic second subjectAltName if only one hostname was specified on the command line.

renew [OPTIONS] HOSTNAME

Renew the certificate for the given hostname.

The following options are understood:

--timeout=SECONDS

Wait up to SECONDS seconds for the certificate to be issued. If the certificate is not issued before the timeout elapses, sslmate exits without downloading any certificate files. Instead, the certificate must be downloaded later with the sslmate download command.

--no-wait

Return immediately after placing the order instead of waiting for the new certificate to be issued. If this option is used, no certificate files are downloaded; instead the new certificate must be downloaded separately with the sslmate download command.

This option is equivalent to --timeout 0.

--invoice-note=NOTE

Include the given note with the invoice for this purchase.

--email-invoice-to=ADDRESS

Email the invoice for this purchase to the given address.

By default, invoices are not emailed, but can be downloaded from your online SSLMate dashboard.

-f, --force

Renew the certificate even if it's not about to expire. Note that the renewed certificate will expire one year from the today's date, not from the expiration date of the current certificate.

reissue [OPTIONS] HOSTNAME

Generate a new private key (unless --same-key is specified) and reissue the certificate for the given hostname.

Note: sslmate reissue without the --same-key option is deprecated. Starting with SSLMate 2.0, --same-key will be implied. To reissue a certificate with a new key, use sslmate rekey instead.

Reissuing a certificate does not revoke it. Use the sslmate revoke command to revoke a certificate after you have reissued it.

The following options are understood:

--same-key

Keep the same private key when reissuing. This is useful if you are reissuing a certificate not because of a lost key, but to add or remove the alternative names of a multi-hostname certificate.

Note: Starting with SSLMate 2.0, --same-key will be implied. To reissue a certificate with a new key, use sslmate rekey instead.

--timeout=SECONDS

Wait up to SECONDS seconds for the certificate to be issued. If the certificate is not issued before the timeout elapses, sslmate exits without downloading any certificate files. Instead, the certificate must be downloaded later with the sslmate download command.

--no-wait

Return immediately after requesting the reissue instead of waiting for the new certificate to be issued. If this option is used, no certificate files are downloaded; instead the new certificate must be downloaded separately with the sslmate download command.

This option is equivalent to --timeout 0.

rekey [OPTIONS] HOSTNAME

Generate a new private key and reissue the certificate for the given hostname.

Reissuing a certificate does not revoke it. Use the sslmate revoke command to revoke a certificate after you have rekeyed it.

The following options are understood:

--timeout=SECONDS

Wait up to SECONDS seconds for the certificate to be issued. If the certificate is not issued before the timeout elapses, sslmate exits without downloading any certificate files. Instead, the certificate must be downloaded later with the sslmate download command.

--no-wait

Return immediately after requesting the rekey instead of waiting for the new certificate to be issued. If this option is used, no certificate files are downloaded; instead the new certificate must be downloaded separately with the sslmate download command.

This option is equivalent to --timeout 0.

-f, --force

Overwrite existing files.

--key-type=rsa|ecdsa

Specify the type of the new key: RSA (the default), or ECDSA (elliptic curve). The certificate will be signed with a signature of the same type.

See the documentation for sslmate buy for more information. If in doubt, do not use this option.

revoke [OPTIONS] HOSTNAME

Revoke the certificate(s) for the given hostname.

Revoking a certificate does not issue a new certificate. If you need a new certificate, use the sslmate reissue command to generate and issue a new certificate before running sslmate revoke.

The following options are understood:

-a, --all

Revoke all certificates for this hostname, including the most recent active certificate. If this option is omitted, all but the most recent active certificate are revoked.

WARNING: if you use this option, SSLMate will no longer be able to issue new certificates for this hostname unless you buy a brand new certificate. Generally, to revoke a certificate, you should first reissue it with the reissue command and then use revoke without the --all option. Only use --all if you no longer need any certificates for a hostname.

You will be prompted for confirmation unless you also specify the --batch global option.

download [OPTIONS] HOSTNAME...

Download the certificate(s) for the given hostname(s), or, if --all is specified, for all hostnames that have keys in the key_directory.

Certificate files are downloaded from your SSLMate account to your configured cert_directory (/etc/sslmate by default if run as root, $PWD if run as non-root). Existing certificate files are replaced. Exits with status code 0 if new certificate files were downloaded, or 10 if the most up-to-date certificate files have already been downloaded.

This command is designed to be run from a cron job or configuration management script so that auto-renewed certificates are automatically propagated to your server. You can check the exit status and, if zero, restart daemons so they load the latest version of the certificate.

The following options are understood:

-a, --all

Download certificate files for every key present in the key_directory (/etc/sslmate by default if run as root, $PWD if run as non-root).

If this option is used, specific hostnames cannot be specified on the command line.

--temp

If the certificate has not been issued yet, download a temporary, self-signed, certificate instead. See the documentation for sslmate buy for more information about temporary certificates.

list [OPTIONS]

List the certificates in your SSLMate account.

The following options are understood:

--local

List only certificates that are also installed locally.

--no-local

List only certificates that are not installed locally.

-c COLUMNS, --columns=COLUMNS

Include the given columns in the output, where COLUMNS is a comma-separated list of the following column names:

name

The certificate's common name.

status

The certificate's status.

expiration

The certificate's expiration date, in YYYY-MM-DD format.

local_status

The status of the locally-installed copy of the certificate ("Installed", "Temporary", "Mismatched key", "No key file", "Out-of-date", or "None").

fingerprint

The certificate's SHA-1 fingerprint, in uppercase hex with octets separated by colons.

sha256_fingerprint

The certificate's SHA-256 fingerprint, in uppercase hex with octets separated by colons.

auto_renew

The certificate's auto-renew setting.

type

Always "DV". This column exists for backwards compatibility only and should no longer be used.

approval_method

The approval method.

approver_email

The approver email address.

--sort=COLUMNS

Sort the output by the given column(s), where COLUMNS is a comma-separated list of column names as understood by the --columns option. If more than one column is specified, the latter columns are used to break ties if the earlier columns are equal.

Columns are sorted in ascending order by default. To sort a column in descending order, prefix it with a ^ symbol.

-z

Generate machine-parseable output. By default, columns and lines are separated by a NUL character, but this can be customized by setting the OFS (output field separator) and ORS (output record separator) environment variables.

When using -z, you must explicitly enumerate the columns you want with the --columns option.

The output of -z is guaranteed not to change format, making it suitable for use in scripts.

show [OPTIONS] HOSTNAME

Show information about the given certificate.

The following options are understood:

-f FIELDS, --fields=FIELDS

Include the given fields in the output, where FIELDS is a comma-separated list of the following column names:

name

The certificate's common name.

all_alt_names

The certificate's subject alternative names (SANs), including any automatically-added SAN for a single-hostname certificate.

alt_names

The certificate's subject alternative names (SAN). For backwards compatibility, this field is null if the certificate is a single-hostname certificate with the automatically-added SAN. You generally want to use all_alt_names instead.

status

The certificate's status.

expiration

The certificate's expiration date, in YYYY-MM-DD format.

local_status

The status of the locally-installed copy of the certificate ("Installed", "Temporary", "Mismatched key", "No key file", "Out-of-date", or "None").

fingerprint

The certificate's SHA-1 fingerprint, in uppercase hex with octets separated by colons.

sha256_fingerprint

The certificate's SHA-256 fingerprint, in uppercase hex with octets separated by colons.

auto_renew

The certificate's auto-renew setting.

type

Always "DV". This field exists for backwards compatibility only and should no longer be used.

approval_method

The approval method.

approver_email

The approver email address.

--json

Generate JSON output. The output format is guaranteed not to change, apart from backwards-compatible changes such as adding new fields to the JSON object.

edit OPTIONS... HOSTNAME

Change one or more setting of the given certificate. The settings are specified by the OPTIONS arguments, as described below. Every setting is optional; if omitted, the setting is left unchanged.

--approval=email|dns|http

Change the approval method for this certificate. The new method will be used for approving future reissues and renewals of the certificate. If the certificate is currently pending approval, the approval process will be re-initiated.

For more information about approval methods, see the documentation for sslmate buy.

If this is a multi-hostname certificate, the approval method specified by this option applies to every hostname. To edit the approval method for a single hostname only, pass an option of the form --approval=HOSTNAME=METHOD.

--email=ADDRESS

Change the approver email address of this certificate. The new address will be used for approving future reissues and renewals of the certificate. If the certificate is currently pending approval, the approval email will be resent to the new address.

The new address must be one of the acceptable addresses that is listed when you run sslmate buy for this host name. This option is only applicable when email approval is used.

If this is a multi-hostname certificate, the email address specified by this option applies to every hostname. To edit the email address for a single hostname only, pass an option of the form --email=HOSTNAME=METHOD.

--auto-renew, --no-auto-renew

Enable or disable auto-renew for this certificate.

--add-name=HOSTNAME, --rm-name=HOSTNAME

Add or remove the given hostname to or from this certificate. Only alternative names (not the common name) can be removed.

The name is not added or removed immediately. Instead, the changes take effect on the next call to sslmate reissue. Any names that were added since the last issuance will need to be approved. Existing names do not need to be re-approved as long as you preserve the existing private key by passing the --same-key option to sslmate reissue. If there has been a net increase in hostnames since the last issuance, your account will be charged for the new names.

test [OPTIONS] HOSTNAME

Test whether your certificate for HOSTNAME has been correctly installed.

This command works by connecting to the host specified in the certificate and checking that the server returns both the correct certificate and the correct certificate chain. The results of the test are printed to standard out. There may be more than one test result if HOSTNAME resolves to more than one IP address. This command exits with status 0 if all tests were successful, 11 if one or more tests failed, and some other exit code if there was an error that prevented the test from running.

The following options are understood:

-p PORTNUMBER, --port=PORTNUMBER

Test the server on the given port number. (Default: 443)

-h HOSTNAME, --host=HOSTNAME

Test the server running on the given hostname. Defaults to the certificate's common name.

mkconfig [OPTIONS] TEMPLATE HOSTNAME

Output the configuration directives necessary to securely use the given certificate with the server software (such as Apache, nginx, etc.) specified by the TEMPLATE argument. For a list of server software for which configuration templates are available, pass the --templates option.

By default, sslmate mkconfig includes the "intermediate compatibility" security settings recommended by Mozilla's Server Side TLS Guide. These settings enable forward secrecy and disable broken ciphers and protocols, while supporting a broad range of clients.

The following options are understood:

--templates

Output a list of available configuration templates. No other arguments are required if you use this option.

--no-security

Don't include recommended security settings. Output only the bare minimum configuration needed to use the certificate.

retry-approval HOSTNAME

Retry the approval process of a certificate that's pending approval. If the certificate uses email approval, the email will be resent. If the certificate uses DNS approval, the DNS record will be added if not already present, and then re-checked.

To change the approval method or approver email of a pending certificate, use the sslmate edit command.

link

Link this system with your SSLMate account. sslmate link prompts for your SSLMate username and password and writes your API credentials to your personal SSLMate configuration file, permitting you to use the sslmate commands without having to enter your username and password.

Note: if you have enabled a daily purchase limit through your online SSLMate account page, you will always need to enter your password after exceeding the limit, even if you have linked this system.

help [COMMAND]

Display help for the given COMMAND , or an overview of all commands if no command is specified.

version [OPTIONS]

Print the currently-installed version of sslmate. By default, check if this version is up-to-date and print a message if a newer version is available.

The following options are understood:

--no-check

Do not check for a newer version.

--is-latest

Print no output, but exit with 0 if this version of sslmate is up-to-date, 10 if a newer version is available, and some other exit code if there is an error.

This option cannot be combined with --no-check.

--batch

Don't prompt for confirmation or for additional information. This option should be used when running sslmate unattended from scripts.

Any information which sslmate would have prompted for must be specified on the command line instead. For example, when buying a certificate, you must specify the approval method with the --approval option, and, if applicable, the approver email address with the --email=ADDRESS option.

--verbose

Display additional information about what sslmate is doing.

-p PROFILE, --profile=PROFILE

Use the given configuration profile, instead of the default. If this option is specified, the string "-PROFILE" will be appended to the paths of the configuration file and default key and certificate directories.

For example, if --profile=company is used, the global configuration file will be /etc/sslmate-company.conf and the default certificate directory will be /etc/sslmate-company, instead of /etc/sslmate.conf and /etc/sslmate.

This option is intended for those who need to use several different SSLMate accounts on a single server, since each configuration file can contain distinct SSLMate API credentials.

api_key KEY

Your API key, which can be found on your online SSLMate account page. This option is automatically set (in your personal configuration file) when you run sslmate link.

key_directory PATH, cert_directory PATH

The directories where sslmate places keys and certificates. When running as root, the default is /etc/sslmate. When running as non-root, the default is the current working directory.

wildcard_filename PREFIX

When creating files for wildcard certificates, use PREFIX in the filename instead of a * character.

cert_format.FORMAT yes|no

Enable or disable the given certificate format. When a format is enabled, sslmate will create a file of that format in your certificate directory when buying, reissuing, renewing, and downloading. After enabling a format that was previously disabled, you can create the missing files by running sslmate download --all. The formats are documented below in the CERTIFICATE FILES section. All formats are disabled by default except for "chained".

key_type rsa|ecdsa

The key type to use by default when buying or reissuing a certificate. Can be overridden by the --key-type command line flag. See the documentation for sslmate buy for details.

api_endpoint URI

The URI to the SSLMate API endpoint. This option does not need to be configured under normal circumstances.

~/.sslmate

Your personal configuration file. Options set in this file override options set in the global configuration file. See the "Configuration" section above for the syntax of this file.

/etc/sslmate.conf

The global configuration file. See the "Configuration" section above for the syntax of this file.

/etc/sslmate

The default directory for storing keys and certificates when run as root. Can be overridden by the key_directory and cert_directory configuration options.

hostname.key

The private key file for hostname, in PEM encoding (specifically, the PEM encoding of the ASN.1 DER encoding of a PKCS#1 RSAPrivateKey (for RSA) or a RFC 3279 EcpkParameters (for ECDSA)). This is the default format used by OpenSSL and is accepted by typical applications on Linux.

hostname.crt

The public certificate file for hostname, in PEM encoding (specifically, the PEM encoding of the ASN.1 DER encoding of the X.509 certificate). This is the default format used by OpenSSL and is accepted by typical applications on Linux. Warning: This file does not work on its own since it does not contain the certificate chain. You must also configure the chain certificate(s) using one of the other formats.

hostname.chain.crt

The certificate chain (aka intermediate certificate) file for hostname. This file contains the concatenation of each intermediate certificate, in PEM encoding. The first certificate is the issuer of the end-entity certificate, and the last certificate is signed by the root certificate. The root certificate is not included.

hostname.chained.crt (cert_format.chained)

A concatenation of the certificate and chain files for hostname, in PEM encoding. This format is enabled by default. This is the file you should use with most applications on Linux, which require the certificate and chain to be specified in the same file.

hostname.combined.pem (cert_format.combined)

A concatenation of the private key, certificate, and chain files for hostname, in PEM encoding. This format is intended for Linux applications which require the key and certificates to be specified in the same file.

hostname.p12 (cert_format.p12)

A PKCS#12 file (also known as a P12 or PFX file) containing the private key, certificate, and chain for hostname. The PKCS#12 file's password is "sslmate". PKCS#12 files are primarily used by Windows applications.

hostname.jks (cert_format.jks)

A Java keystore file containing the private key, certificate, and chain for hostname. The keystore's password is "sslmate". The keytool(1) command, from the Java runtime environment, must be installed to use this format. JKS files are generally used only by Java applications, such as Tomcat.

hostname.root.crt (cert_format.root)

The root certificate for hostname, in PEM encoding. You do not generally need the root certificate, so you should leave this format disabled unless you have a special requirement.

hostname.chain+root.crt (cert_format.chain+root)

A concatenation of the chain and root certificate files for hostname. This format is required for verifying OCSP responses and configuring OCSP stapling. You do not need it in a basic configuration.

SSLMATE_CONFIG

The path to your personal configuration file. Defaults to $HOME/.sslmate.