Config variables

serverco edited this page Feb 18, 2017 · 28 revisions

getssl config

All the variables can be set at both the "account" level and the "domain" level. Anything set at the domain level will overwrite account level settings. In this way the top level is essentially your defaults, which you can modify for any particular domain.

ACCOUNT_EMAIL="me@example.com" (default="")

Account email, if you need to be contacted by the CA ( for example as a reminder of certificate expiry )

ACCOUNT_KEY_LENGTH=4096

Account key length. 4096 is the default, and max currently supported by LetsEncrypt.

ACCOUNT_KEY="$WORKING_DIR/account.key"

The location of the account key

ACCOUNT_KEY_TYPE="rsa"

GetSSL also supports prime256v1, secp384r1 and secp521r1 EC keys.

###ACL= The ACME Challenge Location for the domain and each SAN. These are included in quotes, so for a main domain and a single SAN it would look like;

ACL=('/var/www/example.com/web/.well-known/acme-challenge' 'ssh:server5:/var/www/example.com/web/.well-known/acme-challenge')

These should be of the form "/path/to/your/website/folder/.well-known/acme-challenge" where "/path/to/your/website/folder/" is the path, on your web server, to the web root for your domain.

You can use "ssh:servername:" or "ssh:user@servername:" at the start of any remote server location that you have ssh access to.

If a location for a file starts with ftp: or sftp: then the next variables are userid:password:servername:path

sftp requires sshpass and can be used for copying certificates and keys.

If the tokens need to be copied to more than one location, then separate each location with a semi-colon.

AGREEMENT="https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf"

The agreement that has to be signed with the CA. If not defined, then the current agreement will be used.

###AUTH_DNS_SERVER="" The authoritative DNS server for the domain, for use where you want to force it to a specific value rather than for nslookup try to determine the authoritative nameserver for the domain. If more than one, specify them as a space limited list.

CA="https://acme-staging.api.letsencrypt.org"

The "certification authority" where you are getting the certificates from. The above (staging) server is the default, and is good for testing as there are no real rate limits, so you are not likely to get blocked whilst testing. Change to a valid server ( CA="https://acme-v01.api.letsencrypt.org\" ) to obtain a fully signed certificate one you have tested. I personally leave the default as the staging, so any new domain I want to get certificates for is initially provided only a test cert ( from Happy Hacker) until I know I have all the variables correct, then change to the valid server.

CA_CERT_LOCATION="/etc/ssl/chain.crt"

If blank, then no file is copied, the original will be stored in ~/.getssl/example.com/chain.crt by default (where example.com is the main domain for this certificate)

CHECK_ALL_AUTH_DNS="false"

By default the script checks one authoritative DNS server, and assumes that all are in sync. If you want it to check all the DNS servers ( for the DNS challenge, to check the tokens are correct at every server ) then set the value to "true".

CHECK_REMOTE="true"

If set to "true" then the remote server will be checked for correct installation of the certificate as defined by the SERVER_TYPE

CHECK_REMOTE_WAIT="0"

The time in seconds after running the RELOAD_CMD before checking the certs. Normally the pause, or check that the reload / restart of any services would be included in the RELOAD_CMD statement, this wait period is added as an alternative method.

CSR_SUBJECT="/"

Most of the CSR_SUBJECT will be stripped out by Let's Encrypt ( as it will only include in anything it can verify). This option allows you to modify the subject line though.

DEACTIVATE_AUTH="false"

By default, once a domain has been authorised then, for your private account key, ACME remembers this for a period of time so that you don't need to authorise again to obtain a new certificate. If you wish to remove this authorisation then set to the value to true, and you will need to re-authorise next time you need a certificate for this domain.

DEFAULT_REVOKE_CA="https://acme-v01.api.letsencrypt.org"

Defines the default CA server that is used for revoking certificates, if you don't specify the CA on the command line.

###DNS_ADD_COMMAND="" The script of command used to remove a DNS challenge ( it will be passed the domain name and the challenge text as two arguments)

###DNS_DEL_COMMAND="" The script of command used to remove a DNS challenge ( it will be passed the domain name and the challenge text as two arguments)

###DNS_EXTRA_WAIT=0 The time period to wait, after the internal checks of DNS server have returned the correct value, before asking the ACME server to verify the tokens are correct. Default=0

###DNS_WAIT=10 The time period in seconds the systems waits before rechecking the DNS token. Default=10

Domain Certificate Locations

Whilst all the certificates will be stored in a folder ( of the main domain name) within the working directory, copies will be placed in the location that they are required by apache / nginx etc. these can be listed as local or remote (ssh:servername:) locations

If a location for a file starts with sftp: then the next variables are userid:password:servername:path Note. sftp requires sshpass and can be used for copying certificates and keys.

If you wish to copy to more than one location, separate the locations with a semi-colon.

See also CA_CERT_LOCATION

DOMAIN_CERT_LOCATION="ssh:server5:/etc/ssl/domain.key"

  • If blank, then no file is copied, the original will be stored in ~/.getssl/example.com/example.com.crt by default (where example.com is the main domain for this certificate)

DOMAIN_CHAIN_LOCATION=""

  • This is a single file containing both the domain certificate and the CA certificate
  • If blank, then no file is created / copied

DOMAIN_KEY_LOCATION="ssh:server5:/etc/ssl/domain.key"

  • If blank, then no file is copied, the original will be stored in ~/.getssl/example.com/example.com.key by default (where example.com is the main domain for this certificate)

DOMAIN_KEY_CERT_LOCATION=""

  • This is a single file with both the private key and domain certificate
  • If blank, then no file is created / copied

DOMAIN_PEM_LOCATION=""

  • This is a single file with all three certificates in it
  • If blank, then no file is created / copied

DOMAIN_KEY_LENGTH=4096

Domain key length. 4096 is the default, and max currently supported by LetsEncrypt. This is only used for RSA keys. By default the existing key is used, so delete any existing key if you change this value ( or set REUSE_PRIVATE_KEY="false" )

DOMAIN_STORAGE=~/.getssl

The directory below which all domain config and certificates etc are stored. Each certificate will have a folder based on it's primary domain within this directory.

DUAL_RSA_ECDSA="false"

If DUAL_RSA_ECDSA is set to "true" then two certificates will be obtained. One using an RSA key, and the other using whatever key is defined by PRIVATE_KEY_ALG. You can then have a web server which uses both an RSA and Elliptic curve certificate.

GETSSL_IGNORE_CP_PRESERVE="false"

If set to true, then permissions are not preserved whilst copying files with cp. It is not recommended to set this to true for security, however some file systems do not support preserving permissions.

HTTP_TOKEN_CHECK_WAIT=0

If a period of time is needed between uploading the token, and checking that it is correctly deployed then a wait time ( in seconds) can be defined.

IGNORE_DIRECTORY_DOMAIN="false"

If set to true, then the name of the "main domain" which would normally be the directory name, is not used on the certificate. For example you might want to create folders "group1", "group2" etc for certificates, which can be done using this option.

###OCSP_MUST_STAPLE="false" Setting this to "true" will add the flag to the CSR / certificate to set a flag which instructs the browser that the certificate must be served with a valid OCSP response or the browser should hard fail on the connection

###PREVENT_NON_INTERACTIVE_RENEWAL="false" If you have a certificate that should only be renewed interactively, then set PREVENT_NON_INTERACTIVE_RENEWAL="true". I.e. you have a domain which you don't want to leave the server keys active, or isn't always online, or requires some manual intervention. This enables the certificate to only be checked when run via cron ( say with the -a option ) but can then be run interactively with the same -a option and it will be renewed.

PRIVATE_KEY_ALG="rsa"

The algorithm used for the domain key. "rsa", "prime256v1", "secp384r1" and "secp521r1" are supported by GetSSL.

###PUBLIC_DNS_SERVER="" The DNS server to be used, if you want anything other than the computers default DNS server to be used. If your default DNS server is internal to the network, and you need to force usage of an external DNS server ( such as 8.8.8.8) then it can be specified here.

###RELOAD_CMD="" The command required to reload or restart services once a certificate has been issued and copied to the correct location. Typically this would be something like "service apache2 reload" but could also include a remote server such as "ssh:server5:service apache2 reload" which will connect to server5 via SSH and issue the reload command. You can add a user if required "ssh:user@server5:service apache2 reload"

###REMOTE_EXTRA="" Used when defining your own SERVER_TYPE for CHECK_REMOTE

###RENEW_ALLOW="30" The number of days left on a certificate before the script will allow you to renew. Keeping this at something likes 30 days helps prevent you asking for certificates repeatedly ( due to an error somewhere) and hitting rate limits. 30 days also gives plenty of time to still renew if there are any issues.

REUSE_PRIVATE_KEY="true"

By default private keys are kept, this can make it easier for those using Key pinning security measures. You can set REUSE_PRIVATE_KEY="false" to renew the key for every certificate if you prefer though.

###SANS="" Subject Alternative Name: The default is blank, but can be any list of alternate domains you want on the same certificate e.g. SANS="www.example.com, sub.example.com, www.sub.example.com" You should not include the primary domain in the SANS list ( you would typically just have www.domain.com in the SANS list). If you have a long list, you can place over multiple lines with either

SANS="domain1.com,\
domain2.com,\
domain3.com"

or

SANS="domain1.com,"
SANS+="domain2.com,"
SANS+="domain3.com" 

SERVER_TYPE="https"

The server type that GetSSL will check to determine if the certificate is installed correctly. These can be;

Server-Type Port Extra
https 443
ftp 21 FTP Explicit
ftpi 990 FTP Implicit
imap 143 StartTLS
imaps 993
pop3 110 StartTLS
pop3s 995
smtp 25 StartTLS
smtps_deprecated 465
smtps 587 StartTLS
smtp_submission 587 StartTLS
xmpp 5222 StartTLS
xmpps 5269
ldaps 636
port number

If you define it as a port number, you can also define REMOTE_EXTRA

###SKIP_HTTP_TOKEN_CHECK="false" If set to "true" then the script will not check that the url "http://yourdomain.com/.well-known/acme-challenge/token" can be reached after uploading the token. If there was an issue with the webroot path then validation will fail. This was added as a feature request for when a VM couldn't check it's own server).

SSLCONF=/etc/ssl/openssl.cnf

used by openssl when generating keys etc. The default should generally be fine.

TOKEN_USER_ID=""

When adding a token to your webroot/.well-known/acme-challenge and your web-server requires that to be a specific user ( different to the user running getssl) then it can be specified here. if you require a specific user and group then just specify them both in the same command, separated by a period ( TOKEN_USER_ID="user.group" )

USE_SINGLE_ACL="false"

If USE_SINGLE_ACL is set to true (the default is false), then only the first ACL is used for all domains

VALIDATE_VIA_DNS="false"

The default is to use HTTP / HTTPS to challenge / validate ownership. setting this variable to "true" will use the DNS-01 challenge

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.