-
Notifications
You must be signed in to change notification settings - Fork 382
Config variables
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="[email protected]" (default="")
Account email, if you need to be contacted by the CA ( for example as a reminder of certificate expiry )
Account key length. 4096 is the default, and max currently supported by LetsEncrypt.
The location of the account key
GetSSL also supports prime256v1, secp384r1 and secp521r1 EC keys.
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.
The agreement that has to be signed with the CA. If not defined, then the current agreement will be used.
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.
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-v02.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.
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)
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".
If set to "true" then the remote server will be checked for correct installation of the certificate as defined by the SERVER_TYPE
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.
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.
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.
The script of command used to remove a DNS challenge ( it will be passed the domain name and the challenge text as two arguments)
The script of command used to remove a DNS challenge ( it will be passed the domain name and the challenge text as two arguments)
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
The time period in seconds the systems waits before rechecking the DNS token. Default=10
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
- 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)
- This is a single file containing both the domain certificate and the CA certificate
- If blank, then no file is created / copied
- 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)
- This is a single file with both the private key and domain certificate
- If blank, then no file is created / copied
- This is a single file with all three certificates in it
- If blank, then no file is created / copied
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" )
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.
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.
Options to add to the FTP command, e.g.
FTP_ARGS="-p"
will call ftp with -p (passive mode), i.e. ftp -p <user@host>
Options to add to the ftp script, e.g.
FTP_OPTIONS=passive
will add passive to the list of commands in the ftp script
Options to specify the port for use in ftp, sftp, ftps and ftpes, e.g.
FTP_PORT=99
will use port 99 for all variants of ftp
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.
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.
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.
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
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.
The algorithm used for the domain key. "rsa", "prime256v1", "secp384r1" and "secp521r1" are supported by GetSSL.
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.
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"
Used when defining your own SERVER_TYPE for CHECK_REMOTE
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.
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.
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"
If set this adds additional options to the scp command used to upload the response to challenges, e.g. to specify an identify file.
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
If set this adds additional options to the sftp command used to upload the response to challenges, e.g. to specify a non-standard port.
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).
If set this adds additional options to the ssh command used to upload the response to challenges, e.g. to specify a non-standard port or an identify file. (alternative ports/identify files can be specified in the ~/.ssh/config file - see #455 for details)
used by openssl when generating keys etc. The default should generally be fine.
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" )
If USE_SINGLE_ACL is set to true (the default is false), then only the first ACL is used for all domains
The default is to use HTTP / HTTPS to challenge / validate ownership. setting this variable to "true" will use the DNS-01 challenge