Settings.json
Some of the applications’ settings can be modified in a file called settings.json.
If this file is not present when the program starts it will be automatically
created on first run, copied from settings_default.json. This allows you to
xcopy new releases without worrying about overwriting your previously
customized settings.
Client
ClientName |
The name of the client, which comes back in several places like the scheduled task name, Windows event viewer, notification messages, user agent and the ConfigurationPath.
Type: string Default: "simple-acme"
|
|
|---|---|---|
ConfigurationPath |
Change the location where the program stores its (temporary) files.
Paths should be JSON-encoded, e.g. Default: undefined (resolves to %programdata%\{Client.ClientName}\{ACME.DefaultBaseUri})
|
|
LogPath |
The path where log files for the past 31 days are stored.
Paths should be JSON-encoded, e.g. Default: undefined (resolves to {Client.ConfigurationPath}\Log)
|
|
VersionCheck |
Automatically check for new versions at startup.
Type: bool Default: false
|
UI
DateFormat |
A string that is used to format the date of the certificates friendly name. Documentation for possibilities is available from Microsoft.
Type: string Default: "yyyy/M/d H:mm:ss"
|
|
|---|---|---|
PageSize |
The number of items to display per page in list views.
Type: number Default: 50
|
|
TextEncoding |
Encoding to use for the console output. A list of possible values can be found here. For certain languages "unicode" might give better results displaying the characters.
Note that changing this setting reduces compatibility with other programs that may be processing output generated by simple-acme. Default: "utf-8"
|
|
Color.Background |
When set to "black", the background color for the UI will be forced to black using VT100 escape sequences. This only works in modern terminals, i.e. nothing before Windows 2016 / Windows 10.
Type: string Default: undefined |
ACME
DefaultBaseUri |
Default ACME endpoint to use when none is specified with the command line. The client will attempt to get the service directory from both the literal uri provided and the /directory path under it (which is the convention used by Let's Encrypt, and therefor done for backwards compatibility reasons).
Type: string Default: "https://acme-v02.api.letsencrypt.org/"
|
|
|---|---|---|
DefaultBaseUriTest |
Default ACME endpoint to use when none is specified with the command line and the ‑‑test switch is activated.
Type: string Default: "https://acme-staging-v02.api.letsencrypt.org/"
|
|
DefaultBaseUriImport |
Default ACMEv1 endpoint to import renewal settings from.
Type: string Default: "https://acme-v01.api.letsencrypt.org/"
|
|
PostAsGet |
Use POST-as-GET mode as defined in RFC8555 section 6.3, as required by Let's Encrypt since November 2020.
Type: boolean Default: true
|
|
ValidateServerCertificate |
Set this to false to disable certificate validation of the ACME endpoint.
Note that setting this to Default: true
|
|
RetryCount |
Maximum numbers of times to refresh validation and order status, while waiting for the ACME server to complete its tasks.
Type: number Default: 15
|
|
RetryInterval |
Amount of time in seconds to wait for each retry.
Type: number Default: 5
|
|
PreferredIssuer |
In some exceptional cases an ACME service will offer multiple certificates signed by different root authorities. This setting can be used to give a preference. I.e. "ISRG Root X1" can be used to prefer Let's Encrypt self-signed chain over the backwards compatible "DST Root CA X3".
Note that this only really works for Apache and other software that uses Default: undefined |
Execution
DefaultPreExecutionScript |
Path to a script that is executed before renewing a certificate.
This may be useful to temporarely relax security measures, e.g. opening port 80 on the firewall. Paths should be JSON-encoded, e.g. Default: undefined |
|
|---|---|---|
DefaultPostExecutionScript |
Path to a script that is called after renewing a certificate, this may be useful to undo any actions taken by the script configured as the DefaultPreExecutionScript. Not to be confused with the script installation plugin. The difference is that the installation plugin can be configured separately for each renewal and has access to a lot more context about the new and previous certificates. Also when the installation script fails, the renewal will be retried later. That is not the case for the pre/post execution scripts. Any errors there are logged but otherwise ignored.
Paths should be JSON-encoded, e.g. Default: undefined |
Proxy
Url |
Configures a proxy server to use for communication with the ACME server and other HTTP requests done by the program.
Type: string Default: "[system]"
|
|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
UserName |
Username used to access the proxy server.
Type: string Default: undefined |
|||||||||||||
Password |
Password used to access the proxy server.
You don't have store a literal password here, but may also place a reference to the secret vault like Default: undefined |
Cache
Path |
The path where certificates, request files and private keys are cached. If you are using CentralSsl, this can not be set to the same path.
Paths should be JSON-encoded, e.g. Default: undefined (defaults to {Client.ConfigurationPath}\Certificates.)
|
|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ReuseDays |
When renewing or re-creating a previously requested certificate that has the exact same set of domain names, the program will used a cached version for this many days, to prevent users from running into rate limits while experimenting. Set this to a high value if you regularly re-request the same certificates, e.g. for a Continuous Deployment scenario.
Setting this to 0 will not entirely disable the cache (the program also needs the files for different reasons), but it will prevent the files from being used for renewals and will also ensure that no private key material is stored in the cache, unless specifically requested by ‑‑reuse-privatekey.
Type: number Default: 1
|
|||||||||||
DeleteStaleFiles |
Automatically delete files older than DeleteStaleFileDays many days from the folder {Cache.Path}. Running with default settings, these should only be long-expired certificates, generated for abandoned renewals.
Type: boolean Default: false
|
|||||||||||
DeleteStaleFileDays |
This value should be increased if you are working with long-lived certificates and enable DeleteStaleFiles.
Type: number Default: 120
|
|||||||||||
ProtectionMode |
Determines how the .pfx files in the cache are encrypted.
A
Default: "default"
|
Scheduled task
RenewalDays |
The number of days to renew a certificate after. Let's Encrypt certificates are currently for a max of 90 days so it is advised to not increase the days much.
If you increase the days, please note that you will have less time to fix any issues if the certificate doesn't renew correctly. Default: 55
|
|
|---|---|---|
RenewalDaysRange |
To spread service load, program run time and/or to minimize downtime, those managing a large amount of renewals may want to spread them out of the course of multiple days/weeks. The number of days specified here will be substracted from RenewalDays to create a range within which the renewal will e processed. E.g. if RenewalDays is 55 and RenewalDaysRange is 10, the renewal will be processed between 45 and 55 days after issuing.
If you use an order plugin to split your renewal into multiple orders, orders may run on different days.
Type: number Default: 0
|
|
RenewalMinimumValidDays |
The minimum number of days a certificate should still be valid. If the certificate is valid for a smaller number of days, it will be renewed regardless of the RenewalDays setting.
Type: number Default: 7
|
|
RenewalDisableServerSchedule |
By default, servers implementing ARI may suggest that renewals should happen earlier than the regularly scheduled moment. When set to true, ARI suggestions will be ignored (not recommended).
Type: boolean Default: false
|
|
RandomDelay |
Configures random time to wait for starting the scheduled task. This spreads the load on the servers and thus prevents users from getting TooManyRequests errors.
Type: string Default: "04:00:00"
(4 hours)
|
|
StartBoundary |
Configures start time for the scheduled task.
Type: string Default: "09:00:00"
(9:00 am)
|
|
ExecutionTimeLimit |
Configures time after which the scheduled task will be terminated if it hangs for whatever reason.
Type: string Default: "02:00:00"
(2 hours)
|
Notifications
SmtpServer |
SMTP server to use for sending email notifications. Required to receive renewal failure notifications.
Type: string Default: undefined |
|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
SmtpPort |
SMTP server port number.
Type: number Default: 25
|
|||||||||||
SmtpUser |
User name for the SMTP server, in case of authenticated SMTP.
Type: string Default: undefined |
|||||||||||
SmtpPassword |
Password for the SMTP server, in case of authenticated SMTP.
You don't have store a literal password here, but may also place a reference to the secret vault like Default: undefined |
|||||||||||
SmtpSecure |
Change to true to enable secure SMTP.
Type: boolean Default: false
|
|||||||||||
SmtpSecureMode |
Control the way the connection with the mail server is established. Only change this if you run into connection issues.
Type: number Default: 1
|
|||||||||||
SmtpSenderName |
Display name to use as the sender of notification emails.
Type: string Default: undefined (equivalent to {Client.ClientName}.)
|
|||||||||||
SenderAddress |
Email address to use as the sender of notification emails. Required to receive renewal notifications.
Type: string Default: undefined |
|||||||||||
ReceiverAddresses |
Email address to use as the sender of notification emails. Required to receive renewal failure notifications. The correct format for the receiver is ["example@example.com"] for a single address and ["example1@example.com", "example2@example.com"] for multiple addresses.
Type: string[] Default: undefined |
|||||||||||
EmailOnSuccess |
Send an email notification when a certificate has been successfully created or renewed, as opposed to the default behavior that only send failure notifications. Only works if at least SmtpServer, SmtpSenderAddress and SmtpReceiverAddress have been configured.
Type: boolean Default: false
|
|||||||||||
ComputerName |
This value replaces the Windows machine name reported in emails.
Type: string Default: undefined |
Proxy
Url |
Configures a proxy server to use for communication with the ACME server and other HTTP requests done by the program.
Type: string Default: "[system]"
|
|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
UserName |
Username used to access the proxy server.
Type: string Default: undefined |
|||||||||||||
Password |
Password used to access the proxy server.
You don't have store a literal password here, but may also place a reference to the secret vault like Default: undefined |
Script
Timeout |
Time in seconds to allow installation and DNS scripts to run before terminating them forcefully.
Type: number Default: 600
|
|
|---|---|---|
PowershellExecutablePath |
Customize this value to use a different version of Powershell to execute .ps1 scripts. E.g. C:\\Program Files\\PowerShell\\6.0.0\\pwsh.exe for Powershell Core 6.
Paths should be JSON-encoded, e.g. Default: "powershell.exe"
|
Validation
DefaultValidation |
Default validation plugin.
Type: string Default: undefined (equivalent to "selfhosting", with "filesystem" as backup for unprivileged users.)
|
|
|---|---|---|
DefaultValidationMode |
Default validation method.
Type: string Default: undefined (equivalent to "http-01")
|
|
DisableMultiThreading |
Disable multithreading features for validation. Inceases runtime but may help to fix bugs caused by race conditions.
Type: boolean Default: true
|
|
ParallelBatchSize |
Maximum number of validations to run simultaneously. We recommend limiting this to about 20 to prevent issues like overrunning the maximum size of a DNS response. The default is set to 100 for backwards compatibility reasons.
Type: number Default: 100
|
|
CleanupFolders |
If set to true, the program will automatically delete file it created after HTTP validation is complete. It will also cleanup the ./well-known/acme-challenge folder, if (and only if) there are no other files present.
Type: boolean Default: true
|
|
PreValidateDns |
If set to true, it will wait until it can verify that the validation record has been created and is available before beginning DNS validation.
Type: boolean Default: true
|
|
PreValidateDnsRetryCount |
Maximum numbers of times to retry DNS pre-validation, while waiting for the name servers to start providing the expected answer.
Type: number Default: 5
|
|
PreValidateDnsRetryInterval |
Amount of time in seconds to wait between each retry.
Type: number Default: 30
|
|
PreValidateDnsLocal |
Normally the program will verify the existence of the TXT record by querying the authoritative DNS servers for the record. Changing this to true will also wait until at least one of the configured DnsServers see the correct value, making the process potentially slower but more robust.
Type: boolean Default: false
|
|
AllowDnsSubstitution |
If your goal is to get a certificate for example.com using DNS validation, but the DNS service for that domain does not support automation, there is no plugin available for it and/or your security policy doesn't allow third party tools like simple-acme to access the DNS configuration, then you can set up a CNAME from _acme-challenge.example.com to another (sub)domain under your control that doesn't have these limitations.
acme-dns is based on this principle, but the same trick can be applied to any of the DNS plugins. Set this value to false to disable the feature.
Note that for the program to understand your DNS setup, the Default: true
|
|
DnsServers |
A list of servers to query during DNS prevalidation checks to verify whether or not the validation record has been properly created and is visible for the world. These servers will be used to locate the actual authoritative name servers for the domain. You can use the string "[System]" to have the program query your default name servers.
Type: string[] Default: [ "[System]" ]
|
|
Ftp.UseGnuTls |
If you experience connection issues with Unix FTPS servers, using the GnuTLS library instead of Microsofts native TLS implementation might solve the problem. This page by the FluentFTP project explains the reasons behind and limitations of this method.
Note that it's not enough to merely change this setting, check the documentation of the FTP plugin for more details. Default: false
|
Order
DefaultOrder |
Default order plugin.
Type: string Default: undefined (equivalent to "single")
|
|
|---|---|---|
DefaultValidDays |
Number of days requested certificates should remain valid.
Note that not all servers support this property. Specifically Let's Encrypt throws an error when using this at the time of writing. Default: undefined |
CSR
DefaultCsr |
Default CSR plugin.
Type: string Default: undefined (equivalent to "rsa")
|
|
|---|---|---|
Rsa.KeyBits |
The number of bits to use for RSA private keys, ultimately determining the strength of the encryption. Minimum is 2048.
Type: number Default: 3072
|
|
Rsa.SignatureAlgorithm |
Algorithm to use to sign CSR with RSA public key. Full list of possible options available here.
Note that not all servers will support all types of signatures. Default: "SHA512withECDSA"
|
|
Ec.CurveName |
The curve used to use to generated key pairs on.
Type: string Default: "secp384r1"
|
|
Ec.SignatureAlgorithm |
Algorithm to use to sign CSR with EC public key. Full list of possible options available here.
Note that not all servers will support all types of signatures. Default: "SHA512withECDSA"
|
Store
DefaultStore |
Default store plugin(s).
This may be a comma separated value for multiple default store plugins. Default: undefined (equivalent to "certificatestore" on Windows and "pemfiles" on other platforms)
|
|---|
Windows Certificate Store
DefaultStore |
The name of the certificate store to save the certificates in.
Type: string Default: undefined (certificates will be installed either in the "WebHosting" store, or if that is not available, the "My" store (better known in the Microsoft Management Console as as "Personal"))
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
PrivateKeyExportable |
If set to true, private keys stored in the Windows Certificate Store will be marked as exportable, allowing you to transfer them to other computers.
Note that this setting doesn't apply retroactively but only to certificates issued from the moment that setting has changed. For tips about migration please refer to this page. Default: false
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
UseNextGenerationCryptoApi |
If set to true, the program will use the Cryptography API: Next Generation (CNG) to handle private keys, instead of the legacy CryptoAPI.
Note that enabling this option may make the certificates unusable or behave differently in subtle ways for software that only supports or assumes the key to exist in CryptoAPI. For example:
|
Looking for win-acme?
simple-acme is a backwards compatible, drop-in replacement built by the same person. Project history.